AGENTS.md — Guide for AI Agents Working on These Docs A "README for agents." If you are an AI assistant reading, navigating, or editing this documentation, read this first. It tells you where things live, what you may change, and the hard boundaries. This follows the agents.md convention and complements . Project overview This folder is the single source of truth for the WebGPU OS stack documentation. The stack has five subsystems: , , , , and . Start at for the human entry point and for a curated machine index. Where things are (navigate here) Curated, hand authored prose: , , and each subsystem's / / / . Generated API reference: — produced from source by . Navigation manifest: (the one place that defines curated nav for all viewers). Tooling: (Python only — no Node). Conventions: (style guide, API standard, AI & accessibility, workflow). Commands (run from ) After editing Markdown, run . After touching source code that has reference pages, run then . What you MAY change Curated pages under (follow the style guide). The section (everything below the marker) in any generated reference page — this is preserved across regenerations. when adding/removing curated pages. Hard boundaries (do NOT do these) Do not edit generated content above in — it is overwritten on the next run. To fix a signature or description, edit the JSDoc in the source file upstream , then regenerate. Do not edit files outside as part of docs work. The originals under , , , and per component files are read only reference sources . (The single exception, already made, is the app under .) Do not invent APIs, file paths, or behavior. Every claim about how something works must be verifiable against a source file — cite it (e.g. (Source: §4) ). If unsure, say so rather than guessing. Do not auto run network


how something works must be verifiable against a source file — cite it (e.g. (Source: §4) ). If unsure, say so rather than guessing. Do not auto run network or destructive commands (e.g. , deletes) without explicit human approval. Code & writing style Active voice, short sentences, descriptive link text, alt text on images/diagrams. See Docs Style Guide. Keep Markdown plain and standard (the zero build viewer has only a minimal fallback parser). Make sections self contained : front load context, avoid "as mentioned above," so a chunk read in isolation still makes sense. See AI & Accessibility. Security considerations Never put secrets (keys, tokens, passwords) in documentation or examples. The docs describe a real security/trust model; keep Security & Trust Model accurate and do not weaken or misstate capability/permission claims. Treat the generated reference as machine extracted : it can lag the source. Verify against the cited source file before relying on it. Verify your work Run — it must exit 0 (all nav paths resolve). Open over HTTP and click through changed pages (no "Page not found"). Run through the Writing Checklist.


Changelog

Changelog
[Unreleased]
Changed
Added
Notes
[0.1.0] — 2026-06-05
Added

Changelog All notable changes to this documentation set are recorded here. Format follows Keep a Changelog; this set is versioned independently of the code. [Unreleased] Changed Updated Particle Realms Studio to the six stage recipe workflow: recipe backed demos, Simulate first tuning, project schema v2, typed recipe plans, native adapters, bounded evidence paths, and CSE/sandbox persistence. Legacy Artist/Twin sidecars remain losslessly compatible without appearing as workspaces. Expanded Recipe into a full width visual typed builder with add/remove/connect/disconnect operations, draggable persisted node positions, exact invalid draft diagnostics, last valid execution plan retention, a bounded measured native readback preview, and direct navigation to the authoritative Simulate canvas. Scoped dialog styling now prevents the Recipe workspace from inheriting modal width and height constraints. Changed Simulate to keep its tuning drawer closed until explicitly requested and replaced user selectable particle tiers with an automatic, measured population controller targeting stable 60 FPS. Population uses smoothed cadence, hysteresis, cooldown, workgroup quantization, and only internal device/runtime safety ceilings. Added Initial restructured documentation set in (single source of truth). Zero build HTML viewer ( ) with sidebar nav, search, in page TOC, code copy, and Mermaid support, plus a built in fallback Markdown renderer. Viewer QoL pass: collapsible/nested API reference tree (lazy rendered, per folder counts), sidebar filter box ( ) with highlighted matches, custom themed scrollbars, breadcrumbs, reading progress bar, back to top button, collapse all control, and persisted open/scroll state via . Active reference pages auto expand their folders and scroll into view.


Changelog

bar, back to top button, collapse all control, and persisted open/scroll state via . Active reference pages auto expand their folders and scroll into view. AI safe & human safe pass: (agent boundaries/commands), + (llmstxt.org discovery standard) generated by , YAML frontmatter support across the viewer + build tools (title/description/updated; reference pages stamped + ), a AI & Accessibility conventions page, a home page accuracy/safety notice, per page View source links, and accessibility upgrades ( , / ). Discovery & metadata pass: (allows crawlers, references + the indexes); a repo wide root for coding agents (the one stays docs scoped); git based "last updated" fallback — now emits and the viewer uses it when a page has no frontmatter; and hand authored / / frontmatter on every curated page (Getting Started, Concepts, all five subsystems, and Contributing). Author attribution: Author & Credits page, a persistent "Built by Jake Wehmeier" viewer footer credit, and SPDX license headers across the docs tooling and the wider source tree (see root , , and ). Ported website guides: the curated guides from were hand ported into MD as the single source of truth — a new Guides (How To) section (Capabilities — What You Can Build, Engine Stack Usage) plus Engine deep dives (Virtual GPU, ECS v2, Rendering, Shaders & WGSL, Particle System, Physics, GPU Physics Engine, Math Library, Audio). Website single source docs: the public site's Guide and API tabs now embed the MD zero build viewer ( + are thin shells over ), backed by a new API Reference hub. now ships into on every build (fresh cache, no manual copy) for both the website embeds and the WebGPU OS , refreshing the search index first; the dev embed path is rewritten to for the release layout. Hand authored notes overlay


Changelog

