Dsxir.Artifact (dsxir v0.2.0)

Copy Markdown

Encode and decode Dsxir.Program save/load artifacts.

The on-disk JSON envelope (format_version "2"):

{
  "format_version": "2",
  "source_kind": "module" | "runtime",
  "source": <blob>,
  "predictors": {"<name>": {"instructions": ..., "demos": [...]}, ...},
  "metadata": {"compiled_with": ..., "score": ..., "trainset_hash": ...}
}

For source_kind: "module", source is the user-module atom name (e.g. "Elixir.MyApp.QA"). For source_kind: "runtime", source is a JSON-safe serialization of the wrapped %Dsxir.RuntimeProgram{} carrying guard sources only — never parsed ASTs. On load the runtime program is re-validated end-to-end so guard sources are re-parsed and type-checked.

encode/1 always emits format_version "2"; saving as v1 is unsupported. decode/2 and decode_and_hydrate/2 upgrade v1 (legacy unwrapped per-predictor maps) on the fly by inferring source_kind: "module".

Summary

Functions

decode(target_module, envelope)

Rebuild a %Dsxir.Program{} from an already-Jason-decoded artifact map. The companion to encode/1 for inline (file-IO-free) serialization; load/3 is the file path convenience built on this.

decode_and_hydrate(json_or_map, opts \\ [])

Decode a v2 envelope (or v1, upgrading on the fly) directly from a JSON string into a %Program{}. Raises on validation failure or on a malformed envelope.

load(target_module, path, opts \\ [])

Read a saved artifact from path and hydrate it into a fresh program for target_module. Returns {:ok, program} or {:error, exception} on read, decode, or structural validation failures.

load!(target_module, path, opts \\ [])

Bang variant of load/3. Returns the program on success and raises the underlying exception on failure.

save(prog, path)

Write prog to path as pretty JSON. Returns {:ok, path} on success or {:error, exception} when encoding or I/O fails. The target directory is created if missing.

save!(prog, path)

Bang variant of save/2. Returns the path on success and raises the underlying exception on failure.

Functions

decode(target_module, envelope)

Rebuild a %Dsxir.Program{} from an already-Jason-decoded artifact map. The companion to encode/1 for inline (file-IO-free) serialization; load/3 is the file path convenience built on this.

Returns {:ok, program} or {:error, %Dsxir.Errors.Invalid.SignatureMismatch{}} when the persisted shape does not match the target module's declared predictors.

decode_and_hydrate(json_or_map, opts \\ [])

@spec decode_and_hydrate(
  String.t() | map(),
  keyword()
) :: Dsxir.Program.t()

Decode a v2 envelope (or v1, upgrading on the fly) directly from a JSON string into a %Program{}. Raises on validation failure or on a malformed envelope.

Pass :target_module to disambiguate a v1 legacy payload that does not carry its source identity inline. Without :target_module, v1 payloads raise Dsxir.Errors.Invalid.Configuration.

load(target_module, path, opts \\ [])

@spec load(module(), Path.t(), keyword()) ::
  {:ok, Dsxir.Program.t()} | {:error, Exception.t()}

Read a saved artifact from path and hydrate it into a fresh program for target_module. Returns {:ok, program} or {:error, exception} on read, decode, or structural validation failures.

Accepts v1 (legacy, per-predictor top-level map) and v2 envelopes. For v2 module-source envelopes the on-disk module name must match target_module.

load!(target_module, path, opts \\ [])

@spec load!(module(), Path.t(), keyword()) :: Dsxir.Program.t()

Bang variant of load/3. Returns the program on success and raises the underlying exception on failure.

save(prog, path)

@spec save(Dsxir.Program.t(), Path.t()) :: {:ok, Path.t()} | {:error, Exception.t()}

Write prog to path as pretty JSON. Returns {:ok, path} on success or {:error, exception} when encoding or I/O fails. The target directory is created if missing.

save!(prog, path)

@spec save!(Dsxir.Program.t(), Path.t()) :: Path.t()

Bang variant of save/2. Returns the path on success and raises the underlying exception on failure.