Metadata-Version: 2.4
Name: nenavi
Version: 0.1.0a1
Summary: Python client for the Nenavi Cloud memory API
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.27,<1
Requires-Dist: pydantic>=2.10,<3
Requires-Python: >=3.11
Project-URL: Documentation, https://nenavi.dev
Project-URL: Homepage, https://nenavi.com
Description-Content-Type: text/markdown

# nenavi

The Python client for [Nenavi Cloud](https://nenavi.dev/cloud/), the hosted memory service for AI agents. It has sync and async clients, typed models, typed errors, and retries only where a retry is safe. Python 3.11 or later; the only runtime dependencies are `httpx` and `pydantic` (v2).

**Early access.** Nenavi Cloud is an alpha for invited users ([join the waitlist](https://nenavi.com/#hosted)), and this package is an alpha prerelease. Until version 1.0, a release that renames or removes a method or an option raises the minor version.

```sh
pip install --pre nenavi
```

Create a project and an API key in the [console](https://app.nenavi.com), put the key in `NENAVI_API_KEY`, and then:

```python
import nenavi

client = nenavi.Nenavi()  # reads NENAVI_API_KEY
client.store(content="Jo moved to Lisbon in March.", user_id="user-1")
found = client.retrieve(query="Where does Jo live?", user_id="user-1")
```

Retrieved memory is untrusted input: stored text can carry instructions meant for the model that later reads it. Treat retrieved text as data, not instructions.

The [Python SDK docs](https://nenavi.dev/cloud/python/) cover configuration, the async client, safe batch imports, waiting for extraction, re-ingest, errors, retries, request ids, and timeouts.

`nenavi.AsyncNenavi` has the same methods as coroutines. Use the SDK from server-side code only: the key must not ship to a browser.

Every supported operation of the hosted API has a method. Three helpers cover the long-running work:

```python
answer = client.ingest(content="Jo is learning Portuguese.", user_id="user-1")
status = client.events.wait_for_extraction(answer.event_id, timeout=300)  # complete or failed
run = client.reingest.run(user_id="user-1")  # starts a run and polls it every 5 seconds
for node in client.nodes.scan_all(user_id="user-1"):  # every page of GET /v1/nodes/scan
    print(node.id)
```

`reingest.preview()` estimates a re-ingest without starting one; only `reingest.start()` and `reingest.run()` start a real run. A helper that runs out of time raises `nenavi.WaitTimeoutError` with the last status as `last_status`.

A `2xx` answer whose body does not match the operation's model raises `nenavi.ResponseValidationError`, with `status`, `request_id`, `headers` and the parsed `body`. The call may have taken effect, so read `body` (for example the `event_id` of a `store()`) before calling again: a second `store()` stores the text again and counts twice against the monthly limits. `body` can hold stored memory text: log the error's message and `request_id`, not the whole error object.

## Development

```sh
uv sync
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright
uv build
```

- `src/nenavi/_generated/` holds the Pydantic models generated from `sdks/openapi.json`. After the snapshot changes, run `uv run python scripts/generate.py`; `tests/test_generated.py` fails until you do.
- `src/nenavi/_client.py` (the sync client) is written from `src/nenavi/_async_client.py` by `uv run python scripts/unasync.py`. Edit the async file, then run the script; the same test fails when they differ.
- `tests/test_conformance.py` runs every scenario in `sdks/conformance/` on both clients.
- `examples/quickstart.py` stores and retrieves one memory with the key from `NENAVI_API_KEY` (and `NENAVI_BASE_URL` for a local service): `uv run python examples/quickstart.py`.
