Eve library

Aja V1 Descope Decision (V1-P2-0331)

Guide

Revision 1

On this page

Date: 2026-04-27 Decision driver: aja-readiness-audit.md (V1-P2-0330) Owner: Platform / Aja domain leads Status: Locked — informs V1-P2-0332..0334 and the V1-MET-197/198/199 exit criteria below.

Decision#

Adopt the descope-to-MVP recommendation from V1-P2-0330.

V1 ships a thin Aja MVP that is shippable today. All GPU / ML-inference / distributed-worker functionality is deferred to V2, gated on the runtime decisions captured in V1-P2-0333 (Kubernetes runtime) and V1-P2-0334 (GPU pipeline) and the canonical contract scaffold from V1-P2-0332.

What ships in V1#

Area Subproject Why it's V1-ready
Client SDK (TS) libs/aja/motion-pipeline-sdk Real OAuth2 client, retry, NDJSON streaming, batch ops. ~7k LOC, has tests.
Client SDK (Python) libs/aja/motion-pipeline-sdk-python Real httpx/pydantic async + sync clients, optional torch. ~8k LOC.
Format conversion libs/aja/motion-formats BVH/FBX/GLB/USD/Alembic; non-ML, deterministic.
Orchestration service apps/aja/svc-motion-pipeline Fastify-based job manager, webhooks, polling, streaming download. No GPU dependency.
CLI apps/aja/cli Real CLI; thin wrapper over the SDK.
Embodied-instruction contract layer apps/aja/svc-motion-ai/src/embodied-instruction/* and the canonical wiring in libs/metis/integrations/src/aja-canonical-wiring.ts Already shipped via V1-MET-197/198/199. Contract-level surface is real and tested.
New for V1 libs/contracts/src/aja/ To be created in V1-P2-0332. Houses the canonical job/format/status contract that the SDK + service share.
New for V1 A helm/aja-service chart for svc-motion-pipeline only No GPU node pool; document explicitly that ML workers are V2.

What is deferred to V2#

These remain in libs/aja/ but are not part of the V1 ship list and must be excluded from V1 release artifacts (Helm, ArgoCD apps, docker-compose production profiles, CI release pipelines):

  • GPU paths: batch-inference GPU memory queries, pipeline-parallelism, model-optimization (TensorRT/mixed-precision/quantization).
  • ML inference: neural-retargeting, human-mesh-recovery, pose-lifting, depth-sensing, multi-view-reconstruction, blend-shape-retargeting, proportional-adaptation, skeleton-mapping, semantic-retargeting.
  • Distributed scaling: distributed-workers (its K8s health checks are simulated).
  • ML-adjacent stubs: content-moderation, content-security, content-watermarking, consent-management, data-retention.
  • Apps: apps/aja/svc-motion-ai (the embodied-instruction routes are real-looking but their underlying motion analysis depends on the deferred libs above), apps/aja/svc-reference-video.

The deferred libraries continue to compile and pass type checks so the monorepo stays green; they just are not promoted to release tagging or production deployment in V1.

Why descope, not complete#

Captured in detail in aja-readiness-audit.md §7.1. Summary:

  1. Load-bearing inference paths are simulated (17 explicit "in production" markers; 124 Math.random() calls in implementation source; SMPL model data initialized as empty Float32Arrays).
  2. External procurement / decision blockers stand in the way of real motion AI: SMPL weights, ONNX runtime selection, GPU runtime strategy, K8s operator strategy.
  3. Deployment posture is bare: zero Aja Dockerfiles, no Helm chart, no GPU node-pool config, no aja-ci.yml.
  4. Test coverage is 9 / 37 libs (~24 %), zero E2E tests connecting cli → service → workers.
  5. Other Tier-A domains (lilith, saraswati) already ship Helm charts; matching their floor in V1 needs material work that must precede shipping any inference layer.

Completing the full domain in V1 would require a multi-quarter ML platform build-out (model procurement, inference runtime, GPU operator, fault tolerance) before any code in human-mesh-recovery etc. could be promoted beyond a stub. Descoping removes that critical path from V1.

Revised V1-MET-197/198/199 exit criteria#

These three were already marked [x] in OSHUN_V1_TODOS.md (lines 5164–5187). Their substance lives at the canonical Metis↔Aja contract layer in libs/metis/integrations/src/aja-canonical-wiring.ts and the embodied-instruction service surface in apps/aja/svc-motion-ai, both of which are real today. The descope does not regress them; it simply clarifies the surface they are guaranteeing.

The locked exit criteria after this decision:

  • V1-MET-197 — Confirm Aja embodied-instruction services exist as stable backend APIs: Exit criterion is satisfied at the service-interface level — embodied-instruction/service.ts, embodied-instruction/types.ts, capabilities discovery endpoint, and demonstration / coaching-overlay / session-handoff endpoints with stable schemas. No requirement that the underlying motion-AI inference (e.g. human-mesh-recovery) be backed by real ML in V1 — the contract is what Metis consumes, and the contract is real.

  • V1-MET-198 — Canonical Aja adapter interface for Metis: Exit criterion is satisfied by libs/metis/integrations/src/aja-canonical-wiring.ts defining the movement-demonstration / coaching-overlay / session-handoff contracts. The descope does not change this — the canonical wiring is the V1 ship target and remains valid.

  • V1-MET-199 — End-to-end integration tests: Exit criterion is satisfied by libs/metis/integrations/src/aja-canonical-wiring.integration.test.ts exercising the canonical contract path. Under this descope, the test is expected to run against the contract surface, not against a live GPU-backed inference runtime. That posture is already what the test does today and is locked in by this decision.

If V2 rebuilds the underlying inference, V1-MET-197/198/199 will not need re-opening — the canonical contract is the stable surface. New V2 tickets will cover the live-inference exit criteria.

Knock-on tasks#

  • V1-P2-0332 — Create libs/contracts/src/aja/ housing canonical contracts now that the descope is locked. The contracts to scaffold are the ones already drafted in libs/metis/integrations/src/aja-canonical-wiring.ts (movement demonstration, coaching overlay, session handoff) plus the job / format / status contracts already implicit in motion-pipeline-sdk.

  • V1-P2-0333 — Kubernetes runtime decision is deferred but should still produce a strategy doc at docs/releases/p2/aja-runtime-strategy.md recording the V1 posture (single Helm chart for the orchestration service; GPU node pool deferred).

  • V1-P2-0334 — GPU pipeline decision is deferred but should produce a strategy doc capturing the V2 candidates (CUDA via NVML, ROCm, cloud-only) and the data points needed to choose between them.

What this decision does not change#

  • The Metis side of the integration (already shipped via V1-MET-197/198/199) is not regressed. Metis lessons that hand off to embodied-instruction continue to do so.
  • The libs/aja/README.md aspirational claims about HMR 2.0, CLIFF, PyMAF-X, etc. must be rewritten before V1 ship to match the descoped reality. (Tracked separately under documentation hygiene.)
  • No code is deleted by this decision. Deferred libraries continue to compile and pass type checks so the monorepo stays green. They are simply not on the V1 release manifest.