Metadata-Version: 2.4
Name: quorex
Version: 0.1.0
Summary: Python SDK for the Quorex persistent memory engine.
Project-URL: Homepage, https://quorex.fr
Project-URL: Repository, https://github.com/quorex-ai/quorex-SDK
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"

# quorex

Official Python SDK for **Quorex** — the memory layer for AI agents.
Store, retrieve and inject persistent user context into any LLM in one call.

Requires Python 3.10+. One dependency: `httpx`.

## Install

```bash
pip install quorex
```

## Quickstart

```python
from quorex import Memory

qx = Memory(api_key="qx_live_...")  # or set QUOREX_API_KEY

# Store a memory for one of your end-users
qx.remember("user_123", "I switched to Vue.js, React feels too verbose")

# Recall the relevant context before calling your LLM
memories = qx.recall("user_123", "what framework does this user prefer?")
for m in memories:
    print(m.text, m.final_score)
```

Get your secret key from the [dashboard](https://quorex.fr) → API Keys.

## Client

```python
Memory(
    api_key=None,                     # or QUOREX_API_KEY env var
    base_url="https://api.quorex.fr", # default
    timeout=30.0,                     # seconds
)
```

`Memory` is an alias of `QuorexClient`. It can be used as a context manager
(`with Memory() as qx: ...`) to close the underlying HTTP client automatically.

## API

| Method | Description |
| --- | --- |
| `remember(user_id, text, *, action?, metadata?, timestamp?, ttl_days?)` | Store a memory → `StoreResult(vec_id)` |
| `recall(user_id, query, *, top_k?, threshold?)` | Ranked memories → `list[Memory]` |
| `explain(user_id, query, *, top_k?)` | Memories + score breakdown → `list[ExplainResult]` |
| `forget(user_id, vec_id)` | Delete one memory → `ForgetResult(deleted, vec_id)` |
| `purge(user_id)` | GDPR — delete all of a user's memories → `int` |
| `export(user_id)` | GDPR — export all data → `ExportResult` |
| `freeze(user_id)` | Stop temporal decay → `bool` |
| `stats(user_id=None)` | Usage stats for the key → `dict` |

### Examples

```python
r = qx.remember("user_123", "prefers dark mode", action="preference")
r.vec_id  # 42

explained = qx.explain("user_123", "ui preference?")
explained[0].explanation
explained[0].score_breakdown

qx.forget("user_123", vec_id=42)
removed = qx.purge("user_123")     # int
data = qx.export("user_123")       # ExportResult
qx.freeze("user_123")              # bool
usage = qx.stats()                 # dict
```

## Errors

All errors extend `QuorexError` (which carries a `status_code`). Catch the
specific type you care about:

```python
from quorex import Memory, AuthenticationError, QuorexError

qx = Memory()
try:
    qx.recall("user_123", "...")
except AuthenticationError:
    print("Check your API key")
except QuorexError as e:
    print("Quorex error:", e)
```

`AuthenticationError` (401) · `NotFoundError` (404) · `RateLimitError` (429) · `ServerError` (5xx).

## Develop

```bash
pip install -e ".[dev]"   # install in editable mode + test deps
pytest                    # run the offline unit tests
python examples/e2e.py    # run a real end-to-end check (needs QUOREX_API_KEY)
```

## License

MIT
