cortexos 0.2.0__py3-none-any.whl

cortexos/__init__.py

@@ -0,0 +1,64 @@
+"""CortexOS Python SDK — developer-facing interface to the CortexOS memory engine."""
+
+from cortexos.async_client import AsyncCortex
+from cortexos.client import Cortex
+from cortexos.errors import (
+    AuthError,
+    CortexError,
+    MemoryNotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+from cortexos.exceptions import CortexOSError, MemoryBlockedError
+from cortexos.models import CheckResult, ClaimResult, GateResult, ShieldResult
+from cortexos.types import (
+    Attribution,
+    CAMAAttribution,
+    CAMAClaim,
+    CAMAClaimSource,
+    EASScore,
+    Memory,
+    Page,
+    RecallAndAttributeResult,
+    RecallResult,
+)
+from cortexos.verification import VerificationClient
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("cortexos")
+except PackageNotFoundError:
+    __version__ = "0.2.0"  # fallback for editable installs
+
+__all__ = [
+    # Clients
+    "Cortex",
+    "AsyncCortex",
+    "VerificationClient",
+    # Types
+    "Memory",
+    "Attribution",
+    "CAMAAttribution",
+    "CAMAClaim",
+    "CAMAClaimSource",
+    "EASScore",
+    "RecallResult",
+    "RecallAndAttributeResult",
+    "Page",
+    # Verification models
+    "CheckResult",
+    "ClaimResult",
+    "GateResult",
+    "ShieldResult",
+    # Errors
+    "CortexError",
+    "CortexOSError",
+    "MemoryBlockedError",
+    "AuthError",
+    "RateLimitError",
+    "MemoryNotFoundError",
+    "ValidationError",
+    "ServerError",
+]

cortexos/_http.py

@@ -0,0 +1,206 @@
+"""Internal HTTP layer — sync and async httpx clients with retry and auth."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import httpx
+
+from cortexos.errors import (
+    AuthError,
+    CortexError,
+    MemoryNotFoundError,
+    RateLimitError,
+    ServerError,
+    ValidationError,
+)
+
+_DEFAULT_RETRIES = 3
+_RETRY_STATUSES = {429, 502, 503, 504}
+_BACKOFF_BASE = 0.5  # seconds
+
+
+def _build_headers(api_key: str | None) -> dict[str, str]:
+    headers: dict[str, str] = {"Content-Type": "application/json"}
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def _raise_for_status(resp: httpx.Response, memory_id: str | None = None) -> None:
+    if resp.status_code < 400:
+        return
+    body = resp.text
+
+    if resp.status_code == 401 or resp.status_code == 403:
+        raise AuthError("Invalid or missing API key", status_code=resp.status_code, response_body=body)
+
+    if resp.status_code == 404:
+        if memory_id:
+            raise MemoryNotFoundError(memory_id)
+        raise CortexError("Resource not found", status_code=404, response_body=body)
+
+    if resp.status_code == 422:
+        raise ValidationError(f"Validation error: {body[:300]}", status_code=422, response_body=body)
+
+    if resp.status_code == 429:
+        retry_after: float | None = None
+        try:
+            retry_after = float(resp.headers.get("Retry-After", ""))
+        except (ValueError, TypeError):
+            pass
+        raise RateLimitError(retry_after=retry_after, status_code=429, response_body=body)
+
+    if resp.status_code >= 500:
+        raise ServerError(f"Server error {resp.status_code}: {body[:300]}", status_code=resp.status_code, response_body=body)
+
+    raise CortexError(f"Unexpected HTTP {resp.status_code}: {body[:300]}", status_code=resp.status_code, response_body=body)
+
+
+# ── Sync HTTP client ───────────────────────────────────────────────────────
+
+
+class SyncHTTP:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None,
+        timeout: float,
+        max_retries: int,
+    ):
+        self._client = httpx.Client(
+            base_url=base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+        self._max_retries = max_retries
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "SyncHTTP":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        memory_id: str | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries):
+            try:
+                resp = self._client.request(method, path, **kwargs)
+                if resp.status_code in _RETRY_STATUSES and attempt < self._max_retries - 1:
+                    time.sleep(_BACKOFF_BASE * (2 ** attempt))
+                    continue
+                _raise_for_status(resp, memory_id=memory_id)
+                return resp
+            except (AuthError, MemoryNotFoundError, ValidationError):
+                raise  # Never retry these
+            except (RateLimitError, ServerError, CortexError) as exc:
+                last_exc = exc
+                if attempt < self._max_retries - 1:
+                    time.sleep(_BACKOFF_BASE * (2 ** attempt))
+            except httpx.TimeoutException as exc:
+                last_exc = CortexError(f"Request timed out: {exc}")
+                if attempt < self._max_retries - 1:
+                    time.sleep(_BACKOFF_BASE * (2 ** attempt))
+            except httpx.RequestError as exc:
+                last_exc = CortexError(f"Connection error: {exc}")
+                if attempt < self._max_retries - 1:
+                    time.sleep(_BACKOFF_BASE * (2 ** attempt))
+        raise last_exc or CortexError("Request failed after retries")
+
+    def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("GET", path, **kwargs)
+
+    def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("POST", path, **kwargs)
+
+    def patch(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("PATCH", path, **kwargs)
+
+    def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return self.request("DELETE", path, **kwargs)
+
+
+# ── Async HTTP client ──────────────────────────────────────────────────────
+
+
+class AsyncHTTP:
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None,
+        timeout: float,
+        max_retries: int,
+    ):
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            headers=_build_headers(api_key),
+            timeout=timeout,
+        )
+        self._max_retries = max_retries
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncHTTP":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        memory_id: str | None = None,
+        **kwargs: Any,
+    ) -> httpx.Response:
+        import asyncio
+
+        last_exc: Exception | None = None
+        for attempt in range(self._max_retries):
+            try:
+                resp = await self._client.request(method, path, **kwargs)
+                if resp.status_code in _RETRY_STATUSES and attempt < self._max_retries - 1:
+                    await asyncio.sleep(_BACKOFF_BASE * (2 ** attempt))
+                    continue
+                _raise_for_status(resp, memory_id=memory_id)
+                return resp
+            except (AuthError, MemoryNotFoundError, ValidationError):
+                raise
+            except (RateLimitError, ServerError, CortexError) as exc:
+                last_exc = exc
+                if attempt < self._max_retries - 1:
+                    await asyncio.sleep(_BACKOFF_BASE * (2 ** attempt))
+            except httpx.TimeoutException as exc:
+                last_exc = CortexError(f"Request timed out: {exc}")
+                if attempt < self._max_retries - 1:
+                    await asyncio.sleep(_BACKOFF_BASE * (2 ** attempt))
+            except httpx.RequestError as exc:
+                last_exc = CortexError(f"Connection error: {exc}")
+                if attempt < self._max_retries - 1:
+                    await asyncio.sleep(_BACKOFF_BASE * (2 ** attempt))
+        raise last_exc or CortexError("Request failed after retries")
+
+    async def get(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("GET", path, **kwargs)
+
+    async def post(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("POST", path, **kwargs)
+
+    async def patch(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("PATCH", path, **kwargs)
+
+    async def delete(self, path: str, **kwargs: Any) -> httpx.Response:
+        return await self.request("DELETE", path, **kwargs)

cortexos/async_client.py

@@ -0,0 +1,254 @@
+"""Asynchronous CortexOS client — same interface as Cortex but fully async."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cortexos._http import AsyncHTTP
+from cortexos.client import _memory_payload, _DEFAULT_BASE_URL, _API_PREFIX, _DEFAULT_TIMEOUT, _DEFAULT_RETRIES
+from cortexos.types import Attribution, CAMAAttribution, Memory, Page, RecallAndAttributeResult, RecallResult
+
+
+class AsyncCortex:
+    """
+    Asynchronous CortexOS SDK client.
+
+    Usage::
+
+        from cortexos import AsyncCortex
+
+        async with AsyncCortex(api_key="sk-...", agent_id="my-agent") as cx:
+            mem = await cx.remember("User prefers dark mode", importance=0.8)
+            results = await cx.recall("UI preferences?", top_k=5)
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        api_key: str | None = None,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_RETRIES,
+    ):
+        """
+        Args:
+            agent_id:    The default agent namespace for all operations.
+            api_key:     Bearer token sent as ``Authorization: Bearer <key>``.
+            base_url:    Root URL of the CortexOS engine.
+            timeout:     Per-request timeout in seconds.
+            max_retries: Number of retry attempts on transient errors.
+        """
+        self.agent_id = agent_id
+        self._http = AsyncHTTP(base_url, api_key, timeout, max_retries)
+        self._prefix = _API_PREFIX
+
+    # ── Context manager support ────────────────────────────────────────────
+
+    async def __aenter__(self) -> "AsyncCortex":
+        return self
+
+    async def __aexit__(self, *_: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Close the underlying async HTTP connection pool."""
+        await self._http.aclose()
+
+    # ── Memory CRUD ────────────────────────────────────────────────────────
+
+    async def remember(
+        self,
+        content: str,
+        *,
+        importance: float = 0.5,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        tier: str = "warm",
+        ttl: int | None = None,
+        agent_id: str | None = None,
+    ) -> Memory:
+        """Store a new memory. See :meth:`~cortexos.Cortex.remember` for full docs."""
+        payload = _memory_payload(
+            content=content,
+            agent_id=agent_id or self.agent_id,
+            importance=importance,
+            tags=tags or [],
+            metadata=metadata or {},
+            tier=tier,
+            ttl=ttl,
+        )
+        resp = await self._http.post(f"{self._prefix}/memories", json=payload)
+        return Memory._from_api(resp.json())
+
+    async def get(self, memory_id: str) -> Memory:
+        """Fetch a memory by ID. Raises :class:`~cortexos.errors.MemoryNotFoundError` if missing."""
+        resp = await self._http.get(
+            f"{self._prefix}/memories/{memory_id}",
+            memory_id=memory_id,
+        )
+        return Memory._from_api(resp.json()["memory"])
+
+    async def update(
+        self,
+        memory_id: str,
+        *,
+        importance: float | None = None,
+        tags: list[str] | None = None,
+        metadata: dict[str, Any] | None = None,
+        tier: str | None = None,
+    ) -> Memory:
+        """Update memory fields. See :meth:`~cortexos.Cortex.update` for full docs."""
+        values: dict[str, Any] = {}
+        if importance is not None:
+            values["criticality"] = importance
+        if tier is not None:
+            values["tier"] = tier
+        if tags is not None or metadata is not None:
+            current = await self.get(memory_id)
+            merged_meta = dict(current.metadata)
+            if tags is not None:
+                merged_meta["_tags"] = tags
+            if metadata is not None:
+                merged_meta.update(metadata)
+            values["metadata"] = merged_meta
+        resp = await self._http.patch(
+            f"{self._prefix}/memories/{memory_id}",
+            json=values,
+            memory_id=memory_id,
+        )
+        return Memory._from_api(resp.json())
+
+    async def forget(self, memory_id: str) -> None:
+        """Soft-delete a memory. Raises :class:`~cortexos.errors.MemoryNotFoundError` if missing."""
+        await self._http.delete(
+            f"{self._prefix}/memories/{memory_id}",
+            memory_id=memory_id,
+        )
+
+    async def list(
+        self,
+        *,
+        limit: int = 50,
+        offset: int = 0,
+        tier: str | None = None,
+        sort_by: str = "created_at",
+        order: str = "desc",
+        agent_id: str | None = None,
+    ) -> Page:
+        """List memories with pagination. See :meth:`~cortexos.Cortex.list` for full docs."""
+        params: dict[str, Any] = {
+            "agent_id": agent_id or self.agent_id,
+            "limit": limit,
+            "offset": offset,
+            "sort_by": sort_by,
+            "order": order,
+        }
+        if tier is not None:
+            params["tier"] = tier
+        resp = await self._http.get(f"{self._prefix}/memories", params=params)
+        data = resp.json()
+        return Page(
+            items=[Memory._from_api(m) for m in data["items"]],
+            total=data["total"],
+            offset=data["offset"],
+            limit=data["limit"],
+        )
+
+    # ── Recall ─────────────────────────────────────────────────────────────
+
+    async def recall(
+        self,
+        query: str,
+        *,
+        top_k: int = 10,
+        min_score: float = 0.0,
+        tags: list[str] | None = None,
+        agent_id: str | None = None,
+    ) -> list[RecallResult]:
+        """Semantic search. See :meth:`~cortexos.Cortex.recall` for full docs."""
+        params: dict[str, Any] = {
+            "q": query,
+            "agent_id": agent_id or self.agent_id,
+            "top_k": top_k,
+        }
+        resp = await self._http.get(f"{self._prefix}/memories/search", params=params)
+        results = [
+            RecallResult(memory=Memory._from_api(item["memory"]), score=item["similarity"])
+            for item in resp.json()
+            if item["similarity"] >= min_score
+        ]
+        if tags:
+            tag_set = set(tags)
+            results = [r for r in results if tag_set.intersection(r.memory.tags)]
+        return results
+
+    # ── Attribution ─────────────────────────────────────────────────────────
+
+    async def attribute(
+        self,
+        query: str,
+        response: str,
+        memory_ids: list[str],
+        *,
+        agent_id: str | None = None,
+    ) -> Attribution:
+        """Run EAS attribution. See :meth:`~cortexos.Cortex.attribute` for full docs."""
+        payload = {
+            "query_text": query,
+            "response_text": response,
+            "retrieved_memory_ids": memory_ids,
+            "agent_id": agent_id or self.agent_id,
+        }
+        resp = await self._http.post(f"{self._prefix}/transactions", json=payload)
+        return Attribution._from_api(resp.json(), query=query, response=response)
+
+    async def cama_attribute(
+        self,
+        transaction_id: str,
+    ) -> CAMAAttribution:
+        """Run CAMA attribution on an existing transaction.
+
+        See :meth:`~cortexos.Cortex.cama_attribute` for full docs.
+        """
+        resp = await self._http.post(f"{self._prefix}/attribution/{transaction_id}/cama")
+        return CAMAAttribution._from_api(resp.json(), transaction_id=transaction_id)
+
+    async def check(
+        self,
+        query: str,
+        response: str,
+        memory_ids: list[str],
+        *,
+        agent_id: str | None = None,
+    ) -> CAMAAttribution:
+        """One-shot hallucination check. See :meth:`~cortexos.Cortex.check` for full docs."""
+        attr = await self.attribute(query, response, memory_ids, agent_id=agent_id)
+        return await self.cama_attribute(attr.transaction_id)
+
+    async def forget_all(self, *, agent_id: str | None = None) -> int:
+        """Delete all memories for the given agent. Returns count deleted."""
+        count = 0
+        while True:
+            page = await self.list(agent_id=agent_id, limit=50, offset=0)
+            if not page.items:
+                break
+            for mem in page.items:
+                await self.forget(mem.id)
+                count += 1
+        return count
+
+    async def recall_and_attribute(
+        self,
+        query: str,
+        response: str,
+        *,
+        top_k: int = 10,
+        min_score: float = 0.0,
+        agent_id: str | None = None,
+    ) -> RecallAndAttributeResult:
+        """Recall then attribute. See :meth:`~cortexos.Cortex.recall_and_attribute` for full docs."""
+        aid = agent_id or self.agent_id
+        recall_results = await self.recall(query, top_k=top_k, min_score=min_score, agent_id=aid)
+        memory_ids = [r.memory.id for r in recall_results]
+        attribution = await self.attribute(query, response, memory_ids, agent_id=aid)
+        return RecallAndAttributeResult(memories=recall_results, attribution=attribution)