# dsxir v0.2.0 - Table of Contents

> An extensible framework for building and optimizing LLM-powered applications in Elixir.

## Pages

- [dsxir](readme.md)

- Guides
  - [Runtime Programs](runtime_programs.md)

- Tutorials
  - [Email Information Extraction](email_extraction.md)
  - [Support Ticket Triage with KNN Few-Shot](knn_few_shot.md)
  - [Content Moderation with MIPROv2](miprov2.md)

## Modules

- [Dsxir.Metric.ScoreWithFeedback](Dsxir.Metric.ScoreWithFeedback.md): Multi-objective score + feedback returned from a metric. Consumed by
`Dsxir.Optimizer.GEPA`; transparent to `Dsxir.Evaluate` and other optimizers,
which see only the aggregated scalar score.
- [Dsxir.Optimizer.GEPA](Dsxir.Optimizer.GEPA.md): Reflective + Pareto-frontier evolutionary optimizer. Implements
`@behaviour Dsxir.Optimizer` and all four checkpointable callbacks, so it
drops into `Dsxir.OptimizerSession` exactly the way MIPROv2 does.
- [Dsxir.Optimizer.GEPA.Auto](Dsxir.Optimizer.GEPA.Auto.md): Preset → resolved config for GEPA. Mirrors `Dsxir.Optimizer.MIPROv2.Auto`.
User-supplied opts override the preset.

- [Dsxir.Optimizer.GEPA.Delta](Dsxir.Optimizer.GEPA.Delta.md): Per-individual delta against the seed program. `apply_to/3` materializes a
`%Dsxir.Program{}` from the seed by overriding each predictor's instruction
and slotting the referenced demo bundle.

- [Dsxir.Optimizer.GEPA.Evaluator](Dsxir.Optimizer.GEPA.Evaluator.md): Parallel devset evaluation for `Dsxir.Optimizer.GEPA`. Returns
`{scores, feedback}` — two ordered lists aligned with the devset.
- [Dsxir.Optimizer.GEPA.FeedbackPool](Dsxir.Optimizer.GEPA.FeedbackPool.md): Samples reflective rollouts from a single individual's per-example score and
feedback arrays. Returns up to K_success best-scoring entries and up to
K_fail worst-scoring entries, skipping entries where feedback is nil.

- [Dsxir.Optimizer.GEPA.Individual](Dsxir.Optimizer.GEPA.Individual.md): One member of the GEPA population. Carries the delta that produced it, its
per-example scores and feedback (positionally aligned with the pinned
devset), and provenance.
- [Dsxir.Optimizer.GEPA.Operators](Dsxir.Optimizer.GEPA.Operators.md): Behaviour and dispatcher for GEPA mutation operators.
- [Dsxir.Optimizer.GEPA.Operators.Crossover](Dsxir.Optimizer.GEPA.Operators.Crossover.md): Two-parent operator. Picks one predictor where the two parents differ in
instruction text (falls back to a uniform random predictor if instructions
are identical across all predictors). Asks the reflective LM to merge the
two parents' instructions for that predictor. Demo bundle ref is inherited
from parent A.

- [Dsxir.Optimizer.GEPA.Operators.MutateDemos](Dsxir.Optimizer.GEPA.Operators.MutateDemos.md): Single-parent operator with no LM call. Picks one predictor uniformly,
picks a different demo bundle from the demo table for it, and returns a
delta swapping that predictor's `demo_bundle_refs[name]`. Falls back to
re-using the same bundle if only one bundle is available for the chosen
predictor.

- [Dsxir.Optimizer.GEPA.Operators.MutateInstr](Dsxir.Optimizer.GEPA.Operators.MutateInstr.md): Single-parent operator. Picks one predictor uniformly at random; samples
K_success + K_fail rollouts from the parent; asks the reflective LM to
rewrite that predictor's instruction. Returns a new delta with all other
predictors' instructions and demo refs unchanged from the parent.

- [Dsxir.Optimizer.GEPA.Pareto](Dsxir.Optimizer.GEPA.Pareto.md): Per-example Pareto frontier and parent selection for GEPA.
- [Dsxir.Optimizer.GEPA.Population](Dsxir.Optimizer.GEPA.Population.md): Opaque collection of `%Individual{}` preserving birth order. Lookup by id is
O(1); iteration is birth-order stable (oldest first).

