# GEPA — Zero to Hero **New to GEPA? Start here.** This folder is a guided, friction‑free path that takes you from "never heard of it" to "I just ran my first optimization" — no prior knowledge of GEPA, prompt engineering, machine learning, or evolutionary algorithms required. If a word ever looks unfamiliar, it is defined in the [Glossary](05-glossary.md). --- ## ▶ The fastest way in: open the interactive guide Open **[`index.html`](index.html)** in any web browser. Double‑click the file, or: | Platform | Command | |---|---| | Windows | `start onboarding\index.html` | | macOS | `open onboarding/index.html` | | Linux | `xdg-open onboarding/index.html` | It is a single, self‑contained page — no installation, no build step, no internet connection required. It animates the whole GEPA loop, lets you click through a real optimization, and shows you the one idea that makes GEPA different (the per‑example Pareto frontier) as a thing you can actually *see*. Most people understand GEPA in about 10 minutes from this page alone. > **Why an interactive page instead of a video?** Your prompt said "interactive HTML **and/or** > Remotion / Hyperframe videos." We deliberately chose the interactive page. A video would need a > Node toolchain to build and render (friction), and it can only be watched. The HTML page renders > instantly with zero setup, works offline, and lets you *drive* the animation — pause on the part > that confuses you, click individual candidates, and replay the loop. For "demystify in the > shortest time," interactive beats video here. The same page also reads like a narrated walkthrough > if you just scroll top to bottom. --- ## 📖 Prefer to read? The 30‑minute path Read these five files in order. Each is self‑contained and ends where the next begins. | # | File | What you'll get | Time | |---|------|-----------------|------| | 1 | [What is GEPA?](01-what-is-gepa.md) | The core idea in plain English, with analogies. Why it exists, what problem it solves, when to use it. | 6 min | | 2 | [How GEPA works](02-how-gepa-works.md) | The optimization loop, the Pareto frontier, reflection, and "ASI" — explained from scratch with diagrams. | 10 min | | 3 | [Quickstart](03-quickstart.md) | Install GEPA and run three working examples, copy‑paste ready. | 8 min | | 4 | [Recipes](04-recipes.md) | Task‑oriented how‑tos: optimize a prompt, optimize *anything*, and plug GEPA into your own system. | 6 min | | 5 | [Glossary](05-glossary.md) | Every term used anywhere in GEPA, defined with an example. | reference | --- ## The one‑paragraph version You have a system that uses some **text** to do a job — a prompt, a config file, a piece of code, an agent's instructions. You can **measure** how well it does the job (a score). GEPA automatically **rewrites that text to make the score go up**. It does this by trying a variant, reading *why* the variant succeeded or failed (the actual error messages, outputs, and logs — not just the number), and using a strong LLM to propose a smarter next variant. It keeps a diverse set of "champions" so it never throws away a variant that's the best at even one tricky case. Typically it finds a big improvement in **100–500 tries** — far fewer than traditional methods. If you can measure it, GEPA can optimize it. --- ## Where to go after onboarding Once the ideas click, the full reference lives in the main docs: - **Guides** — `../docs/docs/guides/` (adapters, callbacks, candidate selection, cost tracking, …) - **API reference** — `../docs/docs/api/` - **Tutorials (runnable notebooks)** — `../docs/docs/tutorials/` - **Examples** — `../examples/` (AIME math, ARC‑AGI, RAG, cloud scheduling, and more) - 👉 **Best first runnable example:** [`../examples/program_synthesis_from_examples/`](../examples/program_synthesis_from_examples/) — GEPA writes a Python function from labeled examples, scored 100% locally (no task LLM). Includes an offline `--smoke` self-test that runs with **no API key**. - **Project README** — [`../README.md`](../README.md) - **Paper** — - **Live docs site** —