cortefy 0.1.4
Python client library for the Cortefy API
License: MIT
Requires Python: >=3.8
Keywords: cortefy, memory, semantic-search, embeddings, ai

# 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_tag="ai-research",
    metadata={"priority": "high", "source": "research-paper"},
    custom_id="doc_2024_01_research_ml"
)

# Upload a file
result = client.memories.upload_file(
    file_path="./document.pdf",
    container_tags="research"
)

# 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_tag` (str, optional): Single container tag/name (recommended, preferred over container_tags)
- `container_tags` (List[str] or str, optional): Container tag(s) - deprecated, use container_tag
- `metadata` (dict, optional): Optional metadata dictionary (values must be strings, numbers, or booleans)
- `custom_id` (str, optional): Custom identifier for deduplication and updates (max 255 chars)
- `raw` (str, optional): Raw content to store alongside processed content
- `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`

#### `client.memories.upload_file(...)`

Upload a file and process it into memories.

**Parameters:**
- `file_path` (str, required): Path to the file to upload
- `container_tags` (str, optional): Container tag for the uploaded file
- `container_tag` (str, optional): Container tag (alternative to container_tags)

**Supported formats:**
- Documents: PDF, DOC, DOCX, TXT, MD
- Images: JPG, PNG, GIF, WebP (requires OCR libraries: Pillow, pytesseract)
- Videos: MP4, WebM, AVI (not yet supported)

**Maximum file size:** 50MB

**Returns:** Response dict with `status`, `chunks`, `memory_ids`, `container`, `filename`, 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