API Reference dsxir v#0.4.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.

Provider-independent record of token usage and cost for LM work.

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 Dsxir.Predictor.ProgramOfThought / Dsxir.Predictor.CodeAct when max_iters is exhausted without a single successful sandbox run. type is the Dune failure type of the last attempt (:restricted | :memory | :exception | :parsing | :timeout) or :max_iters when attempts failed for differing reasons.

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

Raised when a worker exits with :undef — typically the metric or program module was not loaded in the Task.Supervisor worker (a common LiveBook pitfall where the metric cell was not evaluated before the eval cell).

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.

Coordinate-ascent instruction optimizer. Port of DSPy's COPRO.

Budget presets for Dsxir.Optimizer.COPRO. expand/2 overlays user options on the chosen preset; user keys win. Mirrors Dsxir.Optimizer.MIPROv2.Auto.

Scores a candidate program for Dsxir.Optimizer.COPRO. Runs the already-overridden program on the eval set via Dsxir.Evaluate and returns the mean score and the aggregate error summary. This is a pure scoring shim: override application lives in the Dsxir.Optimizer.COPRO wrapper, which hands this function a program whose instruction overrides are already applied. The eval-set rows are scored concurrently; cfg.num_threads sets the fan-out and defaults to System.schedulers_online/0 when absent.

Instruction proposer for Dsxir.Optimizer.COPRO. Dispatches to Basic (round 0, from the current instruction) or GivenAttempts (later rounds, from the sorted attempt history). Both return exactly n instructions.

Round-zero COPRO proposer. Asks the proposer LM for improved instructions for a single predictor, grounded in that predictor's signature and the current instruction. The current instruction always occupies one of the returned slots so the baseline survives the search; the rest are padded with it on a parse shortfall. Returns exactly n instructions.

Later-round COPRO proposer. Asks the proposer LM for improved instructions for a single predictor, grounded in that predictor's signature and the sorted attempt history (worst-first, so the strongest instruction reads last and anchors the LM). Parse shortfalls are padded with the best attempt's instruction. Returns exactly n instructions.

Checkpointable, pure coordinate-ascent state for a Dsxir.Optimizer.COPRO session.

Result statistics for a COPRO run. Open map by convention.

Per-candidate trial record produced during a COPRO run.

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

Runs a program's forward/2 up to n times with diverse sampling, scores each result with reward_fn, and returns the highest-reward attempt — or the first to clear threshold. Invoked directly from a forward/2 body, like Dsxir.Predictor.Parallel; it is not a declared predictor.

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.

ProgramOfThought whose generated code may call user-provided Dsxir.Tools from inside the Dune sandbox. The generated Elixir is constrained to the default safe allowlist plus one dispatcher function; the tools themselves are trusted and run with their own privileges, exactly as Dsxir.Predictor.ReAct trusts its tools.

The generate -> execute -> regenerate -> extract loop shared by Dsxir.Predictor.ProgramOfThought and Dsxir.Predictor.CodeAct.

Wraps Dune.eval_string/2. The only module in dsxir that references Dune.

Builds the three synthetic signatures the engine drives, the same way Dsxir.Predictor.ChainOfThought builds its reasoning-augmented signature. All three are %Dsxir.Signature.Compiled{}.

Accumulator for the Dsxir.Predictor.CodeExec.Engine reduce_while loop. Pure data. trajectory grows newest-last; each entry is one (code, outcome) attempt.

Extends Dune.Allowlist.Default with exactly one additional permitted function: the CodeAct tool dispatcher. Generated code may call user tools only through Dsxir.Predictor.CodeExec.ToolBridge.call/3; everything else remains under the default safe allowlist.

Exposes user Dsxir.Tools to sandboxed CodeAct code.

Runs N programs concurrently over the same inputs and reduces their predictions. Invoked directly from a forward/2 body, like Dsxir.Predictor.Parallel; it is not a declared predictor.

Compares M pre-generated reasoning chains for a signature and integrates a single best answer. A declared predictor (@behaviour Dsxir.Predictor): it augments the signature with one reasoning_attempt_i :string input per chain plus a prepended rationale :string output, then delegates to Dsxir.Predictor.Predict for a single comparison call.

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{}.

Solves a task by generating Elixir code, executing it in the Dune sandbox, regenerating on failure up to :max_iters (default 3), then LM-extracting the signature's typed outputs from the successful run's result.

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

Like Dsxir.Predictor.BestOfN, but reflective: after a sub-threshold attempt it runs the internal OfferFeedback predictor over the captured trace and injects per-predictor corrective advice into the next attempt through the Dsxir.Settings :hints channel. Invoked from a forward/2 body; not a declared predictor.

Runs the OfferFeedback signature for Dsxir.Predictor.Refine and folds the result into a %{predictor_name => advice} map, keeping only keys that match real predictors in the program. Any failure yields %{} so a flaky feedback call degrades refinement to plain resampling rather than crashing the loop.

Internal signature and trace-rendering helpers for Dsxir.Predictor.Refine. Given a failed attempt's trajectory, the active LM proposes per-predictor corrective advice that the next attempt injects through the :hints channel. Not a user-facing signature.

Shared sample-score-select core for Dsxir.Predictor.BestOfN and Dsxir.Predictor.Refine. Runs a program's forward/2 up to n times sequentially, each attempt under an :lm config carrying diversity (temperature, cache: false, a fresh _dsxir_nonce) the same way Dsxir.Optimizer.BootstrapFewShot does. Scores each attempt with reward_fn, keeps the strictly-best, stops early on threshold, and tolerates up to fail_count raising attempts before re-raising the last error wrapped as Dsxir.Errors.Framework.PredictorError.

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.