cortefy 0.1.4

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_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

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

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