Metadata-Version: 2.4
Name: praqtordb-apps
Version: 0.1.0
Summary: Python SDK for PraqtorDB for Apps — per-user memory, knowledge graph, and Deep Memory for your application's end users.
Author: PraqtorDB
License: Proprietary
Project-URL: Homepage, https://www.praqtordb.com/for-apps.html
Project-URL: Repository, https://github.com/AiStyl/PraqtorDB-for-Apps
Project-URL: Documentation, https://github.com/AiStyl/PraqtorDB-for-Apps/blob/main/sdk/python/README.md
Project-URL: Issues, https://github.com/AiStyl/PraqtorDB-for-Apps/issues
Keywords: memory,llm,ai,agents,knowledge-graph,rag,chatbot
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24

# PraqtorDB for Apps — Python SDK

Give your application's end users **persistent, isolated memory** — a per-user knowledge
graph and AI-generated Deep Memory briefing — over two HTTP calls. This SDK wraps the
PraqtorDB for Apps data-plane API (`/v1`).

## Install

```bash
pip install -e sdk/python      # local/dev (from this repo)
# pip install praqtordb-apps   # once published
```

## Quickstart

```python
from praqtordb_apps import Client

c = Client(api_key="pk_live_...")          # your app's secret key
c.add(end_user_id="sarah", text="On the Pro plan at Acme.")
print(c.search(query="plan", end_user_id="sarah"))
```

That's it — the memory is chunked, embedded, and auto-extracted into notes, entities,
and a Deep Memory briefing for `sarah`, isolated from every other user in your app.

## Configuration

```python
Client(api_key="pk_live_...", base_url="https://praqtordb-for-apps.fly.dev", timeout=30.0)
```

- `api_key` — your app's secret key (sent as the `X-API-Key` header). Required.
- `base_url` — the API host. Defaults to the hosted API; override for self-hosted/staging.

## Methods

| Method | Endpoint | Description |
|---|---|---|
| `add(end_user_id, text, source_type="chat")` | `POST /v1/memory` | Store a memory for one user. |
| `search(query, end_user_id=None, limit=10)` | `POST /v1/search` | 3-layer retrieval (semantic + keyword + graph), RRF-fused. Omit `end_user_id` to search the whole app. |
| `list_users()` | `GET /v1/users` | List the app's end users. |
| `get_user(end_user_id)` | `GET /v1/users/{id}` | Full detail: briefing, memories, entities, conversations. |
| `delete_user(end_user_id)` / `forget(...)` | `DELETE /v1/users/{id}` | GDPR cascade erasure for one user. |
| `preload(end_user_id, notes=[...], ...)` | `POST /v1/users/{id}/profile` | Pre-load a user's memory **before they ever chat** (CSV/CRM import). |

### Pre-load (the "known on message one" pattern)

```python
c.preload(
    end_user_id="jordan_cfo",
    notes=["Plan: Enterprise", "Company: Acme Robotics", "Renewal: 2026-03-15"],
    entities=[{"name": "Acme Robotics", "type": "COMPANY"}],
    topics=["enterprise", "onboarding"],
)
```

The user now has a populated Deep Memory briefing and searchable history — so the very
first time they message your bot, it already knows them. Supply `briefing=...` to set the
profile verbatim (no LLM call); omit it and one is synthesized from the notes.

## Async

Same surface, for asyncio apps and agents:

```python
import asyncio
from praqtordb_apps import AsyncClient

async def main():
    async with AsyncClient(api_key="pk_live_...") as c:
        await c.add(end_user_id="sarah", text="On the Pro plan")
        print(await c.search(query="plan", end_user_id="sarah"))

asyncio.run(main())
```

## Errors

```python
from praqtordb_apps import PraqtorAPIError, PraqtorError

try:
    c.get_user("nobody")
except PraqtorAPIError as e:
    print(e.status_code, e.detail)   # e.g. 404 "unknown end_user_id"
except PraqtorError as e:
    print("network/transport error:", e)
```

## Requirements

Python 3.9+, `httpx`.
