GEPA Elixir Logo

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.3.0"}
  ]
end

Start Here

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, Generic RAG, confidence scoring, ReqLLM, Agent Session Manager, and testing
Embedding behavior with a ReqLLM-backed Gemini embedding provider
Generic RAG vector-store behavior with in-memory tests, real local Qdrant, and explicit stubs for pgvector, Weaviate, LanceDB, Chroma, and Milvus
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

Integration Roadmap and Upstream Gaps

gepa_ex is a headless Elixir port focused on the core optimizer, adapter contracts, and live examples. Some upstream surfaces are represented as abstractions or deterministic local backends so users can plug in their own runtime without pulling extra infrastructure into the core package.

Surface	Current status	Remaining gap
Core optimizer	Real implementation: Pareto frontiers, reflection, merge, persistence, callbacks, telemetry, and `optimize_anything` run in Elixir.	Continue tracking upstream semantics and edge cases; no GUI is planned.
LLM adapters	Real normalized facade for ReqLLM and Agent Session Manager. ASM/Gemini defaults to `gemini-3.1-flash-lite-preview`; ReqLLM/Gemini uses the same text model by default.	Provider coverage follows those libraries; upstream Python provider shims are not copied one-for-one. ASM structured output remains unsupported until ASM exposes that contract.
Embeddings	Real `GEPA.Embeddings` behavior with `GEPA.Embeddings.ReqLLM`; default Gemini embedding model is `google:gemini-embedding-001`.	Other embedding providers can replace the behavior implementation later. Qdrant never creates embeddings.
Generic RAG vector store	Real vector-store behavior, deterministic `InMemory` for tests, local Qdrant through Docker/HTTP, and explicit stubs for pgvector, Weaviate, LanceDB, Chroma, and Milvus.	Qdrant currently uses direct HTTP calls by design; a production client or larger vector subsystem can replace that module without changing Generic RAG call sites.
Generic RAG adapter	Headless adapter pipeline with retrieval/generation metrics, injected embedder, and live Qdrant example using real embeddings plus real ASM/Gemini inference.	No hosted document-ingestion service is bundled. Non-Qdrant vector backends are stubs until implemented.
MCP adapter	Existing static/config MCP code may remain, but MCP runtime, transports, live examples, and parity work are WONT BUILD for this line of work by 2026-04-28 user directive.	Reopen only if MCP is explicitly brought back into scope.
Tracking integrations	Dependency-free tracker plus explicit W&B and MLflow stubs behind `GEPA.Tracking`.	Hosted W&B/MLflow clients are optional future work and should remain replaceable.
Examples and guides	Live, headless, adapter-backed scripts and guides. Qdrant RAG requires Docker Qdrant plus Gemini embedding credentials.	Examples should keep using real backends only; deterministic providers stay in tests.

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.