API Reference dsxir v#0.2.0

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.

Adapter behaviour: turn a signature + inputs + demos into LM messages, and parse the LM response back into a typed field map.

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.

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.

Encode and decode Dsxir.Program save/load artifacts.

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.

A demo slotted into a predictor by an optimizer.

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.

Per-call demo resolver: embed the inputs, cosine-search the index, return the top-K examples as demos for this call.

Deterministic input-map rendering for KNN embedding.

One indexed (embedding, example) pair.

Splode aggregator for dsxir-originated errors.

Adapter-class errors: parse, Zoi validation, and fallback exhaustion.

Raised when an adapter's one-shot fallback (Chat->Json or Json schema retry) also fails.

Raised when an adapter fails to parse an LM response into the declared output shape.

Raised when an adapter's per-field Zoi validation rejects a parsed value.

Framework-class errors: dsxir internal bugs surfaced as typed errors.

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).

Raised when a GEPA reflective operator fails to produce a valid offspring.

Framework-invariant breach. If validation succeeded, this cannot fire. Never user-facing; if you see this, file a bug.

Raised when an optimizer aggregates more per-example errors than :max_errors allows.

Raised when an internal predictor invariant fails (timeout, trajectory overshoot, etc.).

Halted-class errors: explicit policy stops surfaced through call_plugs and friends.

Raised when a function in Dsxir.Settings.call_plugs returns {:halt, reason} before predictor dispatch.

Raised when a function in program_plugs returns {:halt, reason} at runtime-program construction.

Invalid-class errors: configuration, signature, and trainset shape problems.

Raised when an OptimizerSession operation targets a session that is already in a terminal state.

Raised when Dsxir.configure/1 or runtime settings receive an unknown or malformed key.

Raised when GEPA cannot carve a non-empty devset from the trainset.

Raised when a metric returns a non-numeric/non-boolean value for an example.

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).

Raised when OptimizerSession.start_link/2 is called with an optimizer that does not implement the checkpointing callbacks.

Raised when a checkpoint cannot be resumed because optimizer, sampler version, or trainset hash disagree.

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.

Raised when a signature declaration is malformed at compile time.

Raised when a saved artifact hydrates into a module whose signature shape does not match.

Raised when a Dsxir.Primitives.Tool declaration or call is malformed.

Raised when an optimizer is invoked with an empty or malformed trainset.

LM-class errors: upstream transport, context-window, rate-limit, authentication.

Raised when the LM rejects a request due to missing or invalid credentials.

Raised when the LM rejects a request because the prompt exceeded its context window.

Raised when the LM rejects a request due to rate limits, with optional retry_after.

Raised on a non-classified LM provider error (transport, server error, empty response).

Runtime-class errors raised during executor execution.

Raised when a guard predicate fails at runtime (type mismatch slipping past static checking, missing field, etc.).

Raised by the executor when on_skip: :raise (the default) and any program output's chain was skipped.

Unknown-class errors: Splode fallback when an error cannot be classified.

Splode fallback for errors that cannot be classified into the other five classes.

Devset evaluation runner.

Result of a single Dsxir.Evaluate.run/2 invocation.

A labeled example used as input to optimizers and to the demo channel.

ETS-backed inspect_history developer tool.

Behaviour for LM providers.

Sycophant-backed implementation of the Dsxir.LM behaviour.

Metric contract used by Dsxir.Evaluate and the Dsxir.Optimizer family.

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.

Declarative user-program shell.

Compile-time declaration of one predictor inside a user module.

Dispatches call(prog, :name, inputs) from inside forward/2 to the declared predictor implementation.

Behaviour and dispatcher for program optimizers.

Two-phase optimizer: slot labeled demos from the trainset (phase 1), then augment with bootstrapped demos captured from successful traces (phase 2).

Persistent state for a Dsxir.Optimizer.BootstrapFewShot session.

Compile-scoped LM cache for optimizers that run a program many times.

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.

Preset → resolved config for GEPA. Mirrors Dsxir.Optimizer.MIPROv2.Auto. User-supplied opts override the preset.

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.

Parallel devset evaluation for Dsxir.Optimizer.GEPA. Returns {scores, feedback} — two ordered lists aligned with the devset.

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.

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.

Behaviour and dispatcher for GEPA mutation operators.

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.

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.

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.

Per-example Pareto frontier and parent selection for GEPA.