website embeds and the WebGPU OS , refreshing the search index first; the dev embed path is rewritten to for the release layout. Hand authored notes overlay for the API reference: notes now live outside the generated pages in , so the 1700 reference files stay purely generated (regenerable from scratch) while prose is never clobbered. injects them below the marker on every run: per page notes ( ) and reusable shared blocks ( ) applied to many pages by glob — write common context once instead of copying it onto every page. Expanded to 13 shared blocks with detailed runnable examples: GPU device sharing, package trust tiers, AGI training loop, Plauna lifecycle, ECS pattern (complex queries, system groups, ev


WebGPU OS Documentation (`MD/`)

WebGPU OS Documentation (MD/)
Three viewers, one source
Layout
Regenerate derived artifacts

WebGPU OS Documentation ( ) This folder is the single source of truth for the whole stack's documentation: plain Markdown that AI tools read directly, rendered for humans by three viewers that all read these same files. Start reading: (the docs home). Style & process: and . Three viewers, one source 1. Zero build HTML viewer — serve the repo and open (e.g. ). No build step. 2. MkDocs Material — . 3. app in WebGPU OS — open Docs from the OS Start Menu (embeds the same viewer). Layout Regenerate derived artifacts Run from (Python only — no Node): Existing docs under , , , and per component files are read only reference sources ; new documentation lives here.


Author & Credits

Author & Credits
About the author
Selected work
Connect
Credits & acknowledgements
License

The entire WebGPU OS stack was designed and built by Jake Wehmeier (BTSpaniel). Author & Credits The entire WebGPU OS stack — the engine , the editor , Plauna , AGI , and the WebGPU OS that composes them — was designed and built by Jake Wehmeier . About the author Jake Wehmeier is a Canada based developer who works across the whole stack, from small scripts and Python tools to a from scratch, browser resident, GPU first operating system. He is the sole author of this project, which also carries its original name Particle Realms (ParticleRealms.Online). On GitHub (@BTSpaniel) his profile reads, plainly, "I make Batch Scripts Because I'm lazy." — but the work collected here tells a larger story: a hand built WebGPU engine, an editor, a UI framework, a reinforcement learning rig, and an OS, assembled without heavy third party framework dependencies. The biographical details on this page are limited to what is publicly verifiable (his GitHub profile) and what the author has stated directly. If anything here is wrong or you'd like to expand it, edit this page — it is the canonical place the project credits its author. Selected work — the WebGPU engine at the heart of this stack. NodesIn.Space — frontend project (JavaScript). Dubtitles — Python project. Augment — Python project. Connect GitHub: github.com/BTSpaniel Threads: @zisishans Project site: ParticleRealms.Online Credits & acknowledgements Design, architecture, and implementation: Jake Wehmeier. Documentation viewer — vendored open source libraries (used by the zero build viewer, all permissively licensed): marked — Markdown parser (MIT). highlight.js — syntax highlighting (BSD 3 Clause). Mermaid — diagrams (MIT). License See the project and at the repository root for licensing and attribution terms.


AGI Architecture

AGI Architecture
Layers
Tensor library (agi/tensor/)
Neural networks (agi/brain/)
RL control (agi/core/)
Scene and rig
Studio (agi/studio/)
Multi-runtime + API
Performance targets
See also

How AGI is layered — a WebGPU tensor library, neural networks, an RL control loop, and the rig visuals plus AGI Studio. AGI Architecture How AGI is layered: a WebGPU tensor library at the bottom, neural networks above it, an RL control loop on top, and the rig visuals + Studio around it. Layers Tensor library ( ) A zero dependency tensor implementation on WebGPU: Operations including softmax, layernorm, dropout. A compute graph for chaining operations. WebGPU compute shaders in (matmul, activation, reduction). Automatic differentiation (gradient tape) and a tensor cache for memory management. Neural networks ( ) Policy network (12→64→64→17, tanh) and value network (12→64→64→1, linear). PPO trainer ( ), optimizers (Adam/AdamW/SGD), losses (policy/value/entropy), and training utils (GAE, normalizer, scheduler). Forward/backward passes and network serialization (save/load). RL control ( ) — the main training loop driving episodes. — builds the 12D observation each step. — applies the 17D action as bone impulses. — configurable reward weights. — advances through the 7 training stages. — motion matching guidance. Scene and rig — training scene controller, infinite grid ground, tracking camera, WebGPU scene renderer, debug visualizer. — brain sphere with pulse animation, the 17 tentacle injection system, tentacle renderer (curved paths, electrical effects), and neural activity visualization. Studio ( ) A professional workspace app: core ( , project/workspace managers), panels (Scene/Training/Network/Curriculum), visual editors (Reward/Network/Curriculum/Action), visualizers (Graph/Network/Activation/Gradient), and tools (Exporter/Recorder/Benchmarker/Debugger). Multi runtime + API exposes a Gym compatible environment interface. provides optional WebGPU/Python/WASM/Rust/C++


AGI Architecture

(Exporter/Recorder/Benchmarker/Debugger). Multi runtime + API exposes a Gym compatible environment interface. provides optional WebGPU/Python/WASM/Rust/C++ runtime adapters. Performance targets Physics 60 FPS (16.67 ms), neural inference < 5 ms/forward pass, rendering < 8 ms/frame, total memory < 1 GB. See also Training Guide. AGI API Reference — , , , .


AGI Getting Started

AGI Getting Started
Requirements
Launch AGI Studio
then browse to:
http://127.0.0.1:9001/agi/studio/
First run
Default hyperparameters
Next steps

Launch AGI Studio and start a training run, with the requirements and steps from the AGI README. AGI Getting Started Launch AGI Studio and start a training run. Based on . Assumes Install & Run is done. Requirements A current browser that exposes WebGPU on the machine. Verify both and a successful call. 8 GB RAM minimum (16 GB recommended); a dedicated GPU recommended. Launch AGI Studio First run 1. Create or load a project — click New Project in the header. The system initializes with default settings and configures the WebGPU device. 2. Start training — click Start Training in the viewport controls. The parasite rig injects into the ragdoll; metrics update live; training runs at 60 FPS. 3. Save your model — click Save Model ; the model downloads as JSON. Load it later to continue. Default hyperparameters Parameter Value Learning rate 3e 4 Clip range 0.2 Gamma 0.99 Lambda (GAE) 0.95 Batch size 64 Buffer size 2048 Next steps Training Guide — stages, tuning, troubleshooting. AGI Architecture — how the pieces connect. AGI API Reference — , , .


AGI

Section index for AGI — RL animation rigging with a WebGPU tensor library and AGI Studio (overview, architecture, getting started, training guide, API reference). AGI Reinforcement learning animation rigging ("parasite rig") with a WebGPU tensor library and AGI Studio. Source: . In this section Overview — what AGI is and how the RL loop works. Architecture — tensor → brain → core → scene/rig → studio. Getting Started — launch Studio and start training. Training Guide — curriculum, tuning, troubleshooting. API Reference — per file symbols from (browse ). Module map Related GPU Device Sharing — the tensor library runs on the shared device. Engine — AGI is built on Engine v2.


AGI Overview

AGI Overview
What it provides
Audience
How it works (RL loop)
Module map
Next steps

The reinforcement-learning animation rigging system — a "parasite rig" with its own WebGPU tensor library, neural networks, curriculum, and AGI Studio. AGI Overview AGI ( ) is a reinforcement learning animation rigging system: a "Doc Octavius" style mechanical parasite rig that injects into a humanoid ragdoll and learns to control it through RL. It ships its own WebGPU tensor library , neural networks, a curriculum system, and AGI Studio — a full training workspace application. What it provides From : A custom WebGPU tensor library ( ) with compute shaders (matmul, activation, reduction) and automatic differentiation. Neural networks ( ): policy + value networks, PPO trainer, experience buffer, optimizers, losses. Core RL control ( ): ragdoll controller, observation builder, motor controller, reward function, curriculum manager, motion matching teacher. A parasite rig visual system ( ): brain sphere, 17 tentacles, neural pulses, injection animation. AGI Studio ( ): a workspace app with panels, editors, visualizers, and tools. Audience ML and animation developers training or extending the rig. How it works (RL loop) Observation space (12D): pelvis height, uprightness, angular velocity (3D), linear velocity (3D), ground contact (2D), target direction (2D). Action space (17D): one impulse based action per controllable bone, range . Algorithm: PPO (clipped surrogate objective) with GAE. Module map Module Path Purpose Core RagdollController, ObservationBuilder, MotorController, RewardFunction, CurriculumManager, MotionMatchingTeacher Brain policy/value networks, PPO trainer, optimizers, losses, training utils Tensor WebGPU tensor ops + compute shaders Rig parasite rig visuals (injection, tentacles, brain) Scene training scene, ground, camera, renderer, debug Studio the AGI


AGI Overview

WebGPU tensor ops + compute shaders Rig parasite rig visuals (injection, tentacles, brain) Scene training scene, ground, camera, renderer, debug Studio the AGI Studio workspace app Runtime runtime manager API Gym compatible environment API Adapters multi runtime adapters (WebGPU, Python, WASM, Rust, C++) Loader / Config / Data , , model loading, hyperparameters/curriculum/rewards, data Next steps AGI Architecture. AGI Getting Started. Training Guide. AGI API Reference — generated from .


adapters/PBDRagdollAgentAdapter.js

adapters/PBDRagdollAgentAdapter.js
Classes
class PBDRagdollAgentAdapter
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


brain/ExperienceBuffer.js

brain/ExperienceBuffer.js
Classes
class ExperienceBuffer
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Clear buffer Add experience to buffer Check if buffer is full Get all experiences Get batch of experiences Compute advantages using GAE (Generalized Advantage Estimation) Normalize advantages Get buffer statistics <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


brain/NetworkArchitecture.js

brain/NetworkArchitecture.js
Classes
class Layer
Constants
Notes & Examples
Creating a network
Observation preprocessing
Training configuration
Forward pass (inference)
Saving and loading
Gotchas
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Layer class represents a single neural network layer Method Signature Summary Initialize weights using orthogonal initialization Initialize biases to zero Forward pass Linear transformation Apply activation function Backward pass Activation gradient Get parameters (weights and biases) Get gradients Set parameters Constants — Network Architecture Definitions Layer configurations and hyperparameters for Policy and Value networks <! HUMAN NOTES Notes & Examples Neural network definitions for AGI agents. Supports feedforward, recurrent (LSTM/GRU), transformer, and custom architectures. Networks map observations to actions and are trained via policy gradients (PPO) or Q learning. Creating a network Observation preprocessing Training configuration Forward pass (inference) Saving and loading Gotchas Input normalization : Networks expect normalized inputs (mean=0, std=1). Use to add normalization layers. Action bounds : Continuous outputs use tanh ( 1, 1) — scale to your action space externally. Discrete actions use softmax + argmax. Gradient clipping : Essential for recurrent nets. PPO config defaults to clip by norm (0.5), but increase for very deep nets. See also: AGI Training Guide · ExperienceBuffer · PolicyNetwork Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


brain/PolicyNetwork.js

brain/PolicyNetwork.js
Classes
class PolicyNetwork
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Build network from architecture config Initialize network (async setup if needed) Forward pass compute actions from observations Backward pass compute gradients Get all network parameters Get all gradients Set network parameters Save network to JSON Load network from JSON Get network info <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


brain/ValueNetwork.js

brain/ValueNetwork.js
Classes
class ValueNetwork
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Build network from architecture config Initialize network (async setup if needed) Forward pass estimate value from observations Backward pass compute gradients Get all network parameters Get all gradients Set network parameters Save network to JSON Load network from JSON Get network info <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


brain/trainers/PPOTrainer.js
Classes
class PPOTrainer
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Train on batch of experiences Compute PPO losses Update networks with gradients Update parameters with gradients Helper functions <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


config/curriculum.js

config/curriculum.js
Constants
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Constants — Curriculum Learning Stages Progressive training stages from standing to full locomotion <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


config/hyperparameters.js

config/hyperparameters.js
Constants
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Constants — Neural Network Hyperparameters Configuration for Policy and Value networks, training parameters <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


config/rewards.js

computeReward(state, config = REWARDWEIGHTS.standing)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Compute reward for current state Parameters: (Object) — Current ragdoll state (Object) — Reward configuration Returns: Total reward Constants — Reward Function Weights Configurable reward components for different training objectives <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


core/CurriculumManager.js

core/CurriculumManager.js
Classes
class CurriculumManager
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Get current curriculum stage Get stage index Check if episode was successful for current stage Update curriculum after episode Check if should advance to next stage Advance to next stage Get reward configuration for current stage Get observation configuration for current stage Get perturbation configuration for current stage Reset to first stage Set specific stage (for debugging/testing) Get curriculum statistics <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


core/MotionMatchingTeacher.js

class MotionMatchingTeacher extends MotionMatcher


core/MotorController.js

core/MotorController.js
Classes
class MotorController
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Motor Controller Converts neural network actions into physics impulses Method Signature Summary Apply actions to ragdoll Action space (17 dimensions): One impulse vector per major bone Actions in range [ 1, 1] Scaled to appropriate impulse magnitude Bone mapping: 0: Pelvis, 1: Spine, 2: Head 3 4: Upper arms, 5 6: Lower arms 7 8: Upper legs, 9 10: Lower legs 11 12: Hands, 13 14: Feet 15 16: Shoulders Convert action value to 3D impulse vector Get forward vector from quaternion rotation Apply PD control to reach target pose (Alternative control method for fine tuning) Set impulse scale (for curriculum learning) Set PD gains Get action space info <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


core/ObservationBuilder.js

core/ObservationBuilder.js
Classes
class ObservationBuilder
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Observation Builder Converts ragdoll sensor data into neural network input Method Signature Summary Build observation vector from ragdoll state Observation space (12 dimensions): Pelvis height (1) Uprightness (1) Angular velocity (3) Linear velocity (3) Ground contact (2) left/right foot Target direction (2) x, z normalized Get up vector from quaternion rotation Check if bone is in contact with ground Normalize observation vector Get observation space info <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


core/RagdollController.js

core/RagdollController.js
Classes
class RagdollController
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Initialize controller Run single episode Check if episode should terminate Check if episode was successful Helper: Sum of squared values Get training metrics Save model Load model <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


core/RewardFunction.js

core/RewardFunction.js
Classes
class RewardFunction
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Compute reward for current ragdoll state Extract state information from ragdoll Compute reward from state Get up vector from quaternion rotation Set reward configuration Reset reward function state Get reward breakdown for debugging <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


index.js

index.js
Re-exports
Notes & Examples
Where this fits in the training loop
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Re exports , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/DeviceProfiler.js

llm/DeviceProfiler.js
Classes
class AIDeviceProfiler
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: DeviceProfiler.js WebGPU capability and LLM feasibility profiler. This module is intentionally browser native and dependency free. It can use the kernel's shared GPU device when available, or probe navigator.gpu directly for standalone AGI tests. Classes Method Signature Summary <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/formats/GGUFParser.js
Classes
class GGUFParser
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/formats/GGUFTensorReader.js
Classes
class GGUFTensorReader
Functions
bf16ToF32(value)
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Functions <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


prepareConversation(input, expectedId = null)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Accept a legacy bare conversation and return the canonical durable v1 envelope. Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/formats/ModelPackageReader.js
Classes
class ModelPackageReader
Notes & Examples
Where this fits in the training loop


llm/formats/ModelPackageWriter.js
Classes
class ModelPackageWriter
Notes & Examples
Where this fits in the training loop


inferQuantization(tensors = [], metadata = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


class UnsupportedTensorShardIndexVersionError extends Error

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Method Signature Summary Functions Accept legacy bare indexes and return a canonical, independently cloned v1 document. Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/index.js

llm/index.js
Re-exports
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Re exports , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , , <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


planAdaptivePreload(tensors = [], options = {})

adaptiveEvictionScore(name, entry = {}, options = {})


llm/inference/CpuTensorRunner.js
Classes
class CpuTensorRunner
Notes & Examples
Where this fits in the training loop


llm/inference/Gemma4GraphRunner.js
Classes
class Gemma4GraphRunner
Notes & Examples
Where this fits in the training loop


llm/inference/GenerationLoop.js
Classes
class GenerationLoop
Notes & Examples
Where this fits in the training loop


mapAsyncWithTimeout(buffer, mode, timeoutMs, message)


llm/inference/GpuRuntimeResources.js
Classes
class GpuParameterArena
class GpuBindGroupCache
Functions
uniformBinding(allocation)
isArenaAllocation(value)
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Method Signature Summary Functions <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/inference/GraphCompiler.js
Classes
class GraphCompiler
Notes & Examples
Where this fits in the training loop


llm/inference/InferenceEngine.js
Classes
class InferenceEngine
Notes & Examples
Where this fits in the training loop


llm/inference/KVCache.js
Classes
class KVCache
Notes & Examples
Where this fits in the training loop


llm/inference/LocalGGUFExecutor.js
Classes
class LocalGGUFExecutor
Notes & Examples
Where this fits in the training loop


createKQuantParityProbeData(quantization, { rows = SUBGROUPPROBEROWS } = {})


llm/inference/StaticMemoryPlanner.js
Classes
class StaticMemoryPlanner
Notes & Examples
Where this fits in the training loop


llm/inference/TransformerExecutor.js
Classes
class TransformerExecutor
Notes & Examples
Where this fits in the training loop


llm/inference/WeightCache.js
Classes
class WeightCache
Notes & Examples
Where this fits in the training loop


llm/kernels/KernelRegistry.js
Classes
class KernelRegistry
Notes & Examples
Where this fits in the training loop


async createComputePipelineChecked(device, module, { label, name = label, entryPoint = 'main' } = {})

async assertShaderCompiled(module, name = 'shader')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Functions <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/kernels/shaders/attentiondecode.js
Functions
shader()
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/dequantrowdense.js
Functions
shader({ format = 'F16' } = {})
shaderDequantF32(options = {})
shaderDequantF16(options = {})
shaderDequantBF16(options = {})
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/dequantrowkquant.js
Functions
shader({ quant = 'Q4K' } = {})
shaderDequantQ4K(options = {})
shaderDequantQ5K(options = {})
shaderDequantQ6K(options = {})
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/dequantrowq40.js
Functions
shader()
shaderDequantQ40(options = {})
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/dequantrowq80.js
Functions
shader()
shaderDequantQ80(options = {})
Notes & Examples
Where this fits in the training loop


shader({ quant = 'Q4K', workgroupSize = WORKGROUPSIZE } = {})


llm/kernels/shaders/matmulq4.js
Functions
shader()
Notes & Examples
Where this fits in the training loop


shader({ workgroupSize = WORKGROUPSIZE } = {})


shader({ format = 'F32', workgroupSize = WORKGROUPSIZE } = {})


shader({ quant = 'Q4K', workgroupSize = WORKGROUPSIZE, useSubgroups = false } = {})


shader({ hiddenSize = 1536, epsilon = '0.000001', workgroupSize = 256 } = {})


llm/kernels/shaders/ropebatch.js
Functions
shader({ theta = '10000.0' } = {})
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/ropefused.js
Functions
shader({ theta = '10000.0' } = {})
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/ropekvappend.js
Functions
shader({ theta = '10000.0' } = {})
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/ropetable.js
Functions
shader()
Notes & Examples
Where this fits in the training loop


llm/kernels/shaders/samplingtopktopp.js
Functions
shader()
Notes & Examples
Where this fits in the training loop


shader({ activation = 'gelupytorchtanh' } = {})


llm/kernels/shaders/vectorops.js
Functions
shader({ op = 'add' } = {})
Notes & Examples
Where this fits in the training loop


llm/runtime/LLMSession.js
Classes
class LLMSession
Notes & Examples
Where this fits in the training loop


logRuntimeEvent(event, data = {}, options = {})


llm/runtime/ModelRegistry.js
Classes
class ModelRegistry
Notes & Examples
Where this fits in the training loop


llm/runtime/PromptTemplate.js
Classes
class PromptTemplate
Constants
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/runtime/Sampler.js
Classes
class Sampler
Notes & Examples
Where this fits in the training loop


llm/runtime/Tokenizer.js
Classes
class Tokenizer
Notes & Examples
Where this fits in the training loop


llm/runtime/TokenizerWorkerClient.js
Classes
class TokenizerWorkerClient
Notes & Examples
Where this fits in the training loop


llm/runtime/ToolBridge.js
Classes
class ToolBridge
Notes & Examples
Where this fits in the training loop


async replaceJSONCopyOnWrite(store, path, value, { validate = null, label = 'JSON record' } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: Publish JSON through a verified staging file while retaining the previous revision until the replacement move succeeds. Functions Publish JSON through a verified staging file while retaining the previous revision until the replacement move succeeds. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


async checksumBytes(bytes, algorithm = 'SHA-256')

async checksumString(text, algorithm = 'SHA-256')


llm/storage/ModelCache.js
Classes
class ModelCache
Notes & Examples
Where this fits in the training loop


class ModelHandleStoreError extends Error

prepareModelHandleRecord(value, expectedModelId = null)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Method Signature Summary Functions Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/storage/OPFSStore.js
Classes
class OPFSStore
Notes & Examples
Where this fits in the training loop


llm/storage/VFSConversationStore.js
Classes
class VFSConversationStore
Notes & Examples
Where this fits in the training loop


llm/workers/LLMLoadPlannerWorker.js
Exports
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Exports No ES module exports detected in this file. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


llm/workers/LLMTokenizerWorker.js
Exports
Notes & Examples
Where this fits in the training loop


loader/ModelLoader.js

modelLoaderVertexDedupHash32(posBits, pOff, uvBits = null, uOff = 0)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Method Signature Summary Load model from file Load model from blob URL Parse GLB binary format Parse GLTF JSON Extract bone hierarchy for ragdoll Get bone count Get model info Functions <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. See also: AGI Training Guide · AGI Architecture Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


network/TrainingStateChannel.js

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: No file level description found in source. Add one as a leading JSDoc comment, or document it below. Classes Bind AGI Studio telemetry to the standard State Channel stack. The training runtime is authoritative; same origin tabs need no setup, and callers hosted inside WebGPU OS may pass NetworkDriver to publish over mesh. Method Signature Summary Functions Constants <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


createBreathReservoirState({ sampleIndex, pressure, compliance, targetSubglottalPressure })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: BreathReservoirState.js — Phase 2 Voice Box state schema ( ). "Lung pressure, compliance, target subglottal pressure" per §4 — the JS side state container wrapping 's per instance recurrence ( , proven against (R6A)). This module owns the derivation from / (the caller computed value that kernel's docstring says it expects pre computed, not recomputed in shader) and the timestamped state container the kernel's / buffers round trip through across chunks — it does not itself dispatch the kernel (that is 's job once a real model exists to drive it). Functions — matches (R6A)'s proven formula exactly; 's own docstring requires this be computed by the caller, not the kernel. Returns: A validated, timestamped for one instance. Advance one by one sample using the exact same recurrence / implement — the CPU side single sample equivalent, useful for tests and for any non GPU fallback path, not a replacement for the GPU kernel's chunked dispatch. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


impulseResponse(areas, { glottalReflection, lipReflection, responseLength, wallLoss = 1 })

findFormants(areas, sampleRate, options = {})

fitVowelAreas(target, numSections, sampleRate, options = {})

fitTargets(targets, numSections, sampleRate, options = {})

fitAllVowels(numSections, sampleRate, options = {})

fitAllApproximants(numSections, sampleRate, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: FormantSolver.js — Phase 3 ParticleVoice articulatory calibration. Measures the resonances a Kelly Lochbaum area profile actually produces, and inverts that: given target formants, searches for an area profile that hits them. Why this exists Vowel identity in speech is carried almost entirely by F1 and F2 . An area profile invented from articulatory adjectives ("high", "back", "rounded") produces some formants, but nothing forces them to be the RIGHT ones — and if they are wrong, every vowel collapses toward a neutral timbre and the speech is unintelligible no matter how clean the pipeline is. That was the state before this module: 's height/backness → area mapping was plausible but uncalibrated. Defining vowels by their measured formant targets and SOLVING for the geometry inverts the dependency: the targets are citable data (Peterson & Barney 1952 / Hillenbrand et al. 1995 male averages, whose vowel set maps exactly onto 's ten monophthongs), and the geometry becomes a derived quantity that stays correct if the section count or sample rate changes. The response is measured with the SAME recurrence the GPU runs reimplements 's scattering recurrence on the CPU rather than using an analytic transfer function. That is deliberate: an analytic formula would be a second model that could disagree with the kernel, and then a "calibrated" vowel would not actually be calibrated for the thing doing the synthesis. In particular this omits the lip first difference, matching 's (its source is already a flow derivative). Functions Impulse response of the lossless KL chain, mirroring 's recurrence (and, like , WITHOUT the lip first difference). Resonance frequencies of an area profile, lowest


response of the lossless KL chain, mirroring 's recurrence (and, like , WITHOUT the lip first difference). Resonance frequencies of an area profile, lowest first. Returns: Peak frequencies in Hz. Build the profile this solver searches over. exists because a single control point is not enough for high front vowels. interpolates LINEARLY between control points, so one narrow point produces a smooth V — a tract that tapers and re widens with no distinct cavities. /i/ needs the opposite: a genuinely SHORT front cavity (F2 = 2290 Hz implies c/(4 F2) 3.7 cm) sharply separated from a long back cavity. Giving the constriction a WIDTH creates that two cavity structure, and with it F2 values a single point cannot reach (an earlier 3 point version topped out at 1889 Hz against IY's 2290 Hz target, 333 cents low, which made IY and IH nearly identical in F2). A width of 0 degenerates to the original 3 point shape, so the parametrisation strictly extends the old one rather than replacing it. Search for an area profile whose first two resonances match . Error is measured in the LOG frequency domain, because formant perception is roughly logarithmic: being 100 Hz off matters far more at F1 = 270 than at F2 = 2290, and a linear error would happily sacrifice F1 accuracy to shave a little off F2. Exhaustive over a coarse grid, then a local refinement pass. Exhaustive rather than gradient based on purpose: the map from geometry to formants is non monotonic (moving a constriction can swap which cavity dominates F2), so a descent method lands in whichever basin it started in. Fit every entry in a formant target table. Slow (a full grid per entry) — intended for a calibration tool/test, not a hot path. The tract length a section count represents, for reporting alongside a fit. Constants —


