cortefy 0.1.3

Python client library for the Cortefy API

Cortefy Python Client

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

Installation

pip install cortefy

Quick Start

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

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

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