ANIMA V0.1.0 — First Reference Implementation Landed

For the past two weeks, the standalone ANIMA repo was a skeleton: a 7-line Python file with __version__ = "0.0.0" — module boundaries were drawn but there was barely any runnable code. In parallel, inside a BCI medical-care research prototype (human-brain-interface-demo), a full L0–L5 stack + five-factor assessment + LLM-as-Parser reference implementation had grown — 11 files, 1,037 lines, pytest green, pip-installable.

2026-04-21 merged the two: the reference implementation migrated from the prototype repo into the main ANIMA repo, was generalized by stripping BCI-specific semantics, and the version jumped straight from 0.0.0 to v0.1.0.

All six layers ship with code

   upstream signal (BCI / ASR / vision / text)
                    ↓
   ┌─────────────────────────────┐
   │ L0 Signal                   │  signal → intent token + confidence + drift
   ├─────────────────────────────┤
   │ L1 Parser (LLM)             │  instruction → TaskSpec (forced tool-calling)
   ├─────────────────────────────┤
   │ Test-and-Check (six gates)  │  JSON / intent / skill / params / safety / preconds
   ├─────────────────────────────┤
   │ L2 Planner                  │  TaskSpec → py_trees behavior tree
   ├─────────────────────────────┤
   │ L3 Skill                    │  Function-Calling + Affordance Scoring
   ├─────────────────────────────┤
   │ L4 Adapter                  │  device-agnostic actuation (arm / base / ...)
   ├─────────────────────────────┤
   │ L5 Assessment               │  ITA · MQA · SQA · GOA · PEA (Pre / Runtime / Post)
   └─────────────────────────────┘

Every layer now has a real source file (src/anima/l0_signal.py through src/anima/l5_assessment.py) — no more docstring placeholders.

Five-factor formulas land

v0.0.0 only named the five factors; v0.1.0 gives them concrete formulas:

ITA intent alignment, absorbing upstream drift: MQA_ita = 1 − drift_score
MQA motion quality: trajectory smoothness / contact force envelope / grasp margin
SQA skill competence: Beta prior updated from a rolling read of pea_log.jsonl
GOA goal outcome: multiplicative composition P(success) = ∏ Pᵢ — never averaged
PEA preference-experience retrieval: three-factor weighted recency × 0.5 + relevance × 3.0 + importance × 2.0

These aren't placeholders — they're the formulas the research prototype ran.

LLM-as-Parser, LLM-agnostic

L1 talks to the LLM through an LLMToolCaller protocol, not any specific vendor SDK. The current reference implementation supports both DeepSeek and OpenAI (100% OpenAI-SDK compatible). The core constraint is forced tool-calling — the LLM can only emit a structured TaskSpec JSON, never free-form low-level commands.

BCI-specific terminology stripped

The original reference implementation grew inside a BCI research prototype, so it carried quite a bit of BCI-specific semantics. During the merge into the main repo, those were generalized:

drift_score no longer specifically means neural-signal drift; the docstring now reads "upstream signal uncertainty, e.g. BCI drift or ASR confidence"
IntentToken keeps its 35-word vocabulary but labels it "example vocabulary; extend per application"
"BCI" / "neural" / "patient" / "clinician" language in README and docstrings was rephrased generically
The EmbodiedAdapter protocol was already generic; the README now makes explicit that it plugs into manipulators, mobile bases, wheelchairs, and future humanoids

Keywords shifted from bci / assistive-robotics to cognitive-architecture / embodied-ai / behavior-tree / llm-tool-use / intent-to-action / self-assessment.

Open-source scaffolding in place

Previously there was just a LICENSE and a README. v0.1.0 brings:

pyproject.toml — pip install -e . works
tests/test_pipeline.py — 6/6 green
CONTRIBUTING.md / SECURITY.md / CODE_OF_CONDUCT.md / CHANGELOG.md
PR template

Installation:

pip install git+https://github.com/jeffliulab/anima.git@main

Downstream applications (soma-care) depend on it this way — no more embedded copies.

Two application branches in place on the same day

The same day, SOMA Care was spun out as a standalone repo (jeffliulab/soma-care), ported from human-brain-interface-demo/demo/ as the v0.4 starting point. Its core/pyproject.toml already reads anima @ git+https://github.com/jeffliulab/anima.git@main; tests are 17/17 green; the import chain runs from the anima framework all the way through to soma-care's FastAPI main.py.

With the existing SOMA Arm (chess manipulation), ANIMA now has two active application branches:

Branch	Repo	What it does
SOMA Care	`jeffliulab/soma-care`	Simulated-ward care intent-to-action loop
SOMA Arm	`jeffliulab/soma-arm`	Tabletop chess manipulation (real hardware)

Domain-specific skills (grasp a cup, move a chess piece, turn a patient) live in the L4 adapter layer of each application repo, not in the framework.

Status: Alpha

v0.1.0 is an alpha release. The API may still change before v1.0 — breaking changes will be prefixed with ! in the commit message and called out explicitly in the CHANGELOG.

The next anima roadmap node is expand the skill library + stabilize the v0.2 API (alongside the soma-care v0.4 contact-rich skills), followed by a v1.0 stable release (frozen API, complete docs, PyPI).