Dsxir.Program (dsxir v0.3.0)

Copy Markdown

Runtime state container for a user program.

Carries a Dsxir.Program.Source describing the program's structural origin (a static use Dsxir.Module, a runtime-authored shape, etc.), a per-predictor State map, and an open metadata map populated by optimizers. Flows explicitly through forward/2 and Dsxir.Module.Runtime.call/4 — never held as ambient state.

Summary

Types

t()

Functions

forward(prog, inputs, opts \\ [])

Dispatch a forward pass through the program.

from_runtime(rp)

Build a fresh program wrapping a runtime-authored %Dsxir.RuntimeProgram{}.

get_state(program, name)

Fetch the per-predictor State slot, raising if name is unknown.

identity_module(source)

Return the static-module atom for a Source.Module source.

new(mod)

Build a fresh program from either a Dsxir.Module-tagged module atom or an already-built Dsxir.Program.Source struct. Raises Dsxir.Errors.Invalid.Module when an atom is given that is not a Dsxir.Module.

new(mod_or_source, predictor_names)

Build a program with explicit predictor names. Accepts either a module atom (wrapped via Source.Module.new!/1) or a pre-built source struct. Used internally by load paths where the predictor list is taken from the artifact rather than the source.

put_state(prog, name, state)

Replace the State for name in prog, returning the updated program.

Types

t()

@type t() :: %Dsxir.Program{
  metadata: map(),
  predictors: %{required(atom()) => Dsxir.Program.State.t()},
  source: Dsxir.Program.Source.t()
}

Functions

forward(prog, inputs, opts \\ [])

@spec forward(t(), map(), keyword()) ::
  {t(), Dsxir.Prediction.t()} | {t(), {:partial, Dsxir.Prediction.t()}}

Dispatch a forward pass through the program.

Asks the source to execute first (via Source.execute/4). When the source returns nil (the static-module case), falls back to the user-defined forward/2 on the underlying module.

from_runtime(rp)

@spec from_runtime(Dsxir.RuntimeProgram.t()) :: t()

Build a fresh program wrapping a runtime-authored %Dsxir.RuntimeProgram{}.

Constructs a Dsxir.Program.Source.RuntimeProgram source and seeds the per-predictor State map with one slot per node in the runtime program.

get_state(program, name)

@spec get_state(t(), atom()) :: Dsxir.Program.State.t()

Fetch the per-predictor State slot, raising if name is unknown.

identity_module(source)

@spec identity_module(Dsxir.Program.Source.t()) :: module()

Return the static-module atom for a Source.Module source.

Raises Dsxir.Errors.Invalid.Configuration for runtime sources — callers that need to dispatch behaviour on the source must go through the Dsxir.Program.Source behaviour (Source.execute/4, Source.predictors/1, Source.signature_for/2). For error-formatting use cases that just need a display value, use identity_for_error/1.

new(mod)

@spec new(module() | Dsxir.Program.Source.t()) :: t()

Build a fresh program from either a Dsxir.Module-tagged module atom or an already-built Dsxir.Program.Source struct. Raises Dsxir.Errors.Invalid.Module when an atom is given that is not a Dsxir.Module.

new(mod_or_source, predictor_names)

@spec new(module() | Dsxir.Program.Source.t(), [atom()]) :: t()

Build a program with explicit predictor names. Accepts either a module atom (wrapped via Source.Module.new!/1) or a pre-built source struct. Used internally by load paths where the predictor list is taken from the artifact rather than the source.

put_state(prog, name, state)

@spec put_state(t(), atom(), Dsxir.Program.State.t()) :: t()

Replace the State for name in prog, returning the updated program.