Metadata-Version: 2.5
Name: youspot
Version: 0.1.0
Summary: Official Python client for YouSpot, the AI-native personal CRM. Ask questions, read the docs, list and call the MCP tools, and try them in the sandbox.
Project-URL: Homepage, https://youspot.com
Project-URL: Documentation, https://youspot.com/docs/api
Project-URL: Repository, https://github.com/OnStartups/youspot-agent-tools
Project-URL: Issues, https://youspot.com/support
Author: YouSpot, Inc.
License: MIT
Keywords: agent,crm,mcp,model-context-protocol,personal-crm,sdk,youspot
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# youspot

The official Python client for [YouSpot](https://youspot.com), the AI-native personal CRM. It is the twin of the [`youspot` npm package](https://www.npmjs.com/package/youspot): same endpoints, same rules about what needs a credential.

No dependencies. Standard library only.

```bash
pip install youspot
```

## Ask without a credential

```python
import youspot

youspot.ask("what does youspot cost")
youspot.search_docs("mcp oauth")
youspot.read_markdown("/pricing")
youspot.index()
```

## Try the tools without an account

`https://youspot.com/mcp/sandbox` runs the read tools against a demo account whose contacts and interactions are generated. No signup, no credits, and every tool that writes is refused there.

```python
youspot.sandbox_tools()
youspot.call_sandbox_tool("search_graph_objects", {"query": "consulting"})
```

## Call a member's own tools

Every tool reads one person's CRM, so this needs their token. Mint one at [youspot.com/user/mcp](https://youspot.com/user/mcp) and set `YOUSPOT_TOKEN`, or run the OAuth 2.1 flow described in [auth.md](https://youspot.com/auth.md).

```python
youspot.tools()
youspot.call_tool("search_graph_objects", {"query": "acme"})
youspot.identity("service_auth", token="...")
```

## Errors

Everything raises `youspot.YouSpotError`, which carries `.status`, `.code` and a readable message.

```python
try:
    youspot.call_tool("search_graph_objects", {"query": "acme"})
except youspot.YouSpotError as error:
    print(error.code, error)
```

## Configuration

| Variable | Default |
| --- | --- |
| `YOUSPOT_BASE_URL` | `https://youspot.com` |
| `YOUSPOT_TOKEN` | unset; required only for `call_tool` |

The machine description of every endpoint is at [youspot.com/openapi.json](https://youspot.com/openapi.json).
