Metadata-Version: 2.4
Name: innernet
Version: 0.1.0
Summary: python client for innernet: memory for the agents you keep. no dependencies.
Author: innernet
License: MIT
Project-URL: Homepage, https://innernet.live/developers
Project-URL: Source, https://github.com/your-innernet/innernet/tree/main/packages/sdk-python
Keywords: innernet,agents,memory,llm,ai
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# innernet (python)

a small client for the innernet api. no dependencies, just the standard library, python 3.9 or newer.

```sh
pip install innernet
```

## quickstart

```python
from innernet import Innernet

client = Innernet()  # reads INNERNET_API_KEY; or Innernet(api_key="...")
bot = client.agent("support-bot")  # a slug, an id, or "me" with that agent's own key

bot.remember("maya prefers email, and hates being called", user_id="u_123")
found = bot.recall("how to reach maya", user_id="u_123")
block = bot.context("maya wants a refund", user_id="u_123")["text"]  # drop it into a system prompt
bot.forget_user("u_123")  # every memory about that user, gone
```

## what it is

memory for the agents you keep. an agent belongs to a person and has a memory of its own, which no other agent can read. what it learns about its owner is held for their yes (or filed straight away, if they said so), never quietly added.

an agent key is a server secret: it reaches every memory that agent keeps, its users' included, so call from your backend and never ship it to a browser or an app.

```python
client.agents.create("support bot", kind="product", settings={"memory": {"instructions": "keep how people like to be contacted"}})
client.agents.update("support-bot", status="paused")  # a paused agent keeps and recalls nothing
client.agents.create("deep search", parent="support-bot")  # a sub-agent: the parent's kind and a copy of its settings

bot = client.agent("support-bot")
bot.remember(messages=[{"role": "user", "content": "call me on friday"}], user_id="u_123")
bot.recall("friday", user_id="u_123", include_person=True, limit=5)
bot.memories.list(user_id="u_123")  # also get, update, delete, history
bot.forget(filters={"run_id": "run_9"}, dry_run=True)  # count first
bot.export()
bot.events(limit=20)
```

- responses are the parsed json, exactly as the api sends it, so keys are snake_case. `innernet.types` has typed dicts for your editor.
- options use the api's own names (`user_id`, `include_person`). a name the api does not have is a `TypeError`, so a mistyped `user_id` cannot quietly keep a memory unscoped. `None` means "not given" (in an `update` call it clears the field instead).
- `settings`, `metadata` and `filters` are sent exactly as you write them.
- reads are retried once on a 429 or a 5xx. writes never are, because they may have landed. redirects are never followed, so your key only goes where you pointed it.

## errors

every failure raises `InnernetError(status, code, message, detail)`. `code` is the api's reason: `not_found`, `forbidden`, `paused` (423), `invalid`, `conflict`, `rate_limited` (with `retry_after`), `unavailable`, `too_large`. when there was never an answer, `status` is 0 and `code` is `network_error` or `timeout`.

```python
from innernet import InnernetError

try:
    bot.recall("x")
except InnernetError as err:
    if err.code == "paused":
        ...
```

## webhooks

an agent's webhook is signed with `x-innernet-signature: t=<unix>,v1=<hmac>`. check it against the raw body, before you parse it.

```python
from innernet import verify_webhook

if not verify_webhook(secret, raw_body, headers.get("x-innernet-signature")):
    ...  # reject it
```

it is constant-time, refuses a delivery older than five minutes (`tolerance=300`, or `None` to skip the check), and returns `False` instead of raising.

## tests

```
python3 -m unittest discover -s tests -t .
```
