GEPA for Elixir

GEPA for Elixir is a library for optimizing text-based system components with LLM-backed reflection, Pareto search, and evaluator-driven workflows.

Installation

Add gepa_ex to your list of dependencies in mix.exs:

def deps do
  [
    {:gepa_ex, "~> 0.2.0"}
  ]
end

Start Here

• Getting Started
• Core API
• LLM and Adapters
• Optimization Workflow
• Optimize Anything
• Observability
• Examples and Livebooks

Quick Start

llm = GEPA.LLM.req_llm(:openai)
adapter = GEPA.Adapters.Basic.new(llm: llm)

{:ok, result} =
  GEPA.optimize(
    seed_candidate: %{"instruction" => "Answer exactly."},
    trainset: [%{input: "What is 2+2?", answer: "4"}],
    valset: [%{input: "What is 5+5?", answer: "10"}],
    adapter: adapter,
    max_metric_calls: 20
  )

IO.puts("Best score: #{GEPA.Result.best_score(result)}")

For evaluator-driven tasks, use GEPA.OptimizeAnything.optimize_anything/1 and provide a candidate, evaluator, dataset, and objective text.

What Ships

• Core optimization engine with Pareto fronts, state persistence, stop conditions, merge scheduling, and acceptance criteria
• Adapter contract plus shipped adapters for Q&A, default chat-style tasks, ReqLLM, Agent Session Manager, and testing
• LLM facade with structured output support, streaming, and provider normalization
• Candidate proposal, batch sampling, and selection strategies including epsilon-greedy
• Telemetry, callbacks, tracking, and terminal progress output
• Result serialization and utility modules for code execution and evaluation caching

Examples and Livebooks

• Live scripts: examples/README.md
• Batch runner: examples/run_all.sh
• Notebooks: livebooks/README.md

The scripts and notebooks are tied to the current codebase and should be read alongside the guide set above.

HexDocs

The full API reference is generated from mix.exs and the module docs in lib/. The guide menu now lives under guides/*.md.

Changelog

See CHANGELOG.md for release notes.