- [Dsxir.Optimizer.GEPA.Proposer.Reflective](Dsxir.Optimizer.GEPA.Proposer.Reflective.md): Reflective instruction proposer. One LM call per invocation. Two flavours
- [Dsxir.Optimizer.GEPA.Sampler](Dsxir.Optimizer.GEPA.Sampler.md): Checkpointable state for a GEPA session. `serialize/1` round-trips via
`:erlang.term_to_binary/2` with `[:deterministic]`; `deserialize/2`
uses `[:safe]` and confirms shape.
- [Dsxir.Optimizer.GEPA.Stats](Dsxir.Optimizer.GEPA.Stats.md): Open-map result for `Dsxir.Optimizer.GEPA.compile/4`. New optimizer keys land
alongside without versioning.

- [Dsxir.Optimizer.GEPA.Trial](Dsxir.Optimizer.GEPA.Trial.md): One-trial pipeline: select operator, apply, build child, evaluate, admit.
Catches the framework-recognised exception classes at its boundary and
surfaces them as a `:error`-status trial record (degraded sampler) rather
than crashing the caller.

- [Dsxir.Optimizer.MIPROv2.Auto](Dsxir.Optimizer.MIPROv2.Auto.md): Pure-data preset table for MIPROv2's `auto: :light | :medium | :heavy` knob.
- [Dsxir.Optimizer.MIPROv2.Candidates](Dsxir.Optimizer.MIPROv2.Candidates.md): Builds the categorical search space for MIPROv2 and the lookup table that
maps `{predictor_name, dim, index}` back to the actual instruction string or
demo bundle.
- [Dsxir.Optimizer.MIPROv2.Proposer.DatasetSummarizer](Dsxir.Optimizer.MIPROv2.Proposer.DatasetSummarizer.md): Asks the proposer LM to summarize the kind of task represented by a trainset.
- [Dsxir.Optimizer.MIPROv2.Proposer.Grounded](Dsxir.Optimizer.MIPROv2.Proposer.Grounded.md): Asks the proposer LM to produce `n_candidates` candidate instructions for a
single predictor, grounded in a program summary, a dataset summary, and an
optional stylistic tip.
- [Dsxir.Optimizer.MIPROv2.Proposer.ProgramSummarizer](Dsxir.Optimizer.MIPROv2.Proposer.ProgramSummarizer.md): Asks the proposer LM to summarize a user program — its predictor names,
signatures, and current instructions — in a few sentences.
- [Dsxir.Optimizer.MIPROv2.Proposer.Tips](Dsxir.Optimizer.MIPROv2.Proposer.Tips.md): Static lookup of proposer "tips" — short stylistic hints prepended to the
grounded-proposer prompt to nudge instruction-generation style.
- [Dsxir.Optimizer.MIPROv2.Stats.Record](Dsxir.Optimizer.MIPROv2.Stats.Record.md): Per-trial record produced by `Dsxir.Optimizer.MIPROv2.Trial.run/1`.
- [Dsxir.Optimizer.MIPROv2.Trial](Dsxir.Optimizer.MIPROv2.Trial.md): Runs one MIPROv2 trial: apply a sampled config to a program's per-predictor
state, run the program over a minibatch in parallel, score each prediction
with the metric, and return a `Dsxir.Optimizer.MIPROv2.Stats.Record`.
- [Dsxir.Predicate](Dsxir.Predicate.md): Bounded expression DSL for runtime predicates.
- [Dsxir.Predicate.AST](Dsxir.Predicate.AST.md): Parsed predicate tree.
- [Dsxir.Predicate.Evaluator](Dsxir.Predicate.Evaluator.md): Pure-total predicate evaluator.
- [Dsxir.Predicate.Parser](Dsxir.Predicate.Parser.md): NimbleParsec grammar for the predicate DSL.
- [Dsxir.Predicate.Source](Dsxir.Predicate.Source.md): Holds a predicate source string. The parsed AST is attached later by the
predicate parser; until then `ast:` stays `nil`. Hashing uses only the
`:source` field, so attaching an AST never changes a program's version.

