Quickstart

This is the shortest path to an "aha": write one tiny spec, run jaunt build, and call real generated code like normal Python.

jaunt build calls your configured LLM provider (default: OpenAI) and will spend tokens. Set OPENAI_API_KEY first.

Project Layout

Create a small "src layout" project:

myproj/
  jaunt.toml
  src/
    my_app/
      __init__.py
      specs.py
  tests/
    __init__.py
    specs_email.py

1) Install

Jaunt is an MVP and is typically installed from a local checkout.

If you’re working from the Jaunt repo:

uv sync
export OPENAI_API_KEY=...
uv run jaunt --version

If you’re adding Jaunt to your own project, install it however you vend it (local path, internal index, or git). You also need pytest for jaunt test:

# Example (local path):
uv add --editable /path/to/jaunt
uv add pytest
export OPENAI_API_KEY=...

2) Create `jaunt.toml`

myproj/jaunt.toml:

version = 1

[paths]
source_roots = ["src"]
test_roots = ["tests"]
generated_dir = "__generated__"

3) Write Your First Spec (`@jaunt.magic`)

myproj/src/my_app/specs.py:

from __future__ import annotations

import jaunt


@jaunt.magic()
def normalize_email(raw: str) -> str:
    """
    Normalize an email address for stable comparisons.

    Rules:
    - Strip surrounding whitespace.
    - Lowercase the whole string.
    - Must contain exactly one "@".
    - Local-part and domain must both be non-empty after splitting.

    Errors:
    - Raise ValueError if `raw` is invalid by the rules above.
    """
    raise RuntimeError("spec stub (generated at build time)")

This docstring is the contract. The type hints matter. The body is a placeholder.

4) Generate Code

From myproj/:

jaunt build

Jaunt will write a real module under:

src/my_app/__generated__/specs.py

5) Use It (Runtime Forwarding)

You import the spec module. The decorator forwards your call into __generated__/.

PYTHONPATH=src python - <<'PY'
from my_app.specs import normalize_email

print(normalize_email("  A@B.COM  "))  # -> "a@b.com"
PY

If you call it before building, you’ll get jaunt.JauntNotBuiltError with a hint to run jaunt build.

6) Add A Test Spec (`@jaunt.test`)

myproj/tests/specs_email.py:

from __future__ import annotations

import jaunt


@jaunt.test()
def test_normalize_email__lowercases_and_strips() -> None:
    """
    Assert normalize_email:
    - strips surrounding whitespace
    - lowercases
    - rejects invalid inputs like "no-at-sign" (ValueError)

    Examples:
    - normalize_email("  A@B.COM  ") == "a@b.com"
    """
    raise AssertionError("spec stub (generated at test time)")

Now generate tests and run pytest:

PYTHONPATH=src jaunt test

Jaunt writes generated tests under:

tests/__generated__/specs_email.py

Project Layout

1) Install

2) Create `jaunt.toml`

3) Write Your First Spec (`@jaunt.magic`)

4) Generate Code

5) Use It (Runtime Forwarding)

6) Add A Test Spec (`@jaunt.test`)

What Next

How It Works

Writing Better Specs

JWT Walkthrough (Hero Demo)

On this page