grid per entry) — intended for a calibration tool/test, not a hot path. The tract length a section count represents, for reporting alongside a fit. Constants — Peterson & Barney (1952) male averages, Hz. Their vowel set — heed, hid, head, had, hod, hawed, hood, who'd, hud, heard — is exactly this project's ten monophthongs, so no mapping or interpolation is needed. F3 is carried for only, where the unusually LOW F3 is the defining rhotic cue; for the others F1/F2 determine identity. — The solved geometry for each vowel, produced by and baked here so the runtime does not pay for the search (a full grid per vowel takes tens of seconds). re verifies this table against the targets cheaply on every run, so it cannot


createNeuralPhysiologyState({ sampleIndex, respiratoryDrive, glottalState, tractGesture, articulationEvent = null, uncertainty = { confidence: 1 }, })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: NeuralPhysiologyState.js — Phase 2 Voice Box state schema ( ). The model's predicted per frame physiology state, per §4: four control heads plus an uncertainty head, version . This is a working definition of each head's field set — the heads themselves are named and required by the plan, but their exact field composition was not otherwise specified anywhere in the frozen documents, so the fields chosen here are deliberately the smallest set that maps DIRECTLY onto an already built, already tested GPU kernel's input parameters (not invented ahead of a consumer): → drives / . ( / / / / ) → the exact parameter names takes per instance. → the area profile / consume. ( / / ) → drives / injection points (the actual multi port coupling math those two kernels' docstrings still flag as deferred — this head only carries the control values, not a coupling implementation). → a single scalar per frame confidence, the minimal representation until a real model exists to justify a richer (e.g. per head covariance) shape. Like every other document in this project, this field set may still change before a freeze — it is not a claim that these are the final head shapes, only that they are usable today and traceable to real kernel inputs rather than speculative. Per §4's timestamping rule, every state object here carries the absolute sample counter it was produced at ( ), never a chunk relative index. Functions Returns: A validated , throwing on any missing/invalid required field rather than silently defaulting physiologically meaningful values. Constants — NeuralPhysiologyState.js — Phase 2 Voice Box state schema ( ). The model's predicted per frame physiology state, per §4: four control heads plus


