Welcome

JIT codegen, import-shaped

Write the import you wish existed.

from wishful.static.text import extract_emails

raw = "Contact us at team@example.com or sales@demo.dev"
emails = extract_emails(raw)
print(emails) # prints ["team@example.com","sales@demo.dev"] probably...

First run: wishful asks the LLM, validates the code, and caches it under .wishful/text.py.Later runs: just a normal Python import — no latency, no API call.

import wishful turns “someone should really write this helper” into cached, type-aware Python modules — with safety checks, offline-friendly stubs, and a dash of mischief.

LLM-generated modules with real files on disk

Static (cached) and dynamic (runtime-aware) imports

Type- and context-aware prompts

Multi-variant exploration with automatic winner caching

Prefer reading code? Start with the README and come back here for the deeper “how it works” tour.

Moments that make this “click”

Imports as intent

You describe the behavior in comments, write the import you wish you had, and let the model do the boring glue work.

Real files you can edit

Generated modules land in .wishful/ as plain .py files. If the LLM gets close-but-not-perfect, tweak it once and you’re done.

Types that steer the model

Register dataclasses, Pydantic models, or TypedDicts with @wishful.type so the generated code returns exactly the shapes you expect.

Context-aware by default

wishful forwards nearby comments and call sites into the prompt, so “parse nginx logs into dicts” actually does what it says on the tin.

Explore: test before you trust

Generate multiple variants, test each one, keep the winner. wishful.explore() caches proven code, not just generated code.

What lives where?

• Quickstart — pip install, your first wish, and fake-LLM mode.
• How it works — the import hook, cache layout, static vs dynamic.
• Explore — generate multiple variants, test them, keep the winner.
• Configuration & CLI — knobs you can turn from code or env vars.
• Types — using @wishful.type to nudge the model.
• Advanced context discovery — how wishful harvests hints from your code.
• Contributing — how to hack on the project (with uv and good vibes).

If you’re here to just try it, hop to Quickstart.
If you want the internals, continue with How it works.