Unhardcoded Contribute

Contributing to unhardcoded (the host)

This repo is the host: the I/O, auth, providers, HTTP service and operator dashboard around the pure-Lua policy algebra. The algebra is vendored as the core/ git submodule (genlayerlabs/unhardcoded-engine) and the host never changes its semantics — to touch selection semantics, go to the core and its own contribute skill. Clone with the submodule:

git clone --recursive git@github.com:genlayerlabs/unhardcoded.git
# or, after a plain clone: git submodule update --init

The architecture, by module

shim.py            OpenAI-compatible FastAPI app: /v1/* (chat, responses, models,
                   compact) + the operator /x/* surface. Where a request meets a policy.
serve.py           entry point: wires api_kind → provider backend, resolves provider
                   auth, installs the streaming dispatcher, runs uvicorn.
llm_router_host.py embeds core/ via lupa (one shared Lua VM); sync + async call_provider
                   hooks; init / rank / execute / execute_async / execute_flow_async;
                   dump/restore runtime state; injects the host `cache_hot` field.
flow_runner.py     Σ_flow scheduler (Python port of the core's flow.lua): topological
                   order, per-node policy calls, assembled multipart inputs.
providers.py       the provider registry — the four-aspect Provider record (below).
provider_adapters/ per-api_kind wire backends: openai_compatible (default), anthropic,
                   bedrock, google.
codex_backend.py   the Codex (ChatGPT-subscription) backend — a special provider, at the repo root.
sources/           marketplace/pricing ProviderSource implementations (e.g. antseed).
auth_proxy.py      ingress + the operator dashboard; strips/injects x-llm-router-caller,
                   rate limiting, synthetic probes.
host_store.py      Postgres operational state (see below).
config.live.lua    the catalog: providers, model families, the `default` policy, the
                   policy_envelope, the field schema. config.internal.lua is an alias.
model_meta.lua     generated by scripts/refresh_model_meta.py (OpenRouter traits/benchmarks).
metrics.live.lua   EMA seed — intentionally fake (docs/METRICS.md).

host_store.py tables: calls (telemetry, best-effort async), route_observations (per-attempt reliability/latency learning), and the durable ones — settings_overrides (operator knobs), provider_overlays (hot-added providers), consumer_keys (minted keys), plus peer_offers / buyer_status (written by the AntSeed sidecar). Sync-write the durable tables; surface their failures.

Adding a provider — the path

A provider is up to four composable aspects (see providers.py):

1. Declaration — a catalog entry in config.live.lua: base_url, api_kind, auth_env, tier, discovery (static / marketplace / local).
2. Adapter — the wire backend selected by api_kind. openai_compatible is the default and needs no code. A native kind (anthropic/bedrock/google) lives in provider_adapters/<kind>.py with a streaming twin. Add a new api_kind here and wire it in serve.py's dispatcher.
3. Source (optional) — a ProviderSource in sources/ if the provider has dynamic pricing/discovery/balances (a marketplace or subscription-quota model).
4. Knobs (optional) — operator-tunable settings declared next to the Provider record; merged into settings.SCHEMA at import.

Register the Provider record in providers.py (source factory, enabled predicate, adapter, knobs). Auth is resolved at call time from host.env[provider.auth_env] → an Authorization header, or an OAuth refresh (Codex), or nothing (auth = none, e.g. AntSeed). The core never sees a key.

The two special providers show the extremes:

• Codex (openai_codex) — a ChatGPT subscription behind the Responses API; reads ~/.codex/auth.json with token auto-refresh, and imputes a scarcity price (ramped by 429s/quota) so it ranks near-free. See docs/OPENAI-CODEX.md.
• AntSeed — a marketplace meta-router (auth = none): a ProviderSource ingests peer offers, the router pins a peer per call, and an operator funds an on-chain escrow. See docs/PROVIDERS.md.

The SKILL.md gate (don't break it)

The root SKILL.md (the sigma-policy-author authoring guide) is test-gated: tests/test_skill_md.py parses every term in the guide and asserts each op exists in core/llm_policy/sig.lua. If you bump the core submodule and an op is renamed or removed, or you edit the guide, this test catches a guide that would hand an assistant a term the host rejects at admission. Keep the guide in sync with the core, or the gate fails.

Tests & dev loop

python -m pytest tests -q     # unit — real host, mocked provider responses
behave                        # BDD e2e — drives the live stack (router + ingress + dashboard)

• behave.ini sets paths=features, tags=-manual. AntSeed spend tests are gated behind RUN_ANTSEED_SPEND=1 (they move real funds — see CONTRIBUTING.md).
• shell.nix pins the dev shell (pytest, behave, selenium/chromium for the browser pass). No Makefile — invoke pytest/behave directly.
• compose.yml brings up the local stack (router + ingress, optional antseed profile). live_smoke.py drives real providers end-to-end.
• Local first run: docker compose up -d --build, then curl -fsS http://127.0.0.1:8080/healthz. DASHBOARD_NO_AUTH=1 for dev only.

Where to read more

• CONTRIBUTING.md — setup, tests, PR conventions, AntSeed-spend safety.
• docs/DEPLOY.md — deployment + the provider modes (codex/openrouter/bedrock/antseed).
• docs/PROVIDERS.md — provider auth kinds and the AntSeed node in depth.
• docs/OPENAI-CODEX.md — the Codex provider internals (Responses API, token refresh).
• core/docs/ + the unhardcoded-engine-contribute skill — the policy algebra itself.