# Unhardcoded Contribute > Develop and extend the unhardcoded router/host — add a provider (declaration + source + adapter + knobs), touch the OpenAI-compatible shim or the /x/* operator surface, the Σ_flow runner, the Postgres host store, the ingress + dashboard, or the lupa embedding of the engine core. Load this when changing host code, adding a provider or api_kind, editing the catalog, or running the test suite. To change the *policy algebra* itself, that lives in the core submodule — use unhardcoded-engine-contribute. To merely use the router, use unhardcoded-use. - Skill: `genlayerlabs/unhardcoded-contribute` (Agent Skill) - Install (CLI): `npx skillmds@latest add genlayerlabs/unhardcoded-contribute` - Raw SKILL.md: https://api.skillmd.com/api/skills/genlayerlabs/unhardcoded-contribute/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: genlayerlabs (https://skillmd.com/u/genlayerlabs) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/genlayerlabs/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: ```bash 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/.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 ```bash 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.