Constants — NeuralPhysiologyState.js — Phase 2 Voice Box state schema ( ). The model's predicted per frame physiology state, per §4: four control heads plus an uncertainty head, version . This is a working definition of each head's field set — the heads themselves are named and required by the plan, but their exact field composition was not otherwise specified anywhere in the frozen documents, so the fields chosen here are deliberately the smallest set that maps DIRECTLY onto an already built, already tested GPU kernel's input parameters (not invented ahead of a consumer): → drives / . ( / / / / ) → the exact parameter names takes per instance. → the area profile / consume. ( / / ) → drives / injection points (the actual multi port coupling math those two kernels' docstrings still flag as deferred — this head only carries the control values, not a coupling implementation). → a single scalar per frame confidence, the minimal representation until a real model exists to justify a richer (e.g. per head covariance) shape. Like every other document in this project, this field set may still change before a freeze — it is not a claim that these are the final head shapes, only that they are usable today and traceable to real kernel inputs rather than speculative. Per §4's timestamping rule, every state object here carries the absolute sample counter it was produced at ( ), never a chunk relative index. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


sectionsForLength(lengthM, sampleRate, speedOfSound = SPEEDOFSOUNDMPERS)

lengthForSections(numSections, sampleRate, speedOfSound = SPEEDOFSOUNDMPERS)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleTract.js — Phase 2 ParticleVoice Voice Box orchestrator. The GPU resident articulatory synthesizer: composes the already verified Phase 2 articulatory kernels into audible speech, one fixed size chunk at a time, with all cross chunk state persisted ON THE GPU (no CPU round trip mid pipeline). This is the production counterpart of R6's pure CPU , and deliberately reproduces the same four controllable behaviors that probe proved: stable vowels, nasal coupling, closure/release/frication, and pitch sweeps. Signal graph per chunk (7 GPU passes + 4 state copies, ONE submit): glottal lf ────────────────► voicing ──┐ ├─ signal add ─► source flow ─┐ constriction noise(asp seed) ─► asp ────┘ │ ▼ constriction noise(fric seed) ─► frication ──────► tract waveguide (oral) │ │ radiated ◄─────────┘ └──► nasal tap │ │ │ nasal junction ◄────┘ │ │ └── signal add ◄── radiated │ ▼ final PCM Design decisions worth knowing: Frication is injected at the constriction, not the glottis. The frication noise buffer goes to 's input and is added to the right going wave at , so only the cavity in FRONT of the constriction filters it. Mixing it into instead would make every fricative sound like a whisper. Aspiration, which really is glottal, IS mixed into . No pass. already applies the radiation first difference internally (exactly as R6's does). Running on its output would differentiate twice and produce a thin, bass less buzz. That kernel exists for callers holding an undifferentiated signal. Fixed . / pack their radiated signal and persisted state into one buffer whose internal offsets depend on , so a varying chunk size would move every offset and invalidate the pre built bind groups. A fixed chunk


into one buffer whose internal offsets depend on , so a varying chunk size would move every offset and invalidate the pre built bind groups. A fixed chunk size is also what a real time audio bridge wants anyway ( schedules in fixed frame buckets), so it is required here rather than worked around. Reflection coefficients are computed CPU side each chunk via 's proven , matching 's stated contract. Changing between chunks is how closure/release is articulated. Visualization is optional and structurally incapable of changing the PCM. §4 requires visualization to be "bit identically disable able without changing rendered PCM". Here that is not a runtime convention but a structural property: when is 0 (the default) the visualization buffers, pipeline and dispatches are never created at all, and when it is enabled every visualization buffer is WRITE ONLY from the acoustic path's perspective — the field is copied OUT of / 's already final packed outputs, and nothing in the visualization path is ever read back into the acoustic path. makes the same guarantee at kernel level (it has no read write access to anything the acoustic path reads). Known limitations, stated honestly rather than papered over: and are DISPATCH WIDE (they live in the kernels' uniform structs, not per instance storage arrays), so all instances of one share them. Per instance variation would require promoting both to storage buffers. They are therefore top level controls here, not per instance ones, so the API does not imply a capability that does not exist. The nasal tap is a read only observation of the oral tract, not a rigorous 3 port scattering junction — the oral tract is not loaded by the nasal branch. This matches R6 exactly and is noted in 's docstring too. The visualization field carries the THREE


— the oral tract is not loaded by the nasal branch. This matches R6 exactly and is noted in 's docstring too. The visualization field carries the THREE per sample solver signals the kernels actually expose (oral radiated, nasal tap, nasal radiated), not one channel per tube section. §4 describes the richer per section field, but does not emit a field — only its radiated signal, final state and the single tapped section. Adding one would mean a output block ( 512 KB per chunk at 32 sections / 1024 samples) allocated whether or not visualization is on. That is a deliberate follow up, not an oversight; the three channels here are enough to drive a ribbon/heatmap of what the solver is actually radiatin


createPhysiologyFeedbackState({ sampleIndex, numFrames, mean, rms })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PhysiologyFeedbackState.js — Phase 2 Voice Box state schema ( ). §4's : "a reduced/decimated feedback signal from the acoustic solve back toward the model". The JS side timestamped container for one dispatch's output — per instance (mean, RMS) pairs, one pair per fixed size frame — distinct from 's multi channel visualization field ( 's output): this shape is what the model's control loop reads back, not what a rig/visual system reads. Every consumer of this state should treat it as internal physiology feedback, not a real acoustic measurement — matching §8's / / three domain separation (this is 's reduced form, never to be confused with a microphone observed or rendered PCM measured energy value). Functions Returns: A validated, timestamped for one dispatched reduction. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


createTractStateSnapshot({ sampleIndex, numChannels, numFrames, field })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TractStateSnapshot.js — Phase 2 Voice Box state schema ( ). §4's : "low rate timestamped state for rigs/visualization, decimated from the per sample waveguide state". The JS side timestamped container for one dispatch's output — a box averaged field (one channel per tube section, per that kernel's docstring), NOT the model feedback (mean, RMS) shape wraps ( 's output) — the two are read by different consumers (a rig/visual system here, the model's control loop there) and were kept as separate kernels for exactly this reason (see 's own docstring). Per §4's requirement that visualization "must be bit identically disable able without changing rendered PCM", this container holds ONLY derived/decimated data for display — nothing here is ever read back into the acoustic path, matching 's structural read only guarantee. Functions Returns: A validated, timestamped for one decimated field dispatch. Reads channel 's decimated time series out of a snapshot's flat field — matches 's packing (single instance view; the caller selects / slicing upstream of this helper). <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


createVoiceAnatomyProfile({ oralAreas, nasalAreas = null, glottalReflection = DEFAULTGLOTTALREFLECTION, lipReflection = DEFAULTLIPREFLECTION, nostrilReflection = DEFAULTNOSTRILREFLECTION, formantScale = 1, pitchRangeHz = { min: 80, max: 400 }, } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: VoiceAnatomyProfile.js — Phase 2 Voice Box state schema ( ). §4's : "persistent per character morphology (equivalent role to 's /pitch range calibration, but for non cloned/authored characters rather than captured voices)". This is the STATIC per voice data that stays constant across frames — the rest position oral tube area profile, optional nasal branch area profile, and the three boundary reflection coefficients / require ( / / , all magnitude for BIBO stability per (R6)) — as distinct from 's , which is the per FRAME predicted deviation/gesture applied on top of this rest profile, not a replacement for it. (R6/R6A) already proved out / , , , as one working anatomy — below reuses those exact proven values as the default rather than inventing new ones. Functions Returns: A validated, immutable . The R6/R6A proven default anatomy (uniform tube, no nasal coupling) — a reasonable starting profile for an authored (non cloned) character, not a claim of acoustic realism. Constants — VoiceAnatomyProfile.js — Phase 2 Voice Box state schema ( ). §4's : "persistent per character morphology (equivalent role to 's /pitch range calibration, but for non cloned/authored characters rather than captured voices)". This is the STATIC per voice data that stays constant across frames — the rest position oral tube area profile, optional nasal branch area profile, and the three boundary reflection coefficients / require ( / / , all magnitude for BIBO stability per (R6)) — as distinct from 's , which is the per FRAME predicted deviation/gesture applied on top of this rest profile, not a replacement for it. (R6/R6A) already proved out / , , , as one working anatomy — below reuses those exact proven


applied on top of this rest profile, not a replacement for it. (R6/R6A) already proved out / , , , as one working anatomy — below reuses those exact proven values as the default rather than inventing new ones. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


createWaveguideAcousticState({ sampleIndex, numSamples, radiated, finalRight, finalLeft, finalPrevOutput, nasalRadiated = null })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: WaveguideAcousticState.js — Phase 2 Voice Box state schema ( ). "The R6 tract's per sample output (radiated signal + nasal tap)" per §4 — the JS side timestamped container for one dispatched chunk's worth of ( , plus the persisted / / continuation state that kernel's packed output layout produces) and, optionally, a coupled chunk's own radiated output. This container does not itself dispatch either kernel or compute ( 's own docstring notes the nasal tap read out is still deferred there) — it only fixes the shape a caller that DOES dispatch those kernels should hand back, so downstream consumers (the audio bridge, , ) have one stable state shape to depend on regardless of which kernel(s) produced it. Functions Returns: A validated, timestamped for one dispatched chunk. Builds the next chunk's initial state inputs ( 's / / bindings) from a previous chunk's — the exact cross chunk continuity 's test verifies at the kernel level. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


