# dsxir v0.1.0 - API Reference

## Modules

- [Dsxir.Program.State](Dsxir.Program.State.md): Per-predictor mutable slot: demos, instruction override, signature override.

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

- 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.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.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.Invalid.Configuration](Dsxir.Errors.Invalid.Configuration.md): Raised when `Dsxir.configure/1` or runtime settings receive an unknown or malformed key.
  - [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 `Dsxir.Module` predicate dispatches to an undeclared predictor name.
  - [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.Unknown.Unknown](Dsxir.Errors.Unknown.Unknown.md): Splode fallback for errors that cannot be classified into the other five classes.