@leumas/body — the Universal Body Engine

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.

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

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

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.