Compiler Architecture Overview¶

Codaris treats a pipeline request as a compilation problem rather than a conversation. Nextflow DSL2 has invariants that free-form generation breaks in predictable ways: a call's arity has to match the module's input: block, an include has to name something the file defines, a channel is consumed once, and a process runs in a container that exists. The build graph enforces those invariants with tools, and asks a language model only for the parts that need judgment.

The harness around the compiler¶

A request enters a bounded agent loop. The model sees a fixed tool surface and decides only the next narrow step; every dispatch passes the policy fence, every gate result returns to context as evidence, and the pipeline itself is assembled by nf_compiler from module signatures. Knowledge stores, guardrails, and observability wrap the loop, and the hand-off at the end is a pipeline tree with its compliance report.

How Codaris works: a trigger enters a harness that builds context, lets the model decide, dispatches a bound tool through a policy fence, and returns verification evidence to context until the gates pass; knowledge, guardrails, and observability with evals wrap the loop; the output is a pipeline directory and compliance report handed to the human. — The loop, the fence around it, and the blocks that make it auditable.

The compilation path¶

flowchart TD
    A[Request: prompt, playbook, or legacy workflow] --> B[Intent and plan]
    B -->|nf-pilot classifies the turn; the plan model resolves assay, modules, assets| C[Staged plan questions]
    C -->|references, sample sheet, structure, defaults, parameters| D[Scaffold]
    D -->|nf-core pipelines create| E[Install modules and subworkflows]
    E -->|nf-core modules install| F[Stitch]
    F -->|compiler writes workflows, configs, fixtures| G[Symbol repair]
    G --> H{Compile gate}
    H -->|nextflow -preview and the entry-point check| I{Lint}
    H -->|failure| J[Fix]
    J -->|deterministic include repair, else a corrected file from the build model| H
    I -->|nf-core pipelines lint| K[Judge and report]
    I -->|failure, within budget| J
    K --> L[Pipeline tree with provenance record]

The parts¶

1. Two engines with different jobs¶

The decision model (Primeomicx/nf-pilot) runs locally and answers fixed-choice questions: the kind of turn, the failure category in a log, the best of several candidate tools or layouts. It is fast and offline, and it never writes code.
The language model (OpenAI, Anthropic, Google, Perplexity, or a local server) writes the plan, proposes repairs, and judges the result. The dual-engine page describes the split.

2. A bounded tool surface¶

Each chat turn binds a small fixed set of file, build, repair and discovery tools, plus the tools a slash command or a research turn asks for; search_tools finds and binds the rest (the other core tools, MCP tools, skills and references) when a turn needs them. Whether a tool may act is decided at dispatch time by a policy that sees the concrete arguments, so a read-only review cannot write files however the model phrases the call. The tool surface page lists the tools.

3. Deterministic synthesis¶

workflows/<name>.nf is written by the compiler from the installed modules' input: and output: declarations, not from a prose description of them. Arity, emit names, and include paths come from the files on disk; the compiler leaves a call out, and says so in the report, rather than guess an arity it cannot read.

4. Verification before the report¶

nextflow run . -preview resolves every include and call without running a task. The gate also checks the pipeline positively: main.nf includes and calls the pipeline workflow, the workflow calls at least one process, and no planned module is included without being called. nf-core pipelines lint runs after that. Failures go through a fix node with a budget; a repair that would empty or gut a file is refused.

5. A record of what was built¶

.codaris/provenance.json lists a sha256 for every generated Nextflow and config file plus one digest over the set, computed after the last write of the build. python -m app.engine.security_scanner verify <pipeline> recomputes it and names the files that changed since.