How It Works

Jaunt works when you can picture the loop: specs in, generated modules out, and a tight edit-regenerate-review cycle. What the hammer? what the chain? -- specs enter the furnace, implementations emerge on the other side.

The Flow

You write specs
  -> Jaunt discovers them (source_roots / test_roots)
  -> builds a dependency graph (explicit deps + best-effort inference)
  -> picks a generation runtime (Aider by default, or legacy)
  -> for each module:
       - build prompt = system template + your spec source segment (+ extras)
       - LLM generates Python
       - Jaunt validates + writes to __generated__/
  -> at runtime, @jaunt.magic forwards calls into __generated__/

What The LLM Sees

At build time, Jaunt sends the backend a prompt composed of:

• A system template (packaged under src/jaunt/prompts/).
• Your spec’s source segment: signature, docstring, type hints, decorator options.
• Optional per-spec extra context (e.g., prompt="...").
• Optional "PyPI skills" text for external libraries (see guide below).

The job is simple: implement the contract implied by your spec.

Agent Runtimes

Jaunt now has two internal ways to execute generation:

• aider: Jaunt creates an isolated temp workspace, lets Aider edit the target file, then validates the result before writing it back
• legacy: Jaunt calls the provider SDK directly

This changes the planning and editing loop, but not the rest of the product surface. Discovery, staleness, validators, generated file locations, and the runtime forwarding model are the same either way.

See: Aider Runtime.

Incremental Rebuilds (Digests)

Jaunt hashes the spec source for each module and writes the digest into the generated file header. On the next run, Jaunt skips modules whose digest still matches.

You change a spec, Jaunt regenerates just what’s stale.

Jaunt also fingerprints the generation runtime. Switching from legacy to aider, changing Aider mode, or changing relevant prompt/runtime settings can also mark generated files stale.

See: Output Locations.

Dependency Ordering (DAG)

Jaunt builds a spec-level DAG so:

• dependencies generate first
• changes to dependencies propagate staleness to dependents

You can declare deps explicitly with deps=..., and Jaunt can also infer edges best-effort.

See: Dependencies.

Runtime Forwarding

@jaunt.magic doesn't "generate on call." It forwards your call into the generated module under __generated__/.

• If the generated module exists: your call delegates to it.
• If it doesn’t: you get JauntNotBuiltError (run jaunt build).

This is why you import your spec module in normal code: it’s the stable API surface.

PyPI Skills Injection (Optional)

On jaunt build, Jaunt can (best-effort) generate "skills" from PyPI READMEs for the external libraries you import, then inject those skills into the build prompt.

This tends to improve correctness for unfamiliar libraries without you writing a giant prompt.

Guide: Auto-Generated PyPI Skills.

Where To Go Deeper

Next: Writing Specs.