cortexdbai 0.2.0__py3-none-any.whl

cortexdb/exceptions.py

@@ -0,0 +1,69 @@
+"""Exception hierarchy for the CortexDB Python SDK."""
+
+from __future__ import annotations
+
+
+class CortexError(Exception):
+    """Base exception for all CortexDB SDK errors."""
+
+    def __init__(self, message: str = "") -> None:
+        self.message = message
+        super().__init__(message)
+
+
+class CortexAPIError(CortexError):
+    """Raised when the CortexDB API returns an error response.
+
+    Attributes:
+        status_code: HTTP status code from the server.
+        error_code: Application-level error code returned by the API, if any.
+        message: Human-readable error description.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int,
+        error_code: str | None = None,
+    ) -> None:
+        self.status_code = status_code
+        self.error_code = error_code
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        parts = [f"[HTTP {self.status_code}]"]
+        if self.error_code:
+            parts.append(f"[{self.error_code}]")
+        parts.append(self.message)
+        return " ".join(parts)
+
+
+class CortexConnectionError(CortexError):
+    """Raised when the SDK cannot connect to the CortexDB server."""
+
+
+class CortexTimeoutError(CortexConnectionError):
+    """Raised when a request to the CortexDB server times out."""
+
+
+class CortexAuthError(CortexAPIError):
+    """Raised when authentication fails (HTTP 401 or 403)."""
+
+
+class CortexRateLimitError(CortexAPIError):
+    """Raised when the API returns HTTP 429 Too Many Requests.
+
+    Attributes:
+        retry_after: Number of seconds to wait before retrying, parsed from
+            the Retry-After header. None if the header was absent.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = 429,
+        error_code: str | None = None,
+        retry_after: float | None = None,
+    ) -> None:
+        self.retry_after = retry_after
+        super().__init__(message=message, status_code=status_code, error_code=error_code)

cortexdb/models.py

