embodiment 0.10.0

The agentic loop that gives an app an embodied AI presence. Install embodiment in an app or wrap one, supply a model seam plus IO callbacks, and it drives the perceive-decide-act loop and the presence pump - extracted from colleague so the loop is written once and imported, not reimplemented per host.

embodiment

The agentic loop that gives an app an embodied AI presence. Install embodiment in an app or wrap one, supply a model seam plus IO callbacks, and it drives the perceive → decide → act loop and the presence pump — extracted from colleague so the loop is written once and imported, not reimplemented per host.

Software presence, not a robot body. "Embodiment" is an overloaded word in this mesh: reachy-mini-cli owns the physical robot, reachy-lobes its local brain. This package gives an application a loop and a presence — it does not drive hardware, and nothing here claims a body. If that ever changes it will be a stated goal agreed with the robot siblings, never an implication drawn from the name.

Status

The extraction has landed. The loop, the presence pump, the muse thinking loop, perception, continuity and its lifecycle checkpoints, Gwen framing, the degradation ledger, event emission and the demo are all checked in on main (PR #13). The demo has been run against a real two-model rig, not only against fakes.

Still outstanding: colleague's answer to the seam proposal, filed and open as colleague#358 — the C1b dependency decision is colleague's to make, not ours — and depth in the live evidence. Deviation d4's live bar was met, but every result behind it is n≤4 on one rig with one model pair, so it is listed here rather than quietly counted as settled. See Roadmap and issue #1; CLAUDE.md carries the module-by-module status and devague deviate --list the approved departures from the plan.

What you get

• The bounded tool loop and the presence pump — the actual point of the package. run() is driven by an injected model seam and an injected tool executor; termination is proved structurally, not just tested.
• An agent-first CLI cited from teken (afi-cli).
• A mesh identity — culture.yaml (suffix + backend) and the matching resident prompt file (AGENTS.colleague.md, since this agent runs backend: colleague).
• The canonical guildmaster skill kit (18 skills) under .claude/skills/, vendored cite-don't-import. See docs/skill-sources.md.
• A build + deploy baseline — pytest, lint, the agent-first rubric gate, and PyPI Trusted Publishing wired into GitHub Actions.

Dependencies — what installing this costs you

embodiment is a library host apps import, so its dependencies become theirs. That is worth stating plainly rather than burying:

Dependency	Pulls in	For
eidetic-cli	data-refinery-cli[store] → neo4j, pymongo	durable memory
coherence-cli	numpy, httpx	memory-to-present coherence
events-cli	paho-mqtt	event emission

This package began with a hard zero-dependency rule; deviation d2 replaced it with a human gate. tests/test_zero_deps.py pins the approved set and the runtime import set and fails on any change in either direction — a new dependency cannot arrive without someone deciding, and the failure message says what approval is being asked for. Adding one is a deliberate act, not an edit.

Two honest caveats:

• Install footprint ≠ import footprint. neo4j, pymongo and paho are installed but never imported at rest — data-refinery resolves its backends lazily and events-cli loads paho on demand. A test guards that distinction so nobody "fixes" one to match the other.
• import embodiment still costs nothing. The package root stays lazy (PEP 562), so a consumer that only wants the loop never pays for the continuity stack. This is the strongest surviving piece of the original rule.

Quickstart

uv sync
uv run pytest -n auto                 # run the test suite
uv run embodiment whoami              # identity from culture.yaml
uv run embodiment learn               # self-teaching prompt (add --json)
uv run teken cli doctor . --strict    # the agent-first rubric gate CI runs

The demo: an app that remembers you

examples/greenhouse.py is a small potting-shed assistant — not a coding agent, and not colleague. Three domain tools, no shell, no filesystem outside its own directory. It exists to show the one thing an agentic loop cannot show on its own: an embodiment without memory is a sequence of awakenings, so run it twice and watch the sequence close.

uv run python examples/greenhouse.py --reset "New plant card - name: Marlow; sensor: s-fig-01; water below: 30% moisture. It is the fig by the north window. Check it in and log the visit."
uv run python examples/greenhouse.py --moisture 22 "Does Marlow need water today?"

The second command is a separate process. Its utterance never names s-fig-01, and nothing about Marlow is in the code. It reads that sensor anyway, decides to water (22% is under the 30% threshold it was told about once, in the previous process), and logs the visit — because the first run's summary was written to a durable store and this run recalled it. Add --json to either command for the machine-readable report: what was recalled, what each step did, what was remembered, and every degradation along the way.

Delete the store (--reset) and ask the second question on its own: the assistant says it has no plant card and asks for one. That refusal is the control experiment — it is what proves the recall is load-bearing rather than decorative.

The four seams the demo wires

An app author copies these four things and nothing else:

Seam	What you supply	In the demo
Tool surface	an object with execute(name, arguments) -> ToolOutcome	Greenhouse — read_sensor, log_care, finish
Model seam	complete(messages) -> ModelResponse, one call = one model turn	scripted_cortex, or gateway_seam(...) with --live
Continuity	build_continuity_fn(LifecycleConfig(data_dir=...)), injected as run(..., continuity=...)	lifecycle_config()
Presence	PresenceIO(render=..., task_state=...) → PresenceEngine	lines go to stderr

from embodiment import LifecycleConfig, build_continuity_fn, run

lifecycle = build_continuity_fn(LifecycleConfig(data_dir="/var/lib/myapp/memory"))
outcome = run(complete, task, executor=my_tools, max_steps=8, continuity=lifecycle)
for event in lifecycle.events:      # the C3 ledger: recalled, assessed, remembered
    log(event.to_dict())

Three things worth knowing before you copy it:

• data_dir is mandatory, not a convenience. It is the sole store anchor. Without it, a public record resolves against whatever git repo the host process happens to be running in — so an app started inside a checkout would quietly commit its memories into it. Every eidetic call refuses, with a recorded degradation, rather than guessing.
• embodiment recalls; it never injects. What the acting mind is told is host policy, so the demo does that itself in build_task() — one recall rendered into Task.context. embodiment owns when something is perceived, considered, acted on and remembered; it does not own your prompt.
• The host names which actions are consequential. LifecycleConfig.consequential takes a predicate; the demo's says log_care matters and read_sensor does not. embodiment cannot know that, and guessing from a tool name would be the kind of inference this package refuses everywhere else.
• Only what the mind puts in its summary is remembered. The durable record's text is TaskResult.summary, so what survives to the next process is a prompt-quality question, not a storage one. Two findings from running this demo against real models, both now in its system prompt: say what a summary must restate, and say that memory is a past visit rather than a present reading — without the second, a model will happily answer today's question with yesterday's sensor value.

Running it against a real rig

Everything above is hermetic: a scripted mind, no network, no gateway, no Docker. Pointing the same host at real models is one flag:

export COLLEAGUE_API_KEY=…    # read from the environment; never hardcoded, never printed
uv run python examples/greenhouse.py --live --identity Gwen --muse --base-url http://localhost:8001/v1 "Does Marlow need water today?"

--live is opt-in and has no default anywhere — the demo's test suite asserts that, so CI cannot trip into a real endpoint. --muse starts a second, advisory mind beside the actor: it proposes, it never decides, and it is given no tool schema at all. Without it the report says "muse": null, truthfully — a single-model run never claims another mind exists. --identity Gwen frames the prompts; with no identity the prompt is byte-identical to the unframed one.

Two measured notes about the reference rig, so a first live run is not a mystery: the cortex is a thinking model (it emits a long reasoning field before any content, which ModelResponse carries separately), and a stingy --max-tokens will return content: None while still mid-thought. The default is deliberately generous.

The live tests are skipped, never failed, unless you ask for them:

EMBODIMENT_LIVE_RIG=1 COLLEAGUE_API_KEY=… uv run pytest tests/test_demo_greenhouse.py -k LiveRig

CLI

Verb	What it does
whoami	Report this agent's nick, version, backend, and model from culture.yaml.
learn	Print a structured self-teaching prompt.
explain <path>	Markdown docs for any noun/verb path.
overview	Read-only descriptive snapshot of the agent.
doctor	Check the agent-identity invariants (prompt-file-present, backend-consistency).
cli overview	Describe the CLI surface itself.

Every command supports --json. Results go to stdout, errors/diagnostics to stderr (never mixed). Exit codes: 0 success, 1 user error, 2 environment error, 3+ reserved.

Where embodiment sits

Layer	Package	Owns
Surface	agentfront	CLI / MCP / HTTP / TAUI fronts, the App registry
Tools	shell-cli	The file-and-shell tool surface + approval policy
Loop + presence	embodiment	The pump: perceive → decide → act, and the presence between acts
Memory / trust	eidetic-cli, coherence-cli	Durable recall + provenance; drift and consistency signals
Product	colleague	The coder-agent harness — the opinions, not the plumbing

Three questions, three layers: how does a human or agent reach it (agentfront), what can it do (shell-cli), what makes it keep going and feel present (embodiment).

There is a second way to read the same parts — by function rather than by position: what notices, what acts, what reflects, what remembers, what sequences the rest. That map, with the caveat that its names are design metaphors for allocating responsibility across seams rather than claims about cognition, lives in docs/relationships.md. It stays there on purpose: it is promoted into this README only if the association-work experiment supports it, and an honest negative keeps it where it is. This table is the one to build against until then.

Gwen — the embodiment we ship

The reference embodiment is Gwen: one prompt-visible teammate produced by cooperating cognitive roles across two model families — G from Gemma, wen from Qwen. Colleague stays the runtime; embodiment drives the roles; Gwen is who the operator talks to.

Concept	Value	Authority
Runtime	colleague	the harness
Loop + presence	embodiment	the pump
Teammate identity	Gwen	who the operator addresses
Cortex	Qwen 3.6 27B (sakamakismile/Qwen3.6-27B-Text-NVFP4-MTP)	bounded tool loop, repo actions, final synthesis — final authority. Framed by embodiment.
Muse	Gemma 4 31B (nvidia/Gemma-4-31B-IT-NVFP4)	reflective counsel, tools opt-in: reframes the problem, challenges the cortex's assumptions and offers materially different alternatives, running its own parallel thinking loop — it proposes, never decides. A host may wire a working-memory pad and a bounded workspace onto its tool bench; neither is on by default (see below). Framed by embodiment.
Senses	Gemma 4 12B (coolthor/gemma-4-12B-it-NVFP4A16)	intake, perception, speak-back; never acts on the repo. Lives in colleague, not here — see the scope note below.
Ears / voice	Parakeet STT + Chatterbox TTS (lobes audio overlay)	the realtime lane below

Scope: embodiment frames cortex and muse, not senses. The table describes the whole reference rig, but only part of it is this package. embodiment ships one actor loop; colleague's senses coordination loop stays in colleague, and so does its framing. This split is recorded on colleague#352. A single-model run — the default tested path — starts no muse and claims no second mind.

Muse tools are opt-in, and a validation pass kept them that way. A host may hand the muse's thinking loop embodiment.muse_pad.MusePad (write-only working memory) and embodiment.workspace.MuseWorkspace (a bounded, network-less, disposable container) as tools on its bench; with no bench wired the muse stays exactly the tools-off mind it always was, byte for byte. Task t18's pre-registered three-arm series (docs/live-test-results/muse-arms.md, n=8 per arm, real Docker, 0 transport failures) tested that default against +pad and +pad+workspace and returned INCONCLUSIVE: arm A's confidently-wrong rate was 0 of 8, so there was no headroom left for a tool lane to reduce — the 5-of-6 figure that motivated the question was measured on a different loop and different problems, and is not this series' control. Alongside that inconclusive headline the series measured harm the operator's standing rule (the measured failure mode never ships as default behaviour) will not let ship: 9 of the 16 tool-arm runs came back NO_ANSWER against 0 for tools-off (issue #32 — handed tools, the muse writes a tool call and no prose), and 74% of the workspace arm's calls were refused because the muse sent command as a string rather than an array (issue #33). Arm C's answers were never wrong (4 correct, 0 wrong, 4 no-answer) and arm B's pad protocol adherence was clean (0 open intents in 8 of 8 runs) — this is not a finding that tools are harmful, only that the case for a default flip was not made. Revisiting the default needs #32 and #33 fixed first.

Roles resolve by name from a lobes gateway's /capabilities contract — never by parsing model names. The identity contract is tracked in colleague#352 and holds four rules that keep it honest:

1. Absent identity ⇒ byte-identical prompts. Un-named deployments behave exactly as they do today.
2. Identity never changes authority. Framing renames who speaks; it does not touch tool authority, routing, or safety policy.
3. Same identity, role-specific authority. Cortex is framed only on the top-level acting loop — typed subagents never receive it; muse receives its authority boundary on every advisory path. (Senses framing and neutral transcription are colleague's half of the contract, not embodiment's.)
4. Traces stay truthful — they always expose the actual contributing role, model, and machine, and a single-model run never claims another mind exists.

The realtime interface (lobes)

The rig's lobes gateway serves a /v1/realtime WebSocket (server-VAD, pcm16 @ 24 kHz). Gwen's ear rides it ears-only: the client never triggers the bridge's own model, so senses stays the only mind that answers and replies go out over the batch TTS lane. The microphone is opt-in per session, a client-edge half-duplex mute substitutes for AEC on hardware without one, and turn-based voice is the degrade floor — a flaky socket degrades with a recorded notice, never an exception into the host's main path.

Roadmap

Both seams already exist in colleague, written injection-shaped, so this is decoupling work rather than redesign:

• The bounded tool loop (colleague/loop.py) — engine-agnostic: handed a complete callable that performs one model turn, it drives until the model finishes, stops requesting tools, or the step budget is reached. Termination is guaranteed; hooks at four lifecycle points can deny or rewrite a tool call but add no exit path.
• The presence pump (colleague/presence_engine.py + presence.py) — one pump every surface shares, assuming no TTY, no thread, and no clock: all IO rides injected callbacks and cadence is step/phase-based.
• The senses coordination loop (colleague/senses_loop.py) — agentic without ever putting a tool schema on the wire, with an explicit loop → beats → off degradation ladder that records every transition.

Two invariants come across unchanged: the operator's words are preserved verbatim, never round-tripped through a model, and perception never raises — it degrades to a recorded, observable failure. A presence layer that can lose the user's words, or fail loudly into an app's main path, is worse than no presence layer.

Open issues

Issue	What it asks
#1	The build brief: extract the loop + presence from colleague, stay pure-stdlib (colleague's zero-deps guard), don't overclaim the name, keep degradation observable. Parks five questions to answer before building — one loop or two, one model seam or two, library mode or wrapper mode first, the decoupling cost of loop.py's dozen module-scope imports, and whether embodiment owns the presence event stream that harmonics-cli and reterminal currently consume without a shared producer.
#2	Continuity: compose eidetic-cli (memory, provenance, ageing) and coherence-cli (agreement between memory and the present) rather than reimplementing either. Embodiment owns the lived sequence; memory and coherence are runtime, not tools the model picks arbitrarily; checks happen at meaningful boundaries; degradation is visible to the host. Done means a second, non-colleague app gains the same continuity.

Neither issue has replies yet — answers belong on the issue or in an exported spec, not only in a commit message.

Make it your own

This repo was minted from culture-agent-template. To mint another agent from it:

1. Rename the package embodiment/ and the embodiment CLI/dist name throughout pyproject.toml, the package, tests/, sonar-project.properties, and this README.md. The name is hard-coded in ~100 places, so list every occurrence first: git grep -nF -e embodiment.
2. Edit culture.yaml with your suffix and backend.
3. Rewrite CLAUDE.md for your agent and run /init.
4. Re-vendor only the skills you need from guildmaster (see docs/skill-sources.md).

See CLAUDE.md for the full conventions (version-bump-every-PR, the cicd PR lane, worktree layout, memory discipline, deploy setup).

License

Apache 2.0 — see LICENSE.