# Mantr Python SDK

Official Python client for [Mantr](https://mantr.net) - Deterministic Semantic Memory for AI.

[![PyPI version](https://badge.fury.io/py/mantr.svg)](https://badge.fury.io/py/mantr)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Installation

```bash
pip install mantr
```

## Quick Start

```python
from mantr import MantrClient

# Initialize with your API key
client = MantrClient(api_key='vak_live_...')

# Walk the semantic graph
result = client.walk(phonemes=['dharma', 'karma', 'yoga'])

# Access results
for path in result.paths:
    print(f"{' → '.join(path.nodes)} (score: {path.score})")
```

## Features

- ✅ **Type-safe** - Full Pydantic model validation
- ✅ **Async support** - Built-in retry logic with exponential backoff
- ✅ **Error handling** - Detailed exception types
- ✅ **Context manager** - Automatic cleanup
- ✅ **No dependencies** - Only `requests` and `pydantic`

## API Reference

### MantrClient

```python
client = MantrClient(
    api_key: str,              # Your Mantr API key (required)
    base_url: str = "https://api.mantr.net",  # API endpoint
    timeout: int = 30          # Request timeout in seconds
)
```

### walk()

Traverse the semantic graph to discover connections.

```python
result = client.walk(
    phonemes: List[str],       # Sanskrit concepts to explore
    pod: Optional[str] = None, # Context pod (coming soon)
    depth: int = 3,            # Traversal depth (1-10)
    limit: int = 100           # Max results (1-1000)
)
```

**Returns**: `WalkResponse` with:
- `paths` - List of discovered paths
- `latency_us` - Execution time in microseconds
- `credits_used` - Credits consumed

## Examples

### Chatbot with Memory

```python
from mantr import MantrClient

client = MantrClient(api_key='vak_live_...')

# Store conversation context
user_message = "How do I implement OAuth?"
context = client.walk(phonemes=['authentication', 'security'])

# Pass to your LLM
response = openai.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "system", "content": f"Context: {context}"},
        {"role": "user", "content": user_message}
    ]
)
```

### Document Q&A

```python
# Query your knowledge base
answer = client.walk(
    phonemes=['pricing', 'policy'],
    depth=5,
    limit=10
)

for path in answer.paths:
    print(f"Relevance: {path.score:.2%} - {path.nodes}")
```

## Error Handling

```python
from mantr import (
    MantrClient,
    AuthenticationError,
    InsufficientCreditsError,
    RateLimitError
)

try:
    result = client.walk(['test'])
except AuthenticationError:
    print("Invalid API key")
except InsufficientCreditsError:
    print("Out of credits - upgrade your plan")
except RateLimitError as e:
    print(f"Rate limit exceeded - retry after {e.retry_after}s")
```

## Context Manager

```python
with MantrClient(api_key='vak_live_...') as client:
    result = client.walk(['dharma'])
# Session automatically closed
```

## Get API Key

1. Sign up at [mantr.net/signup](https://mantr.net/signup)
2. Get 5,000 free walks/month
3. No credit card required

## Documentation

- **API Docs**: https://docs.mantr.net
- **Examples**: [/examples](./examples)
- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)

## Support

- **Issues**: [GitHub Issues](https://github.com/mantr/python-sdk/issues)
- **Email**: sdk@mantr.net
- **Discord**: https://discord.gg/mantr

## License

MIT License - see [LICENSE](./LICENSE) for details.