@@ -0,0 +1,390 @@
+"""Pydantic models for the CortexDB Python SDK.
+
+These models mirror the Rust-side Episode schema and API request/response types.
+All models use snake_case field names with camelCase JSON serialization for
+wire compatibility.
+"""
+
+from __future__ import annotations
+
+import enum
+from datetime import datetime
+from typing import Any
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+def _to_camel(name: str) -> str:
+    """Convert snake_case to camelCase for JSON serialization."""
+    parts = name.split("_")
+    return parts[0] + "".join(word.capitalize() for word in parts[1:])
+
+
+_SHARED_CONFIG = ConfigDict(
+    populate_by_name=True,
+    alias_generator=_to_camel,
+    use_enum_values=True,
+)
+
+
+# ---------------------------------------------------------------------------
+# Enums
+# ---------------------------------------------------------------------------
+
+
+class EpisodeType(str, enum.Enum):
+    """Classification of an episode's content type."""
+
+    MESSAGE = "message"
+    CODE_CHANGE = "code_change"
+    INCIDENT = "incident"
+    DEPLOYMENT = "deployment"
+    ISSUE = "issue"
+    DOCUMENT = "document"
+    REVIEW = "review"
+    MEETING = "meeting"
+    ALERT = "alert"
+    DECISION = "decision"
+    CUSTOM = "custom"
+
+
+class ActorType(str, enum.Enum):
+    """The kind of actor that produced an episode."""
+
+    PERSON = "person"
+    BOT = "bot"
+    SYSTEM = "system"
+    SERVICE = "service"
+
+
+class VisibilityLevel(str, enum.Enum):
+    """Access level for an episode."""
+
+    ORGANIZATION = "organization"
+    RESTRICTED = "restricted"
+    PRIVATE = "private"
+    PUBLIC = "public"
+
+
+# ---------------------------------------------------------------------------
+# Core domain models
+# ---------------------------------------------------------------------------
+
+
+class Actor(BaseModel):
+    """Represents the entity that produced an episode."""
+
+    model_config = _SHARED_CONFIG
+
+    id: str
+    name: str = ""
+    actor_type: ActorType = ActorType.PERSON
+    email: str | None = None
+
+
+class Source(BaseModel):
+    """Provenance information for an episode."""
+
+    model_config = _SHARED_CONFIG
+
+    connector: str
+    external_id: str = ""
+    url: str | None = None
+    channel: str | None = None
+
+
+class Visibility(BaseModel):
+    """Access control specification for an episode."""
+
+    model_config = _SHARED_CONFIG
+
+    level: VisibilityLevel = VisibilityLevel.ORGANIZATION
+    allowed_groups: list[str] = Field(default_factory=list)
+    allowed_users: list[str] = Field(default_factory=list)
+
+
+class EntityRef(BaseModel):
+    """A reference to a named entity mentioned in an episode."""
+
+    model_config = _SHARED_CONFIG
+
+    name: str
+    entity_type: str = ""
+    role: str | None = None
+
+
+class Episode(BaseModel):
+    """A single episode of memory stored in CortexDB.
+
+    An episode represents a discrete unit of information — a message,
+    document, code snippet, decision, or any other event worth remembering.
+    """
+
+    model_config = _SHARED_CONFIG
+
+    id: UUID | None = None
+    tenant_id: str = "default"
+    episode_type: EpisodeType = EpisodeType.MESSAGE
+    content: str
+    actor: Actor | None = None
+    source: Source | None = None
+    visibility: Visibility | None = None
+    entities: list[EntityRef] | None = None
+    metadata: dict[str, Any] | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+# ---------------------------------------------------------------------------
+# API request / response models
+# ---------------------------------------------------------------------------
+
+
+class IngestEpisodeRequest(BaseModel):
+    """Request body for POST /v1/episodes."""
+
+    model_config = _SHARED_CONFIG
+
+    content: str
+    tenant_id: str = "default"
+    episode_type: EpisodeType = EpisodeType.MESSAGE
+    actor: Actor | None = None
+    source: Source | None = None
+    visibility: Visibility | None = None
+    entities: list[EntityRef] | None = None
+    metadata: dict[str, Any] | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> IngestEpisodeRequest:
+        """Create an IngestEpisodeRequest from a plain dictionary.
+
+        Accepts a simplified dict with the following keys:
+
+        - ``content`` (str, required): The episode text content.
+        - ``type`` (str, optional): Episode type name (default ``"message"``).
+        - ``source`` (str, optional): Connector/system name (default ``"sdk"``).
+        - ``actor`` (str, optional): Actor name (default ``"sdk"``).
+        - ``tenant_id`` (str, optional): Tenant namespace (default ``"default"``).
+        - ``metadata`` (dict, optional): Arbitrary key-value metadata.
+
+        Any other keys are folded into the ``metadata`` dict so that callers
+        can pass domain-specific fields without worrying about the schema.
+
+        Returns:
+            A fully-formed ``IngestEpisodeRequest`` ready for ingestion.
+
+        Raises:
+            ValueError: If ``content`` is missing from the dict.
+        """
+        data = dict(data)  # shallow copy to avoid mutating caller's dict
+
+        content = data.pop("content", None)
+        if content is None:
+            raise ValueError(
+                "The 'content' key is required when constructing an "
+                "IngestEpisodeRequest from a dict."
+            )
+
+        episode_type_raw = data.pop("type", "message")
+        try:
+            episode_type = EpisodeType(episode_type_raw)
+        except ValueError:
+            episode_type = EpisodeType.MESSAGE
+
+        source_name = data.pop("source", "sdk")
+        actor_name = data.pop("actor", "sdk")
+        tenant_id = data.pop("tenant_id", "default")
+        metadata = data.pop("metadata", None)
+
+        # Remaining unknown keys get merged into metadata so nothing is lost.
+        if data:
+            if metadata is None:
+                metadata = {}
+            metadata.update(data)
+
+        return cls(
+            content=content,
+            episode_type=episode_type,
+            tenant_id=tenant_id,
+            actor=Actor(id=actor_name, name=actor_name, actor_type=ActorType.SERVICE),
+            source=Source(connector=source_name, external_id="sdk"),
+            metadata=metadata if metadata else None,
+        )
+
+
+class IngestEpisodeResponse(BaseModel):
+    """Response from POST /v1/episodes."""
+
+    model_config = _SHARED_CONFIG
+
+    episode_id: str
+    event_id: str
+    ingested_at: str
+
+
+class RememberRequest(BaseModel):
+    """Request body for POST /v1/remember."""
+
+    model_config = _SHARED_CONFIG
+
+    content: str
+    tenant_id: str = "default"
+    scope: str | None = None
+    metadata: dict[str, Any] | None = None
+
+
+class RememberResponse(BaseModel):
+    """Response from POST /v1/remember."""
+
+    model_config = _SHARED_CONFIG
+
+    event_id: str
+
+
+class RecallRequest(BaseModel):
+    """Request body for POST /v1/recall."""
+
+    model_config = _SHARED_CONFIG
+
+    query: str
+    tenant_id: str = "default"
+    max_tokens: int = 4096
+    min_confidence: float = 0.0
+
+
+class RecallResponse(BaseModel):
+    """Response from POST /v1/recall."""
+
+    model_config = _SHARED_CONFIG
+
+    context: str
+    confidence: float
+    latency_ms: int = 0
+
+
+class ForgetRequest(BaseModel):
+    """Request body for POST /v1/forget."""
+
+    model_config = _SHARED_CONFIG
+
+    query: str | None = None
+    reason: str = ""
+    tenant_id: str = "default"
+
+
+class ForgetResponse(BaseModel):
+    """Response from POST /v1/forget."""
+
+    model_config = _SHARED_CONFIG
+
+    forgotten_entities: int = 0
+    forgotten_edges: int = 0
+    audit_id: str = ""
+
+
+class EpisodeBrief(BaseModel):
+    """Summary of an episode returned by GET /v1/episodes.
+
+    This matches the ``EpisodeSummary`` struct in the Rust API which returns
+    a lightweight representation without the full content body.
+    """
+
+    model_config = _SHARED_CONFIG
+
+    id: str
+    actor_name: str = ""
+    source_connector: str = ""
+    episode_type: EpisodeType = EpisodeType.MESSAGE
+    content_preview: str = ""
+    occurred_at: str = ""
+    entity_count: int = 0
+
+
+class ListEpisodesResponse(BaseModel):
+    """Response from GET /v1/episodes."""
+
+    model_config = _SHARED_CONFIG
+
+    episodes: list[EpisodeBrief] = Field(default_factory=list)
+    total: int = 0
+    has_more: bool = False
+
+
+class HealthResponse(BaseModel):
+    """Response from GET /v1/admin/health."""
+
+    model_config = _SHARED_CONFIG
+
+    status: str
+    storage: str | None = None
+    version: str | None = None
+
+
+class MetricsResponse(BaseModel):
+    """Response from GET /v1/admin/metrics."""
+
+    model_config = _SHARED_CONFIG
+
+    requests_total: int = 0
+    requests_active: int = 0
+    errors_total: int = 0
+    rate_limited_total: int = 0
+
+
+# ---------------------------------------------------------------------------
+# Entity / Link / Search models
+# ---------------------------------------------------------------------------
+
+
+class EntityRelationship(BaseModel):
+    """A relationship edge associated with an entity."""
+
+    id: str
+    source_entity_id: str
+    target_entity_id: str
+    relationship: str
+    fact: str
+    confidence: float
+    created_at: str
+
+
+class EpisodeBrief(BaseModel):
+    """A lightweight summary of an episode."""
+
+    id: str
+    actor_name: str
+    source_connector: str
+    episode_type: str
+    content_preview: str
+    occurred_at: str
+
+
+class EntityResponse(BaseModel):
+    """Response from GET /v1/entities/{entity_id}."""
+
+    id: str
+    name: str
+    entity_type: str
+    first_seen: str
+    last_seen: str
+    episode_count: int
+    relationships: list[EntityRelationship] = []
+    recent_episodes: list[EpisodeBrief] = []
+
+
+class LinkResponse(BaseModel):
+    """Response from POST /v1/link."""
+
+    id: str
+    created_at: str
+
+
+class SearchResponse(BaseModel):
+    """Response from POST /v1/search."""
+
+    context: str
+    confidence: float
+    latency_ms: int
+    episodes: list[EpisodeBrief] = []
+    total_episodes: int = 0

