Vili/docs/verse-service-contract.md
Meta Vens 5050de58b5 Gate: one slot judged where the GPU is taken, own VRAM discounted, truthful placement body, env refusal
acquire() judges at the slot: household signals first (admission), then a held slot (slot);
nothing queues, so a request can no longer wait on the worker lock past a changed gate. While
Vili's job holds the slot, and until free VRAM recovers to its pre-job level (capped), low free
VRAM is not the household's; full-screen and 3D always count. A sample with no resolved 3D
counters is a probe fault and the gate fails closed. The placement 503 carries no gate status.
A malformed VILI_GPU_* override refuses to start, naming the variable.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 00:19:08 +02:00

6.8 KiB

Vili Verse Service Contract

Objective

Vili turns Persona performance intent into animation work. The near-term body is Kimodo on Raven; the durable contract is a service surface that can accept a gesture/action prompt, run or queue motion synthesis, and publish inspectable state for Odin and Idunn.

Vili is an animation service, not a per-request CLI wrapper. Its Kimodo backend is a resident worker container that owns model lifetime for generation requests.

CultMesh Verses

  • vili.service: service identity, provider advertisement, health, and runtime.
  • vili.animation: animation jobs, prompts, backend choices, and artifact refs.
  • vili.operator: daemon status, backend readiness, and Eve/CultUI surface.

Witnesses

  • .vili/vili.service.cc: Vili-owned CultCache store for provider advertisement, operator state, Eve surface, command boundary, and transport profile records.
  • .vili/provider-advertisement.json: compatibility export derived from the provider advertisement record.
  • .vili/operator-state.json: compatibility export derived from daemon health and backend readiness.
  • .vili/eve-operator-surface.json: compatibility export of the current operator surface.
  • .vili/command-boundary.json: compatibility export of Vili command authority.
  • .vili/transport-profile.json: compatibility export of Vili transport state.
  • .vili/jobs/{jobId}.json: accepted animation job records.
  • .vili/artifacts/{jobId}/: generated motion outputs when generation succeeds.
  • vili-kimodo-worker: resident Docker container exposing the loaded Kimodo model to Vili inside Raven's Ubuntu-24.04 WSL runtime.

JSON is a compatibility witness. Vili's service/operator/command/transport truth is the daemon-owned .cc store; animation job schemas may still be promoted from JSON once that request/receipt shape stabilizes.

Command Boundary

POST /motion/generate accepts an explicit animation request and forwards the supported Kimodo generation controls to the resident worker. Vili owns job identity, request persistence, worker lifecycle, timeout handling, and the artifact stem. Kimodo owns synthesis and model-specific export. Vili also owns GPU tenancy admission: the daemon holds one GPU slot, and POST /motion/generate is judged when it reaches the slot. It answers HTTP 503 with retry-after: 60 and one of three bodies, by source: { "ok": false, "code": "gpu-busy", "source": "admission", "gpu": { inUse, since, checkedAt, probeOk } } while the household is using the GPU; { "ok": false, "code": "gpu-busy", "source": "slot" } while another job holds the slot (nothing queues); and { "ok": false, "code": "gpu-busy", "source": "placement", "jobId" } when the encoder child refused its own placement, where the job file was written and no household status is claimed. The code field is the only carrier; a consumer retries after retry-after and never matches error text. A job already running finishes.

{
  "prompt": "a person gives a small friendly wave",
  "duration": 1,
  "diffusionSteps": 20,
  "seed": 123,
  "bvh": true
}

Kimodo metadata can be sent directly when callers need multi-segment or multi-sample generation:

{
  "meta": {
    "texts": [
      "a person gives a small friendly wave",
      "a person takes one careful step"
    ],
    "durations": [0.5, 0.5],
    "num_samples": 1,
    "diffusion_steps": 20
  },
  "model": "Kimodo-SOMA-RP-v1.1",
  "numTransitionFrames": 3,
  "cfgType": "regular",
  "cfgWeight": [1.5],
  "seed": 6101,
  "bvh": true,
  "bvhStandardTpose": true,
  "saveExampleDir": true
}

Request fields accepted by Vili:

  • prompt / utterance plus duration / durationSeconds
  • texts plus durations, or a full meta object
  • inputFolder / input_folder for a container-visible Kimodo input folder containing meta.json and optional constraints.json
  • model; the daemon keeps one resident model loaded, so a model change restarts vili-kimodo-worker
  • diffusionSteps / diffusion_steps
  • numSamples / num_samples
  • numTransitionFrames / num_transition_frames
  • constraints as an object/list, or constraints, constraintsPath, or constraints_path as a container-visible path
  • seed
  • cfg, cfgType / cfg_type, cfgWeight / cfg_weight
  • bvh, bvhStandardTpose / bvh_standard_tpose
  • noPostprocess / no_postprocess
  • saveExampleDir / save_example_dir
  • timeoutMs, workerTimeoutMs

Vili does not accept arbitrary output paths from callers. Every generation writes beneath .vili/artifacts/{jobId}/, with the worker receiving /outputs/{jobId}/motion. The job record is the authority for artifact refs. Model-specific exports are preserved: SOMA writes NPZ and optional BVH, SMPLX also writes AMASS NPZ, and G1 also writes CSV.

The daemon may reject or defer requests when:

  • Kimodo image is unavailable.
  • Docker/GPU backend is unhealthy.
  • Hugging Face token is absent and the selected backend requires gated model access.
  • The resident Kimodo worker cannot start or does not become healthy before the request timeout.
  • The request omits concrete prompt, metadata, batch text, or input-folder intent.
  • Batch texts are provided without matching durations.

Credential State

Raven has a Hugging Face token installed in the Ubuntu-24.04 WSL cache, and Vili mounts it into Kimodo containers read-only. Verified on 2026-06-12: a Kimodo container launched by Raven could read gated metadata for meta-llama/Meta-Llama-3-8B-Instruct.

Kimodo Worker Boundary

The resident worker is started by Vili as Docker container vili-kimodo-worker. Because Raven's Docker Engine lives inside WSL, Vili also starts a minimal WSL keepalive process recorded at /tmp/vili-wsl-keepalive.pid; it owns no service truth and exists only to keep the Docker substrate alive while the resident worker holds the model.

It mounts:

  • /root/.cache/huggingface for model/token access.
  • E:\Projects\Vili\scripts\kimodo-resident-worker.py as the worker program.
  • E:\Projects\Vili\.vili\artifacts as /outputs for generated artifacts.

Inside the worker, Kimodo owns synthesis. Vili owns worker lifecycle, request/response persistence, timeout handling, and artifact references. Direct user requests, programmatic requests, and smoke-started warmup all use the same resident worker health and generation path.

Observed on 2026-06-12: first worker model load took about 100 seconds. Once resident, five 1 second / 20 step service-path generations averaged about 54.4 seconds per clip, or about 0.0184x realtime.

First Runtime Invariant

Health checks must be cheap. They may verify process, port, backend metadata, and cached readiness, but they must not launch a Kimodo generation job or start model load. Smoke checks may start the resident worker because their purpose is backend readiness, not cheap liveness.