textToPhonemeSequence(normalized, { g2p = new G2PModel()

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: G2PModel.js — Phase 3 ParticleVoice text frontend. Grapheme to phoneme fallback for words does not cover, plus — the deterministic lowering §4 describes, which turns raw text into the triple the model consumes. It is rules, not a network — deliberately The plan calls for a "minimal " in Phase 3, and this is a deterministic, context sensitive letter to sound rule set , not a trained model. That is the honest choice at this stage: a neural G2P needs a pronunciation corpus to train against, and this project vendors no external data (CMUdict included). Rules give reproducible output today, and the class boundary here is what a learned model would later slot into without touching callers. The name matches the plan's; the implementation does not pretend to be learned. Accuracy expectations, stated plainly English orthography is not a function of spelling alone, so a rule set of this size gets the regular cases right and a meaningful minority wrong ( has two pronunciations; breaks the rule; stress placement in long words is genuinely lexical). That is exactly why exists and is consulted FIRST — every word whose spelling actively lies belongs there. G2P's job is to make unseen words (character names, invented words, rare vocabulary) pronounceable and stable, not to be a dictionary. Rule format Each rule is , tried in order at each position, first match winning. Rules are authored longest target first per letter so digraphs beat single letters. The context pattern language is deliberately tiny — three metacharacters, no regex — so a rule's behaviour is obvious by inspection: word boundary (start of a left context, end of a right context) exactly one consonant letter exactly one vowel


so a rule's behaviour is obvious by inspection: word boundary (start of a left context, end of a right context) exactly one consonant letter exactly one vowel letter anything else, a literal letter Stress is assigned afterwards by syllable heuristic (see ), because stress is a property of the whole word, not of any single grapheme. Classes Method Signature Summary Resolve one word, preferring the lexicon. (from ) triggers spell out ONLY when the lexicon has no entry — so , once added to a lexicon, is spoken as a word, while an unknown is spelled out. That ordering is the whole reason the normalizer defers the decision rather than making it. Functions Apply the rule set to a spelling. Returns: Phoneme SYMBOLS (stress is assigned separately). Place a single primary stress by syllable heuristic. Documented as a heuristic because English stress is genuinely lexical — the lexicon is the place to be exact. Suffixes pull stress onto the syllable immediately before them (na TION al → "NA tion", in for MA tion). pull stress two syllables back. Otherwise stress the first syllable, unless the word opens with a normally unstressed prefix and has more than one syllable, in which case stress the second. Returns: null} only if the spelling produced no phonemes at all. Deterministic lowering of normalized text into §4's . All three arrays are the same length, one entry per phoneme instance including structural tokens, exactly as that spec requires. Structural insertion follows §4's Effect column: a phrase's token ( for comma level, for terminals) is appended after its words, and a paragraph boundary additionally emits before its (§4: "longer SIL, breath event likely"). Parameters: (object) — Output of . Returns: } Constants — Letter to sound rules, grouped by first letter of . Order


(§4: "longer SIL, breath event likely"). Parameters: (object) — Output of . Returns: } Constants — Letter to sound rules, grouped by first letter of . Order within a group IS the priority order. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


