Metadata-Version: 2.4
Name: outhad-contextkit-sdk
Version: 1.0.0
Summary: Thin Python client for the Outhad ContextKit cloud — paywalled by API key minted at https://contextkit.outhad.com
Project-URL: Homepage, https://contextkit.outhad.com
Project-URL: Documentation, https://contextkit.outhad.com/docs
Project-URL: Source, https://github.com/outhad/contextkit
Project-URL: Issues, https://github.com/outhad/contextkit/issues
Author-email: Outhad <idrisitanzil@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agents,ai,contextkit,long-term-memory,memory,outhad,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software 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 :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Requires-Dist: httpx>=0.27.0
Requires-Dist: typing-extensions>=4.8.0; python_version < '3.11'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.7; extra == 'test'
Requires-Dist: pytest>=8.2.2; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

# outhad-contextkit-sdk

Thin Python client for the **Outhad ContextKit** cloud — long-term memory
for AI agents, with multimodal + temporal-causal recall, personalised
retrieval, and tenant isolation built in.

This package ships **client only**. There is no local memory engine, no
vector store driver, no LLM provider. Calls go to the Outhad ContextKit
cloud where the heavy lifting happens — billed against the API key you
mint at https://contextkit.outhad.com.

## Install

```bash
pip install outhad-contextkit-sdk
```

## Quickstart

```python
from outhad_contextkit_sdk import MemoryClient

client = MemoryClient(api_key="ock_live_...")  # or set OUTHAD_CONTEXTKIT_API_KEY

client.add(
    messages=[
        {"role": "user", "content": "Hi, my name is Alice and I love sushi."},
    ],
    user_id="alice",
)

hits = client.search(query="What food does Alice like?", user_id="alice")
for hit in hits["results"]:
    print(hit["score"], hit["memory"])
```

## Get an API key

1. Sign up at <https://contextkit.outhad.com>.
2. Open the dashboard → **API keys**.
3. Click **Create key**, copy the one-shot secret (looks like
   `ock_live_<8-char-prefix>_<32-byte-secret>`).
4. Either pass it as `MemoryClient(api_key=…)` or export it in your
   shell as `OUTHAD_CONTEXTKIT_API_KEY`.

## Auth header

The SDK sends `Authorization: Token <api-key>` on every request. The
cloud dispatcher also accepts `Bearer` and `X-API-Key` if you prefer to
hit the HTTP API directly (e.g. from `curl`).

## Host resolution

| Resolution order | Default |
|------------------|---------|
| `host=` constructor arg | (none) |
| `OUTHAD_CONTEXTKIT_HOST` env var | (none) |
| Production default | `https://contextkit.outhad.com` |
| Dev fallback (transparent retry on connection error) | `http://localhost:8000` |

When the production default is unreachable (DNS failure / connection
refused) the client transparently retries against
`http://localhost:8000` and pins itself there for the rest of the
session — useful while you are working against `make cloud-up` locally.
The fallback is disabled when you pass `host=` or set
`OUTHAD_CONTEXTKIT_HOST` explicitly.

## Async

```python
from outhad_contextkit_sdk import AsyncMemoryClient

async def main():
    async with AsyncMemoryClient(api_key="ock_live_...") as client:
        await client.add(
            messages=[{"role": "user", "content": "I prefer dark mode."}],
            user_id="alice",
        )
```

## API surface

* `add(messages, *, user_id, agent_id, run_id, metadata, infer)`
* `get_all(*, user_id, agent_id, run_id, limit)`
* `get(memory_id)`
* `search(query, *, user_id, agent_id, run_id, filters, limit)`
* `update(memory_id, *, text)`
* `history(memory_id)`
* `delete(memory_id)`
* `delete_all(*, user_id, agent_id, run_id)`

For dashboard-style operations the same client also exposes
`list_api_keys()`, `create_api_key()`, `revoke_api_key()` — those
require a Clerk session JWT and are intended for interactive tooling.

## License

Apache-2.0.
