cortexdbai 0.3.0__tar.gz → 0.3.1__tar.gz

{cortexdbai-0.3.0 → cortexdbai-0.3.1}/.gitignore

@@ -69,3 +69,11 @@ dist/
 # Scratch/debug text files at root
 /*.txt
 /*.log
+
+# Local debug / marketing / private content (not for repo)
+harness/.reports/
+harness_data_*/
+blog/
+sales/
+videos/
+local-instance/

cortexdbai-0.3.1/PKG-INFO

@@ -0,0 +1,175 @@
+Metadata-Version: 2.4
+Name: cortexdbai
+Version: 0.3.1
+Summary: The Long-Term Memory Layer for AI Systems
+Project-URL: Homepage, https://cortexdb.ai
+Project-URL: Documentation, https://docs.cortexdb.ai
+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.ai>
+License-Expression: Apache-2.0
+Keywords: ai,cortexdb,event-sourcing,knowledge-graph,llm,memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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.10
+Requires-Dist: httpx>=0.24
+Requires-Dist: pydantic>=2.0
+Requires-Dist: requests>=2.31
+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, structured memory. Capture experiences, then recall a stratified pack (events, facts, beliefs, episodes, concepts) or get a grounded answer — all scoped to a hierarchical `scope` path.
+
+[![PyPI version](https://img.shields.io/pypi/v/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
+[![Python](https://img.shields.io/pypi/pyversions/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/cortexdb/cortexdb/blob/main/LICENSE)
+
+This SDK targets the **v1 API** (`/v1/experience`, `/v1/recall`, `/v1/answer`, …), PASETO auth, and hierarchical scopes. The pre-0.3 `remember()`/`tenant_id` client was retired — `Cortex` is now an alias of `V1Client`.
+
+## Installation
+
+```bash
+pip install cortexdbai
+```
+
+## Quick start
+
+```python
+from cortexdb import Cortex
+
+# Local `docker run` with auth disabled (CORTEX_API_KEY unset on the server):
+with Cortex("http://localhost:3141") as c:
+    c.experience("ws:demo", text="Priya at Acme signed for 200 seats. Q3 close.")
+    pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
+    print(pack["context_block"])
+```
+
+### Hosted / multi-tenant (PASETO bearer + actor)
+
+```python
+with Cortex(
+    "https://api-v1.cortexdb.ai",
+    actor="user:alice",
+    bearer="v4.public…",          # PASETO v4 public or JWT (RS256/ES256)
+) as c:
+    out = c.answer(
+        "org:initech/user:alice",
+        "What did Alice say about coffee?",
+    )
+    print(out["answer"])
+```
+
+### One-call signup (no prior credentials)
+
+```python
+from cortexdb import Cortex
+
+c = Cortex.signup()                      # POST /v1/auth/signup → free-tier PASETO
+c.experience(c.actor, text="hello, memory!")
+print(c.recall(c.actor, query="what did I say?")["context_block"])
+```
+
+## Core operations
+
+```python
+# Write — async by default (202); pass wait= for synchronous indexing.
+c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.")
+c.experience("ws:demo", text="Rolled back auth-gateway.", wait="indexed")
+
+# Recall — returns a StratifiedPack { context_block, layers, provenance }.
+pack = c.recall("ws:demo", query="recent deploys", view="holistic")
+
+# Answer — recall + LLM render with citations.
+ans = c.answer("ws:demo", "What changed in payments recently?")
+
+# Forget — GDPR erasure. confirm_all wipes the whole scope.
+c.forget("ws:demo", confirm_all=True, cascade="redact_events",
+         audit_note="GDPR Article 17 request")
+
+# Layer reads (paginated { items, has_more }).
+c.events("ws:demo")
+c.facts("ws:demo")
+c.beliefs("ws:demo")
+c.episodes("ws:demo")
+c.understanding("ws:demo")
+```
+
+## Async usage
+
+`AsyncCortex` mirrors every method:
+
+```python
+import asyncio
+from cortexdb import AsyncCortex
+
+async def main():
+    async with AsyncCortex("http://localhost:3141") as c:
+        await c.experience("ws:demo", text="async memory works great")
+        pack = await c.recall("ws:demo", query="what works?")
+        print(pack["context_block"])
+
+asyncio.run(main())
+```
+
+## Error handling
+
+```python
+from cortexdb import (
+    Cortex,
+    V1Error,             # base
+    V1APIError,          # non-2xx envelope
+    V1AuthError,         # 401 / actor mismatch
+    V1PolicyDeniedError, # 403 — missing capability
+    V1RateLimitError,    # 429 (carries retry_after)
+    V1NotConfiguredError,# 503 — feature not configured
+    V1ConnectionError,
+    V1TimeoutError,
+)
+
+with Cortex("http://localhost:3141") as c:
+    try:
+        c.experience("ws:demo", text="important data")
+    except V1RateLimitError as e:
+        print(f"rate limited; retry after {e.retry_after}s")
+    except V1PolicyDeniedError as e:
+        print(f"missing capability: {e}")
+    except V1APIError as e:
+        print(f"API error [{e.status_code}]: {e}")
+```
+
+## Constructor
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_url` | `str` | `http://localhost:3141` | CortexDB v1 surface URL |
+| `actor` | `str` | `user:default` | Sent as `X-Cortex-Actor`; must match the token subject when authed |
+| `bearer` | `str \| None` | `None` | PASETO v4 public / JWT bearer (omit for auth-disabled dev) |
+| `timeout` | `float` | `30.0` | Request timeout (seconds) |
+
+## Links
+
+- [Documentation](https://docs.cortexdb.ai)
+- [Issue Tracker](https://github.com/cortexdb/cortexdb/issues)
+
+## License
+
+Apache-2.0

cortexdbai-0.3.1/README.md

@@ -0,0 +1,140 @@
+# CortexDB Python SDK
+
+**The Long-Term Memory Layer for AI Systems.**
+
+CortexDB gives your AI agents persistent, structured memory. Capture experiences, then recall a stratified pack (events, facts, beliefs, episodes, concepts) or get a grounded answer — all scoped to a hierarchical `scope` path.
+
+[![PyPI version](https://img.shields.io/pypi/v/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
+[![Python](https://img.shields.io/pypi/pyversions/cortexdbai.svg)](https://pypi.org/project/cortexdbai/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/cortexdb/cortexdb/blob/main/LICENSE)
+
+This SDK targets the **v1 API** (`/v1/experience`, `/v1/recall`, `/v1/answer`, …), PASETO auth, and hierarchical scopes. The pre-0.3 `remember()`/`tenant_id` client was retired — `Cortex` is now an alias of `V1Client`.
+
+## Installation
+
+```bash
+pip install cortexdbai
+```
+
+## Quick start
+
+```python
+from cortexdb import Cortex
+
+# Local `docker run` with auth disabled (CORTEX_API_KEY unset on the server):
+with Cortex("http://localhost:3141") as c:
+    c.experience("ws:demo", text="Priya at Acme signed for 200 seats. Q3 close.")
+    pack = c.recall("ws:demo", query="How many seats did Acme sign for?")
+    print(pack["context_block"])
+```
+
+### Hosted / multi-tenant (PASETO bearer + actor)
+
+```python
+with Cortex(
+    "https://api-v1.cortexdb.ai",
+    actor="user:alice",
+    bearer="v4.public…",          # PASETO v4 public or JWT (RS256/ES256)
+) as c:
+    out = c.answer(
+        "org:initech/user:alice",
+        "What did Alice say about coffee?",
+    )
+    print(out["answer"])
+```
+
+### One-call signup (no prior credentials)
+
+```python
+from cortexdb import Cortex
+
+c = Cortex.signup()                      # POST /v1/auth/signup → free-tier PASETO
+c.experience(c.actor, text="hello, memory!")
+print(c.recall(c.actor, query="what did I say?")["context_block"])
+```
+
+## Core operations
+
+```python
+# Write — async by default (202); pass wait= for synchronous indexing.
+c.experience("ws:demo", text="Deployed payments-service v3.1 to prod.")
+c.experience("ws:demo", text="Rolled back auth-gateway.", wait="indexed")
+
+# Recall — returns a StratifiedPack { context_block, layers, provenance }.
+pack = c.recall("ws:demo", query="recent deploys", view="holistic")
+
+# Answer — recall + LLM render with citations.
+ans = c.answer("ws:demo", "What changed in payments recently?")
+
+# Forget — GDPR erasure. confirm_all wipes the whole scope.
+c.forget("ws:demo", confirm_all=True, cascade="redact_events",
+         audit_note="GDPR Article 17 request")
+
+# Layer reads (paginated { items, has_more }).
+c.events("ws:demo")
+c.facts("ws:demo")
+c.beliefs("ws:demo")
+c.episodes("ws:demo")
+c.understanding("ws:demo")
+```
+
+## Async usage
+
+`AsyncCortex` mirrors every method:
+
+```python
+import asyncio
+from cortexdb import AsyncCortex
+
+async def main():
+    async with AsyncCortex("http://localhost:3141") as c:
+        await c.experience("ws:demo", text="async memory works great")
+        pack = await c.recall("ws:demo", query="what works?")
+        print(pack["context_block"])
+
+asyncio.run(main())
+```
+
+## Error handling
+
+```python
+from cortexdb import (
+    Cortex,
+    V1Error,             # base
+    V1APIError,          # non-2xx envelope
+    V1AuthError,         # 401 / actor mismatch
+    V1PolicyDeniedError, # 403 — missing capability
+    V1RateLimitError,    # 429 (carries retry_after)
+    V1NotConfiguredError,# 503 — feature not configured
+    V1ConnectionError,
+    V1TimeoutError,
+)
+
+with Cortex("http://localhost:3141") as c:
+    try:
+        c.experience("ws:demo", text="important data")
+    except V1RateLimitError as e:
+        print(f"rate limited; retry after {e.retry_after}s")
+    except V1PolicyDeniedError as e:
+        print(f"missing capability: {e}")
+    except V1APIError as e:
+        print(f"API error [{e.status_code}]: {e}")
+```
+
+## Constructor
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `api_url` | `str` | `http://localhost:3141` | CortexDB v1 surface URL |
+| `actor` | `str` | `user:default` | Sent as `X-Cortex-Actor`; must match the token subject when authed |
+| `bearer` | `str \| None` | `None` | PASETO v4 public / JWT bearer (omit for auth-disabled dev) |
+| `timeout` | `float` | `30.0` | Request timeout (seconds) |
+
+## Links
+
+- [Documentation](https://docs.cortexdb.ai)
+- [Issue Tracker](https://github.com/cortexdb/cortexdb/issues)
+
+## License
+
+Apache-2.0

{cortexdbai-0.3.0 → cortexdbai-0.3.1}/cortexdb/__init__.py

@@ -16,7 +16,7 @@ Quick start::
 
     # Hosted / multi-tenant deployment with PASETO bearer + actor header:
     with Cortex(
-        "https://api.cortexdb.ai",
+        "https://api-v1.cortexdb.ai",
         actor="user:alice",
         bearer="eyJ...",
     ) as c:
@@ -49,7 +49,7 @@ from cortexdb import v1  # the explicit submodule namespace
 Cortex = V1Client
 AsyncCortex = AsyncV1Client
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"
 __all__ = [
     # Clients (preferred top-level names)
     "Cortex",

{cortexdbai-0.3.0 → cortexdbai-0.3.1}/cortexdb/v1/__init__.py

@@ -12,7 +12,7 @@ Quick start:
     from cortexdb.v1 import V1Client
 
     client = V1Client(
-        api_url="https://api.cortexdb.ai",  # or http://localhost:3142 for v1 surface
+        api_url="https://api-v1.cortexdb.ai",  # or http://localhost:3142 for v1 surface
         actor="user:alice",
         bearer="eyJ...",  # PASETO v4 public or JWT (RS256/ES256)
     )

{cortexdbai-0.3.0 → cortexdbai-0.3.1}/cortexdb/v1/client.py

@@ -323,9 +323,21 @@ class V1Client:
         answer_max_tokens: Optional[int] = None,
         use_pack_id: Optional[str] = None,
         temporal: Optional[Mapping[str, Any]] = None,
+        diagnostics: str = "none",
     ) -> dict:
-        """``POST /v1/answer`` — runs recall + LLM render."""
-        body: dict = {"scope": scope, "view": view, "question": question}
+        """``POST /v1/answer`` — runs recall + LLM render.
+
+        ``diagnostics`` matches the semantics of :meth:`recall` (audit FRI-1):
+        defaults to ``"none"`` so free-tier tokens don't hit the
+        ``diagnostics.read`` gate. Pass ``"summary"`` or ``"full"`` when
+        you hold the elevated capability.
+        """
+        body: dict = {
+            "scope": scope,
+            "view": view,
+            "question": question,
+            "diagnostics": diagnostics,
+        }
         if question_type:
             body["question_type"] = question_type
         if question_date:
@@ -656,8 +668,16 @@ class AsyncV1Client:
         question_type: Optional[str] = None,
         question_date: Optional[str] = None,
         view: str = "holistic",
+        diagnostics: str = "none",
     ) -> dict:
-        body: dict = {"scope": scope, "view": view, "question": question}
+        """``POST /v1/answer``. ``diagnostics`` defaults to ``"none"`` so
+        free-tier tokens succeed (audit FRI-1)."""
+        body: dict = {
+            "scope": scope,
+            "view": view,
+            "question": question,
+            "diagnostics": diagnostics,
+        }
         if question_type:
             body["question_type"] = question_type
         if question_date:

{cortexdbai-0.3.0 → cortexdbai-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cortexdbai"
-version = "0.3.0"
+version = "0.3.1"
 description = "The Long-Term Memory Layer for AI Systems"
 readme = "README.md"
 license = "Apache-2.0"

cortexdbai-0.3.0/PKG-INFO

@@ -1,235 +0,0 @@
-Metadata-Version: 2.4
-Name: cortexdbai
-Version: 0.3.0
-Summary: The Long-Term Memory Layer for AI Systems
-Project-URL: Homepage, https://cortexdb.ai
-Project-URL: Documentation, https://docs.cortexdb.ai
-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.ai>
-License-Expression: Apache-2.0
-Keywords: ai,cortexdb,event-sourcing,knowledge-graph,llm,memory
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-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.10
-Requires-Dist: httpx>=0.24
-Requires-Dist: pydantic>=2.0
-Requires-Dist: requests>=2.31
-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/cortexdbai/)
-[![Python](https://img.shields.io/pypi/pyversions/cortexdb.svg)](https://pypi.org/project/cortexdbai/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/cortexdb/cortexdb/blob/main/LICENSE)
-
-## Installation
-
-```bash
-pip install cortexdbai
-```
-
-For HTTP/2 support (recommended for async workloads):
-
-```bash
-pip install cortexdbai[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.ai)
-- [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.3.0/README.md

@@ -1,200 +0,0 @@
-# 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/cortexdbai/)
-[![Python](https://img.shields.io/pypi/pyversions/cortexdb.svg)](https://pypi.org/project/cortexdbai/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/cortexdb/cortexdb/blob/main/LICENSE)
-
-## Installation
-
-```bash
-pip install cortexdbai
-```
-
-For HTTP/2 support (recommended for async workloads):
-
-```bash
-pip install cortexdbai[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.ai)
-- [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