How It Works

Jaunt works when you can picture the loop: specs in, generated modules out, and a tight edit-regenerate-review cycle.

The Flow

You write specs
  -> Jaunt discovers them (source_roots / test_roots)
  -> builds a dependency graph (explicit deps + best-effort inference)
  -> 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.

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.

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.