regulateLength({ durationFrames, f0Hz, voiced, features = null, featureDim = 0, maxFrames = 1 << 20 })

resampleFrames(regulated, fromRateHz, toRateHz, featureDim = 0)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: LengthRegulator.js — Phase 3 ParticleVoice model. Expands per PHONEME encoder features and prosody into per FRAME streams, and — because §5 explicitly assigns it here — handles resampling between the 100 Hz plan frame rate and whatever rate the consumer runs at (the Activity path is 8 ms/frame = 125 Hz, §1; the two "are not required to be equal; any resampling between them is 's job, not assumed away here"). F0 is interpolated, features are held These two streams are expanded differently, on purpose: F0 is linearly interpolated between phoneme centres. Holding one value per phoneme would produce a pitch STAIRCASE, and a discontinuous F0 is audible as a click or a warble at every phoneme boundary — the exact artifact the Phase 2 exit gate spent effort eliminating from the waveguide. Interpolating between centres (not edges) means each phoneme's nominal pitch is actually reached at its midpoint. Feature vectors are HELD across a phoneme's frames, not interpolated. They are a learned representation, and blending two phonemes' embeddings produces a vector that means neither. Holding is the standard FastSpeech style length regulation and is what the downstream expects. The voiced flag is held — it is boolean; interpolating it would invent half voiced frames that no source model can honour. Where it runs CPU side. The encoder's features are produced on GPU, so using them here costs a readback — but the consumer ( → ) needs per chunk control values in JS anyway ( , ), so the readback is not avoided by moving this to GPU, only relocated. A GPU gather kernel is a straightforward follow up IF profiling later shows the feature upload dominating; the condition that would justify it is stated


