| name | unhardcoded-contribute |
| description | 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. |
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
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):
- Declaration — a catalog entry in
config.live.lua: base_url, api_kind,
auth_env, tier, discovery (static / marketplace / local).
- 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.
- Source (optional) — a
ProviderSource in sources/ if the provider has
dynamic pricing/discovery/balances (a marketplace or subscription-quota model).
- 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
behave
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.
