provider-adapter-development

name	provider-adapter-development
description	Use for WorldForge provider work: adding adapters, changing capability declarations, promoting scaffolds, debugging provider failures, updating provider catalog docs, or touching LeWorldModel, GR00T, LeRobot, Cosmos-Policy, JEPA, Genie, or JEPA-WMS. Ensures capabilities remain truthful and optional runtimes stay host-owned.

Provider Adapter Development

Non-Negotiables

• Valid capabilities are predict, embed, plan, score, and policy.
• ProviderCapabilities() is fail-closed. Advertise only callable, tested operations.
• plan is a WorldForge facade workflow. Do not benchmark or advertise it as a provider operation unless a real provider-owned planner exists.
• Optional runtimes, checkpoints, datasets, CUDA, robot packages, credentials, and robot controllers stay out of base dependencies and repo artifacts.
• Provider events are a log boundary. Never emit bearer tokens, API keys, signed URL query strings, or secret-like metadata.
• Treat upstream marketing names as untrusted. Capability labels come from observed callable behavior and contract tests, not from model family branding.

Capability Map

Provider	Truthful surface	Registration
mock	predict, embed	always
cosmos-policy	policy	COSMOS_POLICY_BASE_URL
leworldmodel	score	LEWORLDMODEL_POLICY or LEWM_POLICY
gr00t	policy	GROOT_POLICY_HOST
lerobot	policy	LEROBOT_POLICY_PATH or LEROBOT_POLICY
jepa	score	JEPA_MODEL_NAME
genie	scaffold only	env-gated reservation
jepa-wms	direct-construction score candidate	not exported or auto-registered

Workflow

1. Read the closest existing adapter, then src/worldforge/providers/base.py, src/worldforge/providers/catalog.py, and docs/src/provider-authoring-guide.md.
2. Classify the upstream runtime by what it actually does, not by model marketing language.
3. For a new scaffold, start with uv run python scripts/scaffold_provider.py ...; keep capabilities unadvertised until real methods return validated WorldForge models.
4. Validate public inputs before network calls, filesystem reads, or optional runtime calls.
5. Return the correct public model: PredictionPayload, EmbeddingResult, ActionScoreResult, or ActionPolicyResult.
6. Add success and malformed/error fixtures under tests/fixtures/providers/.
7. Add worldforge.testing.assert_provider_contract() coverage for every advertised capability.
8. Update .env.example, provider docs, generated catalog surfaces, README, changelog, AGENTS.md, or CLAUDE.md only when public behavior or env vars change.
9. Validate with focused provider tests, ruff, generated provider-doc check, and the coverage/package gates when the public surface changes.

Definition Of Done

• Every advertised capability has a provider-contract test and at least one malformed/provider-error test.
• Provider metadata, docs, generated catalog output, and .env.example agree on capabilities and configuration.
• Events and public errors redact credentials, signed URLs, host-local secrets, and unsafe metadata.
• Optional-runtime paths degrade to typed skipped/preflight results without installing host-owned packages.

Sharp Edges

Symptom	Cause	Fix
Provider appears in docs with wrong surface	ProviderCapabilities declaration drifted	Fix adapter capabilities, run provider docs generator, update tests
Optional provider missing from doctor	Required env var absent	Confirm variable name from .env.example; do not read .env
Contract helper fails on JSON	Metadata/raw payload not JSON-native	Validate at construction and convert tuples/objects before return
Remote test leaks URL/query	Event target/message metadata not sanitized	Add regression in tests/test_observability.py or provider test