Metadata-Version: 2.4
Name: manav
Version: 0.1.0
Summary: Official Python SDK for the Manav AI platform
Project-URL: Homepage, https://manavagi.com
Project-URL: Documentation, https://docs.manavagi.com/sdk/python
Project-URL: Repository, https://github.com/devsngh/manav-python
Project-URL: Issues, https://github.com/devsngh/manav-python/issues
Author-email: Manav AI <devsngh313@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,llm,manav,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: typing-extensions>=4.7.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: openapi-python-client>=0.21.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# Manav Python SDK

Official Python client for the [Manav AI](https://manavagi.com) platform.

## Install

```bash
pip install manav
```

Requires Python 3.9+.

## Quick start

Generate an API key at [platform.manavagi.com/settings/api-keys](https://platform.manavagi.com/settings/api-keys), then:

```python
from manav import Client

client = Client(api_key="mnv_...")

# List your agents
agents = client.get("/api/agents")
print(agents)

# Send a message to an agent
response = client.post("/api/chat/dialogues/stream", json={
    "agent_name": "manav",
    "message": "What's on my task list today?",
})
```

Or set the API key via environment variable:

```bash
export MANAV_API_KEY=mnv_...
```

```python
from manav import Client
client = Client()  # picks up MANAV_API_KEY automatically
```

## Async usage

```python
import asyncio
from manav import AsyncClient

async def main():
    async with AsyncClient(api_key="mnv_...") as client:
        agents = await client.get("/api/agents")
        print(agents)

asyncio.run(main())
```

## Error handling

The SDK raises typed exceptions:

```python
from manav import Client, AuthenticationError, RateLimitError, NotFoundError

client = Client(api_key="mnv_...")

try:
    result = client.post("/api/agents", json={"name": "my-bot"})
except AuthenticationError:
    print("Bad or expired API key")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after} seconds")
except NotFoundError:
    print("Resource not found")
```

Exception hierarchy:

```
ManavError                    # root — catch-all
├── AuthenticationError       # 401 — bad/missing/expired API key
├── NotFoundError             # 404 — resource doesn't exist / no access
├── RateLimitError            # 429 — .retry_after has seconds
├── ValidationError           # other 4xx — bad payload
└── APIError                  # 5xx — unexpected server error
```

Every exception also exposes `.status_code` and `.body` for debugging.

## Configuration

```python
client = Client(
    api_key="mnv_...",
    base_url="https://api.manavagi.com",  # default
    timeout=30.0,                          # default (seconds)
    max_retries=2,                         # default — retries on 429/5xx
)
```

## Retries

By default the SDK retries on `429` (rate limit) and `5xx` (server error), honoring the
`Retry-After` header when present and falling back to exponential backoff otherwise.
Set `max_retries=0` to disable.

## Versioning

Follows [semantic versioning](https://semver.org/). While the SDK is in `0.x`,
minor releases may include breaking changes — pin exact versions in production.

## Development

```bash
git clone https://github.com/devsngh/manav-python.git
cd manav-python
pip install -e ".[dev]"
pytest
```

## Regenerating the low-level API client

The low-level client under `manav/_generated/` is regenerated from the live
OpenAPI schema at `https://api.manavagi.com/openapi.json`:

```bash
openapi-python-client generate --url https://api.manavagi.com/openapi.json \
    --output-path manav/_generated \
    --overwrite
```

A weekly GitHub Actions workflow does this automatically and opens a PR when
new endpoints appear.

## License

MIT — see [LICENSE](./LICENSE).

## Links

- [Platform](https://manavagi.com)
- [App](https://platform.manavagi.com)
- [Docs](https://docs.manavagi.com)
- [Issues](https://github.com/devsngh/manav-python/issues)
