GEPA Elixir Logo

GEPA for Elixir

ElixirOTPTestsCoveragePhase 1Phase 2License

An Elixir implementation of GEPA (Genetic-Pareto), a framework for optimizing text-based system components using LLM-based reflection and Pareto-efficient evolutionary search.

About GEPA

GEPA optimizes arbitrary systems composed of text components—like AI prompts, code snippets, or textual specs—against any evaluation metric. It employs LLMs to reflect on system behavior, using feedback from execution traces to drive targeted improvements.

This is an Elixir port of the Python GEPA library, designed to leverage:

🎉 Phase 1 Complete - Production Ready!

Core Features (Current v0.1.0 Release)

Optimization System:

Phase 1 Additions - NEW! 🎉

Production LLM Integration:

Advanced Batch Sampling:

Working Examples:

Phase 2 Additions - NEW! 🎉

Merge Proposer:

Incremental Evaluation:

Advanced Stop Conditions:

Test Quality:

What's Next? See the Roadmap on GitHub

✅ Phase 1: Production Viability - COMPLETE!

✅ Phase 2: Core Completeness - COMPLETE!

Phase 3: Production Hardening - 8-10 weeks

Phase 4: Ecosystem Expansion - 12-14 weeks

See Implementation Gap Analysis on GitHub for detailed comparison with Python GEPA.

Quick Start

With Mock LLM (No API Key Required)

# Define training data

trainset = [

  %{input: "What is 2+2?", answer: "4"},

  %{input: "What is 3+3?", answer: "6"}

]



valset = [%{input: "What is 5+5?", answer: "10"}]



# Create adapter with mock LLM (for testing)

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



# Run optimization

{:ok, result} = GEPA.optimize(

  seed_candidate: %{"instruction" => "You are a helpful assistant."},

  trainset: trainset,

  valset: valset,

  adapter: adapter,

  max_metric_calls: 50

)



# Access results

best_program = GEPA.Result.best_candidate(result)

best_score = GEPA.Result.best_score(result)



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

IO.puts("Iterations: #{result.i}")

With Production LLMs (NEW!)

# OpenAI (GPT-4o-mini) - Requires OPENAI_API_KEY

llm = GEPA.LLM.ReqLLM.new(provider: :openai)

adapter = GEPA.Adapters.Basic.new(llm: llm)



# Or Gemini (`gemini-flash-lite-latest`) - Requires GEMINI_API_KEY

llm = GEPA.LLM.ReqLLM.new(provider: :gemini)

adapter = GEPA.Adapters.Basic.new(llm: llm)



# Then run optimization as above

{:ok, result} = GEPA.optimize(

  seed_candidate: %{"instruction" => "..."},

  trainset: trainset,

  valset: valset,

  adapter: adapter,

  max_metric_calls: 50

)

See Examples overview for complete working examples!

Interactive Livebooks (NEW!)

For interactive learning and experimentation:

# Install Livebook

mix escript.install hex livebook



# Open a livebook

livebook server livebooks/01_quick_start.livemd

Available Livebooks:

See livebooks/README.md for details!

With State Persistence

{:ok, result} = GEPA.optimize(

  seed_candidate: seed,

  trainset: trainset,

  valset: valset,

  adapter: GEPA.Adapters.Basic.new(),

  max_metric_calls: 100,

  run_dir: "./my_optimization"  # State saved here, can resume

)

Development

# Get dependencies

mix deps.get



# Run tests

mix test



# Run with coverage

mix test --cover



# Run specific tests

mix test test/gepa/utils/pareto_test.exs



# Format code

mix format



# Type checking

mix dialyzer

Architecture

Based on behavior-driven design with functional core:

GEPA.optimize/1

  ↓

GEPA.Engine ← Behaviors → User Implementations

  ├─→ Adapter (evaluate, reflect, propose)

  ├─→ Proposer (reflective, merge)

  ├─→ Strategies (selection, sampling, evaluation)

  └─→ StopCondition (budget, time, threshold)

Documentation

Current Status & Planning

Technical Documentation

Related Projects

License

MIT License