Eve library

Galatea — Systems Deep Dive

Guide

Revision 1

On this page

The libs/galatea/ area: a humanoid-robotics software stack for fashion-retail and entertainment robots — kinematics, whole-body control, locomotion, embedded firmware, perception, ISO 13482 safety, choreography, fleet ops, garment handling, and AI — built as ~37 Nx projects that mix TypeScript domain logic with no_std Rust crates for the real-time/embedded paths.

What this area is#

Galatea (named for Pygmalion's statue brought to life) is a library-only domain that implements a full robotics stack for humanoid "robot mannequin" platforms. It spans from low-level motor firmware up through kinematics, balance, perception, behavioural AI, and multi-robot show choreography. Every project carries the scope:galatea, type:lib, layer:domain Nx tags and a galatea:<name> tag, and every TypeScript library exports a GALATEA_LIBRARY_ID constant plus a getGalateaLibraryId() accessor for runtime module identification.

The area is polyglot by design, exactly as the monorepo's stack policy prescribes (TypeScript by default, Rust where performance/real-time requires it). The performance-critical and embedded layers — kinematics, whole-body-control, locomotion, pose-engine, hardware-abstraction, firmware, and communication — ship companion Rust crates (#![no_std] for the on-robot paths). Two patterns appear. In hardware-abstraction and firmware the Rust crate is the implementation and the TypeScript surface is a thin, typed *-rust-manifest.ts descriptor that records the crate path, target profile, and capability list (e.g. CANFD_INTERFACE_RUST_MANIFEST). In kinematics, whole-body-control, locomotion, pose-engine, and communication there is a full TypeScript implementation alongside a companion Rust crate, linked by the same manifest convention — so a node like inverse-kinematics has both a TS solver (inverse-kinematics.ts) and a Rust hierarchical-QP solver (rust-inverse-kinematics/src/inverse_kinematics_qp.rs, JOINT_COUNT = 52).

I verified the Rust is real, not scaffold: the small (3–5 line) lib.rs files are crate roots that delegate via pub mod to sibling modules, and summing each crate's .rs files gives 95–2474 lines of genuine domain code per crate (FOC park/clarke motor control, EtherCAT/CAN-FD/DDS/PTP/WiFi-mesh comms, stereo SLAM, QP IK, etc.). An adversarial stub scan across the area came back clean — the only Math.random() in non-test code is annotated retry-backoff jitter in core/src/errors/error-recovery.ts, and the only placeholder() is a const fn array-seed in the Rust auto-tuning module.

How the area is shaped#

The dependency graph (per docs/domains/galatea/README.md) layers bottom-up: @galatea/core (shared types/constants/utils/errors) underpins the hardware, motion, and safety layers; perception and safety sit beside hardware; kinematics / whole-body-control / locomotion form the motion tier; @galatea/ai is the intelligence tier; and the application tier (fleet, choreography, garment-management, simulation, analytics) plus the developer sdk sit on top. Three projects — @galatea/database, @galatea/event-handlers, and @galatea/inclusivity — are namespace parents: their own src/index.ts carries only the library-ID marker, while the substantive code lives in independently-importable child projects (e.g. @galatea/database/pose-store). @galatea/sdk is a hybrid parent+client: its src/index.ts re-exports the in-project TS client (client-ts) and the client-python manifest, so it is not a pure marker-only aggregation root.

How it fits the wider system#

These are libraries, not running services — there is no Galatea app process here; consumers compose the libraries. Higher tiers import lower ones directly (the IK solver imports GALATEA_JOINT_KINEMATIC_CHAIN and GALATEA_JOINT_LIMITS from @galatea/core; the SDK client wraps fleet/show/analytics operations). The embedded Rust crates target on-robot controllers (edge-linux / rt-preempt profiles) and are referenced from TypeScript only as manifests, so the build graph stays buildable in a Node toolchain while the real-time code is compiled for the robot. External integrators consume the @galatea/sdk family — a TypeScript client and a typed Python package (galatea_client). Walk the "used by" edges on any node below to see exact consumers.

Entity reference#

@galatea/core#

The foundational library every other Galatea node depends on (libs/galatea/core/src). It owns the shared domain vocabulary: types/ (pose/motion, robot-state), utils/ (quaternion.ts, se3.ts, trajectory-interpolation.ts, procedural-motion.ts), constants/ (physical-constants, morphing-constants, safety-thresholds), config/runtime-config.ts, and errors/ (a structured error-taxonomy plus error-recovery with exponential-backoff-with-jitter). It exports the canonical kinematic chain (GALATEA_JOINT_KINEMATIC_CHAIN), joint limits, toRotationMatrix, and Quaternion/Vector3 types consumed across the motion stack. Real, ~5k lines of TypeScript.

@galatea/kinematics#

Computational kinematics (libs/galatea/kinematics/src) with both TypeScript and Rust solvers across six modules: forward-kinematics (computeFullBodyForwardKinematics), inverse-kinematics, dynamics, collision-geometry, jacobian-computation, and urdf-parser. Each module pairs a real TS implementation with a companion #![no_std] Rust crate linked by a *-rust-manifest.ts; for example inverse-kinematics.ts solves a prioritised multi-task (end-effector / COM / gaze / posture) damped-least-squares problem in TS, while rust-inverse-kinematics implements a hierarchical QP over JOINT_COUNT = 52 with joint/velocity constraints. Substantial and genuine on both sides.

@galatea/whole-body-control#

Whole-body / operational-space control (libs/galatea/whole-body-control/src): task-space-controller, impedance-controller, admittance-controller, postural-controller, center-of-mass, and momentum-controller. Each is a real TS controller with a companion Rust crate (95–190 lines of .rs per crate, e.g. rust-momentum-controller) for the real-time path. It provides the compliant- interaction and balance-regulation layer that locomotion and the AI tiers drive.

@galatea/locomotion#

The largest motion library (libs/galatea/locomotion/src, ~15.6k TS lines, 29 spec files). Beyond the classic bipedal controllers — gait-planner, balance-controller, footstep-planner, step-controller, push-recovery, stair-navigation, walking-styles (each with a companion Rust crate) — it carries an extensive procedural-animation suite the domain README under-documents: procedural-walk-cycle, procedural-bird-flight, procedural-fish-swimming, procedural-snake-locomotion, procedural-arthropod-locomotion, procedural-quadruped-locomotion, procedural-reach-and-grab, procedural-head-look-at, procedural-lip-sync, procedural-emotion-blending, procedural-appendage-animation, secondary-motion, terrain-adaptive-foot-placement, wind-reactive-fabric-hair, and control-rig-integration. All real TypeScript.

@galatea/pose-engine#

Humanoid pose generation and validation (libs/galatea/pose-engine/src): breathing-simulator, contrapposto-solver, hand-pose-library, micro-movement-gen, pose-library, pose-optimizer, pose-validation, and transition-planner. It produces the lifelike "presence" behaviours (subtle breathing, micro-movement, classical contrapposto stances) plus joint-limit and garment-safety validation (JointLimitViolation, GarmentSafetyViolation types). Each module has a real TS implementation backed by a companion Rust crate.

@galatea/hardware-abstraction#

The hardware abstraction layer (libs/galatea/hardware-abstraction/src). Rust-primary: every module's TypeScript index.ts re-exports only a typed *-rust-manifest.ts descriptor (the TS surface is ~220 lines total), while the real implementation is #![no_std] Rust — joint-interface, actuator-profiles (with auto-tuning), sensor-fusion, body-morphing, face-system, hand-system, thermal-management, rfid-reader, and tactile-skin, each crate 548–1672 lines of genuine code. The manifests record crate path, target profile, and capabilities for the build graph; the algorithms live in the crates.

@galatea/firmware#

Low-level embedded firmware (libs/galatea/firmware/src), also Rust-primary with TS reduced to driver manifests (~396 TS lines). The crates are real and sizeable #![no_std] embedded code: motor-drivers/rust-foc (~2.5k lines of field-oriented control — Clarke/Park transforms, current protection, multi-mode control, motor identification), safety-controller (~2.1k lines), power-management, comms-bus, rtos-runtime, bootloader, board-support, and a sensor-interfaces family of device drivers (rust-bno085 IMU, rust-mini45 F/T, rust-vl53l5cx ToF, rust-tactile-skin, rust-foot-pressure), each 440–675 lines.

@galatea/communication#

Robot communication protocols (libs/galatea/communication/src). Unlike firmware and hardware-abstraction, this library has both a real TS surface and companion Rust crates per protocol: ethercat-master, canfd-interface, dds-bridge (ROS 2 interop), wifi-mesh (multi-robot mesh, ~1.2k-line crate), cloud-connector, and ptp-sync (IEEE 1588). The *-rust-manifest.ts files (e.g. CANFD_INTERFACE_RUST_MANIFEST) bind each TS module to its crate and record edge-Linux/RT-PREEMPT targets and capability sets. All six crates are substantial (443–1245 lines).

@galatea/perception#

Computer vision and environment understanding (libs/galatea/perception/src), TypeScript-only and substantial (~6.1k lines): audience-awareness, camera-only-perception, depth-processing, fit-analysis, garment-recognition, obstacle-detection, person-detection, slam, and visual-servoing. The slam module (~848 lines) models a stereo visual-SLAM pipeline with calibration, feature observations, landmarks, keyframes, loop-closure events, and a mapping/localization-only mode switch.

@galatea/safety#

ISO 13482 personal-care-robot safety infrastructure (libs/galatea/safety/src, ~5.1k TS lines): iso-13482 (operating-state machine, HAZOP guide-word analysis, ISO 12100 risk assessment with Iso12100RiskLevel low→intolerable), risk-assessment, force-limiting, emergency-systems, functional-safety (watchdogs), regulatory-toolkit, audit-logger (tamper-aware event logging), and access-control. Real, domain-specific safety-standard modelling rather than generic CRUD.

@galatea/ai#

The intelligence tier (libs/galatea/ai/src, ~15.9k TS lines, 22 spec files) with sixteen modules barrelled from index.ts: vla-runtime, behavioral-engine, natural-motion-gen, customer-engagement, llm-interaction, emotion-expression, fashion-trend-ai, attention-prediction, reinforcement-learning, quiet-locomotion, end-to-end-control (with reflex-vla-runtime), large-behavior-model (flow-matching/diffusion-transformer training config plus an lbm-evaluation-suite), motor-cortex-policy, teleoperation, data-collection (plus training-data-management), and training-infrastructure. These are deterministic, configuration-and-orchestration implementations of the model pipelines (types, schedules, evaluation), not bundled model weights.

@galatea/choreography#

Multi-robot show authoring and performance (libs/galatea/choreography/src, ~9.8k lines): show-designer, show-dsl (a ~1.2k-line domain-specific language with show/robot declarations, track/formation/cue/parallel statements and cue departments), formation-engine, music-sync, lighting-bridge (DMX/ArtNet), stage-mapper, timing-engine, rehearsal-engine, and show-scheduler. It is the application-tier system that turns choreography into coordinated robot motion and stage effects.

@galatea/fleet#

Multi-robot fleet operations (libs/galatea/fleet/src, ~8.3k lines): orchestrator (task allocation), health-monitoring, scheduling-engine, ota-updates, raas-billing (Robotics-as-a-Service metering), remote-diagnostics, capacity-planning, incident-management, federated-learning, and digital-nervous-system (fleet-wide telemetry aggregation and anomaly detection). All real TypeScript application logic.

@galatea/garment-management#

Clothing and costume handling (libs/galatea/garment-management/src, ~3.8k lines): outfit-tracking (RFID/vision inventory), digital-product-passport (provenance), cloth-manipulation (grasp/pull/drape primitives with garmentlab/isaac-sim policy-training backends and dual-arm support), quick-change, fit-validation, wardrobe-scheduler, fabric-safety, and size-adaptation. This is the fashion-specific layer that distinguishes Galatea from a generic robot stack.

@galatea/simulation#

Physics simulation and digital twin (libs/galatea/simulation/src, ~7.9k lines): physics-engine (~1.5k lines, mujoco/isaac-sim backends, urdf/mjcf model loading, contact/friction/damping parameter sets), cloth-simulator, digital-twin, show-preview, rl-training-env (Gym-like), wear-simulator, virtual-showroom, and scenario-tester. Real simulation-orchestration TypeScript; the heavy physics backends are integration targets, modelled here as typed parameter/interface layers.

@galatea/analytics#

Engagement and business analytics (libs/galatea/analytics/src, ~8.7k lines): engagement-tracker, ab-testing, heatmap-engine (store-traffic heatmaps), pos-integration, inventory-bridge, revenue-attribution (~1.1k lines modelling robot-vs-static-mannequin display-variant attribution with exposure/sale events and cost models), and reporting-dashboard. Real attribution and experimentation logic, not stubs.

@galatea/database#

A namespace-parent library (libs/galatea/database/src): its own index.ts carries only GALATEA_LIBRARY_ID and getGalateaLibraryId(). The substantive persistence code lives in five independently-importable child store projects (below). It is an intentional thin aggregation root, not an empty scaffold.

@galatea/database/pose-store#

Pose persistence (libs/galatea/database/pose-store/src/pose-store.ts, ~757 lines). A real store defining pose record schemas, validation, and query/append operations for the pose-engine data — re-exported from the one-line index.ts.

@galatea/database/event-store#

Operational/safety event persistence (libs/galatea/database/event-store/src/event-store.ts, ~658 lines). Defines event-domain and severity taxonomies (EventDomain, EventSeverity), operational-event record schemas, append inputs, and SQL schema generation (EventStoreSchemaSql, EventStoreSchemaOptions). Real, domain-specific.

@galatea/database/telemetry-store#

Telemetry persistence (libs/galatea/database/telemetry-store/src/telemetry-store.ts, ~1.3k lines — the largest store). Handles time-series robot telemetry record schemas and aggregation/query operations. Real implementation.

@galatea/database/garment-store#

Garment data persistence (libs/galatea/database/garment-store/src/garment-store.ts, ~1.0k lines). The store for outfit/garment records backing garment-management, with schemas and query operations. Real implementation.

@galatea/database/show-store#

Show/choreography persistence (libs/galatea/database/show-store/src/show-store.ts, ~865 lines). Stores show definitions, schedules, and performance records backing the choreography and fleet scheduling tiers. Real implementation.

@galatea/event-handlers#

A namespace-parent library (libs/galatea/event-handlers/src): index.ts holds only the library-ID marker. The real event-processing logic lives in five child handler projects (below), one per event family.

@galatea/event-handlers/robot-events#

Robot lifecycle/status event processing (libs/galatea/event-handlers/robot-events/src/robot-events.ts, ~1.6k lines — the largest handler). Models robot lifecycle states, subsystem states, registration, boot self-test sequences (BootSelfTestCheck, SelfTestReport), and status transitions. Real, domain-specific.

@galatea/event-handlers/safety-events#

Safety-system event processing (libs/galatea/event-handlers/safety-events/src/safety-events.ts, ~849 lines). Handles emergency-stop, hazard, and safety-state-transition events from the @galatea/safety layer. Real implementation.

@galatea/event-handlers/show-events#

Show-performance event processing (libs/galatea/event-handlers/show-events/src/show-events.ts, ~1.1k lines). Processes cue/timing/performance events emitted during choreographed shows. Real implementation.

@galatea/event-handlers/garment-events#

Garment-interaction event processing (libs/galatea/event-handlers/garment-events/src/garment-events.ts, ~627 lines). Handles outfit-change, fit, and garment-tracking events. Real implementation.

@galatea/event-handlers/customer-events#

Customer-interaction event processing (libs/galatea/event-handlers/customer-events/src/customer-events.ts, ~470 lines). Processes engagement/interaction events feeding the analytics and customer-engagement layers. Real implementation.

@galatea/inclusivity#

A namespace-parent library (libs/galatea/inclusivity/src) holding only the library-ID marker; the real inclusivity logic lives in four child projects (below). Thin aggregation root.

@galatea/inclusivity/body-profiles#

Body-profile configuration (libs/galatea/inclusivity/body-profiles/src/body-profiles.ts, ~667 lines). Defines body-shape and gender-presentation taxonomies, US/EU sizing scales (WOMENS_US_SIZES, MENS_ALPHA_SIZES), and a BodyProfileRegistry (createBodyProfileRegistry()) for diverse body-type configuration. Real domain-specific code.

@galatea/inclusivity/accessibility#

Accessibility adaptations (libs/galatea/inclusivity/accessibility/src/accessibility.ts, ~1.4k lines — the largest inclusivity module). Implements accessibility configuration and adaptation logic for diverse user needs. Real implementation.

@galatea/inclusivity/cultural-config#

Cultural customization (libs/galatea/inclusivity/cultural-config/src/cultural-config.ts, ~1.4k lines). Configures market/region-specific customizations (etiquette, gestures, presentation norms) for international deployment. Real implementation.

@galatea/inclusivity/multilingual#

Multilingual support (libs/galatea/inclusivity/multilingual/src/multilingual.ts, ~925 lines). Handles language configuration and localization for international robot deployment. Real implementation.

@galatea/sdk#

A namespace-parent plus the TypeScript developer client (libs/galatea/sdk/src). Its index.ts re-exports client-ts/client.ts (~1.1k lines: fleet/show/analytics operations and realtime robot-status subscriptions — FleetRobotStatus, ScheduleShowRequest, startDueSchedules, etc.) and a client-python/index.ts that is a typed manifest (GALATEA_PYTHON_CLIENT_SDK_MANIFEST) pointing at the separate Python package. The two SDK extension projects (analytics-sdk, show-sdk) and the Python client are independent sibling projects.

@galatea/sdk/analytics-sdk#

A developer SDK extension for analytics (libs/galatea/sdk/analytics-sdk/src/analytics-sdk.ts, ~1.2k lines). Provides custom-event schema definitions, event tracking, and aggregate/ratio metric definitions for instrumenting and querying Galatea analytics. Real implementation.

@galatea/sdk/show-sdk#

A developer SDK extension for show authoring (libs/galatea/sdk/show-sdk/src/show-sdk.ts, ~943 lines). Offers builders for path/pose/pivot tracks and formation templates, music-sync point import, and a show validation/timing report (ShowValidationReport, ShowValidationTimingSummary). Real implementation.

@galatea/sdk/client-python#

A typed Python client package (libs/galatea/sdk/client-python, pyproject.toml, package galatea_client). It exposes GalateaClient with FleetClient, show, and analytics sub-clients over a backend abstraction (backend.py), models.py dataclasses, a py.typed marker, and tests/test_client.py. The shipped backend is an InMemoryGalateaBackend, so the package is exercisable end-to-end against an in-memory implementation rather than a live service. Real, typed Python — the only non-TypeScript/Rust SDK in the area.