unhardcoded-engine

A small, embeddable policy algebra for LLM provider selection, in pure Lua. You describe what you need from an LLM call (a contract); a policy — composed from four verbs over a declarative catalog — decides which (provider, model) to call, with what request, and what to do on failure. The embedding host performs the I/O.

The four verbs (see docs/POLICY_DESIGN.md):

• filter — which candidates are eligible (pure predicates).
• rank / select — order the eligible candidates (pure scorers + selector).
• mutate — transform the outgoing request for a chosen candidate.
• sequence — what to do when an attempt fails (declarative, fixed vocabulary).

Two consumers, one language:

• Off-chain (agent fleets) — a policy that converges on the best available provider: resilience + cost optimization for an agent fleet.
• On-chain (GenVM greyboxing) — each validator writes its own policy; the ease of writing 1000 different policies, over a well-defined provider object, is the security property. See docs/GENVM-LLM-POLICY.md.

Properties

• Pure Lua, no I/O, no credentials, no globals. The verbs are pure functions of an explicit ctx; the engine (the impure orchestrator) snapshots runtime state into ctx and performs no I/O itself. Embeddable in lupa (Python), mlua (Rust / GenVM), luerl (Elixir).
• Two execution modes. Synchronous (execute) and cooperative async (execute_step, yield-on-IO) so one host process overlaps many in-flight calls.
• Host-resolved auth. Providers declare auth = {kind="none"|"bearer"|"oauth"}; the host turns that into headers. The core never sees a key.
• Same decision, two runtimes. Given the same (policy, catalog, ctx, seed), selection is identical under mlua and lupa — the defining invariant. The semantics use only correctly-rounded IEEE ops (no transcendentals), so this holds bit-for-bit regardless of libm.
• Policies are data. Every declarative policy compiles through the Σ_pol IR (see below): serializable terms with a canonical form and an identity hash. Lua closures remain a local-only escape hatch.

The IR (Σ_pol)

A policy is a term — a plain array like { "cmp", "price_out", "le", 25 } — over a closed, versioned signature of operations and an open, declared vocabulary of observation fields (any provider/candidate fits by declaring its fields; the operations never grow per-field). Terms are admitted (check: sorts, arity, bounds), normalized to a canonical form, encoded deterministically (identity = sha256 of the encoding), and interpreted by a ~20-line fold. That buys:

• Per-call policies:execute({ ..., policy_ir = <term> }) — a policy arriving with the call is data, not code: no I/O, no loops, O(|term|) cost, rejected at admission if malformed. The host envelope (config.policy_envelope) is ∧-ed on so callers narrow, never widen.
• Policy identity: canonical hash for caching, audit ("request X ran policy H"), and on-chain commitment; trace.policy_fingerprint on every run.
• Conformance as a checklist: any host, in any language, that reproduces the per-op semantics and replays tests/golden/sigma_pol_v2.json bit-for-bit computes the same decisions. Spec: docs/SIGMA-POL.md.

Package

The core is the llm_policy package; router.lua is a compatibility shim (return require("llm_policy")) so existing embedders keep working.

localllm_policy=require("llm_policy") -- or dofile("router.lua")llm_policy.init(config, metrics)
localresult=llm_policy.execute({
prompt="Classify this feedback as positive / negative / neutral: ...",
requirements= { needs= { "json_mode" }, min_context=4000 },
profile="cheap_explore",
})
ifresult.okthenprint(result.response.text) elseprint(result.error) end

Repo layout

This repo is the core (sealed): pure Lua + a minimal embedding reference (example_host/) + the on-chain adapter overlay (genvm/). The production off-chain host moved to its own repo, genlayerlabs/unhardcoded. The core never references a host — hosts import the core.

# ── core (this repo) ──
llm_policy.lua -- package entry (init / execute / execute_step / rank / …)
llm_policy/
filter.lua rank.lua mutate.lua sequence.lua policy.lua -- the algebra
sig.lua term.lua fields.lua interp.lua elaborate.lua ir.lua
-- the Σ_pol IR (policies as data)
candidate.lua util.lua -- object + helpers
router.lua -- compat shim: return require("llm_policy")
config.example.lua -- example catalog + profiles (schema illustration)
metrics.example.lua -- example metrics seed
docs/
POLICY_DESIGN.md -- the candidate object + the policy algebra
SIGMA-POL.md -- the policy IR: terms, encoding, hashing, reference semantics
GENVM-LLM-POLICY.md -- using llm_policy as a node's greyboxing algebra
example_host/ -- the minimal embedding reference (~80 lines, mock provider)
tests/ -- Lua unit tests (run_lua.lua, unit/, golden/)
golden/ -- sigma_pol_v2.json conformance vectors + generator
genvm/ -- on-chain greybox adapter overlay (dispatch.lua + integrate.sh); tests/

Hosts

• example_host/ — the minimal embedding reference (~80 lines): load the core, install the host table, init, execute. The "hello world" of embedding llm_policy.
• Off-chain production host — genlayerlabs/unhardcoded: the async OpenAI-compatible shim + Codex (ChatGPT subscription) + AntSeed + the auth resolver, serving agent fleets. It vendors this core as a git submodule.
• On-chain adapter — genvm/dispatch.lua: a drop-in for genlayer-node's genvm-llm-greybox.lua that routes greyboxing through the algebra (see docs/GENVM-LLM-POLICY.md).