particlevoice/frontend/PhonemeSet.js
Functions
phonemeIdOf(symbol)
hasPhoneme(symbol)
phonemeAt(id)
phonemeBySymbol(symbol)
diphthongTargetIds(id)
constrictionPositionOf(id)
isValidStress(stress)
isValidPunctuationContext(tag)
isVowel(id)
isConsonant(id)
isStructural(id)
isVoiced(id)
isDiphthong(id)
Constants
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PhonemeSet.js — Phase 3 ParticleVoice text frontend. The executable form of : the English phoneme inventory, its per entry articulatory feature vectors, the stress scale, and the punctuation context tags. This module is the SINGLE SOURCE OF TRUTH every other Phase 3 component reads — validates against it, targets it, sizes its embedding table from , and consumes the feature vectors to bias . Corrections to Encoding the spec surfaced four places where its §1 tables (the actual data) disagree with its §1 summary line or its §2 enum declarations. The tables are treated as normative and the spec has been corrected to match; each is recorded here because a reader comparing the two must know which way the discrepancy was resolved. 1. Inventory size. §1 claimed "24 vowel symbols + 24 consonant symbols + 3 structural tokens = 51" and IDs . The tables actually list 10 monophthongs + 5 diphthongs = 15 vowels , so the real total is 42 entries, IDs . "24 vowel symbols" appears to be an accidental duplication of the consonant count. This matters concretely: it sets 's embedding table size and the legal range in §4, both of which were also stated as 51/ and are now corrected. 2. Vowel height values. §2 declares , but §1's table also uses ( ) and ( ). All five values are kept (see ); the narrower §2 enum was the error. 3. 's rounded column contains , which is not a rounded ness value at all. Modeled here as plus a separate flag, since rhoticity is an independent articulatory property (it shapes the area profile rather than the lip aperture). 4. 's place is in §1's table, which is not one of §2's values. Modeled as with , preserving the information without inventing an enum member the spec does


