Skip to content

Engine map

mini-ork ships the loop, not the workflow opinions. Recipes under recipes/ define node graphs; the Python package under mini_ork/ provides the primitives, registries and execution machinery every recipe shares. This page maps the moving parts so a change lands in the right module.

Entrypoint and path contract

Everything starts at bin/mini-ork, which resolves the engine root and hands off to mini_ork.cli.main. The dispatcher is a registry, not a chain of ifs: each subcommand is a handler (rest, root) -> exit code registered in SUBCOMMAND_REGISTRY, and new commands are added with register_subcommand(name, handler).

Path resolution is centralised in mini_ork.context.RunContext:

Variable Meaning Default
MINI_ORK_ROOT Engine checkout derived from the package location
MINI_ORK_HOME Project home <cwd>/.mini-ork
MINI_ORK_DB SQLite state $MINI_ORK_HOME/state.db
MINI_ORK_RUN_ID Current run identity set by the executor
MINI_ORK_RUN_DIR Current run directory $MINI_ORK_HOME/runs/<id>
MINI_ORK_RECIPE Recipe name for this run set at resolve time
MINI_ORK_TASK_CLASS Classified task class set at resolve time

RunContext.from_env() / .as_env() convert between the dataclass and the environment, and apply_env_overrides / scoped_environ are the only sanctioned ways to mutate process env. Per-run isolation uses a contextvars.ContextVar, so two runs can share one process without clobbering each other's variables.

Component map

flowchart TB
  CLI["bin/mini-ork<br/>mini_ork.cli.main"]

  subgraph loop["Lifecycle"]
    CLS["classify<br/>mini_ork.classify"]
    PLN["planning<br/>mini_ork.planning"]
    EXE["execute<br/>mini_ork.cli.execute"]
    VER["verify / gates<br/>mini_ork.gates, mini_ork.verify"]
    REF["reflect<br/>mini_ork.learning"]
  end

  subgraph dispatch["Dispatch plane"]
    ROUTE["routing<br/>mini_ork.dispatch.routing"]
    PROV["providers / lanes<br/>mini_ork.dispatch.providers"]
    SAND["sandbox / placement<br/>mini_ork.dispatch.sandbox*"]
  end

  subgraph trust["Verification plane"]
    CERT["certify (Assay)<br/>mini_ork.certify"]
    LEVELS["level vector<br/>mini_ork.verify.levels"]
    GATES["gate registry<br/>mini_ork.gates.gate_registry"]
  end

  subgraph state["State plane"]
    DB[("state.db")]
    RUNS[(".mini-ork/runs/<id>/")]
    MEM["memory namespaces<br/>mini_ork.memory"]
  end

  subgraph surface["Surfaces"]
    BOARD["board / web app<br/>mini_ork.cli.board_cmd, mini_ork.web"]
    PAGES["IDE page JSON<br/>mini_ork.ide_pages"]
    PUB["publisher<br/>mini_ork.cli.publisher"]
  end

  CLI --> CLS --> PLN --> EXE
  EXE --> ROUTE --> PROV --> SAND
  EXE --> VER --> GATES
  VER --> LEVELS
  CERT --> LEVELS
  VER --> REF --> MEM
  EXE --> DB
  EXE --> RUNS
  BOARD --> DB
  PAGES --> DB
  PUB --> RUNS

Module responsibilities

Path Responsibility
mini_ork/cli/ Every subcommand handler, the dispatcher and shared CLI helpers
mini_ork/context.py The canonical run-context and environment contract
mini_ork/classify*, mini_ork/planning/ Task-class matching and plan decomposition
mini_ork/cli/execute.py, mini_ork/workflow/ Node dispatch, DAG ordering, artifact handoffs
mini_ork/dispatch/ Routing policies, providers, transports, lane health, cost ledger
mini_ork/gates/ Gate registry and built-in evaluators (budget, scope, adequacy, hackability…)
mini_ork/verify/ Behavioural verifier, level vector, equivalence operators
mini_ork/certify/ The Assay oracle: reproduction, delta gate, relations, differential
mini_ork/learning/ Gradients, patterns, candidates, GRPO writeback, lessons
mini_ork/memory/ Semantic memory, embedders, namespaced recall
mini_ork/recovery/ Recovery planner, retry hints, healer, escalation, circuit breaker
mini_ork/checkpoints/ Per-step ledger used by run --resume
mini_ork/ide_pages/ Page JSON consumed by the IDE and web surfaces
mini_ork/web/ Local web app, routes and event stream
mini_ork/cli/publisher.py Publish gates and delivery (commit/merge/push)
mini_ork/automations.py, mini_ork/scheduler.py Scheduled runs and the epic queue
mini_ork/vcs/ Worktrees, node checkpoints, git ops

Registries and extension seams

Behaviour is added by registration, not by editing the core:

Seam API
Node types mini_ork.cli.execute.register_node_handler(type, fn, phase=)
Routing policies mini_ork.dispatch.routing.register_policy(name, fn)
Gate evaluators mini_ork.gates.gate_registry.register_gate_evaluator(type, fn)
Provider kinds / transports mini_ork.dispatch.providers.register_provider_kind / register_dispatch_backend
Subcommands mini_ork.cli.main.register_subcommand(name, handler)
Embedders mini_ork.memory.semantic.register_embedder_provider(name, factory)
Completion contracts mini_ork.execute_compat.register_completion_contract(pattern, fn)
Equivalence operators mini_ork.verify.equivalence.register_operator(name, fn)

Extending mini-ork has working skeletons for each.

Two data planes

state.db is the queryable record: task runs, execution traces, gate results, attempts, costs, lessons and benchmark results. It is SQLite, so it is also the debugging surface:

sqlite3 .mini-ork/state.db '.tables'
sqlite3 .mini-ork/state.db 'SELECT id, status, verdict FROM task_runs LIMIT 5;'

The run directory is the evidence: prompts, node outputs, verifier logs and verdict files. Anything a verdict cites lives under .mini-ork/runs/<run-id>/, so a verdict can be audited without re-running the work.

Design rules that shape the code

  • The control plane is trusted; execution is not. Credentials never enter a prompt, and an LLM judge may veto a pass but never create one.
  • Everything is resumable. The checkpointer and the recovery planner are read-only over durable state; only the execute loop writes.
  • Every write is attributable. Memory and traces carry run_id, node id, model and timestamp.
  • Failure is a first-class outcome. UNVERIFIED, VACUOUS, blocked and escalated are distinct states, not renamed errors.