- [Dsxir.Predicate.TypeChecker](Dsxir.Predicate.TypeChecker.md): Walks a predicate AST against a per-namespace field-type environment.
- [Dsxir.Program.OptimizableSite](Dsxir.Program.OptimizableSite.md): A predictor site eligible for optimizer demo writes.
- [Dsxir.Program.PredictorDecl](Dsxir.Program.PredictorDecl.md): Normalized predictor declaration as returned by `Source.predictors/1`.
- [Dsxir.Program.Source](Dsxir.Program.Source.md): Abstracts over a `%Dsxir.Program{}`'s structural origin.
- [Dsxir.Program.Source.Module](Dsxir.Program.Source.Module.md): Source impl wrapping a static `use Dsxir.Module` user module.
- [Dsxir.Program.Source.RuntimeProgram](Dsxir.Program.Source.RuntimeProgram.md): Source impl wrapping a `%Dsxir.RuntimeProgram{}` record.
- [Dsxir.Program.State](Dsxir.Program.State.md): Per-predictor mutable slot: demos, instruction override, signature override.
- [Dsxir.ProgramContext](Dsxir.ProgramContext.md): Value type handed to `program_plugs` at runtime-program construction time.
- [Dsxir.RuntimeProgram](Dsxir.RuntimeProgram.md): Pure-data runtime-authored program shape.
- [Dsxir.RuntimeProgram.Canonical](Dsxir.RuntimeProgram.Canonical.md): Canonical IO-list encoding of a `Dsxir.RuntimeProgram` used as the input to
the SHA-256 content hash that becomes the program's `:version`.
- [Dsxir.RuntimeProgram.Edge](Dsxir.RuntimeProgram.Edge.md): Typed data flow between a producer endpoint and a consumer endpoint inside a
runtime program.
- [Dsxir.RuntimeProgram.Executor](Dsxir.RuntimeProgram.Executor.md): Sequential topological DAG walk with skip cascading and an `on_skip` policy.
- [Dsxir.RuntimeProgram.FieldSpec](Dsxir.RuntimeProgram.FieldSpec.md): Typed I/O slot on a runtime program's boundary.
- [Dsxir.RuntimeProgram.Node](Dsxir.RuntimeProgram.Node.md): One predictor invocation site inside a runtime program.
- [Dsxir.RuntimeProgram.Store](Dsxir.RuntimeProgram.Store.md): Behaviour for runtime-program persistence.
- [Dsxir.RuntimeProgram.Store.ETS](Dsxir.RuntimeProgram.Store.ETS.md): ETS-backed in-memory implementation of `Dsxir.RuntimeProgram.Store`.
- [Dsxir.RuntimeProgram.Store.File](Dsxir.RuntimeProgram.Store.File.md): File-backed reference implementation of `Dsxir.RuntimeProgram.Store`.
- [Dsxir.RuntimeProgram.Topological](Dsxir.RuntimeProgram.Topological.md): Kahn's algorithm for sorting `%Dsxir.RuntimeProgram.Node{}` values into a
valid execution order.
- [Dsxir.RuntimeProgram.Validator](Dsxir.RuntimeProgram.Validator.md): Three-phase semantic validator for `%Dsxir.RuntimeProgram{}`.
- [Dsxir.Trace.Entry](Dsxir.Trace.Entry.md): One predictor invocation captured by `Dsxir.with_trace/1`.

- Core
  - [Dsxir](Dsxir.md): Top-level facade for the dsxir framework. Re-exports the user-facing entry
points; predictors, adapters, optimizers, and LM impls are reached for under
their own module names.

  - [Dsxir.CallContext](Dsxir.CallContext.md): Value type handed to `call_plugs`. Carries the call-site information a plug
needs to make an `:ok | {:halt, reason}` decision before the predictor's
`forward/4` runs.
  - [Dsxir.Program](Dsxir.Program.md): Runtime state container for a user program.
  - [Dsxir.Settings](Dsxir.Settings.md): Three-layer settings stack: globals (`:persistent_term`, with a per-process
override), per-process scope (process dict), per-call opts (passed as args).

- Signature
  - [Dsxir.Signature](Dsxir.Signature.md): Declarative signature module. Wraps `Spark.Dsl` so authors write
  - [Dsxir.Signature.Compiled](Dsxir.Signature.Compiled.md): Runtime-compiled signature carrying the same introspection shape as a
module-based signature. Produced by `Dsxir.Signature.from_string/2` and
`Dsxir.Signature.from_string!/2` (string form) and by
`Dsxir.Predictor.ChainOfThought` (field augmentation).
  - [Dsxir.Signature.Field](Dsxir.Signature.Field.md): Internal struct produced by the Signature DSL for each `input` / `output` entity.
  - [Dsxir.Signature.Runtime](Dsxir.Signature.Runtime.md): Stable introspection surface for signature modules. Callers depend on this