4. 's place is in §1's table, which is not one of §2's values. Modeled as with , preserving the information without inventing an enum member the spec does not define. Structural tokens ( / / ) carry , , and are identified by — deliberately NOT given invented enum values, since §2's / enums describe articulated speech sounds only. Functions Returns: The id for . Throws on an unknown symbol rather than returning a sentinel, so a G2P/lexicon typo fails loudly instead of silently synthesizing the wrong phone. Returns: The frozen entry for . Returns: null} The two monophthong Returns: The normalized 0..1 constriction position for Returns: True if is one of §3's three legal values. Returns: True if is one of §4's six legal punctuation context ids. Constants — §3: per vowel instance stress, separate from the phoneme symbol. — §4: punctuation context tag ids, emitted per phoneme by . — Includes §1's / , which §2's three value enum omitted (correction 2). — §2: place → normalized position (0 = glottis, 1 = lips) of the narrowest point, fed to 's control points. Provisional estimates per the spec's own §6 — NOT measured against vocal tract MRI data. — The inventory, in §1 table order. Array index IS the phoneme id — appending is safe, reordering is a breaking change to every trained embedding table. — 42 — sizes 's embedding table. See correction 1. — Highest legal phoneme id (41). <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


parsePronunciation(pronunciation, wordLabel = '<unknown>')

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PronunciationLexicon.js — Phase 3 ParticleVoice text frontend. Word → phoneme sequence dictionary, checked entry by entry against at construction time. Sits between and : a lexicon hit is authoritative, and only words with no entry fall through to G2P's letter to sound rules. ⚠ Stress digits are the INVERSE of CMUdict Pronunciation strings use CMUdict's familiar shape ( ), but the digit follows §3: 0 = unstressed, 1 = SECONDARY, 2 = PRIMARY CMUdict is the other way round ( = primary, = secondary). Copying CMUdict strings verbatim would therefore silently swap primary and secondary stress on every polysyllabic word — audible as wrong prosody, not as an error. This module cannot detect that mistake for you, so the convention is stated here, in §3, and enforced by range validation only. Authoring rules (validated, not merely documented) Every symbol must exist in . A typo throws at construction, naming the word — never at synthesis time. A stress digit is legal ONLY on a vowel. Spec §3 defines stress as a per vowel instance property, so is rejected outright rather than quietly ignored. Omitting the digit on a vowel means unstressed (0). This keeps reduced function words ( = ) readable. At most one primary stress per word. Not exactly one: genuinely reduced function words ( , , ) carry no stress at all, and forcing a primary onto them would produce robotically over stressed speech. Scope is a deliberately curated core, NOT a full dictionary. It covers high frequency function/content words plus — the reason a lexicon exists at all — words whose spelling actively lies about their pronunciation ( , , , , , , ), which any letter to sound rule set gets wrong. CMUdict is not vendored: this


