cortexdbai 0.2.0__tar.gz → 0.2.2__tar.gz

cortexdbai-0.2.2/.gitignore

@@ -0,0 +1,71 @@
+# Rust
+/target
+**/*.rs.bk
+
+# Environment / secrets
+.env
+.env.local
+.env*.local
+*.pem
+*.key
+.npmrc
+
+# SQLite database
+*.sqlite
+*.sqlite-wal
+*.sqlite-shm
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Data directories
+cortexdb_data*/
+/data/
+# Per-bench tenant stores (RocksDB + Tantivy + HNSW state; regeneratable per run)
+/data_*/
+# Experimental per-branch stores (not tracked on this branch but left gitignored
+# so checkout from other branches doesn't surface them in git status)
+/event_memory_store/
+/llm_cache/
+
+# Benchmark inputs and per-run outputs (kept local, regenerated each run)
+benchmarks/longmemeval/data/
+benchmarks/longmemeval/server_results/
+benchmarks/longmemeval/fast_results/
+benchmarks/longmemeval/micro_results/
+benchmarks/longmemeval/server_logs/
+benchmarks/longmemeval/*.log
+benchmarks/locomo/locomo_results*.json
+benchmarks/locomo/server_results/
+benchmarks/locomo/*.log
+/answer_out.json
+
+# Local Claude Code state
+.claude/
+.tmp/
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+venv/
+
+# Node
+node_modules/
+dist/
+.next/
+
+# Egg info
+*.egg-info/
+
+# Scratch/debug text files at root
+/*.txt
+/*.log

{cortexdbai-0.2.0 → cortexdbai-0.2.2}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: cortexdbai
-Version: 0.2.0
+Version: 0.2.2
 Summary: The Long-Term Memory Layer for AI Systems
-Project-URL: Homepage, https://cortexdb.io
-Project-URL: Documentation, https://docs.cortexdb.io
+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.io>
+Author-email: Prashant Malik <prashant@cortexdb.ai>
 License-Expression: Apache-2.0
 Keywords: ai,cortexdb,event-sourcing,knowledge-graph,llm,memory
 Classifier: Development Status :: 3 - Alpha
@@ -40,20 +40,20 @@ Description-Content-Type: text/markdown
 
 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/)
+[![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 cortexdb
+pip install cortexdbai
 ```
 
 For HTTP/2 support (recommended for async workloads):
 
 ```bash
-pip install cortexdb[async]
+pip install cortexdbai[async]
 ```
 
 ## Quick Start
@@ -226,7 +226,7 @@ cortex = Cortex(
 
 ## Links
 
-- [Documentation](https://docs.cortexdb.io)
+- [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)

{cortexdbai-0.2.0 → cortexdbai-0.2.2}/README.md

@@ -1,200 +1,200 @@
-# 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
+# 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