module rather than on the Spark `Info` generator output.

- Module
  - [Dsxir.Module](Dsxir.Module.md): Declarative user-program shell.
  - [Dsxir.Module.PredictorDecl](Dsxir.Module.PredictorDecl.md): Compile-time declaration of one predictor inside a user module.
  - [Dsxir.Module.Runtime](Dsxir.Module.Runtime.md): Dispatches `call(prog, :name, inputs)` from inside `forward/2` to the
declared predictor implementation.

- Adapter
  - [Dsxir.Adapter](Dsxir.Adapter.md): Adapter behaviour: turn a signature + inputs + demos into LM messages, and
parse the LM response back into a typed field map.
  - [Dsxir.Adapter.Chat](Dsxir.Adapter.Chat.md): Chat adapter: prompts the LM with `[[ ## field ## ]]` markers and parses the
response by splitting on those markers, JSON-decoding typed fields, and
validating each output through its Zoi schema.
  - [Dsxir.Adapter.Json](Dsxir.Adapter.Json.md): Json adapter: instructs the LM to return a structured object validated against
the signature's output Zoi schema, and parses the returned map through that
schema directly.

- Predictor
  - [Dsxir.Predictor](Dsxir.Predictor.md): Predictor behaviour. A predictor is a stateless module that turns inputs into
a `%Dsxir.Prediction{}` by routing through an adapter and the active LM.
  - [Dsxir.Predictor.ChainOfThought](Dsxir.Predictor.ChainOfThought.md): Wraps `Dsxir.Predictor.Predict` by prepending a `:reasoning :string` output
field to the signature. The reasoning text lands on `pred.fields.reasoning`;
remaining output fields follow.
  - [Dsxir.Predictor.Parallel](Dsxir.Predictor.Parallel.md): Fan-out predictor helper. Runs N predictor calls concurrently under
`Dsxir.TaskSupervisor`, replaying the caller's `Dsxir.Settings.snapshot/0`
in each worker so settings-scoped state (metadata, lm, adapter, cache)
is preserved.
  - [Dsxir.Predictor.Predict](Dsxir.Predictor.Predict.md): Atomic predictor: format with the configured adapter, dispatch through the
LM, parse, validate, wrap in a `%Dsxir.Prediction{}`.
  - [Dsxir.Predictor.ReAct](Dsxir.Predictor.ReAct.md): Tool-using agent predictor. Drives a per-step `Predict` loop until the model
emits `next_tool_name: "finish"` or `:max_iters` is reached.

- Optimizer
  - [Dsxir.Optimizer](Dsxir.Optimizer.md): Behaviour and dispatcher for program optimizers.
  - [Dsxir.Optimizer.BootstrapFewShot](Dsxir.Optimizer.BootstrapFewShot.md): Two-phase optimizer: slot labeled demos from the trainset (phase 1), then
augment with bootstrapped demos captured from successful traces (phase 2).
  - [Dsxir.Optimizer.BootstrapFewShot.Sampler](Dsxir.Optimizer.BootstrapFewShot.Sampler.md): Persistent state for a `Dsxir.Optimizer.BootstrapFewShot` session.
  - [Dsxir.Optimizer.Cache](Dsxir.Optimizer.Cache.md): Compile-scoped LM cache for optimizers that run a program many times.
  - [Dsxir.Optimizer.KNNFewShot](Dsxir.Optimizer.KNNFewShot.md): Per-call dynamic demo selection optimizer.
  - [Dsxir.Optimizer.LabeledFewShot](Dsxir.Optimizer.LabeledFewShot.md): Optimizer that slots up to `:max_labeled_demos` examples from `trainset` into