— words whose spelling actively lies about their pronunciation ( , , , , , , ), which any letter to sound rule set gets wrong. CMUdict is not vendored: this project takes no external data dependencies, and the long tail is 's job. Callers add domain vocabulary (character names, place names) via / . Classes Method Signature Summary defaults to true; pass false for a lexicon containing only caller supplied entries (useful for testing G2P fallback). Words are matched case insensitively; already lowercases, but a caller adding entries by hand should not have to remember that. Add or REPLACE one entry. Replacement is intentional and silent: a caller supplying a character specific pronunciation must be able to override the core lexicon without first removing the default. Spell a token out letter by letter ( → "you ess ay"). The caller decides WHEN to do this — 's flag is the signal, but only the caller knows whether a given initialism is pronounced as a word instead. Functions Parse one pronunciation string. Returns: } Constants — Spoken letter names, for spelling out initialisms. flags all caps tokens with but deliberately does not decide whether they are words or initialisms; here is the mechanism for the latter. — Curated core lexicon. Stress digits: 2 = PRIMARY (see the warning above). Grouped by why each entry is here. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TextNormalizer.js — Phase 3 ParticleVoice text frontend. Turns raw author/LLM text into speakable words plus the per phrase punctuation context tags §4 defines, ready for / to lower into phoneme ids. Output shape ( ): { raw: string, phrases: [{ words: [{ text, wasAllCaps }], boundary: PUNCTUATION CONTEXT id, // §4 tag for THIS phrase's end structural: 'SP' 'SIL' null, // token to insert at the boundary breathLikely: boolean, // §4: paragraph breaks only }] } One tag per phrase (not per phoneme): §4's per phoneme array is produced downstream by repeating a phrase's tag across the phonemes its words expand into, which is exactly what that spec means by "repeats within a phrase, changes at boundaries". Ordering matters Abbreviation expansion and decimal point protection run BEFORE phrase splitting, because both consume characters that would otherwise be mistaken for sentence terminators — is one phrase, not two, and is one number, not then . Getting this order wrong is the classic text frontend bug, so it is enforced by construction here rather than left to a later cleanup pass. Deliberate non guesses Two things this module refuses to infer, because guessing wrong is worse than not trying: Years. could be a year ("nineteen ninety nine") or a quantity ("one thousand nine hundred ninety nine"), and proves the quantity reading is often right. Bare integers are ALWAYS read as cardinals; is exported for callers that actually know the context (e.g. a date field), rather than being applied by a heuristic that would silently corrupt prices and counts. Acronym pronunciation. is said as a word, letter by letter, and nothing in the surface form distinguishes them. All caps tokens are passed


prices and counts. Acronym pronunciation. is said as a word, letter by letter, and nothing in the surface form distinguishes them. All caps tokens are passed through with so gets first refusal and can fall back to spelling out — the decision belongs where the pronunciation knowledge lives, not here. Dates and clock times are likewise out of scope for (both are format ambiguous: is a date in one locale and a fraction in another). They are documented as unhandled rather than half handled. Functions Returns: as cardinal words. Negative values are prefixed . Returns: as ordinal words ( → ). Returns: Digits spoken individually, for decimal fractions and spelled out sequences. Read a 4 digit year the way speech does. NOT applied automatically — see this module's "deliberate non guesses" note; callers that know a number is a year opt in explicitly. Unicode/typography normalization: NFKC, curly quotes and dashes to ASCII, whitespace collapsed (paragraph breaks preserved as ). Parameters: (string) — No description in source JSDoc. Returns: , boundary: number, structural: string null, breathLikely: boolean } }} Returns: Every spoken word across all phrases, for lexicon coverage checks and tests. Constants — Expanded before phrase splitting, so their trailing never reads as a sentence end. Keys are matched case insensitively without the period. — Standalone symbol → word. Applied per token, so between words works but is left to the lexicon. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


particlevoice/lab/ManualArticulator.js
Classes
class ManualArticulator
Functions
normalizePose(pose = {})
interpolatePoses(a, b, t)
poseAreaProfile(pose, numSections)
createManualArticulator(options)
Constants
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ManualArticulator.js — Phase 3 ParticleVoice lab. Turns direct articulator controls (the Voice Box demo's sliders) into the SAME physiology stream shape produces, so accepts it unchanged. Why this is a module and not inline demo code The plan requires the live demo to have "manual articulator mode + neural mode; same ". If manual mode built its own control path — or worse, called directly — the two modes would diverge: different smoothing, different validation, a different visualization source. By emitting the identical stream shape, manual mode goes through exactly the same → → path, and the visualization comes from the same solver snapshots. That makes "same VisualAirflowState" structural rather than a promise, and it means this logic is testable headlessly instead of only by clicking. Controls Deliberately the physical knobs, not phonemes — the point of manual mode is to drive the tract directly: , — glottal source (0 = glottis, 1 = lips) and — one moving constriction, the single most expressive articulator , — the tube's two ends — velum — turbulence at the constriction — subglottal drive A held pose is rendered as a constant stream; produces a glide between two poses, which is how the demo can sweep a diphthong or a closure/release gesture without hand authoring every frame. Classes Method Signature Summary Build a physiology stream from a per frame pose function — the identical shape returns, so consumes it unchanged. A single held pose for — the "move a slider and listen" case. Glide through a list of poses over , spending equal time on each leg. Two poses give a simple transition; three or more let the demo trace a closure/release or a diphthong. Functions Validate and


spending equal time on each leg. Two poses give a simple transition; three or more let the demo trace a closure/release or a diphthong. Functions Validate and clamp a partial pose into a complete one. Linear blend between two poses; switches at the midpoint since it is boolean. Area profile for one pose, using the same 3 control point shape uses for vowels. Constants — Slider metadata for the demo UI, kept beside the pose it describes so the two cannot drift apart. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


particlevoice/lab/TractSagittalView.js
Classes
class TractSagittalView
Functions
diameterForArea(areaCm2)
Constants
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: TractSagittalView.js — mid sagittal renderer for the vocal tract area function. Draws what the solver is actually doing, as an anatomical cross section: the pharynx rising from the glottis, the bend behind the tongue, the oral cavity, the teeth and the lips. The tract's array IS the picture — section is a slice of tube, and its cross sectional area is the gap between the tongue surface and the roof of the mouth at that point. Why a sagittal view rather than a plot of the numbers A line plot of 32 areas is readable but not diagnosable : it does not tell you whether a shape is a plausible mouth. Errors in this project have repeatedly been of exactly that kind — a tract twice the correct length, a "stop" whose closure never closed, a constriction so tight it would whistle. All of those are obvious at a glance in an anatomical view and invisible in a spectrum. Geometry The centreline follows an arc, matching how the real tract bends 90 degrees behind the tongue: the glottis end points up, the lip end points forward. Each section is drawn radially across that arc, with the OUTER boundary fixed (the rigid palate, teeth and rear pharyngeal wall) and the INNER boundary displaced by the section's diameter (the tongue and jaw, which are what move). Diameter, not area, sets the drawn width: a tube's diameter goes as the SQUARE ROOT of its area, so plotting area directly would exaggerate open sections and make near closures look tighter than they are. Classes Renders one frame of tract geometry. Stateless by design: it takes the geometry and draws it, so the same view can be driven by 's per frame stream, by 's live sliders, or by a single static profile from , with no notion of playback


and draws it, so the same view can be driven by 's per frame stream, by 's live sliders, or by a single static profile from , with no notion of playback inside it. Method Signature Summary Centreline geometry for section of . Draw one frame. Functions Returns: Tube diameter in cm for a cross sectional area in cm^2. Constants — Anatomical landmarks as a fraction of tract length from the glottis, used only for labels and the teeth marker. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered from the world, a brain maps them to actions, the rig applies motion, and rewards shape the next update. Example: Minimal training loop See also: AGI Training Guide · AGI Architecture


physiologyStateAt(result, frame, { glottalReflection, lipReflection } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ArticulationHead.js — Phase 3 ParticleVoice model. Per frame streams → ( ): the four control heads plus uncertainty that actually consumes. This is where §2's articulatory feature vectors finally reach the vocal tract — place becomes a constriction position, manner becomes a constriction degree, height/backness/rounded become a vowel area profile. Rule based, mapping features to geometry Like , this is a deterministic feature→geometry mapping, not a trained head. §6 already flags its place position percentages as "provisional estimates ... not measured against real vocal tract MRI data", and the vowel profiles here are the same kind of estimate: a 3 control point whose constriction position comes from backness, constriction area from height, and lip area from rounding. They are ordered correctly (high vowels narrower than low, front constrictions further forward than back) and produce distinguishable formants — verified in Phase 2 to be what makes a vowel a vowel rather than a buzz — but they are not fitted to measured data. Two constraints that are NOT stylistic 1. must be strictly positive, even when unvoiced. It is tempting to set the glottal excitation to 0 on a voiceless frame. That breaks : its Newton solve for computes , so makes the derivative exactly 0 and the update evaluates to NaN , which then propagates through the whole waveguide. 's own validator independently requires . Voiceless frames therefore use a small positive — inaudible, but numerically safe. 2. Areas are SMOOTHED across frames, per manner. Snapping the area profile to a new target at a phoneme boundary is a step change in the waveguide's reflection coefficients, which radiates as a click — the precise


the area profile to a new target at a phoneme boundary is a step change in the waveguide's reflection coefficients, which radiates as a click — the precise artifact Phase 2's exit gate spent effort eliminating. Each manner gets its own time constant because the right smoothing speed is phonetically real, not a tuning knob: a stop's closure and release ARE fast (smearing them destroys the plosive), while a vowel to vowel transition is genuinely slow. A single global constant would either smear plosives or click on vowels. Output shape returns COMPACT typed arrays (one row per frame), not an array of frozen objects: a few seconds of speech is hundreds of frames, and materializing hundreds of frozen nested objects per utterance would be wasteful when the consumer reads them once, in order. builds the real validated schema object on demand, so the schema is genuinely exercised (and validated) rather than bypassed. Classes Method Signature Summary Target area profile for one phoneme id, cached (profiles are pure functions of the phoneme). Profile for a phoneme at (0..1) through its own duration, which is what makes a diphthong glide. Functions Materialize one frame of a result as a validated . Built on demand rather than eagerly — see the header's "output shape" note — so the schema and its validators are genuinely exercised without allocating hundreds of frozen objects per utterance. Constants — Small but strictly positive glottal excitation for voiceless frames. See constraint 1 in the header: 0 would make 's Newton solve produce NaN. — Fallback constriction position (0 = glottis, 1 = lips) by vowel backness, and cross section by height. These are NO LONGER the primary path for the ten monophthongs — see . They were an articulatory adjective mapping ("front vowels


and cross section by height. These are NO LONGER the primary path for the ten monophthongs — see . They were an articulatory adjective mapping ("front vowels constrict further forward", "high vowels constrict more tightly") that is directionally right but produces whatever formants it happens to produce. Since vowel identity is carried almost entirely by F1/F2, "plausible geometry" is not good enough: uncalibrated profiles pull every vowel toward a neutral timbre, which is heard as speech like noise with no decipherable vowels. Retained only as the fallback for any vowel with no entry in , so adding a phoneme to cannot crash synthesis before it has been calibrated. — Constriction LENGTH by manner, as a fraction of