Momentum
Documentation
The spec that makes decisions telemetry.
Momentum is three independently deployable layers on top of OpenTelemetry. This page is the short version — the working draft of the full convention lives with the team.
The six attribute namespaces
The convention is defined in tiers so it can be adopted incrementally. Tier 0 alone is enough for functional root-cause analysis.
| Namespace | Tier | What it records |
|---|---|---|
| robot.task.* | 0 | Task name, goal descriptor, priority |
| robot.decision.* | 0 | Decision type, inputs, output, confidence |
| robot.joint.* | 0 | Joint identity; joint.id required on metric observations |
| robot.fault.* | 0 | Fault type, severity, affected joint |
| robot.verification.* | 0 | Outcome check; passed=false on an OK span flags a silent failure |
| robot.controller.* | 1 | Active controller mode and name |
The open convention
Protocol- and backend-agnostic. Produces standard OTel traces consumable by Jaeger, AWS X-Ray, Google Cloud Trace, or any OTLP collector. The SDK works with no Momentum backend present — and your data exports in full, always.
The SDK
A Python package whose only required dependency is opentelemetry-api. Four entry points — task, decision, controller_switch, fault — plus verification. Observability-only; it never alters execution.
The engine
Ingests traces over OTLP into a queryable store and watches them as they land — errors and OK-status runs carrying a failed verification, the silent failures nothing else can see. Diagnoses return ranked hypotheses with cited evidence, deliverable by webhook, and every engineer verdict is kept: the engine never diagnoses the same failure from zero twice.
Where the convention is heading
Four additions turn traces into analytics: robot.policy.version (which software/policy build made each decision), robot.decision.id, robot.decision.alternatives (what the model considered and rejected), and robot.decision.outcome — the label linking each decision to whether it ultimately succeeded. Outcome labels are what make regression detection, confidence calibration and deployment gates computable at all — and Momentum derives most of them automatically, from task status, verifications and retries.