Opaque collection of %Individual{} preserving birth order. Lookup by id is O(1); iteration is birth-order stable (oldest first).

Reflective instruction proposer. One LM call per invocation. Two flavours

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.

Open-map result for Dsxir.Optimizer.GEPA.compile/4. New optimizer keys land alongside without versioning.

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.

Per-call dynamic demo selection optimizer.

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.

Joint instruction-and-demo optimizer. Port of DSPy's MIPROv2.

Pure-data preset table for MIPROv2's auto: :light | :medium | :heavy knob.

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.

Asks the proposer LM to summarize the kind of task represented by a trainset.

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.

Asks the proposer LM to summarize a user program — its predictor names, signatures, and current instructions — in a few sentences.

Static lookup of proposer "tips" — short stylistic hints prepended to the grounded-proposer prompt to nudge instruction-generation style.

Persistent state for a Dsxir.Optimizer.MIPROv2 session.

Per-compile statistics returned from Dsxir.Optimizer.MIPROv2.compile/4.

Per-trial record produced by Dsxir.Optimizer.MIPROv2.Trial.run/1.

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.

Uniform-random categorical sampler. Implementation of Dsxir.Optimizer.Search.Sampler.

Behaviour for categorical hyperparameter samplers used by Dsxir.Optimizer.MIPROv2 and any other optimizer that searches a fixed categorical space.

Categorical Tree-structured Parzen Estimator. Implementation of Dsxir.Optimizer.Search.Sampler.

Resumable optimizer session driver.

Persisted record for one OptimizerSession state transition.

Behaviour for OptimizerSession checkpoint persistence.

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.

File-backed Store with atomic writes (temp file plus rename).

Bounded expression DSL for runtime predicates.

Parsed predicate tree.

Pure-total predicate evaluator.

NimbleParsec grammar for the predicate DSL.

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.

Walks a predicate AST against a per-namespace field-type environment.

Typed output of a predictor call.

Predictor behaviour. A predictor is a stateless module that turns inputs into a %Dsxir.Prediction{} by routing through an adapter and the active LM.

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.

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.

Atomic predictor: format with the configured adapter, dispatch through the LM, parse, validate, wrap in a %Dsxir.Prediction{}.

Tool-using agent predictor. Drives a per-step Predict loop until the model emits next_tool_name: "finish" or :max_iters is reached.

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.

Value type describing a tool callable by Dsxir.Predictor.ReAct.

Runtime state container for a user program.

A predictor site eligible for optimizer demo writes.

Normalized predictor declaration as returned by Source.predictors/1.

Abstracts over a %Dsxir.Program{}'s structural origin.

Source impl wrapping a static use Dsxir.Module user module.

Source impl wrapping a %Dsxir.RuntimeProgram{} record.

Per-predictor mutable slot: demos, instruction override, signature override.

Value type handed to program_plugs at runtime-program construction time.

Retrieval primitives.

Brute-force cosine similarity over two flat float lists.

Batched wrapper around Dsxir.LM.embed/2.

Cosine-similarity brute-force retriever backed by a struct value.

Pure-data runtime-authored program shape.

Canonical IO-list encoding of a Dsxir.RuntimeProgram used as the input to the SHA-256 content hash that becomes the program's :version.

Typed data flow between a producer endpoint and a consumer endpoint inside a runtime program.

Sequential topological DAG walk with skip cascading and an on_skip policy.

Typed I/O slot on a runtime program's boundary.

One predictor invocation site inside a runtime program.

Behaviour for runtime-program persistence.

ETS-backed in-memory implementation of Dsxir.RuntimeProgram.Store.

File-backed reference implementation of Dsxir.RuntimeProgram.Store.

Kahn's algorithm for sorting %Dsxir.RuntimeProgram.Node{} values into a valid execution order.

Three-phase semantic validator for %Dsxir.RuntimeProgram{}.

Three-layer settings stack: globals (:persistent_term, with a per-process override), per-process scope (process dict), per-call opts (passed as args).

Declarative signature module. Wraps Spark.Dsl so authors write

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).

Internal struct produced by the Signature DSL for each input / output entity.

Stable introspection surface for signature modules. Callers depend on this module rather than on the Spark Info generator output.

Event-name constants and the emit/3 helper for dsxir telemetry.

Process-local trace accumulator for Dsxir.with_trace/1.

One predictor invocation captured by Dsxir.with_trace/1.

CI invariant: forbid runtime evaluation/compilation in the dynamic-program code paths.