each predictor's `Dsxir.Program.State.demos`. No LM call. The metric argument
is accepted but unused — interface uniformity for richer optimizers.
  - [Dsxir.Optimizer.MIPROv2](Dsxir.Optimizer.MIPROv2.md): Joint instruction-and-demo optimizer. Port of DSPy's MIPROv2.
  - [Dsxir.Optimizer.MIPROv2.Sampler](Dsxir.Optimizer.MIPROv2.Sampler.md): Persistent state for a `Dsxir.Optimizer.MIPROv2` session.
  - [Dsxir.Optimizer.MIPROv2.Stats](Dsxir.Optimizer.MIPROv2.Stats.md): Per-compile statistics returned from `Dsxir.Optimizer.MIPROv2.compile/4`.
  - [Dsxir.Optimizer.Search.Random](Dsxir.Optimizer.Search.Random.md): Uniform-random categorical sampler. Implementation of `Dsxir.Optimizer.Search.Sampler`.
  - [Dsxir.Optimizer.Search.Sampler](Dsxir.Optimizer.Search.Sampler.md): Behaviour for categorical hyperparameter samplers used by `Dsxir.Optimizer.MIPROv2`
and any other optimizer that searches a fixed categorical space.
  - [Dsxir.Optimizer.Search.TPE](Dsxir.Optimizer.Search.TPE.md): Categorical Tree-structured Parzen Estimator. Implementation of
`Dsxir.Optimizer.Search.Sampler`.
  - [Dsxir.OptimizerSession](Dsxir.OptimizerSession.md): Resumable optimizer session driver.
  - [Dsxir.OptimizerSession.Checkpoint](Dsxir.OptimizerSession.Checkpoint.md): Persisted record for one OptimizerSession state transition.
  - [Dsxir.OptimizerSession.Store](Dsxir.OptimizerSession.Store.md): Behaviour for OptimizerSession checkpoint persistence.
  - [Dsxir.OptimizerSession.Store.ETS](Dsxir.OptimizerSession.Store.ETS.md): ETS-backed Store. Named table `:dsxir_optimizer_sessions`, `:public, :set,
write_concurrency: true`. Survives session crashes; does NOT survive node
restarts. Default in `Mix.env() == :test`.

  - [Dsxir.OptimizerSession.Store.File](Dsxir.OptimizerSession.Store.File.md): File-backed Store with atomic writes (temp file plus rename).

- DemoStrategy
  - [Dsxir.DemoStrategy](Dsxir.DemoStrategy.md): Marker module for per-call demo resolution strategies. v1 ships a single
strategy (`Dsxir.DemoStrategy.KNN`); the runtime hook in
`Dsxir.Module.Runtime.call/4` dispatches via a `case` over the struct.
  - [Dsxir.DemoStrategy.KNN](Dsxir.DemoStrategy.KNN.md): Per-call demo resolver: embed the inputs, cosine-search the index, return
the top-K examples as demos for this call.
  - [Dsxir.DemoStrategy.KNN.EmbedText](Dsxir.DemoStrategy.KNN.EmbedText.md): Deterministic input-map rendering for KNN embedding.
  - [Dsxir.DemoStrategy.KNN.Entry](Dsxir.DemoStrategy.KNN.Entry.md): One indexed (embedding, example) pair.

- Evaluate
  - [Dsxir.Evaluate](Dsxir.Evaluate.md): Devset evaluation runner.
  - [Dsxir.EvaluationResult](Dsxir.EvaluationResult.md): Result of a single `Dsxir.Evaluate.run/2` invocation.
  - [Dsxir.Metric](Dsxir.Metric.md): Metric contract used by `Dsxir.Evaluate` and the `Dsxir.Optimizer` family.

- Trace
  - [Dsxir.Trace](Dsxir.Trace.md): Process-local trace accumulator for `Dsxir.with_trace/1`.

- Retrieval
  - [Dsxir.Retrieval](Dsxir.Retrieval.md): Retrieval primitives.
  - [Dsxir.Retrieval.Cosine](Dsxir.Retrieval.Cosine.md): Brute-force cosine similarity over two flat float lists.
  - [Dsxir.Retrieval.Embedder](Dsxir.Retrieval.Embedder.md): Batched wrapper around `Dsxir.LM.embed/2`.
  - [Dsxir.Retrieval.InMemory](Dsxir.Retrieval.InMemory.md): Cosine-similarity brute-force retriever backed by a struct value.

- Primitives
  - [Dsxir.Demo](Dsxir.Demo.md): A demo slotted into a predictor by an optimizer.
  - [Dsxir.Example](Dsxir.Example.md): A labeled example used as input to optimizers and to the demo channel.
  - [Dsxir.Prediction](Dsxir.Prediction.md): Typed output of a predictor call.
  - [Dsxir.Primitives.History](Dsxir.Primitives.History.md): Multi-turn conversation value type. Bind one to a signature input field whose
