Heimdal Engine is a host-agnostic local agent engine. Externally it appears as one agent; internally it runs a quality-controlled orchestration runtime so that smaller local models can produce frontier-like agent outcomes through architecture — context discipline, retrieval, verification, evals, patching, and hardware-adaptive runtime profiles — rather than raw model size.
Multi-GPU machines (v0.7.0): pin one Ollama instance per GPU and map Heimdal's
roles to them via ollama.endpoints in the manifest — worker drafts, the
semantic verifier, and the brain planner then run on separate devices, and
B3/B4 multi-sample drafting runs concurrently across worker endpoints
(heimdal endpoints list|status). This is role-level routing, not tensor
parallelism: splitting one model across GPUs remains Ollama/llama.cpp's job.
With no endpoints configured, everything runs on the single default endpoint.
The full specification lives in docs/builder_pack/;
start with docs/builder_pack/INDEX.md.
Python 3.11+ is required. The only runtime dependency is pyyaml.
bash scripts/dev_setup.sh # venv + install + doctor (Ubuntu native / WSL2)
# or, in an existing environment:
pip install -e .Heimdal runs fully offline. If Ollama is reachable it is used automatically; otherwise a deterministic offline backend keeps the whole pipeline runnable.
# Hardware + runtime profile (v0.6.x)
heimdal doctor [--json] [--capability-test] [--all-models] [--write-profile]
heimdal doctor --profile # print only the recommended profile name
heimdal models {list, capabilities, assign --write, roles, pin, unpin}
heimdal profile {detect, show, set <name>, explain, write}
# Run a task
heimdal run demo # built-in demo task
heimdal run --input examples/tasks/simple_task.json
heimdal run --instruction "Explain a queue." [--role research]
heimdal eval run # run the eval suite + write a summary
heimdal verify --task task.json --answer answer.json # verifier-only path
# Host integrations
heimdal openclaw run --input task.json
heimdal hermes run --input task.json
heimdal hermes capabilities --json
heimdal bridge {init, submit --input <job.json>, once, watch, status}
# Self-improvement loop (v0.4.x / v0.5.x)
heimdal dream {run, report, list} # mine past runs for proposals
heimdal patch {validate, list, show, review, eval, promote --to <ch>, reject --reason "..."}
heimdal skill {list, show, search, validate, install, archive, stats, bootstrap}
heimdal mirror {run, list, report, show, diff, proposals, promote-proposal}
# Local data
heimdal truth {list, add <file>, search "<query>"}
heimdal logs latestWithout an install, use python -m heimdal <command>.
heimdal verify runs only the verifier on an answer a host drafted itself —
useful when a host wants Heimdal to grade a candidate rather than produce one.
A host framework drives Heimdal as a single agent — via a CLI command or in-process:
from heimdal.adapters.openclaw_host import handle as openclaw_handle
from heimdal.adapters.hermes_host import handle as hermes_handle
result = openclaw_handle(openclaw_payload) # -> OpenClaw-style result dict
result = hermes_handle(hermes_payload) # -> Hermes-style result dicthandle() translates the host payload, runs the full Quality Factory, and
translates the result back. It accepts backend / model / verifier
overrides, and when the payload carries callback.file the result is also
written under storage/workspace/. The adapter classes (OpenClawAdapter,
HermesAdapter) only translate; orchestration lives in the *_host modules.
CLI equivalents: heimdal openclaw run and heimdal hermes run.
The Hermes result is schema-formalized (schemas/hermes_result.schema.json):
it carries a machine-readable code (e.g. SOURCE_MISSING,
VERIFIER_SEMANTIC_FAIL), structured needed_inputs on need_input, and only
host-safe relative refs — never absolute paths, raw prompts, the full Context
Packet, or the internal sub-agent graph. heimdal hermes capabilities reports
what the host integration supports.
run and eval accept --backend ollama|offline and --model <name> to force
a backend or override the worker model. doctor --model <name> picks the model
for capability tests. When no override is given, Heimdal prefers an installed
manifest candidate and skips embedding models; if no candidate is installed it
falls back to an installed generative model or fails with an actionable
ollama pull hint.
Verification is rule-based by default. A hybrid mode adds an optional
model-based semantic verifier for B2-B4 tasks — set verifier.mode: hybrid
in config/heimdal.manifest.yml, or pass --verifier hybrid to run / eval.
The gate order is fixed: (1) deterministic rule-based verifier, (2) optional model-based semantic verifier, (3) final deterministic check. A deterministic hard fail short-circuits before the model verifier runs — the semantic verifier is an extra quality layer and can never override a deterministic fail. The offline backend mocks the semantic verifier deterministically.
Host input -> Adapter -> Host Task Envelope -> Core Runtime
Intake -> Role Binding -> Task Contract -> Scheduler (Work mode)
Quality Factory: Context Packet -> Router -> Worker -> Verifier -> Repair loop
-> Result Envelope + Repro Pack + Trace Pack
- Task Contract is built for every task before any model call.
- Context Packet is the exact, token-budgeted context for every model call.
- Verifier returns a structured PASS/FAIL result and never rewrites the answer.
- No-Guess Gate returns
need_inputinstead of inventing unsourced facts. - Repro Pack and Trace Pack are written for every run.
- Patch / Eval gate: no patch reaches the
stablechannel without a passing eval run. - Heimdal core is host-agnostic; OpenClaw is only an adapter. Mirror Mode is disabled by default; Dream Mode is feature-flagged.
heimdal/ engine package (core runtime, models, adapters, hardware, sandbox)
schemas/ JSON schemas for envelopes, contracts, packets, packs, patches
config/ heimdal.manifest.yml + sandbox_policy.yml
examples/ example tasks, truth sources, skills, patches
eval/ the eval suite (smoke / must-pass / schema / no-guess)
docs/builder_pack/ the Heimdal Builder Pack specification
tests/ stdlib unittest suite
python -m unittest discover -s tests -t . -vMIT — see LICENSE.