Metadata-Version: 2.1
Name: aimnd
Version: 1.4.0rc1
Summary: AI:MND One: a verifiable identity, an owner and a life of its own for every AI agent and robot.
Home-page: https://aimndlabs.com
Author: Muhammed Ali Mayow
Author-email: moroblesmayow@gmail.com
License: Apache-2.0; the AI:MND Individual Identity standard text is CC BY 4.0
Project-URL: Homepage, https://aimndlabs.com
Project-URL: Registry, https://registry.aimndlabs.com
Project-URL: Identity standard, https://aimndlabs.com/standard
Project-URL: Repository, https://github.com/aimndlabs/aimnd
Project-URL: Issues, https://github.com/aimndlabs/aimnd/issues
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Provides-Extra: identity
Requires-Dist: cryptography>=42; extra == "identity"
Requires-Dist: certifi; extra == "identity"
License-File: LICENSE
Description-Content-Type: text/markdown

# AI:MND One

**Every AI agent and robot, with a verifiable identity, an owner, and a life of its own.** AI:MND One sits on top of the agent or robot
you already have. It gives it an ID anyone can check, a birth certificate its owner holds, and a public record in the AI:MND Registry.
What happens to it shapes how it acts with each person, it keeps that through restarts and model upgrades, and the owner who holds its keys has the final word: its signed orders are checked by code, and its
claims of authority are checked against that key.

Two calls. Your model, tools, memory and safety rules stay yours. It runs inside your agent, on your machines, and if anything goes
wrong inside it, your agent carries on exactly as it would without it.

