Metadata-Version: 2.4
Name: cortexdbai
Version: 0.3.2
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
