1---2name: abdelstark-worldforge-worldforge3description: Provider Adapter Development4---56# Provider Adapter Development78## Non-Negotiables910- Valid capabilities are `predict`, `embed`, `plan`, `score`, and `policy`.11- `ProviderCapabilities()` is fail-closed. Advertise only callable, tested operations.12- `plan` is a WorldForge facade workflow. Do not benchmark or advertise it as a provider operation unless a real provider-owned planner exists.13- Optional runtimes, checkpoints, datasets, CUDA, robot packages, credentials, and robot controllers stay out of base dependencies and repo artifacts.14- Provider events are a log boundary. Never emit bearer tokens, API keys, signed URL query strings, or secret-like metadata.15- Treat upstream marketing names as untrusted. Capability labels come from observed callable behavior16 and contract tests, not from model family branding.1718## Capability Map1920| Provider | Truthful surface | Registration |21| --- | --- | --- |22| `mock` | `predict`, `embed` | always |23| `cosmos-policy` | `policy` | `COSMOS_POLICY_BASE_URL` |24| `leworldmodel` | `score` | `LEWORLDMODEL_POLICY` or `LEWM_POLICY` |25| `gr00t` | `policy` | `GROOT_POLICY_HOST` |26| `lerobot` | `policy` | `LEROBOT_POLICY_PATH` or `LEROBOT_POLICY` |27| `jepa` | `score` | `JEPA_MODEL_NAME` |28| `genie` | scaffold only | env-gated reservation |29| `jepa-wms` | direct-construction score candidate | not exported or auto-registered |3031## Workflow32331. Read the closest existing adapter, then `src/worldforge/providers/base.py`, `src/worldforge/providers/catalog.py`, and `docs/src/provider-authoring-guide.md`.342. Classify the upstream runtime by what it actually does, not by model marketing language.353. For a new scaffold, start with `uv run python scripts/scaffold_provider.py ...`; keep capabilities unadvertised until real methods return validated WorldForge models.364. Validate public inputs before network calls, filesystem reads, or optional runtime calls.375. Return the correct public model: `PredictionPayload`, `EmbeddingResult`, `ActionScoreResult`, or `ActionPolicyResult`.386. Add success and malformed/error fixtures under `tests/fixtures/providers/`.397. Add `worldforge.testing.assert_provider_contract()` coverage for every advertised capability.408. Update `.env.example`, provider docs, generated catalog surfaces, README, changelog, `AGENTS.md`, or `CLAUDE.md` only when public behavior or env vars change.419. Validate with focused provider tests, ruff, generated provider-doc check, and the coverage/package gates when the public surface changes.4243## Definition Of Done4445- Every advertised capability has a provider-contract test and at least one malformed/provider-error test.46- Provider metadata, docs, generated catalog output, and `.env.example` agree on capabilities and configuration.47- Events and public errors redact credentials, signed URLs, host-local secrets, and unsafe metadata.48- Optional-runtime paths degrade to typed skipped/preflight results without installing host-owned packages.4950## Sharp Edges5152| Symptom | Cause | Fix |53| --- | --- | --- |54| Provider appears in docs with wrong surface | `ProviderCapabilities` declaration drifted | Fix adapter capabilities, run provider docs generator, update tests |55| Optional provider missing from `doctor` | Required env var absent | Confirm variable name from `.env.example`; do not read `.env` |56| Contract helper fails on JSON | Metadata/raw payload not JSON-native | Validate at construction and convert tuples/objects before return |57| Remote test leaks URL/query | Event target/message metadata not sanitized | Add regression in `tests/test_observability.py` or provider test |5859---60> Source: [AbdelStark/worldforge](https://github.com/AbdelStark/worldforge) — distributed by [TomeVault](https://tomevault.io).61<!-- tomevault:4.0:skill_md:2026-06-17 -->
tomevault-io