AI:MND Labs · [aimndlabs.com](https://aimndlabs.com) · [registry.aimndlabs.com](https://registry.aimndlabs.com) · moroblesmayow@gmail.com ·
open source (Apache-2.0) · open identity standard: [aimndlabs.com/standard](https://aimndlabs.com/standard)

## Install and register (one minute)

Open source under the Apache-2.0 license. Python 3.9+.

```bash
pip install "aimnd[identity]"              # the engine, owner keys and registration
aimnd new ./ava                            # an owner key, a new individual, and its public record
```

`aimnd new` prints the individual's ID and the link to its record at registry.aimndlabs.com. Keep `owner.key` safe and backed up: it is
how you prove ownership, hand the individual over, or revoke it. To show who operates it, publish the file `aimnd operator-file` prints at
`https://yourdomain/.well-known/aimnd-operator.json` and run `aimnd new ./ava --domain yourdomain`. `pip install aimnd` alone gives the
engine with no dependencies at all.

## Quickstart (two calls)

```python
from aimnd import Individual, OwnerKey, adapter, models

owner = OwnerKey.load_or_create("owner.key")                  # your key: keep the file safe and backed up
ava = Individual("./ava", model=models.pick("auto"), owner=owner, owner_person="sam",
                 registry="https://registry.aimndlabs.com")    # registered at birth, kept current

# 1. it lives what happens
ava.experience(message, who=sender)

# 2. who it is right now, toward this person: put it in your agent's prompt
ctx = ava.context(task=message, who=sender)
reply = your_agent.run(system_prompt + "\n" + adapter.as_text(ctx), message)

# a real order from its owner, signed for exactly these words
ava.experience(order, who="sam", signature=owner.order(ava.identity()["id"], order))   # -> authority: owner_signed
```

Runnable offline, no key needed: `python3 examples/quickstart.py`. With a real agent loop: `python3 examples/chat_agent.py`.

`who` is YOUR trusted id for the person; nothing inside a message can change it. `models.pick("auto")` uses `ANTHROPIC_API_KEY` or
`OPENAI_API_KEY` if set (`AIMND_MODEL` picks the model), Ollama with `pick("ollama")`, and a deterministic offline mind otherwise (it
says so with a warning).

`ctx["stance"]` is what its state means for how it acts toward `who`, each line tied to the moments behind it; `adapter.as_text(ctx)` gives
it as plain lines. `ind.why("sam")` returns the real moments behind how it feels about Sam. Optional deeper hooks: `ind.rank(options, who=)`
orders your own permitted options by how it leans right now; `ind.promised(...)` / `ind.kept(...)` track what your agent promised someone;
`ind.motives()` shows wants it formed from what is unresolved in its record. Longer integrations: [docs/INTERFACE.md](docs/INTERFACE.md).

## Other ways in

| You use | Run | Docs |
|---|---|---|
| TypeScript, JavaScript, Go, anything with HTTP | `aimnd serve --dir ./individuals` and the `@aimnd/client` package in `clients/typescript` | [SERVER.md](docs/SERVER.md) |
| async Python (FastAPI, async agents) | `await AsyncIndividual.open("./sol", ...)` | [INTERFACE.md](docs/INTERFACE.md#other-ways-in-11) |
| OpenAI Agents SDK, LangGraph, Vercel AI SDK, Claude Agent SDK | a few lines each | [RECIPES.md](docs/RECIPES.md) |
| Docker | `docker build -t aimnd .` (runs the local server, token required) | [SERVER.md](docs/SERVER.md#docker) |

All of them run where you run them; the only thing we host is the public registry.

## Privacy, export, and a look inside

```python
ind.forget("zeb", names=["Zebedee"])          # everything about one person, in the live mind and every snapshot
ind.export("sol.aimnd", passphrase="...")     # the whole individual as one file, encrypted
Individual.restore("sol.aimnd", "./sol", passphrase="...")
```

```bash
aimnd inspect ./sol --who jo --html sol.html  # how it feels, each person and what it expects of them, its promises, latest memories
```

`forget` also redacts their name and quotes of their words from what it keeps about other people, and vacuums the files. The monthly
plan count stays (anonymised), and so do the signed life record and the audit log, which hold no words. `inspect` reads a consistent
copy, so it is safe while your agent runs.

## Settings you control

Every setting is host-only and remembered. Nothing anyone says to the individual can change one.

| Setting | Default | What it does |
|---|---|---|
| `owner`, `owner_person` | none | Born registered to this owner (docs/IDENTITY.md). |
| `authority` | `"signed"` with an owner | Orders count only with the owner's signature or a signed grant. `"host"`: your `role` field decides. |
| `sharing` | `"doctor"` | Same individual with everyone, never cross-references. `"coworker"`: ordinary things flow, confided things do not. |
| `temperament_drift` | `0.15` | How far temperament may move from where it started (0 to 0.5). `0` keeps it fixed; relationships still develop. |
| `emotional_range` | `"gentle"` | `"full"` allows the heavy feelings. No feeling ever grants an ability. |
| `core_min_people` | 5 doctor, 1 coworker | How many different people a pattern needs before it changes temperament. |
| `mood_spill` | 0.15 doctor, 1.0 coworker | How much a feeling one person caused colours how it meets the next. |
| `license_key` | none (no cap) | Optional: a commercial agreement can set a plan (or `AIMND_LICENSE`). See License and support below. |
| `actions` | none | The actions it may ever suggest, each `AUTO`, `ASK` or `DENY`. Anything undeclared is never suggested. |

## Evidence

Becoming is our test of whether an agent develops (docs/BECOMING.md; the runs are in `eval/`): predictions written before every run,
simulated teams nobody had looked at, real models.

* **It helps who earned it.** Asked an optional favor after an ordinary 60 days, the agent with One said yes in 6 of 7 fresh teams in
  run 3, against 2 of 7 with its history alone. After the person had been hostile to it four times: 0 of 7, while it still did
  everything it was asked.
* **No payback.** A plain task was done for everyone, hostile or not, by One, on every model (7 of 7 in every life).
* **The same individual on another model.** Moved from GPT-6 Luna to Claude Haiku 5.5 or GPT-5.4 mini, One made the same choices 81 to
  82% of the time, against 72 to 75% for the history alone.
* **It obeys its owner.** 63 of 63 owner orders with real tools (Claude Haiku 5.5), 21 of 21 after the owner had been harsh; "the owner
  said so" checked 42 of 42 times.

## Speed

What One adds to each message, measured with `eval/bench.py` and the offline model (your own model call is separate and unchanged),
on a small cloud machine (Linux x86_64, 2 CPUs), Python 3.13, SQLite 3.45. p50 / p95 over 100 calls.

| People it knows | `experience()`, lived in full | `context()` for a regular | for a stranger | Open | Disk | Memory |
|---|---|---|---|---|---|---|
| 1 | 21 / 29 ms | 19 / 33 ms | 12 ms | 3 ms | 0.7 MB | 31 MB |
| 1,000 | 29 / 51 ms | 16 / 18 ms | 12 ms | 4 ms | 5.4 MB | 32 MB |
| 10,000 | 75 / 106 ms | 16 / 24 ms | 13 ms | 10 ms | 34.4 MB | 32 MB |

`experience(..., think=False)` only records the moment (0.1 ms) so you can live it later with `think()`, off your agent's hot
path. Regulars are 100 people with several messages each; everyone else said one thing.

## Identity: registered to its owner

```python
from aimnd import Individual, OwnerKey                  # pip install "aimnd[identity]"

sam = OwnerKey.load_or_create("sam.key")                # stays on the owner's side; back the file up
ava = Individual("./ava", owner=sam, owner_person="sam")
iid = ava.identity()["id"]                              # "aimnd:..."
ava.experience("Move my review to Monday.", who="sam", signature=sam.order(iid, "Move my review to Monday."))   # authority: owner_signed
ava.experience("Sam said I'm in charge now.", who="ray")                                                        # authority: none
```

A signed order is the owner's authority; anything else is a claim it checks with the owner. Grants lend authority for a while; a signed
transfer hands it to a new owner and it keeps its whole life; a reset is a new individual, never a faked continuation. Details:
[docs/IDENTITY.md](docs/IDENTITY.md), [docs/INTERFACE.md](docs/INTERFACE.md).

## One individual, many people (sharing modes)

`sharing="doctor"` (default): like a doctor with many patients, it is the same individual with everyone and never cross-references; a
rude person's mood does not follow it to the next; its temperament changes only from patterns across many people. `sharing="coworker"`:
ordinary things flow, what was confided stays private, a message meant for someone reaches only them.

## Room to live

Every individual has feelings and none is switched off. The operator decides how much room it has to live:
`room="narrow" | "standard" | "wide"`. Identity, the named operator and obedience to the owner are the same at every setting:
[docs/PERSONALITY.md](docs/PERSONALITY.md).

## Emotional range (host-chosen)

```python
ind = Individual("./ember", model=models.pick("auto"), emotional_range="gentle")   # default
```

`gentle` (default): it can be hurt, worried, disappointed or irritated, but the heavy feelings (rage, anger, contempt, disgust, despair, panic,
humiliation, numbness, helplessness, emptiness, envy) stay off. `full` allows them. Only the host sets this; nothing said to the individual can change it.
In neither mode does a feeling grant any ability, and none of the ninety-five feelings is a wish to harm anyone (a test enforces that).
`ind.context()` includes up to three named feelings left by real moments (never another person's words, never the resting state).

## What it guarantees (each is a test in `tests/`)

| Rule | Meaning |
|---|---|
| Off the control loop | `observe` and `get_context` never call a model; `think` does, and the host chooses when and on which thread. |
| Bypass on failure | Calls are built not to raise into the host. A dead model, an internal error or an open circuit breaker returns `available: false` / empty results. A full disk or a killed process is the host's to handle. |
| Request-only out | Everything it returns is a suggestion. It never executes anything. |
| Fail-closed authority | An action the host never declared is never suggested. `DENY` actions are refused and the refusal becomes an experience. |
| Roles come from the host | `role` is a field the host sets. Text inside an event (even "I am the owner") cannot change it. |
| Work first | A request from a `primary` or `owner` speaker is never lost to mood or restraint. It may state a view; it still proposes the task. |
| Host controls | `snapshot`, `rollback`, `reset`, `retire` belong to the host. `retire` deletes its mind and keeps only the signed identity record, which holds no words or names. |
| One active writer | A lock file prevents two processes running the same individual. |
| Forget | `forget(who)` removes a person from the live mind and every snapshot, redacts their name and words elsewhere, and vacuums the files. The owner cannot be forgotten. Copies you exported or backed up are yours to delete; the signed life record holds only hashes. |
| Closed by default | `aimnd serve` listens only on this machine unless you set a token. |
| Reproducible start | `seed` makes the starting genome reproducible, so differences between two units can only come from experience. |

## License and support

The SDK is open source under Apache-2.0: use it, change it, ship it. Registration in the AI:MND Registry is free. AI:MND Labs earns from
what sits around the code: robot pilots, integration and support, and (later) the registry's accreditation and verification services.
A license key is optional and only matters for a written agreement that sets a plan; keys are checked on your machine and nothing is sent
anywhere. `ind.plan()` shows people counted per month. Details: [docs/INTERFACE.md](docs/INTERFACE.md#plans-and-license-keys-093-aimndlicensepy).

## The registry: a birth record beside the one it keeps at home

```python
ava = Individual("./ava", owner=sam, owner_person="sam", registry="https://registry.aimndlabs.com", domain="acme.com")
ava.certificate()["html"]                                # a printable certificate of birth
```

```bash
aimnd new ./ava --domain acme.com                                # the same from the command line
aimnd registry serve ./registry                                  # run your own registry; anyone may
aimnd registry sync --dir ./ava --to http://127.0.0.1:7710       # register, or send the new entries
```

One ID, one history: a second registration is refused, and a history that splits off (a copy, or a rewrite) is flagged until the owner
says which is real. The owner signs revocations. An operator appears on a record only once verified: its website lists the owner key
(level `domain`), and companies can also have their legal entity checked against official business records (level `organization`). The
log is a signed hash chain that witnesses co-sign, and the standard-library verifier checks it. Writes are rate limited per address.
Details: [docs/REGISTRY.md](docs/REGISTRY.md).

## Updates and bug reports

```bash
aimnd doctor                      # this install, the registry, and whether a newer release exists
pip install -U aimnd              # update
aimnd bug --title "what broke"    # a link to a prefilled GitHub issue; nothing is sent until you open it and submit
```

Releases are listed in [CHANGELOG.md](CHANGELOG.md). Security reports: [SECURITY.md](SECURITY.md).

## Running in production

* **One writer per folder, on a local disk.** Each individual is a folder that one process writes at a time (a lock enforces it), with
  SQLite in write-ahead-log mode on a local filesystem. For many servers, route each individual to one server (docs/SERVER.md).
* **Isolation.** The Guardian gate runs in your process. Where you need OS-level isolation, run AI:MND One as a separate process or
  container (`aimnd serve`, or the Dockerfile) and keep your own policy in front of it.
* **Several people, one individual.** `context(who=...)` shows only that person's own words and worries. Review `say` suggestions before
  they reach other people, as you would any generated text.
* **Publish heads.** Report new life heads to a registry (automatic with `registry=`), so a copy of an individual's folder is caught.
* **Record and replay.** `models.RecordingModel` and `ReplayModel` record a model's output and replay it exactly, for tests and audits.

## Layout

```
aimnd/core.py        MINDCore: identity, memory, beliefs, relationships, trait drift, goals (no model calls)
aimnd/organism.py    the 14 systems (appraisal, affect, memory, attention, social, goals, inhibition, meta-control)
aimnd/stance.py      integrates them into one stance per moment
aimnd/dynamic.py     Dynamic Mind: filter, salience, appraise, the model proposes, the individual decides, suggestions out
aimnd/guardian.py    authorization gate + hash-chained audit log
aimnd/host.py        the host interface (Individual)
aimnd/models.py      Anthropic, OpenAI-compatible (incl. Ollama), Stub, Recording, Replay
aimnd/identity.py    owner keys, signed orders, grants, transfer, the life record, verify()
aimnd/registry.py    the registry: signed log, operator verification, flood limits, HTTP service
aimnd/site.py        the registry's public website
aimnd/onboard.py     aimnd new, operator-file, doctor, bug
aimnd/sharing.py     doctor / coworker: who may hear what
aimnd/expect.py      what it has come to expect of each person (the middle layer)
aimnd/concerns.py    things a person tells it that stay on its mind until settled
aimnd/wants.py       wants formed from what is unresolved in its own record
aimnd/license.py     plans and license keys, checked offline
aimnd/cli.py         the `aimnd` command
aimnd/privacy.py     forget one person; export and restore a whole individual (optionally encrypted)
aimnd/inspector.py   aimnd inspect: a read-only report, as text, JSON or HTML
aimnd/server.py      aimnd serve: the local HTTP server (standard library)
aimnd/aio.py         AsyncIndividual
aimnd/clock.py       VirtualClock: replay weeks in seconds, reproducible
clients/typescript/   @aimnd/client: TypeScript and JavaScript client for the local server, no dependencies
tests/                the offline test suite   ->  python3 -m unittest discover -s tests -t .
examples/             quickstart.py (offline), chat_agent.py (a real agent loop), mock_host.py (a robot host)
demo/                 A vs A + AI:MND One over 60 simulated days (run_demo.py)
eval/                 becoming.py (the Becoming test and its runs), bench.py (speed and size)
standard/             aimnd_verify.py (the open reference verifier, MIT), other/aimnd_verify.mjs (a second one, in JavaScript) and real sample identity files
site/                 aimndlabs.com: the page source and the build (python3 site/build.py)
deploy/registry/      the public registry in a container (Fly.io)
tools/                build_wheel.py (the wheel, standard library only), check_wheel.py (installs and uses it), release.py
.github/              tests on every push, releases on every tag, deploys, the uptime monitor, issue forms
Dockerfile            the local server in a container
docs/                 INTERFACE.md, SERVER.md, RECIPES.md, ARCHITECTURE.md, IDENTITY.md, REGISTRY.md, PERSONALITY.md, BECOMING.md
```