A GPU gather kernel is a straightforward follow up IF profiling later shows the feature upload dominating; the condition that would justify it is stated so the decision is revisitable rather than forgotten. Classes Method Signature Summary Functions Expand per phoneme streams to per frame streams. durationFrames: ArrayLike<number , f0Hz: ArrayLike<number , voiced: ArrayLike<number , features?: ArrayLike<number , featureDim?: number, maxFrames?: number, }} input Returns: {{ Resample per frame streams from one frame rate to another — the job §5 assigns to this module for crossing between the 100 Hz plan rate and the 125 Hz Activity rate. F0 is linearly interpolated (it is continuous); voicing and the phoneme index use NEAREST neighbour, because both are categorical and interpolating them would invent values that do not exist (a half voiced frame, or a fractional phoneme id). Constants — LengthRegulator.js — Phase 3 ParticleVoice model. Expands per PHONEME encoder features and prosody into per FRAME streams, and — because §5 explicitly assigns it here — handles resampling between the 100 Hz plan frame rate and whatever rate the consumer runs at (the Activity path is 8 ms/frame = 125 Hz, §1; the two "are not required to be equal; any resampling between them is 's job, not assumed away here"). F0 is interpolated, features are held These two streams are expanded differently, on purpose: F0 is linearly interpolated between phoneme centres. Holding one value per phoneme would produce a pitch STAIRCASE, and a discontinuous F0 is audible as a click or a warble at every phoneme boundary — the exact artifact the Phase 2 exit gate spent effort eliminating from the waveguide. Interpolating between centres (not edges) means each phoneme's nominal pitch is actually reached at its


exit gate spent effort eliminating from the waveguide. Interpolating between centres (not edges) means each phoneme's nominal pitch is actually reached at its midpoint. Feature vectors are HELD across a phoneme's frames, not interpolated. They are a learned representation, and blending two phonemes' embeddings produces a vector that means neither. Holding is the standard FastSpeech style length regulation and is what the downstream expects. The voiced flag is held — it is boolean; interpolating it would invent half voiced frames that no source model can honour. Where it runs CPU side. The encoder's features are produced on GPU, so using them here costs a readback — but the consumer ( → ) needs per chunk con


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleVoiceModel.js — Phase 3 ParticleVoice model. Wires the whole Phase 3 path into one call: text → PCM . TextNormalizer → G2P/lexicon → PhonemeSequence → PhonemeEncoder (GPU, optional) → ProsodyPlanner → LengthRegulator → ArticulationHead → NeuralPhysiologyState stream → ParticleTract (GPU acoustic solver) → SafetyLimiter → PCM Why there is no separate in Phase 3 The plan lists " basic harmonic + noise + waveguide output". In Phase 3 that IS : it already runs (harmonic source), two streams (aspiration at the glottis, frication at the constriction) and the Kelly Lochbaum waveguide, with lip radiation applied internally. Adding a wrapper that only forwarded to it would be a layer with no content. Phase 4's full source filter Fourier vocoder (bounded spectral residual, MPD/MRD refinement, IFFT + WOLA) is where that module earns its own file — and the seam for it is , which is already separate from the text frontend. Frame rate vs chunk rate: the decimation that matters emits physiology at the 100 Hz plan frame rate (10 ms), but accepts one control set per chunk — one area profile, one f0, one constriction index. At 32 kHz with 1024 sample chunks a chunk is 32 ms, so roughly 3 physiology frames fall inside each one. Something has to reduce them, and the choice is audible: Areas are AVERAGED across the frames in a chunk. Picking one frame (say the first) would throw away the smoothing deliberately applied and reintroduce exactly the reflection coefficient step it exists to prevent. F0 is averaged for the same reason: a chunk rate pitch staircase is audible as a warble. Constriction index is taken by MAJORITY , not averaged — it is a position index, and the mean of "junction 20"


rate pitch staircase is audible as a warble. Constriction index is taken by MAJORITY , not averaged — it is a position index, and the mean of "junction 20" and "junction 6" is junction 13, a place no phoneme asked for. Voicing/amplitudes are averaged , which naturally cross fades a voiced→voiceless transition across the chunk rather than switching hard. This decimation is the one place a Phase 3 discontinuity could still enter, so it is concentrated in and tested directly. Breath reservoir 's one pole lag is applied CPU side per chunk to turn 's target subglottal pressure into an actual pressure with inertia, and that pressure scales the glottal excitation. This uses the same formula the GPU kernel expects pre computed, so the two agree; running it here rather than on GPU avoids a readback for a single scalar per chunk. Documented as a deliberate simplification: a per SAMPLE reservoir would need the kernel. Classes Method Signature Summary Per sample frication envelope for one chunk, linearly interpolated from the 100 Hz frame stream at each sample's absolute time. Chunk independent by construction: the value at absolute sample depends only on . See the call site for why frication specifically needs this while the other controls do not. Reduce the physiology frames covering one chunk to a single control set. See the header: averaging vs majority is chosen per field because the wrong reduction is audible. Render a physiology stream (from ) to PCM. Separate from so a manual articulator caller — the Voice Box demo's manual mode — can drive the solver without going through text. Full text → physiology plan, without touching the GPU. Exposed so a caller can inspect or override the plan (and so tests can check the frontend/prosody path without a device). Text → PCM, the whole


the GPU. Exposed so a caller can inspect or override the plan (and so tests can check the frontend/prosody path without a device). Text → PCM, the whole Phase 3 path. 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


createDeterministicEncoderWeights(config = {}, seed = 1337)

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: PhonemeEncoder.js — Phase 3 ParticleVoice model. Phoneme ids → contextual per token feature vectors, entirely on GPU: a row embedding table followed by two Conv1D blocks, each with SiLU, and a final RMSNorm. This is the first Phase 3 component that runs the Phase 1 ParticleNN kernels in composition. Pipeline (7 dispatches, ONE submit per ): ids [T] → embedding f16 → [T, D] sequence major → transpose 2d → [D, T] channel major (see "layout" below) → conv1d w8a16 → [H, T] → silu f16 → [H, T] → conv1d w8a16 → [O, T] → silu f16 → [O, T] → transpose 2d → [T, O] sequence major → rmsnorm f16 → [T, O] per token normalization Layout: why two transposes are load bearing The Phase 1 kernels disagree about which axis is major, and each is right for itself: gathers rows so it emits sequence major ; slides a kernel along time so it reads channel major ; normalizes rows, so per token normalization needs sequence major again. Composing them without the axis swaps would not error — it would silently convolve across the feature axis and produce scrambled activations. was added for exactly this, and the two transposes here are the minimum: SiLU is elementwise and therefore layout agnostic, so both convolutions run back to back in channel major before a single swap back for the norm. Weights are placeholders, and this file says so No Phase 3 training exists yet, so produces seeded pseudorandom INT8 weights . They make the pipeline runnable, shape correct and reproducible end to end; they do NOT make it meaningful. The encoder's output is a deterministic function of its input, which is what Phase 3's downstream components need in order to be built and tested — but nothing here has learned anything


deterministic function of its input, which is what Phase 3's downstream components need in order to be built and tested — but nothing here has learned anything about phonetics. Real weights arrive with training; the argument is the seam. Quantization Conv weights are INT8 with a per output channel scale, matching 's packed layout exactly (4 int8 per , flattened index, a multiple of 4 — validated in the constructor rather than left to fail as garbage output). Classes Method Signature Summary The GPU buffer holding the last 's features, for a caller that wants to stay GPU resident. Encode + submit without reading back, leaving features in . Functions Pack int8 weights into s, 4 per word, matching 's documented flattening. Parameters: (Int8Array) — Build a complete, reproducible placeholder weight set. See the header: this is scaffolding so the pipeline can be exercised, not a trained model. Constants — Small by design: Phase 3 is a "tiny deterministic single speaker model", not a production encoder. <! 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/model/ProsodyPlanner.js
Classes
class ProsodyPlanner
Functions
createProsodyPlanner(config)
Constants
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ProsodyPlanner.js — Phase 3 ParticleVoice model. Predicts per phoneme duration , F0 and a voiced flag from a ( §4), at the plan frame rate of 100 Hz / 10 ms per frame that spec fixes. Rule based, and the plan says "minimal" This is a deterministic rule model, not a trained one: durations come from per manner base values scaled by stress and boundary position, and F0 from a declination line with stress excursions and a terminal contour selected by punctuation context. Phase 3's goal is "a tiny deterministic single speaker model", and a learned duration/F0 predictor needs aligned speech data this project does not have. The numbers below are therefore plausible phonetics, not measured values — they are ordered correctly relative to each other (stops shorter than fricatives, diphthongs longer than monophthongs, stressed longer than unstressed), which is what makes speech intelligible, but they are not fitted to any corpus. takes an optional bag so a caller can retune without editing this file, and the class boundary is where a learned predictor slots in. What it deliberately does not do No per phoneme F0 contour inside a phoneme. One target per phoneme; smoothing into a continuous per frame curve is 's job, because that is where frame counts exist. Emitting a flat value per phoneme here and interpolating there avoids the audible pitch STEP that a naive per phoneme hold would produce. No accent/emotion conditioning. §3's factorized conditioning channels exist, but wiring them is Phase 4+; pretending to condition on them now would be fake. Classes Method Signature Summary Functions Constants — §5: the plan frame rate is 100 Hz (10 ms/frame). — Base durations in MILLISECONDS by


now would be fake. Classes Method Signature Summary Functions Constants — §5: the plan frame rate is 100 Hz (10 ms/frame). — Base durations in MILLISECONDS by articulatory manner. Relative ordering is the part that matters (see header); absolute values are plausible defaults. — Structural token durations, keyed by the punctuation context they sit at (spec §4's Effect column: comma level is a short pause, terminals are full silences, a paragraph is longer still). <! 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: BackwardGraphCompiler.js — Phase 1 ParticleNN autodiff STUB. Not wired into anything until Phase 11. Walks a 's recorded forward ops in reverse and builds a node per op that has a registered rule (ops without one are skipped, not silently faked with an identity/zero gradient). Refuses to compile anything if the registry is completely empty — the honest current state (no backward rules exist yet for any real kernel) rather than returning a plausible looking but meaningless empty graph. 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: BackwardRuleRegistry.js — Phase 1 ParticleNN autodiff STUB. Not wired into anything until Phase 11. Maps a forward op name (from 's allowlist, e.g. ) to a backward rule: a function that, given the recorded forward op's inputs/outputs/params plus the gradient(s) flowing into its outputs, produces the gradient(s) with respect to its inputs. No rules are registered for any real kernel yet — that is genuinely Phase 11 work (differentiating through INT8 quantization and FP16 rounding correctly is a real design problem, not something to hand wave here) — this file only fixes the registry shape. Classes BackwardRuleRegistry.js — Phase 1 ParticleNN autodiff STUB. Not wired into anything until Phase 11. Maps a forward op name (from 's allowlist, e.g. ) to a backward rule: a function that, given the recorded forward op's inputs/outputs/params plus the gradient(s) flowing into its outputs, produces the gradient(s) with respect to its inputs. No rules are registered for any real kernel yet — that is genuinely Phase 11 work (differentiating through INT8 quantization and FP16 rounding correctly is a real design problem, not something to hand wave here) — this file only fixes the registry shape. 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


class GradientGraph extends ParticleGraph

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: GradientGraph.js — Phase 1 ParticleNN autodiff STUB. Not wired into anything until Phase 11. The backward pass analogue of : nodes are backward rule applications rather than forward kernels, gradient tensor names rather than activation tensor names. Reuses 's DAG/topological sort machinery directly (a gradient graph's dependency structure is a plain DAG exactly like a forward graph's — no different algorithm is needed) rather than duplicating it, and adds for the one thing a gradient graph needs that a forward graph never does: multiple edges producing a gradient for the same tensor must sum, not overwrite (a tensor used as input to two or more forward ops receives a gradient contribution from each one). Classes Method Signature Summary Register that contributes a partial gradient to (in addition to whatever 's normal single producer bookkeeping tracks) — call this instead of 's plain list when a gradient tensor has multiple contributors, since itself rejects a tensor name appearing in more than one node's (correct for forward graphs, wrong for gradient accumulation). Overrides : the base class treats a tensor produced by more than one node as an error (correct for a forward graph, where that always indicates a naming bug) — but a gradient graph's accumulation targets are LEGITIMATELY produced by several nodes (one partial gradient contribution per forward consumer of the original tensor), so this tracks a set of producers per tensor and requires all of them to have run before a node that reads that tensor is visited. <! HUMAN NOTES Notes & Examples Where this fits in the training loop AGI runs an observation → brain → action → reward loop each tick: observations are gathered


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: ParticleTape.js — Phase 1 ParticleNN autodiff STUB. Not wired into anything until Phase 11 (browser training), per the plan's explicit phasing. This establishes the recording tape contract a future forward pass will write to and will read from — it is NOT exercised by any real training loop yet (R7's training spike used its own hand wired , deliberately separate from this production module). Records forward pass operations (op name, input tensor names, output tensor names, and any params the backward rule will need) in execution order, reverse mode style. Classes ParticleTape.js — Phase 1 ParticleNN autodiff STUB. Not wired into anything until Phase 11 (browser training), per the plan's explicit phasing. This establishes the recording tape contract a future forward pass will write to and will read from — it is NOT exercised by any real training loop yet (R7's training spike used its own hand wired , deliberately separate from this production module). Records forward pass operations (op name, input tensor names, output tensor names, and any params the backward rule will need) in execution order, reverse mode style. Method Signature Summary Record one forward operation. No op while paused (e.g. during a warm up/inference only pass that shouldn't build a tape). Recorded ops in reverse (execution) order — the order a backward pass must walk them in. <! 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


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/nn/core/ParticleGraph.js
Classes
class ParticleGraph
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleGraph.js — Phase 1 ParticleNN core. The uncompiled neural compute graph a model author builds: named nodes with an (must be in §3's operator allowlist) and named input/output tensor slots. (Phase 2+) lowers a into a §8 execution plan / ; this file only builds and validates the DAG itself (topological sort, cycle/dangling reference detection) — it does not compile or dispatch anything. Classes ParticleGraph.js — Phase 1 ParticleNN core. The uncompiled neural compute graph a model author builds: named nodes with an (must be in §3's operator allowlist) and named input/output tensor slots. (Phase 2+) lowers a into a §8 execution plan / ; this file only builds and validates the DAG itself (topological sort, cycle/dangling reference detection) — it does not compile or dispatch anything. Method Signature Summary Topologically sort nodes by producer/consumer dependency (a node depends on whichever other node produces one of its , if any — inputs with no producer are treated as external graph inputs). Throws on a cycle. Result is cached until the next . Every referenced by any node, for a caller to check against a (or §3's allowlist) before compiling. <! 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/nn/core/ParticleKernel.js
Classes
class ParticleKernel
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleKernel.js — Phase 1 ParticleNN core. Kernel specialization: resolves a entry + concrete params ( , kernel specific options like ) into one ready to compile unit — WGSL source, entry point, workgroup size, and the explicit bind group layout entries / proved necessary for kernels ( §8). Classes ParticleKernel.js — Phase 1 ParticleNN core. Kernel specialization: resolves a entry + concrete params ( , kernel specific options like ) into one ready to compile unit — WGSL source, entry point, workgroup size, and the explicit bind group layout entries / proved necessary for kernels ( §8). Method Signature Summary Compile this kernel's pipeline via , using the explicit layout path (required for any kernel — see 's ). <! 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/nn/core/ParticleModel.js
Classes
class ParticleModel
Notes & Examples
Where this fits in the training loop

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleModel.js — Phase 1 ParticleNN core. A loaded model container: a compiled plus its weight memory ( / / ) and header metadata, as one object. Deliberately thin scaffolding at Phase 1 — no real model exists yet ( / that would actually produce one of these from a file are Phase 2+ work); this fixes the shape that loader will hand to callers. Classes ParticleModel.js — Phase 1 ParticleNN core. A loaded model container: a compiled plus its weight memory ( / / ) and header metadata, as one object. Deliberately thin scaffolding at Phase 1 — no real model exists yet ( / that would actually produce one of these from a file are Phase 2+ work); this fixes the shape that loader will hand to callers. Method Signature Summary program: import('./ParticleProgram.js').ParticleProgram, weightPageStore: import('../memory/WeightPageStore.js').WeightPageStore, weightBindWindow: import('../memory/WeightBindWindow.js').WeightBindWindow, weightUploader: import('../memory/WeightPageUploader.js').WeightPageUploader, metadata?: object, }} config Compile every kernel's GPU pipeline ahead of first use. Idempotent. Upload the weight pages required by (defaults to every segment in the program) via , in the given 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleProgram.js — Phase 1 ParticleNN core. A compiled dispatch sequence: 's topological order lowered into an ordered list of steps, one per graph node. builds every step's GPU pipeline via a shared up front (so first dispatch has no compile stall); actually running the steps each frame is 's job, not this file's. Classes Method Signature Summary Compile every step's pipeline via (parallel — pipeline creation for distinct kernels doesn't depend on 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ParticleTensor.js — Phase 1 ParticleNN core. GPU resident tensor with explicit shape/strides/dtype/quant metadata. Mirrors 's ownership/readback/dispose conventions (reference only, not imported at runtime — the plan requires ParticleNN to stay decoupled from the LLM runtime) but adds the metadata ParticleVoice actually needs: multiple dtypes ( / / / ) and optional per block INT8 quantization scale/zero data alongside the raw buffer. Classes , when present, describes INT8 block quantization for tensors: — one scale per block, dequantized as (zero point free, symmetric quantization; PRNN v0's kernel implements this exact scheme — see ). Method Signature Summary Read the tensor back to a host typed array matching (f16 comes back as raw u16 bit patterns, not decoded floats — decoding is the caller's job via ). Functions Row major contiguous strides for (element units, not bytes). Wrap a raw readback in the correct typed array view for . Shared by and so readback interpretation lives in exactly one place. <! 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: ParticleTensorView.js — Phase 1 ParticleNN core. A zero copy view over a parent 's GPU buffer: a different logical shape/strides/byte offset into the SAME underlying buffer, with no copy and no new buffer allocation. Used for things like binding a single weight page's sub range, or reading one layer's slice out of a stacked activation tensor, without a pass. Classes Method Signature Summary The GPUBuffer this view reads/writes — identical object as the parent's, never copied. suitable for a with dynamic offset support. Read just this view's bytes back to a host typed array (still a real copy — GPU readback always is — but no intermediate buffer duplication on the GPU side). <! 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: KernelRegistry.js — Phase 1 ParticleNN kernel infrastructure. Maps kernel name generator, mirroring 's design (reference only, not imported — same LLM runtime decoupling rule as ). Each generator here also declares (how many read only storage bindings it expects before the single read write output binding) so 's caller can build the matching explicit bind group layout required for kernels (see §8 / 's ) without re deriving each kernel's binding count by hand. Classes Method Signature Summary Generate WGSL source for , forwarding (e.g. ) to its generator. The a kernel needs: uniform@0 (unless the kernel declared , e.g. / , which need no per dispatch scalar data), then read only storage bindings, then one read write storage output binding last — matches every Phase 1/2 kernel's binding convention exactly (verified by construction in ). <! 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: ShaderComposer.js — Phase 1 ParticleNN kernel infrastructure. WGSL chunk composition with dependency resolution: register named chunks (each optionally depending on other chunks), then compose an ordered, deduplicated concatenation for a kernel body — so e.g. 's is emitted exactly once even if two requested chunks both depend on it, and always appears before any chunk/body that calls it. Classes ShaderComposer.js — Phase 1 ParticleNN kernel infrastructure. WGSL chunk composition with dependency resolution: register named chunks (each optionally depending on other chunks), then compose an ordered, deduplicated concatenation for a kernel body — so e.g. 's is emitted exactly once even if two requested chunks both depend on it, and always appears before any chunk/body that calls it. Method Signature Summary Topologically order (and their transitive deps) then concatenate with appended last. Functions Pre registers the Phase 1 WGSL chunk set ( , , ) so a kernel generator can immediately without registering each chunk itself. has no WGSL fragment (it is a host side only JS< f16 bit conversion utility, per its own module doc) so it is not registered 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


formatCompilationMessages(messages, { sourceMap = null } = {})

formatDiagnosticReport(kernelName, messages, options = {})

formatErrorsOnly(kernelName, messages, options = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: ShaderDiagnosticFormatter.js — Phase 1 ParticleNN kernel infrastructure. Formats (from ) into human readable diagnostics, optionally resolving each message's line number through a to name which chunk it came from — a strict superset of 's error text (which only reports line:col + message, no chunk attribution). Functions Parameters: (GPUCompilationMessage[]) — @param {{ sourceMap?: import('./WGSLSourceMap.js').WGSLSourceMap }} options Returns: a multi line report, or a one line "no diagnostics" note if is empty. Only the messages, formatted — the subset that should fail a build/test, distinct from warnings/info the caller may want to log but not fail on. <! 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: WGSLSourceMap.js — Phase 1 ParticleNN kernel infrastructure. Generated WGSL line originating chunk mapping. Kernels compose WGSL from named chunks ( ) plus their own body; when the GPU compiler reports an error at line N, this turns that bare line number back into "which named chunk (or the kernel's own body) that line came from" — the JS source itself isn't line mapped (these are template literals, not a separate compilation step), but chunk attribution is usually enough to know where to look. Classes WGSLSourceMap.js — Phase 1 ParticleNN kernel infrastructure. Generated WGSL line originating chunk mapping. Kernels compose WGSL from named chunks ( ) plus their own body; when the GPU compiler reports an error at line N, this turns that bare line number back into "which named chunk (or the kernel's own body) that line came from" — the JS source itself isn't line mapped (these are template literals, not a separate compilation step), but chunk attribution is usually enough to know where to look. Method Signature Summary Append as a named segment, returning it unchanged — call this in place of directly concatenating chunk sources while assembling a kernel's WGSL, so segment boundaries are tracked as a side effect. Combine every added segment's source into the final WGSL string, in the order they were added. Which segment (if any) contains (1 indexed, as reported by ). <! 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


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: WgslPreprocessor.js — Phase 1 ParticleNN kernel infrastructure. Tagged template ...\ supporting / / and / directives, evaluated at kernel generation time (trusted JS call sites only — this is code generation for the kernel author, not a user input template engine, so a plain eval for expressions is an acceptable, deliberate choice here). Directive syntax (each directive must be alone on its own line): if <jsExpression // evaluated with no closure — pre interpolate else // values via before the directive endif // line if the condition depends on a variable for <name in <start ..<end // half open range, start/end integers endfor // body may reference (a // literal placeholder distinct from // , since is already // resolved by template literal // substitution before this runs) Functions Process / / and / directives in a flat WGSL source string, line by line. Tagged template: joins / per normal template literal semantics, then runs over the result. <! 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


siluF16Shader({ useShaderF16 = false } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: activation/silu f16.js — Phase 1 ParticleNN kernel. Elementwise SiLU ( ), composed from 's rather than re deriving the sigmoid inline. 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: breath reservoir.js — Phase 2 ParticleNN articulatory kernel. First order lag filter: , matching (R6A)'s proven recurrence exactly ( is computed by the caller and passed in, not recomputed here). A first order IIR recurrence is inherently sequential in time, but each of up to N simultaneous voice/capsule instances is fully independent — selects the instance, and a single thread per workgroup walks that instance's whole chunk sequentially (cheap: a chunk is a few hundred samples, and GPU dispatch overhead dominates at that size anyway, so there is nothing to gain from parallelizing within one instance's strictly sequential recurrence). Functions Constants — breath reservoir.js — Phase 2 ParticleNN articulatory kernel. First order lag filter: , matching (R6A)'s proven recurrence exactly ( is computed by the caller and passed in, not recomputed here). A first order IIR recurrence is inherently sequential in time, but each of up to N simultaneous voice/capsule instances is fully independent — selects the instance, and a single thread per workgroup walks that instance's whole chunk sequentially (cheap: a chunk is a few hundred samples, and GPU dispatch overhead dominates at that size anyway, so there is nothing to gain from parallelizing within one instance's strictly sequential recurrence). <! 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


constrictionNoiseShader({ spectralShape = 'direct', lowpassHold = 32 } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: constriction noise.js — Phase 2 ParticleNN articulatory kernel. Turbulence/frication noise generator for a chosen internal tract junction (fricatives, plosive bursts) — deliberately a SEPARATE kernel from rather than reusing it directly, because the two have genuinely different shapes: generates one flat, constant amplitude signal for the whole dispatch (aspiration noise mixed at the glottis, (R6)'s ), while frication noise needs a per sample, per instance TIME VARYING amplitude envelope (driven by how tightly a constriction is formed, which changes continuously as an articulator moves) and per instance start index/seed so N simultaneous voices/characters never share correlated turbulence. Sharing the same underlying hash rather than inventing a second one is still correct reuse: below is the identical two round Murmur style avalanche hash as / 's (same technique as ), just applied per instance with an amplitude that varies per output sample instead of being a single dispatch wide uniform scalar. does not (yet) consume this kernel's output at a internally (its own docstring flags that as deferred, matching R6's 's own / option) — this kernel only produces the turbulence signal; injecting it into a specific internal tract junction is a orchestration concern for a later phase, once the model that decides the constriction's time varying amplitude envelope exists. Three spectral shapes are supported: (flat/white ish), the default reference; block interpolated for glottal aspiration, giving the noise a predominantly low frequency, breathy character rather than a hissy fricative one; first differenced (blue, +6 dB/octave) for oral frication and plosive bursts, where the high frequency


breathy character rather than a hissy fricative one; first differenced (blue, +6 dB/octave) for oral frication and plosive bursts, where the high frequency emphasis makes consonants like /s/ and /t/ pop without changing the vowel source. Functions Constants — constriction noise.js — Phase 2 ParticleNN articulatory kernel. Turbulence/frication noise generator for a chosen internal tract junction (fricatives, plosive bursts) — deliberately a SEPARATE kernel from rather than reusing it directly, because the two have genuinely different shapes: generates one flat, constant amplitude signal for the whole dispatch (aspiration noise mixed at the glottis, (R6)'s ), while frication noise needs a per sample, per instance TIME VARYING amplitude envelope (driven by how tightly a constriction is formed, which changes continuously as an articulator moves) and per instance start index/seed so N simultaneous voices/characters never share correlated turbulence. Sharing the same underlying hash rather than inventing a second one is still correct reuse: below is the identical two round Murmur style avalanche hash as / 's (same technique as ), just applied per instance with an amplitude that varies per output sample instead of being a single dispatch wide uniform scalar. does not (yet) consume this kernel's output at a internally (its own docstring flags that as deferred, matching R6's 's own / option) — this kernel only produces the turbulence signal; injecting it into a specific internal tract junction is a orchestration concern for a later phase, once the model that decides the constriction's time varying amplitude envelope exists. Three spectral shapes are supported: (flat/white ish), the default reference; block interpolated for glottal aspiration, giving the noise a predominantly low


Three spectral shapes are supported: (flat/white ish), the default reference; block interpolated for glottal aspiration, giving the noise a predominantly low frequency, breathy character rather than a hissy fricative one; first differenced (blue, +6 dB/octave) for oral frication and plosive bursts, where the high frequency emphasis makes consonants like /s/ and /t/ pop without changing the vowel source. <! 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:


solveLfShapeParameters({ t0, te, tp, ta, ee })

evaluateLfSample(cyclePos, { t0, te, ta, ee, wg, eps, alpha, e0 })

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: glottal lf.js — Phase 2 ParticleNN articulatory kernel. The full Liljencrants Fant (LF) glottal flow DERIVATIVE model, replacing 's raised cosine "LF lite" stand in ( (R6)'s own docstring calls that shape a deliberate simplification and names as the real implementation it stands in for). Per period, given control instants Te (glottal closure / main excitation, 0 < Te < T0), Tp (peak flow instant, 0 < Tp < Te), Ta (return phase time constant), and Ee (excitation strength), the classic two segment LF waveform is: E(t) = E0 exp(alpha t) sin(wg t) 0<=t<Te E(t) = (Ee/(eps Ta)) (exp( eps (t Te)) exp( eps (T0 Te))) Te<=t<T0 with . , , and are NOT free parameters — they are pinned by three physical constraints this file's author derived and verified algebraically (rather than recalling a textbook formula from memory, to avoid presenting an unverified transcendental equation as fact): 1. Boundary match at Te: E(Te ) = Ee, giving . 2. solves (the standard LF return phase time constant equation) via Newton Raphson with the exact analytic derivative , , started at . 3. solves the area balance constraint (glottal flow is periodic, so its derivative integrates to zero over one full period): substituting constraint 1 into the closed form (standard antiderivative) and the closed form return phase integral (simplified using constraint 2) gives where and ; this is solved for via Newton Raphson using the exact analytic derivative of (quotient rule from , ), started at (a safe, singularity free starting point: ). Both Newton solves run for a fixed, generous iteration count (8 each) — cheap scalar math, and every thread in this kernel redoes the same per instance solve redundantly rather than solving


generous iteration count (8 each) — cheap scalar math, and every thread in this kernel redoes the same per instance solve redundantly rather than solving once and broadcasting through workgroup memory: unlike 's per sample recurrence, LF generation has NO cross sample dependency at all (like / ), so the simplest correct design is one thread per (instance, sample) output element, matching those kernels' flat parallel convention exactly. If per period solve cost ever matters at scale, hoisting it into its own once per instance kernel (mirroring 's role for ) is a straightforward follow up, not a design change. Every control instant is expressed in SAMPLES (not seconds), matching 's / / convention and this kernel's own absolute sample counter continuity requirement across chunk boundaries. Functions CPU side reference implementation of the exact same closed form/Newton Raphson math the WGSL kernel below runs — used by the parity test and documented here as the canonical derivation any future GPU side per instance solve kernel (see docstring) must also match bit for bit in structure (same iteration count, same starting values). CPU side reference for a single sample's LF value, given already solved shape parameters — matches the WGSL kernel's per sample branch exactly. Constants — glottal lf.js — Phase 2 ParticleNN articulatory kernel. The full Liljencrants Fant (LF) glottal flow DERIVATIVE model, replacing 's raised cosine "LF lite" stand in ( (R6)'s own docstring calls that shape a deliberate simplification and names as the real implementation it stands in for). Per period, given control instants Te (glottal closure / main excitation, 0 < Te < T0), Tp (peak flow instant, 0 < Tp < Te), Ta (return phase time constant), and Ee (excitation strength), the classic two segment


/ main excitation, 0 < Te < T0), Tp (peak flow instant, 0 < Tp < Te), Ta (return phase time constant), and Ee (excitation strength), the classic two segment LF waveform is: E(t) = E0 exp(alpha t) sin(wg t) 0<=t<Te E(t) = (Ee/(eps Ta)) (exp( eps (t Te)) exp( eps (T0 Te))) Te<=t<T0 with . , , and are NOT free parameters — they are pinned by three physical constraints this file's author derived and verified algebraically (rather than recalling a textbook formula from memory, to avoid presenting an unverified transcendental equation as fact): 1. Boundary match at Te: E(Te ) = Ee, giving . 2. solves (the standard LF return phase time constant equation) via Newton Raphson with the exact analytic derivative ,


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: lip radiation.js — Phase 2 ParticleNN articulatory kernel. Idealized lip radiation filter: a first difference, , matching (R6)'s exactly ( ) — the differentiating characteristic of radiation from an open end. Despite being defined via a one sample recurrence, this is embarrassingly parallel: for is just the previous element of the same input buffer (already fully computed, no accumulation), and only needs externally supplied state ( , the previous chunk's final raw sample) — so every output sample can be computed independently with no sequential loop at all. Functions Constants — lip radiation.js — Phase 2 ParticleNN articulatory kernel. Idealized lip radiation filter: a first difference, , matching (R6)'s exactly ( ) — the differentiating characteristic of radiation from an open end. Despite being defined via a one sample recurrence, this is embarrassingly parallel: for is just the previous element of the same input buffer (already fully computed, no accumulation), and only needs externally supplied state ( , the previous chunk's final raw sample) — so every output sample can be computed independently with no sequential loop at all. <! 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: nasal junction.js — Phase 2 ParticleNN articulatory kernel. Production nasal branch: a second, independent Kelly Lochbaum tube chain generalizing risk/KellyLochbaumWaveguide.js (R6)'s proven createNasalBranch().step() to run a whole sample chunk times N instances on GPU, using the exact same one thread per section / double buffered workgroup memory / sequential workgroupBarrier per sample structure as tract waveguide.js (see that file's docstring for the full parallelization rationale, not repeated here). Differences from tract waveguide.js's oral tract, matching R6's createNasalBranch() exactly: The near end has no reflection term at all: nextRight[0] = inputFlow (R6's oral tract instead does sourceFlow + glottalReflection left[0]) — the nasal branch is driven directly by a coupled fraction of an oral tract tap signal, not its own glottal source. The far end uses a single nostrilReflection coefficient (R6's lipReflection equivalent). selects whether the first difference radiation filter is applied: 1.0 for R6's flow domain parity path, 0.0 for ParticleTract's LF derivative domain production path. This kernel does not itself compute the oral tract tap signal fed into inputFlow — that is tract waveguide.js's nasal tap output block, and inputFlow is an ordinary per instance per sample input buffer here, matching every other Phase 2 kernel's convention of not silently reaching into another kernel's state. input gain is the velum/nasal COUPLING fraction. R6's createNasalBranch() has no such parameter because its caller pre multiplied the tap signal (nasalCoupling nasalTapSignal) before calling step(). On GPU that would force either a whole extra scaling kernel or a CPU round trip in


the tap signal (nasalCoupling nasalTapSignal) before calling step(). On GPU that would force either a whole extra scaling kernel or a CPU round trip in the middle of an otherwise GPU resident chunk, so the scalar lives here instead — exactly where this file's own docstring already says the branch is "driven by a coupled fraction of an oral tract tap signal". input gain = 1.0 reproduces R6's step() bit for bit, which is what the parity test in phase2 dsp.html pins. Functions Shared flat output buffer layout — mirrors tractWaveguideOutputLayout() exactly (same three persisted state pieces plus the radiated signal), kept as its own function per kernel so a future layout change to one tract type can never silently affect the other. Constants — nasal junction.js — Phase 2 ParticleNN articulatory kernel. Production nasal branch: a second, independent Kelly Lochbaum tube chain generalizing risk/KellyLochbaumWaveguide.js (R6)'s proven createNasalBranch().step() to run a whole sample chunk times N instances on GPU, using the exact same one thread per section / double buffered workgroup memory / sequential workgroupBarrier per sample structure as tract waveguide.js (see that file's docstring for the full parallelization rationale, not repeated here). Differences from tract waveguide.js's oral tract, matching R6's createNasalBranch() exactly: The near end has no reflection term at all: nextRight[0] = inputFlow (R6's oral tract instead does sourceFlow + glottalReflection left[0]) — the nasal branch is driven directly by a coupled fraction of an oral tract tap signal, not its own glottal source. The far end uses a single nostrilReflection coefficient (R6's lipReflection equivalent). selects whether the first difference radiation filter is applied: 1.0 for R6's flow domain parity


coefficient (R6's lipReflection equivalent). selects whether the first difference radiation filter is applied: 1.0 for R6's flow domain parity path, 0.0 for ParticleTract's LF derivative domain production path. This kernel does not itself compute the oral tract tap signal fed into inputFlow — that is tract waveguide.js's nasal tap output block, and inputFlow is an ordinary per instance per sample input buffer here, matching every other Phase 2 kernel's convention of not silently reaching into another kernel's state. input gain is the velum/nasal COUPLING fraction. R6's createNasalBranch() has no such parameter because its caller pre multiplied the tap signal (nasalCoupling nasalTapSignal)


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: physiology feedback reduce.js — Phase 2 ParticleNN articulatory kernel. Reduces a high rate (32 kHz per §3) per sample waveguide/tract signal (e.g. 's radiated output, or a raw right/left traveling wave channel) down to one (mean, RMS) pair per fixed size frame — the §4 names as "a reduced/decimated feedback signal from the acoustic solve back toward the model", so the model's control rate loop (100 Hz per §3) can see a compact summary of what the acoustic solver actually produced last frame without reading back and processing the full high rate PCM itself. is expected to be one of the plan's fixed legal chunk buckets (first 12/16/24 frames, steady 32/48/64 frames at the activity frame size, or a caller chosen block size for this specific feedback path) — this kernel does not itself enforce bucket membership, it just requires exactly (no partial trailing frame), matching every other Phase 2 kernel's expectation that framing/bucketing is decided by the caller ( / take the same stance). One thread per (instance, frame) pair does its own small sequential reduction over samples — deliberately not a parallel reduction tree, since typical frame sizes here (tens to a few hundred samples) are small enough that per thread sequential summation is simpler and cheaper than the synchronization a tree reduction would need, the same reasoning 's per instance single thread recurrence gives for its own necessarily sequential loop (this kernel's reduction isn't sequential for correctness, just small enough that a loop is the pragmatic choice). Functions Packed output layout: [mean block (num instances num frames)] then [rms block (num instances num frames)] — kept as its own function so the WGSL


Functions Packed output layout: [mean block (num instances num frames)] then [rms block (num instances num frames)] — kept as its own function so the WGSL offsets and any JS side reader stay in lockstep, matching 's precedent. Constants — physiology feedback reduce.js — Phase 2 ParticleNN articulatory kernel. Reduces a high rate (32 kHz per §3) per sample waveguide/tract signal (e.g. 's radiated output, or a raw right/left traveling wave channel) down to one (mean, RMS) pair per fixed size frame — the §4 names as "a reduced/decimated feedback signal from the acoustic solve back toward the model", so the model's control rate loop (100 Hz per §3) can see a compact summary of what the acoustic solver actually produced last frame without reading back and processing the full high rate PCM itself. is expected to be one of the plan's fixed legal chunk buckets (first 12/16/24 frames, steady 32/48/64 frames at the activity frame size, or a caller chosen block size for this specific feedback path) — this kernel does not itself enforce bucket membership, it just requires exactly (no partial trailing frame), matching every other Phase 2 kernel's expectation that framing/bucketing is decided by the caller ( / take the same stance). One thread per (instance, frame) pair does its own small sequential reduction over samples — deliberately not a parallel reduction tree, since typical frame sizes here (tens to a few hundred samples) are small enough that per thread sequential summation is simpler and cheaper than the synchronization a tree reduction would need, the same reasoning 's per instance single thread recurrence gives for its own necessarily sequential loop (this kernel's reduction isn't sequential for correctness, just small enough that a loop is the pragmatic choice). <! HUMAN


its own necessarily sequential loop (this kernel's reduction isn't sequential for correctness, just small enough that a loop is the pragmatic choice). <! 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: signal add.js — Phase 2 ParticleNN articulatory kernel. Elementwise sum of two equal shaped signals: . needs exactly this twice, at the two points its signal graph merges: 1. Glottal source mix — ( ) + ( with a slowly varying envelope) into the that injects at the glottis. 2. Output mix — the oral tract's signal plus the nasal branch's signal ( , already scaled by its own coupling), producing the final PCM. Note that FRICATION is deliberately NOT a third term here. Turbulence belongs at the constriction, not the glottis, so it is fed to 's input and injected at — only the cavity in front of the constriction then filters it, which is what makes a fricative sound like a fricative rather than a whisper. That is why this kernel takes two inputs and not three. This kernel exists because nothing in the registry could do it. There was no elementwise add op, and — the only existing two signal combiner — is NOT a mixer: it sweeps its ratio across the buffer ( ), making it a one shot transition. Using it here would ramp the voicing/aspiration balance from 0 to 1 across every chunk. There are no gain inputs, deliberately: every amplitude this could scale is already a first class parameter of the kernel that PRODUCES the term — 's per instance , 's per sample , and 's . Duplicating that control here would invite the two copies to disagree. Flat parallel with no cross sample dependency (one thread per output element), matching / . Instance layout is implicit: the caller passes and both inputs share the same row major shape, so no per instance indexing is needed at all. Functions Constants — signal add.js — Phase 2 ParticleNN articulatory kernel. Elementwise sum of two equal shaped signals: .


indexing is needed at all. Functions Constants — signal add.js — Phase 2 ParticleNN articulatory kernel. Elementwise sum of two equal shaped signals: . needs exactly this twice, at the two points its signal graph merges: 1. Glottal source mix — ( ) + ( with a slowly varying envelope) into the that injects at the glottis. 2. Output mix — the oral tract's signal plus the nasal branch's signal ( , already scaled by its own coupling), producing the final PCM. Note that FRICATION is deliberately NOT a third term here. Turbulence belongs at the constriction, not the glottis, so it is fed to 's input and injected at — only the cavity in front of the constriction then filters it, which is what makes a fricative sound like a fricative rather than a whisper. That is why this kernel takes two inputs and not three. This kernel exists because nothing in the registry could do it. There was no elementwise add op, and — the only existing two signal combiner — is NOT a mixer: it sweeps its ratio across the buffer ( ), making it a one shot transition. Using it here would ramp the voicing/aspiration balance from 0 to 1 across every chunk. There are no gain inputs, deliberately: every amplitude this could scale is already a first class parameter of the kernel that PRODUCES the term — 's per instance , 's per sample , and 's . Duplicating that control here would invite the two copies to disagree. Flat parallel with no cross sample dependency (one thread per output element), matching / . Instance layout is implicit: the caller passes and both inputs share the same row major shape, so no per instance indexing is needed at all. <! 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


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: tract transfer.js — Phase 2 ParticleNN articulatory kernel. Converts a per instance tube cross sectional area profile into Kelly Lochbaum junction reflection coefficients — the exact formula (R6)'s proven uses: . 's own docstring notes junction coefficients are "computed CPU side by the caller... not recomputed here", matching 's precedent for a fixed shape precomputation — that is still correct for a STATIC area profile. This kernel exists for the case the plan's implies: an area profile predicted fresh every control frame (100 Hz per §3), which would otherwise force a GPU to CPU to GPU round trip every frame just to run one elementwise division — exactly the per frame readback stall the plan's Production Contract and style staged readback convention are meant to avoid. Keeping the whole path on GPU is what "single owned execution path" requires once area profiles become per frame instead of per utterance. Purely elementwise across pairs — no inter junction dependency at all (unlike 's per sample recurrence), so this is one thread per output element with no workgroup memory or barriers needed. Functions Constants — tract transfer.js — Phase 2 ParticleNN articulatory kernel. Converts a per instance tube cross sectional area profile into Kelly Lochbaum junction reflection coefficients — the exact formula (R6)'s proven uses: . 's own docstring notes junction coefficients are "computed CPU side by the caller... not recomputed here", matching 's precedent for a fixed shape precomputation — that is still correct for a STATIC area profile. This kernel exists for the case the plan's implies: an area profile predicted fresh every control frame (100 Hz per §3), which would otherwise force


profile. This kernel exists for the case the plan's implies: an area profile predicted fresh every control frame (100 Hz per §3), which would otherwise force a GPU to CPU to GPU round trip every frame just to run one elementwise division — exactly the per frame readback stall the plan's Production Contract and style staged readback convention are meant to avoid. Keeping the whole path on GPU is what "single owned execution path" requires once area profiles become per frame instead of per utterance. Purely elementwise across pairs — no inter junction dependency at all (unlike 's per sample recurrence), so this is one thread per output element with no workgroup memory or barriers needed. <! 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: tract waveguide.js — Phase 2 ParticleNN articulatory kernel. Production Kelly Lochbaum single delay per section digital waveguide vocal tract, generalizing (R6)'s proven recurrence to run entirely on GPU across a whole chunk of samples and N simultaneous voice/capsule instances. Junction reflection coefficients ( ) are computed CPU side by the caller via 's (a fixed shape, typically small computation — same rationale gives for precomputing its filter matrix CPU side rather than reproducing it in WGSL) and passed in as , not recomputed here. Constriction noise injection ( + ) and the nasal TAP signal ( ) ARE implemented, as faithful ports of R6's proven options — they were deferred when this kernel was first written, but cannot produce real fricatives or real nasal coupling without them: adds that sample's value to the RIGHT going wave entering junction , exactly as R6's . Injecting at the junction (rather than mixing noise into at the glottis) is what makes a fricative a fricative: only the cavity IN FRONT of the constriction filters the turbulence. writes for that section into the packed output's block every sample, giving an anatomically meaningful to be driven by. Matching R6 exactly, the tap is a READ ONLY observation: the oral tract is not itself perturbed by it. That remains a simplification versus a rigorous 3 port scattering junction (R6's own docstring says the same); it is enough for controllable, stable nasal coupling, and the honest limitation is recorded here rather than overstated. Both are opt in: a negative index disables that feature entirely, so callers that want neither pass and get bit identical behavior to this kernel before they existed. must match what the


index disables that feature entirely, so callers that want neither pass and get bit identical behavior to this kernel before they existed. must match what the SOURCE already is Lip radiation is approximately a differentiator, so R6's ends with . That is correct when the excitation is glottal FLOW, which is what R6's raised cosine pulse produced. It is WRONG when the excitation is already the flow derivative. is explicitly the LF glottal flow DERIVATIVE model, so feeding it in and then differencing again yields the SECOND derivative: +6 dB/octave of spurious tilt (audibly reedy/buzzy) and a far spikier waveform, whose large crest factor then drives any downstream limiter into distorting every single pitch pulse. Injecting a derivative source and skipping the difference is what gives the correct radiated pressure, and is why formant synthesizers use the LF derivative directly. therefore has to agree with the caller's source: 1.0 for a flow source (R6 parity), 0.0 for . There is no safe default that suits both, so it is an explicit parameter rather than a built in assumption. : the tube was perfectly lossless, and that is audible Scattering at a Kelly Lochbaum junction conserves energy exactly, so with only the glottis and lips absorbing anything, the formants of this tube had very high Q. Real vocal tracts lose energy continuously to yielding walls plus viscous and thermal effects, which is what gives formants their bandwidth (roughly 50 100 Hz for F1, more higher up). A resonator with too little damping rings after every excitation, and a whole tube of them reads as a metallic, synthetic buzz laid over the speech no matter how accurate the formant FREQUENCIES are — accurate centres with no bandwidth still does not sound human. multiplies each traveling wave once per


no matter how accurate the formant FREQUENCIES are — accurate centres with no bandwidth still does not sound human. multiplies each traveling wave once per section per sample, so a wave crossing the whole tract is attenuated . Because it is applied per section rather than once at a boundary, the loss accumulates with distance travelled, which is the correct behaviour for a distributed effect. It is a frequency INDEPENDENT approximation of a loss that really does grow with frequency; the honest limitation is recorded here rather than overstated, and a one pole filter per junction would be the refinement. 1.0 restores the lossless tube exactly, which is what the R6 parity test uses. One digital waveguide step is


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: visual state decimate.js — Phase 2 ParticleNN articulatory kernel. Decimates a high rate, multi CHANNEL tract field (e.g. a per section pressure like signal, one channel per tube section) down to one box averaged value per channel per fixed size frame — the §4 names as "a decimated field for ribbon/particle/heatmap visualization". Deliberately NOT a reuse of despite the similar per thread "small sequential average over a window" shape: that kernel reduces a single FLAT per instance signal to (mean, RMS) pairs for model feedback (a statistics reduction); this kernel decimates a multi CHANNEL per instance FIELD (extra channel/section axis) down to mean only per channel per frame, because a rendered airflow ribbon/ heatmap needs a representative value per tube section over time, not an energy statistic, and box averaging over the decimation window (rather than picking every Nth raw sample) avoids visual aliasing/flicker in the downsampled field — ordinary decimation filter practice, and consistent with how / already treat windowing as the caller's/kernel's job rather than raw strided subsampling. §4 also requires that visualization "must be bit identically disable able without changing rendered PCM" — this kernel reads its input field only (never writes back into it), so skipping this kernel's dispatch entirely when visualization is off cannot affect the / PCM path in any way; that invariant is structural (this kernel has no read write access to anything the acoustic path also reads), not merely a runtime convention. Functions Constants — visual state decimate.js — Phase 2 ParticleNN articulatory kernel. Decimates a high rate, multi CHANNEL tract field (e.g. a per section pressure


Constants — visual state decimate.js — Phase 2 ParticleNN articulatory kernel. Decimates a high rate, multi CHANNEL tract field (e.g. a per section pressure like signal, one channel per tube section) down to one box averaged value per channel per fixed size frame — the §4 names as "a decimated field for ribbon/particle/heatmap visualization". Deliberately NOT a reuse of despite the similar per thread "small sequential average over a window" shape: that kernel reduces a single FLAT per instance signal to (mean, RMS) pairs for model feedback (a statistics reduction); this kernel decimates a multi CHANNEL per instance FIELD (extra channel/section axis) down to mean only per channel per frame, because a rendered airflow ribbon/ heatmap needs a representative value per tube section over time, not an energy statistic, and box averaging over the decimation window (rather than picking every Nth raw sample) avoids visual aliasing/flicker in the downsampled field — ordinary decimation filter practice, and consistent with how / already treat windowing as the caller's/kernel's job rather than raw strided subsampling. §4 also requires that visualization "must be bit identically disable able without changing rendered PCM" — this kernel reads its input field only (never writes back into it), so skipping this kernel's dispatch entirely when visualization is off cannot affect the / PCM path in any way; that invariant is structural (this kernel has no read write access to anything the acoustic path also reads), not merely a runtime convention. <! 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


→ 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: chunks/complex math.js — Phase 1 ParticleNN kernel chunk. Generic complex arithmetic WGSL fragment (mul/add/sub/twiddle), split out as reusable infrastructure ahead of Phase 2's / kernels — R3's inlined its own twiddle multiply directly in the butterfly loop (fine for a disposable risk spike); Phase 2's production FFT kernel should compose this chunk instead of re deriving the same four multiplies/two adds. Complex numbers are represented as ( = real, = imag) throughout, not a named struct, to keep it directly usable as a return type/local without an extra struct declaration at every call site. Functions Constants — chunks/complex math.js — Phase 1 ParticleNN kernel chunk. Generic complex arithmetic WGSL fragment (mul/add/sub/twiddle), split out as reusable infrastructure ahead of Phase 2's / kernels — R3's inlined its own twiddle multiply directly in the butterfly loop (fine for a disposable risk spike); Phase 2's production FFT kernel should compose this chunk instead of re deriving the same four multiplies/two adds. Complex numbers are represented as ( = real, = imag) throughout, not a named struct, to keep it directly usable as a return type/local without an extra struct declaration at every call site. <! 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: chunks/f16 utils.js — Phase 1 ParticleNN kernel chunk. On the WGSL side, kernels use WGSL's native type directly ( + / etc.) when is available — no bit manipulation WGSL fragment is needed there, unlike 's manual unpack (WGSL has no native storage type, but it DOES have a native type). This file's job is the host side JS< f16 bit conversion needed to build/verify f16 test vectors and read 's raw f16 readback ( 's deliberately leaves tensors as raw bit patterns — this is where they get decoded). Functions IEEE 754 binary16 JS float64. JS float64 IEEE 754 binary16 bit pattern (round to nearest even is not implemented precisely — round half away from zero on the mantissa, adequate for test vector construction, not for production quality quantization aware training). Decode a raw f16 bits (e.g. from ) into a . Encode a / /plain array into an f16 bits , suitable for with . 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: chunks/int8 pack.js — Phase 1 ParticleNN kernel chunk. WGSL side: the fragment, extracted from R2's (proven correct there — R2's parity test passed with max abs/rel error 3.4e 7 against a JS scalar reference) into a shared chunk so / / all use the exact same unpack logic rather than each re deriving it. JS side: the host side symmetric block quantizer that produces the / pair this WGSL fragment expects, matching 's documented scheme: (zero point free, one scale per sized block). Functions Symmetric per block INT8 quantization: for each contiguous sized block of , scale = max(abs(block)) / 127, quantized = round(value / scale). Returns . must be a multiple of 4 (four int8 values pack into one u32, matching R2's little end is lowest index layout). Dequantize 's output back to a , for host side parity checking against a kernel's GPU output. Constants — chunks/int8 pack.js — Phase 1 ParticleNN kernel chunk. WGSL side: the fragment, extracted from R2's (proven correct there — R2's parity test passed with max abs/rel error 3.4e 7 against a JS scalar reference) into a shared chunk so / / all use the exact same unpack logic rather than each re deriving it. JS side: the host side symmetric block quantizer that produces the / pair this WGSL fragment expects, matching 's documented scheme: (zero point free, one scale per sized block). <! 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: chunks/math common.js — Phase 1 ParticleNN kernel chunk. Small reusable WGSL scalar math fragments shared by multiple kernel generators, so e.g. and any future fused activation kernel define / exactly once rather than each inlining its own copy (the kind of duplication the R2 spike's inline was an acceptable one off for, but Phase 1 kernels should not repeat). Functions Constants — chunks/math common.js — Phase 1 ParticleNN kernel chunk. Small reusable WGSL scalar math fragments shared by multiple kernel generators, so e.g. and any future fused activation kernel define / exactly once rather than each inlining its own copy (the kind of duplication the R2 spike's inline was an acceptable one off for, but Phase 1 kernels should not repeat). <! 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


conv1dW8a16Shader({ useShaderF16 = false } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: convolution/conv1d w8a16.js — Phase 1 ParticleNN kernel. 1D convolution, INT8 weights (same 4 packed per u32 layout and as ) x FP16/FP32 activations, FP32 accumulation. per output channel, padding (input implicitly zero padded so output length equals input length) — stride 1 only; dilation/stride are Phase 2+ follow ups if a consumer needs them (R7's toy Conv1D model used stride 1 only, and no Phase 1/0 document commits to anything else yet). Weight layout: , a u32 whose 4 bytes are int8 weights for the flattened index , where and . is the per output channel scale. must be a multiple of 4. 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


transpose2dShader({ useShaderF16 = false } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: core/transpose 2d.js — Phase 3 ParticleNN kernel. 2D transpose: , i.e. → , both row major. Why this exists The Phase 1 kernels disagree about which axis is major, and building is the first time anything composes them: writes — sequence major (one row per token), the natural shape for a gather. reads — channel major , the natural shape for sliding a kernel along time. normalizes each ROW independently, so per token normalization over the feature axis needs sequence major again. Neither layout is wrong for its own kernel, but the encoder has to cross between them, and nothing in the registry could. Rather than duplicating a transposed variant of the convolution (or silently re interpreting a buffer and producing scrambled activations), the axis swap is its own explicit, testable op. Deliberately naive: one thread per element, no tiling and no shared memory staging. The encoder's tensors are small (tens of channels x hundreds of frames), so the uncoalesced write is not worth the complexity — and a tiled version can replace this later without changing a single caller, since the contract is just "swap the axes". Functions Constants — core/transpose 2d.js — Phase 3 ParticleNN kernel. 2D transpose: , i.e. → , both row major. Why this exists The Phase 1 kernels disagree about which axis is major, and building is the first time anything composes them: writes — sequence major (one row per token), the natural shape for a gather. reads — channel major , the natural shape for sliding a kernel along time. normalizes each ROW independently, so per token normalization over the feature axis needs sequence major again. Neither layout is wrong for its own kernel, but the encoder has to cross


so per token normalization over the feature axis needs sequence major again. Neither layout is wrong for its own kernel, but the encoder has to cross between them, and nothing in the registry could. Rather than duplicating a transposed variant of the convolution (or silently re interpreting a buffer and producing scrambled activations), the axis swap is its own explicit, testable op. Deliberately naive: one thread per element, no tiling and no shared memory staging. The encoder's tensors are small (tens of channels x hundreds of frames), so the uncoalesced write is not worth the complexity — and a tiled version can replace this later without changing a single caller, since the contract is just "swap the axes". <! 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: complex mul.js — Phase 2 ParticleNN DSP kernel. Elementwise complex multiplication: , over interleaved buffers, matching 's interleaved complex layout so FFT output can feed this directly (e.g. frequency domain filtering: then ). Functions Constants — complex mul.js — Phase 2 ParticleNN DSP kernel. Elementwise complex multiplication: , over interleaved buffers, matching 's interleaved complex layout so FFT output can feed this directly (e.g. frequency domain filtering: then ). <! 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: fft1024 f32.js — Phase 2 ParticleNN DSP kernel. Single workgroup, in workgroup memory, iterative radix 2 Cooley Tukey forward FFT — generalizes (R3)'s proven butterfly network to run with 256 threads/workgroup (each thread handles 2 butterfly operations per stage / 4 elements for load scatter) instead of R3's 512, so it needs no elevated request — every conformant WebGPU adapter guarantees 256 by default. This resolves the exact gap §4 flagged as an unresolved "Phase 1/2 follow up": rather than requesting a higher limit with a fallback path for adapters that refuse it, this kernel simply never needs the higher limit. One workgroup computes exactly one 1024 point complex FFT; selects which frame of a batch to process ( ), matching R3's batching design. Complex numbers are interleaved in a single flat per frame ( ) — one input buffer, one output buffer, matching every other Phase 1/2 kernel's single input/single output convention (unlike R3's separate real/imag arrays). No uniform buffer is needed (frame selection comes entirely from ), so this kernel registers with in . Functions Shared by and — (+1 forward, 1 inverse) is baked in at generation time, not read from a uniform, since each op is a distinct, fixed behavior kernel. Constants — fft1024 f32.js — Phase 2 ParticleNN DSP kernel. Single workgroup, in workgroup memory, iterative radix 2 Cooley Tukey forward FFT — generalizes (R3)'s proven butterfly network to run with 256 threads/workgroup (each thread handles 2 butterfly operations per stage / 4 elements for load scatter) instead of R3's 512, so it needs no elevated request — every conformant WebGPU adapter guarantees 256 by default. This resolves the exact gap §4 flagged as


instead of R3's 512, so it needs no elevated request — every conformant WebGPU adapter guarantees 256 by default. This resolves the exact gap §4 flagged as an unresolved "Phase 1/2 follow up": rather than requesting a higher limit with a fallback path for adapters that refuse it, this kernel simply never needs the higher limit. One workgroup computes exactly one 1024 point complex FFT; selects which frame of a batch to process ( ), matching R3's batching design. Complex numbers are interleaved in a single flat per frame ( ) — one input buffer, one output buffer, matching every other Phase 1/2 kernel's single input/single output convention (unlike R3's separate real/imag arrays). No uniform buffer is needed (frame selection comes entirely from ), so this kernel registers with in . <! 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: ifft1024 f32.js — Phase 2 ParticleNN DSP kernel. Inverse of : same butterfly network (see that file's docstring for the full algorithm/limit generalization rationale), with baked in — conjugate the input, run the same forward butterfly network, conjugate + scale by ( ), matching R3's proven identity. Functions 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


matmulW8a16Shader({ useShaderF16 = false } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: matmul/matmul w8a16.js — Phase 1 ParticleNN kernel. INT8 weights (4 packed per u32, per output channel scale, 's ) x FP16 activations, FP32 accumulation, FP16 output — the real target this plan names, superseding R2's FP32 activation stand in ( ) now that R1 has proven is available on at least one reference device. Falls back to FP32 activations/output when is false (DeviceContract v0's tier) — same kernel body, different element type, not two separately maintained kernels. Weight layout (unchanged from R2, already proven): logical weights are [K, N]; is a u32 whose 4 bytes are the int8 weights for k = k4 4 + 0..3 (little end = lowest k); is the per output channel dequantization scale. K must be a multiple of 4. 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


rmsnormF16Shader({ useShaderF16 = false, eps = 1e-6 } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: normalization/rmsnorm f16.js — Phase 1 ParticleNN kernel. Row wise RMSNorm: . One workgroup per row; workgroup shared reduction for the sum of squares (standard tree reduction, must be a power of two). Accumulates in f32 regardless of , matching 's "FP32 accumulation" convention — only the input/output storage element type changes with the feature flag. Functions Constants — normalization/rmsnorm f16.js — Phase 1 ParticleNN kernel. Row wise RMSNorm: . One workgroup per row; workgroup shared reduction for the sum of squares (standard tree reduction, must be a power of two). Accumulates in f32 regardless of , matching 's "FP32 accumulation" convention — only the input/output storage element type changes with the feature flag. <! 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


dequantInt8Shader({ useShaderF16 = false } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: quantization/dequant int8.js — Phase 1 ParticleNN kernel. Standalone unpack+dequantize kernel: / fuse unpack+dequant+multiply accumulate inline for performance, but /tooling sometimes need a plain materialized dequantized tensor (e.g. for a CPU side parity check, or a debug visualization) without running a full matmul — this is that kernel. Uses the same and per block scale scheme as 's documented metadata. 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


<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: quantization/pack unpack.js — Phase 1 ParticleNN kernel. The pack direction complementing 's unpack direction: a GPU kernel that bit packs already quantized int8 values (as inputs already rounded/clamped to [ 127, 127] — computing the scale is a separate reduction pass, not this kernel's job) into 4 packed u32 words, matching 's host side 's packed word layout exactly (so a GPU side requantization pipeline and the JS host side one are interchangeable). Functions Packs (one already quantized value per element, [ 127,127]) into (4 values per word). must be a multiple of 4. JS side reference pack, for parity testing against a CPU implementation. Mirrors 's packing loop exactly. Constants — quantization/pack unpack.js — Phase 1 ParticleNN kernel. The pack direction complementing 's unpack direction: a GPU kernel that bit packs already quantized int8 values (as inputs already rounded/clamped to [ 127, 127] — computing the scale is a separate reduction pass, not this kernel's job) into 4 packed u32 words, matching 's host side 's packed word layout exactly (so a GPU side requantization pipeline and the JS host side one are interchangeable). <! 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: crossfade.js — Phase 2 ParticleNN DSP kernel. Equal power crossfade between two equal length signals over their full length: , — equal power (not linear) so the perceived loudness stays constant through the fade instead of dipping at the midpoint (linear crossfade's well known flaw), matching the constant power crossfade convention 's reaction system voice transitions call for. Functions Constants — crossfade.js — Phase 2 ParticleNN DSP kernel. Equal power crossfade between two equal length signals over their full length: , — equal power (not linear) so the perceived loudness stays constant through the fade instead of dipping at the midpoint (linear crossfade's well known flaw), matching the constant power crossfade convention 's reaction system voice transitions call for. <! 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


embeddingF16Shader({ useShaderF16 = false } = {})

<! AUTOGENERATED by tools/extract api.py — content above HUMAN NOTES is overwritten Source: speech/embedding f16.js — Phase 1 ParticleNN kernel. Row gather embedding lookup: . Named under (not ) because its first production consumer is 's phoneme ID embedding (Phase 3), looking up rows out of 's fixed 42 entry table — but the kernel itself is generic over table/embedding dim size. (That count read "51" until Phase 3: the spec's own summary line miscounted its vowel tables. is the executable source of truth and exports , which is what a caller should size from rather than any hard coded literal.) Output layout is — SEQUENCE major, one row per token. Note that expects CHANNEL major , so composing the two requires in between; does exactly that. Functions Constants — speech/embedding f16.js — Phase 1 ParticleNN kernel. Row gather embedding lookup: . Named under (not ) because its first production consumer is 's phoneme ID embedding (Phase 3), looking up rows out of 's fixed 42 entry table — but the kernel itself is generic over table/embedding dim size. (That count read "51" until Phase 3: the spec's own summary line miscounted its vowel tables. is the executable source of truth and exports , which is what a caller should size from rather than any hard coded literal.) Output layout is — SEQUENCE major, one row per token. Note that expects CHANNEL major , so composing the two requires in between; does exactly that. <! 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: harmonic source.js — Phase 2 ParticleNN DSP kernel. Voiced glottal pulse train — the "LF lite" raised cosine shape proven in (R6): flow(n) = 0.5 (1 cos(2 pi cyclePos(n)/openSamples)) for cyclePos(n) < openSamples flow(n) = 0 otherwise Unlike R6's per sample sequential CPU generator (which tracks as running state, updated one sample at a time), this kernel computes every sample in closed form and fully in parallel : , using an absolute sample counter ( ) the caller persists and advances across chunk boundaries — exactly the "LF glottal source with absolute counter" the plan's checklist calls for, and mathematically identical to R6's per sample recurrence for as long as / hold constant across the dispatched chunk (the same constant until the next period boundary assumption R6's own generator already makes). Aspiration noise is NOT mixed in here (unlike R6's spike, which combined both for simplicity) — that is 's job, mixed downstream, since the operator allowlist treats voiced and unvoiced excitation as independent ops that a later stage combines. Functions Constants — harmonic source.js — Phase 2 ParticleNN DSP kernel. Voiced glottal pulse train — the "LF lite" raised cosine shape proven in (R6): flow(n) = 0.5 (1 cos(2 pi cyclePos(n)/openSamples)) for cyclePos(n) < openSamples flow(n) = 0 otherwise Unlike R6's per sample sequential CPU generator (which tracks as running state, updated one sample at a time), this kernel computes every sample in closed form and fully in parallel : , using an absolute sample counter ( ) the caller persists and advances across chunk boundaries — exactly the "LF glottal source with absolute counter" the plan's checklist calls for, and mathematically


caller persists and advances across chunk boundaries — exactly the "LF glottal source with absolute counter" the plan's checklist calls for, and mathematically identical to R6's per sample recurrence for as long as / hold constant across the dispatched chunk (the same constant until the next period boundary assumption R6's own generator already makes). Aspiration noise is NOT mixed in here (unlike R6's spike, which combined both for simplicity) — that is 's job, mixed downstream, since the operator allowlist treats voiced and unvoiced excitation as independent ops that a later stage combines. <! 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