cortexos 0.2.0__tar.gz

cortexos-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 CortexOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cortexos-0.2.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+recursive-include cortexos *.py *.tcss

cortexos-0.2.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: cortexos
+Version: 0.2.0
+Summary: CortexOS Python SDK — hallucination detection for LLM agents
+License: MIT
+Project-URL: Homepage, https://cortexa.ink
+Project-URL: Documentation, https://cortexa.ink/docs
+Project-URL: Repository, https://github.com/Tactacion/cortexos-sdk
+Project-URL: Bug Tracker, https://github.com/Tactacion/cortexos-sdk/issues
+Keywords: llm,memory,attribution,rag,ai,hallucination
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: tui
+Requires-Dist: textual<1,>=0.80; extra == "tui"
+Requires-Dist: httpx-sse<1,>=0.4; extra == "tui"
+Requires-Dist: click<9,>=8; extra == "tui"
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
+Requires-Dist: respx<1,>=0.21; extra == "dev"
+Dynamic: license-file
+
+# CortexOS Python SDK
+
+The official Python SDK for [Cortexa](https://cortexa.ink) — hallucination detection and verification for LLM agents.
+
+## Quickstart
+
+```bash
+pip install cortexos
+```
+
+```python
+import cortexos
+
+cortexos.configure(api_key="your-key")
+
+result = cortexos.check(
+    response="The return window is 30 days",
+    sources=["Return policy: 30-day window for all items."]
+)
+print(f"Hallucination Index: {result.hallucination_index}")
+# → Hallucination Index: 0.0
+```
+
+Get an API key at [cortexa.ink](https://cortexa.ink)
+
+## Installation
+
+```bash
+pip install cortexos
+```
+
+## Quick start
+
+```python
+from cortexos import Cortex
+
+cx = Cortex(api_key="sk-...", agent_id="support-bot")
+
+# Store a memory
+mem = cx.remember(
+    "User prefers email over Slack for all communications",
+    importance=0.85,
+    tags=["preferences", "communication"],
+    metadata={"source": "conversation_123"},
+)
+
+# Semantic recall
+results = cx.recall("how does the user want to be contacted?", top_k=5)
+for r in results:
+    print(f"[{r.score:.2f}] {r.memory.content}")
+
+# EAS attribution — score which memories contributed to your LLM response
+attr = cx.attribute(
+    query="How should I contact the user?",
+    response="Based on their preferences, contact them via email.",
+    memory_ids=[mem.id],
+)
+print(attr.scores)  # {"mem_xxx": 0.91}
+
+# Combined recall + attribution in one call
+result = cx.recall_and_attribute(
+    query="How should I reach the user?",
+    response="Contact via email.",
+    top_k=10,
+)
+```
+
+## Async usage
+
+```python
+import asyncio
+from cortexos import AsyncCortex
+
+async def main():
+    async with AsyncCortex(api_key="sk-...", agent_id="my-agent") as cx:
+        mem = await cx.remember("User lives in Tokyo", importance=0.7)
+        results = await cx.recall("where does the user live?")
+        await cx.forget(mem.id)
+
+asyncio.run(main())
+```
+
+## API reference
+
+### `Cortex` / `AsyncCortex`
+
+| Method | Description |
+|--------|-------------|
+| `remember(content, *, importance, tags, metadata, tier, ttl)` | Store a new memory |
+| `get(memory_id)` | Fetch a memory by ID |
+| `update(memory_id, *, importance, tags, metadata, tier)` | Update memory fields |
+| `forget(memory_id)` | Soft-delete a memory |
+| `list(*, limit, offset, tier, sort_by, order)` | Paginated memory listing |
+| `recall(query, *, top_k, min_score, tags)` | Semantic search |
+| `attribute(query, response, memory_ids)` | Run EAS attribution |
+| `recall_and_attribute(query, response, *, top_k, min_score)` | Recall + attribute |
+
+### Types
+
+- **`Memory`** — `id`, `content`, `agent_id`, `tier`, `importance`, `tags`, `metadata`, `retrieval_count`, `created_at`
+- **`RecallResult`** — `memory: Memory`, `score: float`
+- **`Attribution`** — `transaction_id`, `query`, `response`, `scores: dict[str, float]`
+- **`RecallAndAttributeResult`** — `memories: list[RecallResult]`, `attribution: Attribution`
+- **`Page`** — `items: list[Memory]`, `total`, `offset`, `limit`, `has_more`
+
+### Errors
+
+| Exception | When |
+|-----------|------|
+| `CortexError` | Base class for all SDK errors |
+| `AuthError` | Invalid or missing API key (401/403) |
+| `RateLimitError` | Too many requests (429); has `.retry_after` |
+| `MemoryNotFoundError` | Memory ID does not exist (404) |
+| `ValidationError` | Invalid request payload (422) |
+| `ServerError` | Unexpected 5xx from the server |
+
+## Configuration
+
+```python
+cx = Cortex(
+    agent_id="my-agent",
+    api_key="sk-...",           # Optional if server has no auth
+    base_url="https://api.cortexa.ink",
+    timeout=30.0,               # Per-request timeout (seconds)
+    max_retries=3,              # Retries on 429/502/503/504
+)
+```
+
+## Running tests
+
+```bash
+# Unit tests (no server required)
+pip install "cortexos[dev]"
+pytest tests/test_client.py -v
+
+# Integration tests (requires a running cortex-engine)
+pytest tests/test_integration.py -v
+```

cortexos-0.2.0/README.md

@@ -0,0 +1,138 @@
+# CortexOS Python SDK
+
+The official Python SDK for [Cortexa](https://cortexa.ink) — hallucination detection and verification for LLM agents.
+
+## Quickstart
+
+```bash
+pip install cortexos
+```
+
+```python
+import cortexos
+
+cortexos.configure(api_key="your-key")
+
+result = cortexos.check(
+    response="The return window is 30 days",
+    sources=["Return policy: 30-day window for all items."]
+)
+print(f"Hallucination Index: {result.hallucination_index}")
+# → Hallucination Index: 0.0
+```
+
+Get an API key at [cortexa.ink](https://cortexa.ink)
+
+## Installation
+
+```bash
+pip install cortexos
+```
+
+## Quick start
+
+```python
+from cortexos import Cortex
+
+cx = Cortex(api_key="sk-...", agent_id="support-bot")
+
+# Store a memory
+mem = cx.remember(
+    "User prefers email over Slack for all communications",
+    importance=0.85,
+    tags=["preferences", "communication"],
+    metadata={"source": "conversation_123"},
+)
+
+# Semantic recall
+results = cx.recall("how does the user want to be contacted?", top_k=5)
+for r in results:
+    print(f"[{r.score:.2f}] {r.memory.content}")
+
+# EAS attribution — score which memories contributed to your LLM response
+attr = cx.attribute(
+    query="How should I contact the user?",
+    response="Based on their preferences, contact them via email.",
+    memory_ids=[mem.id],
+)
+print(attr.scores)  # {"mem_xxx": 0.91}
+
+# Combined recall + attribution in one call
+result = cx.recall_and_attribute(
+    query="How should I reach the user?",
+    response="Contact via email.",
+    top_k=10,
+)
+```
+
+## Async usage
+
+```python
+import asyncio
+from cortexos import AsyncCortex
+
+async def main():
+    async with AsyncCortex(api_key="sk-...", agent_id="my-agent") as cx:
+        mem = await cx.remember("User lives in Tokyo", importance=0.7)
+        results = await cx.recall("where does the user live?")
+        await cx.forget(mem.id)
+
+asyncio.run(main())
+```
+
+## API reference
+
+### `Cortex` / `AsyncCortex`
+
+| Method | Description |
+|--------|-------------|
+| `remember(content, *, importance, tags, metadata, tier, ttl)` | Store a new memory |
+| `get(memory_id)` | Fetch a memory by ID |
+| `update(memory_id, *, importance, tags, metadata, tier)` | Update memory fields |
+| `forget(memory_id)` | Soft-delete a memory |
+| `list(*, limit, offset, tier, sort_by, order)` | Paginated memory listing |
+| `recall(query, *, top_k, min_score, tags)` | Semantic search |
+| `attribute(query, response, memory_ids)` | Run EAS attribution |
+| `recall_and_attribute(query, response, *, top_k, min_score)` | Recall + attribute |
+
+### Types
+
+- **`Memory`** — `id`, `content`, `agent_id`, `tier`, `importance`, `tags`, `metadata`, `retrieval_count`, `created_at`
+- **`RecallResult`** — `memory: Memory`, `score: float`
+- **`Attribution`** — `transaction_id`, `query`, `response`, `scores: dict[str, float]`
+- **`RecallAndAttributeResult`** — `memories: list[RecallResult]`, `attribution: Attribution`
+- **`Page`** — `items: list[Memory]`, `total`, `offset`, `limit`, `has_more`
+
+### Errors
+
+| Exception | When |
+|-----------|------|
+| `CortexError` | Base class for all SDK errors |
+| `AuthError` | Invalid or missing API key (401/403) |
+| `RateLimitError` | Too many requests (429); has `.retry_after` |
+| `MemoryNotFoundError` | Memory ID does not exist (404) |
+| `ValidationError` | Invalid request payload (422) |
+| `ServerError` | Unexpected 5xx from the server |
+
+## Configuration
+
+```python
+cx = Cortex(
+    agent_id="my-agent",
+    api_key="sk-...",           # Optional if server has no auth
+    base_url="https://api.cortexa.ink",
+    timeout=30.0,               # Per-request timeout (seconds)
+    max_retries=3,              # Retries on 429/502/503/504
+)
+```
+
+## Running tests
+
+```bash
+# Unit tests (no server required)
+pip install "cortexos[dev]"
+pytest tests/test_client.py -v
+
+# Integration tests (requires a running cortex-engine)
+pytest tests/test_integration.py -v
+```

cortexos-0.2.0/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-0.2.0/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)