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

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

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

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

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

Raised when a Dsxir.Module predicate dispatches to an undeclared predictor name.

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

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.

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

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.

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.

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

Retrieval primitives.

Batched wrapper around Dsxir.LM.embed/2.

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

Three-layer settings stack: globals (:persistent_term), 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.