# Cortefy Python Client

Python client library for the Cortefy API - a semantic memory and search system.

## Installation

```bash
pip install cortefy
```

## Quick Start

```python
from cortefy import Cortefy
import os

# Initialize the client
client = Cortefy(
    api_key=os.environ.get("CORTEFY_API_KEY"),
    base_url="https://api.cortefy.com"  # Optional, defaults to localhost
)

# Add a memory
result = client.memories.add(
    content="Machine learning enables computers to learn from data",
    container_tags=["ai-research"],
    metadata={"priority": "high"}
)

# Search memories (single container)
results = client.search.memories(
    q="machine learning accuracy",
    limit=5,
    container_tag="ai-research"
)

# Search across multiple containers
results = client.search.memories(
    q="machine learning accuracy",
    container_tags=["ai-research", "notes", "docs"]
)
```

## API Reference

### Cortefy Client

```python
client = Cortefy(api_key: str, base_url: Optional[str] = None)
```

- `api_key`: Your Cortefy API key (required)
- `base_url`: Base URL for the API (defaults to `http://localhost:8000`)

### Memories Resource

#### `client.memories.add(...)`

Add a memory to the Cortefy API.

**Parameters:**
- `content` (str, required): The text content to store
- `container_tags` (List[str] or str, optional): Container tag(s) - uses first if multiple
- `metadata` (dict, optional): Optional metadata dictionary
- `chunk_method` (str, optional): Chunking method ('tokens' or 'sentences', default: 'tokens')
- `chunk_size` (int, optional): Size of chunks (default: 1000)
- `chunk_overlap` (int, optional): Overlap between chunks (default: 200)

**Returns:** Response dict with `status`, `chunks`, `memory_ids`, `container`, and `timing`

### Search Resource

#### `client.search.memories(...)`

Search memories using semantic search.

**Parameters:**
- `q` (str, required): Search query text
- `container_tag` (str or List[str], optional): Single container tag to filter by (deprecated: use container_tags)
- `container_tags` (List[str], optional): List of container tags to search across multiple containers
- `limit` (int, optional): Maximum number of results (default: 5)
- `min_similarity` (float, optional): Minimum similarity score 0.0-1.0 (default: 0.0)

**Returns:** Response dict with `results`, `timing`, and `total`

## Error Handling

The client raises custom exceptions:

- `CortefyException`: Base exception for all Cortefy errors
- `AuthenticationError`: Raised when API key authentication fails
- `APIError`: Raised when API returns an error response
- `ValidationError`: Raised when request validation fails

```python
from cortefy import Cortefy
from cortefy.exceptions import AuthenticationError, APIError

try:
    client = Cortefy(api_key="invalid-key")
    result = client.memories.add(content="test")
except AuthenticationError as e:
    print(f"Auth failed: {e}")
except APIError as e:
    print(f"API error: {e} (status: {e.status_code})")
```

## License

MIT

## Links

- Homepage: https://cortefy.com
- API Documentation: https://cortefy.com/docs

