# @leumas/body — the Universal Body Engine

The Universal Body Engine — the species-agnostic biological primitive: a typed anatomical graph, a species/variant registry, ontology source adapters (Uberon), fuzzy anatomical search...


A new Leumas primitive: **BODY**. A species-agnostic anatomical graph, a species/variant registry,
ontology source adapters, anatomical search, typed traversal and pathfinding, a physiology layer, a
dataset validation engine, and the provenance model that makes every fact citable.

Zero runtime dependencies. Pure isomorphic ESM — the same code answers `/api/body` on the server and
drives the viewer in the browser, so a rule cannot disagree with itself.

```js
import { createSpeciesRegistry, loadBody, ask } from '@leumas/body';
import { installShippedSpecies } from '@leumas/body/data/species/index.js';

const registry = installShippedSpecies(createSpeciesRegistry());
const body = await loadBody({ registry, species: 'human', variant: 'adult-female' });

body.search('cranial nerve').results;          // canonical ids, with HOW each matched
body.describe('heart');                        // the full card, with sources
body.contains({ withinId: 'region:human:hand', category: 'bone' });   // 38 bones
body.trace({ from: 'heart right ventricle', to: 'left cardiac atrium' });
ask('What supplies the heart with blood?', body);   // facts + visual actions + citations
```

## The claim this package exists to make

> **The 3D model is not the body.** The body is a graph; a mesh is one representation hung off a node
> of it.

Every question above is answered with no geometry loaded. Almost every structure has no mesh and is
fully usable.

> **Most positions in this atlas were derived, not authored.** The human body plan places every bone,
> every named joint, every muscle group, the viscera and the major vessels and nerves by hand; the
> rest are put inside whatever the ontology says contains them. `check:body` prints the live split.
> Every placement carries the tier it was arrived at and a sentence explaining it. Read
> `docs/placement.md` before quoting a position anywhere.

## Human is data, not code

Grep `src/` for `human` and you find nothing. It appears in exactly two places: `data/species/human/*`
and the list of shipped species. `data/species/test-organism/` — a synthetic twelve-structure creature
with three systems that are not human systems — is installed through the same registry and exercised
by `test/cross-species.test.js`. That test is the alarm that goes off when the engine quietly learns
what a heart is.

## What ships

| | |
|---|---|
| **human** | 12 systems · 13 regions · 2 variants (male, female) |
| **dog** | 12 systems · 13 regions · 6 variants (three sizes × two sexes) |
| **test-organism** | 3 systems · 2 regions · 2 variants — synthetic, and the reason the engine stays generic |
| Sources | Uberon 2026-06-19 (CC BY 4.0) · OpenStax A&P 2e (CC BY 4.0) · Sisson *Veterinary Anatomy* 1910 (public domain) · Leumas curation |
| Geometry | schematic primitives — see `data/licenses/manifest.json` for why, and what was NOT taken |

Structure and relationship counts are not written here on purpose: they move on every ontology
refresh, and a number in prose is a number that goes stale silently. `pnpm check:body` prints the
live ones, and `ingest.report.json` per species records how that slice was selected.

## The layout

```
src/
  relations.js      the 64 closed relationship types, their inverses and their RO/BFO ids
  schema/           the entity contracts + per-record validators + the id grammar
  graph/            typed adjacency, traversal, pathfinding, sub-graphs
  search/           fuzzy anatomical search over labels, synonyms and ontology aliases
  registry/         species installation and variant resolution
  query/            natural language → graph plan → structured facts + visual actions
  validate/         the cross-record contract every shipped dataset passes
  adapters/         the AnatomySourceAdapter seam + the Uberon OBOGraph adapter
  serialize.js      the on-disk form (interned sources) and its round trip
  load.js           the SDK
  router.js         the express router factory (`@leumas/body/router`)
data/
  species/<id>/     one folder per body — five generated files, three curated ones
  licenses/         the machine-readable licence manifest
docs/               one file per "how do I add a …"
```

## Prove it

```sh
pnpm --filter @leumas/body test    # 37 tests
pnpm check:body                    # the dataset, licences, lessons, manifests — and its own self-test
pnpm anatomy:validate              # every shipped species, as a report
```

## Read next

`docs/README.md` for the developer guides · `.claude/skills/leumas-body/SKILL.md` for the agent's view.


---
Source: shared/packages/body/README.md
Canonical: https://docs.leumas.tech/p/packages/body