Metadata-Version: 2.4
Name: nenavi
Version: 0.1.0a3
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.

One `AsyncNenavi` can serve several event loops in turn, so you can build it once at module scope and call it through `asyncio.run()` in each AWS Lambda invocation or Celery task. On a new loop it opens new connections; the ones left on the closed loop are released when they are garbage-collected, with a `ResourceWarning`. In tests that treat warnings as errors, build the client in a fixture on the test's loop and close it there. An `httpx.AsyncClient` that you pass as `http_client` cannot move between loops: build it inside the loop that uses it, or a call from another loop raises `nenavi.ConfigurationError`, which can follow a request that reached the service.

Every supported operation of the hosted API has a method. Four 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
started = client.reingest.start(user_id="user-2")  # starts a run and returns at once
if started.run_id is not None:
    finished = client.reingest.wait(started.run_id)  # polls a run you have, starts nothing
for node in client.nodes.scan_all(user_id="user-1", limit=1000):  # every page, 1,000 nodes each
    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`, and a poll that fails inside `reingest.run()` raises its own error with `last_status` set the same way, so the run's `run_id` is not lost: pass it to `reingest.wait()`, which polls that run with the same rules and starts nothing. A `409` `reingest_running` raises `nenavi.ConflictError` with the working run's id as `run_id`, so after a lost answer to the start, a cancelled task or an outside timeout, calling `reingest.run()` again while that run is working tells you which run to go on with in `reingest.wait()`; if it has ended, the call starts the next run instead, or returns when nothing is left to re-derive. To find a run whose id you lost, whether or not it has ended, call `reingest.latest(user_id=...)`, which starts nothing and returns the user's newest run; check its `started_at` and `scope`, since another caller may have started a newer one. Every scan page counts against the key's request rate limit (60 a minute by default) like any other call, and `store()`, `ingest()` and `retrieve()` are never retried on a `429`, so for a large scan pass a larger `limit` (up to 1,000 nodes a page), and run background jobs with their own key. The polls of the waiting helpers count against a separate limit of the same size for the two status reads, so they never use up the requests your writes need; to wait on many events at once, use a longer `interval`.

Only `GET` methods and `ingest_fast()` retry by themselves, on a `429 rate_limited` (after `Retry-After`), a `503 database_unavailable` or `lease_unavailable`, a `503` with no reason code (from the load balancer in front of the service), or a connection error. `store()`, `ingest()` and `retrieve()` never retry: a retried store stores the text again and counts twice against the monthly limits. `ingest_fast()` sends one `Idempotency-Key` on every retry of a call. A timeout is never retried, so to retry it by hand, pass the error's `idempotency_key`. If you wrap `ingest_fast()` in your own retry, such as a `tenacity` decorator or a backoff loop, make one key before the first attempt and pass it on every attempt: a call without a key gets a new one, and the service stores and meters the batch again.

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`.