Zoi type is `Dsxir.Primitives.History`; the chat adapter materializes the
conversation into the prompt sequence.
  - [Dsxir.Primitives.Tool](Dsxir.Primitives.Tool.md): Value type describing a tool callable by `Dsxir.Predictor.ReAct`.

- LM
  - [Dsxir.LM](Dsxir.LM.md): Behaviour for LM providers.
  - [Dsxir.LM.Sycophant](Dsxir.LM.Sycophant.md): Sycophant-backed implementation of the `Dsxir.LM` behaviour.

- Telemetry
  - [Dsxir.History](Dsxir.History.md): ETS-backed `inspect_history` developer tool.
  - [Dsxir.Telemetry](Dsxir.Telemetry.md): Event-name constants and the `emit/3` helper for dsxir telemetry.

- Errors
  - [Dsxir.Errors](Dsxir.Errors.md): Splode aggregator for dsxir-originated errors.
  - [Dsxir.Errors.Adapter](Dsxir.Errors.Adapter.md): Adapter-class errors: parse, Zoi validation, and fallback exhaustion.
  - [Dsxir.Errors.Framework](Dsxir.Errors.Framework.md): Framework-class errors: dsxir internal bugs surfaced as typed errors.
  - [Dsxir.Errors.Halted](Dsxir.Errors.Halted.md): Halted-class errors: explicit policy stops surfaced through call_plugs and friends.
  - [Dsxir.Errors.Halted.Plug](Dsxir.Errors.Halted.Plug.md): Raised when a function in `Dsxir.Settings.call_plugs` returns `{:halt, reason}` before predictor dispatch.
  - [Dsxir.Errors.Invalid](Dsxir.Errors.Invalid.md): Invalid-class errors: configuration, signature, and trainset shape problems.
  - [Dsxir.Errors.LM](Dsxir.Errors.LM.md): LM-class errors: upstream transport, context-window, rate-limit, authentication.
  - [Dsxir.Errors.Unknown](Dsxir.Errors.Unknown.md): Unknown-class errors: Splode fallback when an error cannot be classified.

- Artifact
  - [Dsxir.Artifact](Dsxir.Artifact.md): Encode and decode `Dsxir.Program` save/load artifacts.

- Exceptions
  - [Dsxir.Errors.Adapter.FallbackExhausted](Dsxir.Errors.Adapter.FallbackExhausted.md): Raised when an adapter's one-shot fallback (Chat->Json or Json schema retry) also fails.
  - [Dsxir.Errors.Adapter.ParseError](Dsxir.Errors.Adapter.ParseError.md): Raised when an adapter fails to parse an LM response into the declared output shape.
  - [Dsxir.Errors.Adapter.ZoiValidation](Dsxir.Errors.Adapter.ZoiValidation.md): Raised when an adapter's per-field Zoi validation rejects a parsed value.
  - [Dsxir.Errors.Framework.CycleDetected](Dsxir.Errors.Framework.CycleDetected.md): Raised by the executor when topological sort detects a cycle. The
validator already proves runtime programs are acyclic, so this surfaces
a framework-invariant breach (someone bypassed the validator).

  - [Dsxir.Errors.Framework.GEPAOperatorFailed](Dsxir.Errors.Framework.GEPAOperatorFailed.md): Raised when a GEPA reflective operator fails to produce a valid offspring.
  - [Dsxir.Errors.Framework.MissingInput](Dsxir.Errors.Framework.MissingInput.md): Framework-invariant breach. If validation succeeded, this cannot fire.