cortexdbai-0.2.0.dist-info/METADATA

@@ -0,0 +1,236 @@
+Metadata-Version: 2.4
+Name: cortexdbai
+Version: 0.2.0
+Summary: The Long-Term Memory Layer for AI Systems
+Project-URL: Homepage, https://cortexdb.io
+Project-URL: Documentation, https://docs.cortexdb.io
+Project-URL: Repository, https://github.com/cortexdb/cortexdb
+Project-URL: Issues, https://github.com/cortexdb/cortexdb/issues
+Project-URL: Changelog, https://github.com/cortexdb/cortexdb/blob/main/CHANGELOG.md
+Author-email: Prashant Malik <prashant@cortexdb.io>
+License-Expression: Apache-2.0
+Keywords: ai,cortexdb,event-sourcing,knowledge-graph,llm,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: tenacity>=8.0
+Provides-Extra: async
+Requires-Dist: httpx[http2]; extra == 'async'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CortexDB Python SDK
+
+**The Long-Term Memory Layer for AI Systems.**
+
+CortexDB gives your AI agents persistent, searchable memory. Store conversations, decisions, incidents, and domain knowledge as structured episodes. Retrieve relevant context with a single call.
+
+[![PyPI version](https://img.shields.io/pypi/v/cortexdb.svg)](https://pypi.org/project/cortexdb/)
+[![Python](https://img.shields.io/pypi/pyversions/cortexdb.svg)](https://pypi.org/project/cortexdb/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/cortexdb/cortexdb/blob/main/LICENSE)
+
+## Installation
+
+```bash
+pip install cortexdb
+```
+
+For HTTP/2 support (recommended for async workloads):
+
+```bash
+pip install cortexdb[async]
+```
+
+## Quick Start
+
+```python
+from cortexdb import Cortex
+
+# Connect to CortexDB
+cortex = Cortex("http://localhost:3141", api_key="your-api-key")
+
+# Remember something
+cortex.remember("The payments service was migrated to Kubernetes on March 15th.")
+
+# Recall relevant memories
+result = cortex.recall("When did we migrate payments?")
+for match in result.matches:
+    print(f"[{match.confidence:.0%}] {match.content}")
+
+# Forget when needed (GDPR, cleanup, etc.)
+cortex.forget(query="old deploy logs", reason="quarterly cleanup")
+
+# Search with filters
+results = cortex.search(
+    "deploy failure",
+    source="github",
+    time_range="7d",
+    limit=10,
+)
+print(results.context)
+```
+
+## Async Usage
+
+Every method has an async counterpart via `AsyncCortex`:
+
+```python
+import asyncio
+from cortexdb import AsyncCortex
+
+async def main():
+    async with AsyncCortex("http://localhost:3141", api_key="your-api-key") as cortex:
+        await cortex.remember("Async memory storage works great.")
+
+        result = await cortex.recall("How does async work?")
+        for match in result.matches:
+            print(match.content)
+
+asyncio.run(main())
+```
+
+## Episode Ingestion
+
+For structured data, use episodes with full metadata:
+
+```python
+from cortexdb import Cortex, IngestEpisodeRequest, Actor, Source, ActorType, EpisodeType
+
+cortex = Cortex("http://localhost:3141")
+
+# Ingest a structured episode
+episode = IngestEpisodeRequest(
+    content="PR #412: Add retry logic to payment processor",
+    episode_type=EpisodeType.CODE_CHANGE,
+    actor=Actor(id="ci-bot", name="CI Bot", actor_type=ActorType.SERVICE),
+    source=Source(connector="github", external_id="pr-412", url="https://github.com/org/repo/pull/412"),
+    metadata={"branch": "main", "files_changed": 3},
+)
+response = cortex.ingest_episode(episode)
+print(f"Episode {response.episode_id} ingested.")
+
+# Or use the smart store shorthand
+cortex.store("Plain text goes through remember().")
+cortex.store({
+    "content": "Dict data goes through ingest_episode().",
+    "type": "deployment",
+    "source": "slack",
+})
+```
+
+## Entity Lookup
+
+Explore entities and their relationships in the knowledge graph:
+
+```python
+cortex = Cortex("http://localhost:3141")
+
+# Look up an entity
+entity = cortex.entity("payments-service")
+print(f"{entity.name} ({entity.entity_type})")
+print(f"  Episodes: {entity.episode_count}")
+print(f"  First seen: {entity.first_seen}")
+
+# Browse relationships
+for rel in entity.relationships:
+    print(f"  {rel.relationship} -> {rel.target_entity_id} ({rel.confidence:.0%})")
+
+# Create explicit relationships
+cortex.link(
+    source_entity_id="payments-service",
+    target_entity_id="auth-service",
+    relationship="DEPENDS_ON",
+    fact="Payments calls auth for token validation",
+    confidence=0.95,
+)
+```
+
+## Error Handling
+
+The SDK provides a structured exception hierarchy:
+
+```python
+from cortexdb import Cortex
+from cortexdb.exceptions import (
+    CortexError,          # Base exception
+    CortexAPIError,       # HTTP 4xx/5xx errors
+    CortexAuthError,      # HTTP 401/403
+    CortexRateLimitError, # HTTP 429 (includes retry_after)
+    CortexConnectionError,# Network failures
+    CortexTimeoutError,   # Request timeouts
+)
+
+cortex = Cortex("http://localhost:3141")
+
+try:
+    cortex.remember("important data")
+except CortexRateLimitError as e:
+    print(f"Rate limited. Retry after {e.retry_after}s")
+except CortexAuthError as e:
+    print(f"Authentication failed: {e.message}")
+except CortexConnectionError:
+    print("Cannot reach CortexDB server")
+except CortexAPIError as e:
+    print(f"API error [{e.status_code}]: {e.message}")
+```
+
+Transient errors (429, 502, 503, 504) and connection failures are automatically retried with exponential backoff. Configure retry behavior at client initialization:
+
+```python
+cortex = Cortex(
+    "http://localhost:3141",
+    max_retries=5,   # default: 3
+    timeout=60.0,    # default: 30.0 seconds
+)
+```
+
+## Configuration
+
+### Constructor Parameters
+
+| Parameter      | Type    | Default                  | Description                        |
+|----------------|---------|--------------------------|------------------------------------|
+| `base_url`     | `str`   | `http://localhost:3141`  | CortexDB server URL               |
+| `api_key`      | `str`   | `None`                   | Bearer token for authentication    |
+| `timeout`      | `float` | `30.0`                   | Request timeout in seconds         |
+| `max_retries`  | `int`   | `3`                      | Max retries for transient failures |
+
+### Environment Variables
+
+| Variable            | Description                                  |
+|---------------------|----------------------------------------------|
+| `CORTEXDB_API_KEY`  | Fallback API key when none is passed directly |
+
+## Convenience Methods
+
+| Method                | Description                                           |
+|-----------------------|-------------------------------------------------------|
+| `cortex.memory(q)`    | Alias for `recall()` -- the GTM one-liner             |
+| `cortex.store(data)`  | Smart dispatch: `str` -> `remember()`, `dict` -> `ingest_episode()` |
+| `cortex.context(q)`   | Recall with higher token budget (8192) for LLM agents |
+
+## Links
+
+- [Documentation](https://docs.cortexdb.io)
+- [GitHub Repository](https://github.com/cortexdb/cortexdb)
+- [Issue Tracker](https://github.com/cortexdb/cortexdb/issues)
+- [Changelog](https://github.com/cortexdb/cortexdb/blob/main/CHANGELOG.md)
+
+## License
+
+Apache-2.0

cortexdbai-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+cortexdb/__init__.py,sha256=LSlY8w1BUUlJsHxFly1AfnpQG_KplWZ08B11wh-kgHo,1616
+cortexdb/client.py,sha256=2wPZmzwyTgIN6indk2v2HHdrtjKTY0ZmZOgDTAqtzh8,32045
+cortexdb/exceptions.py,sha256=2ldGt_y3K2zx299VvNUVG_b9ZN0CXPbgOdJTaVnhScc,1991
+cortexdb/models.py,sha256=kG-us0qZSKBGZ0Oq8DXVXhq6y-sYvEWw8FdBlPDpTtY,9965
+cortexdb/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+cortexdbai-0.2.0.dist-info/METADATA,sha256=mYOFUmx_WBp1yhERLac-QA4TJ4ycx8NrMcvyDm9CjaA,7763
+cortexdbai-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+cortexdbai-0.2.0.dist-info/RECORD,,

cortexdbai-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any