Never user-facing; if you see this, file a bug.

  - [Dsxir.Errors.Framework.OptimizerError](Dsxir.Errors.Framework.OptimizerError.md): Raised when an optimizer aggregates more per-example errors than `:max_errors` allows.
  - [Dsxir.Errors.Framework.PredictorError](Dsxir.Errors.Framework.PredictorError.md): Raised when an internal predictor invariant fails (timeout, trajectory overshoot, etc.).
  - [Dsxir.Errors.Halted.ProgramPlug](Dsxir.Errors.Halted.ProgramPlug.md): Raised when a function in `program_plugs` returns `{:halt, reason}` at runtime-program construction.
  - [Dsxir.Errors.Invalid.AlreadyTerminal](Dsxir.Errors.Invalid.AlreadyTerminal.md): Raised when an OptimizerSession operation targets a session that is already in a terminal state.
  - [Dsxir.Errors.Invalid.Configuration](Dsxir.Errors.Invalid.Configuration.md): Raised when `Dsxir.configure/1` or runtime settings receive an unknown or malformed key.
  - [Dsxir.Errors.Invalid.EmptyDevset](Dsxir.Errors.Invalid.EmptyDevset.md): Raised when GEPA cannot carve a non-empty devset from the trainset.
  - [Dsxir.Errors.Invalid.Metric](Dsxir.Errors.Invalid.Metric.md): Raised when a metric returns a non-numeric/non-boolean value for an example.
  - [Dsxir.Errors.Invalid.Module](Dsxir.Errors.Invalid.Module.md): Raised when a program dispatches to an undeclared predictor name, or when a
non-`Dsxir.Module` is supplied. The `:module` field carries either the
static module atom (for `Dsxir.Program.Source.Module`) or the runtime
program id binary (for `Dsxir.Program.Source.RuntimeProgram`).

  - [Dsxir.Errors.Invalid.NotCheckpointable](Dsxir.Errors.Invalid.NotCheckpointable.md): Raised when `OptimizerSession.start_link/2` is called with an optimizer that does not implement the checkpointing callbacks.
  - [Dsxir.Errors.Invalid.ResumeMismatch](Dsxir.Errors.Invalid.ResumeMismatch.md): Raised when a checkpoint cannot be resumed because optimizer, sampler version, or trainset hash disagree.
  - [Dsxir.Errors.Invalid.RuntimeProgram](Dsxir.Errors.Invalid.RuntimeProgram.md): Raised by `Dsxir.RuntimeProgram.from_map/2` on structural malformation that
prevents parsing (e.g. `nodes` is not a list, an edge endpoint tuple is the
wrong shape). Semantic validation lives in `Dsxir.RuntimeProgram.Validator`
and produces the same error shape.
  - [Dsxir.Errors.Invalid.Signature](Dsxir.Errors.Invalid.Signature.md): Raised when a signature declaration is malformed at compile time.
  - [Dsxir.Errors.Invalid.SignatureMismatch](Dsxir.Errors.Invalid.SignatureMismatch.md): Raised when a saved artifact hydrates into a module whose signature shape does not match.
  - [Dsxir.Errors.Invalid.Tool](Dsxir.Errors.Invalid.Tool.md): Raised when a `Dsxir.Primitives.Tool` declaration or call is malformed.
  - [Dsxir.Errors.Invalid.Trainset](Dsxir.Errors.Invalid.Trainset.md): Raised when an optimizer is invoked with an empty or malformed trainset.
  - [Dsxir.Errors.LM.Authentication](Dsxir.Errors.LM.Authentication.md): Raised when the LM rejects a request due to missing or invalid credentials.
  - [Dsxir.Errors.LM.ContextWindow](Dsxir.Errors.LM.ContextWindow.md): Raised when the LM rejects a request because the prompt exceeded its context window.
  - [Dsxir.Errors.LM.RateLimited](Dsxir.Errors.LM.RateLimited.md): Raised when the LM rejects a request due to rate limits, with optional retry_after.
  - [Dsxir.Errors.LM.RequestFailed](Dsxir.Errors.LM.RequestFailed.md): Raised on a non-classified LM provider error (transport, server error, empty response).
  - [Dsxir.Errors.Runtime](Dsxir.Errors.Runtime.md): Runtime-class errors raised during executor execution.
  - [Dsxir.Errors.Runtime.PredicateError](Dsxir.Errors.Runtime.PredicateError.md): Raised when a guard predicate fails at runtime (type mismatch slipping past static checking, missing field, etc.).
  - [Dsxir.Errors.Runtime.SkippedOutputs](Dsxir.Errors.Runtime.SkippedOutputs.md): Raised by the executor when `on_skip: :raise` (the default) and any program output's chain was skipped.
  - [Dsxir.Errors.Unknown.Unknown](Dsxir.Errors.Unknown.Unknown.md): Splode fallback for errors that cannot be classified into the other five classes.

## Mix Tasks

- [mix dsxir.check.no_eval](Mix.Tasks.Dsxir.Check.NoEval.md): CI invariant: forbid runtime evaluation/compilation in the dynamic-program code paths.

