Dsxir.Signature (dsxir v0.2.0)

Copy Markdown

Declarative signature module. Wraps Spark.Dsl so authors write:

defmodule MyApp.AnswerQuestion do
  use Dsxir.Signature

  signature do
    instruction "Answer the user's question."
    input :question, :string
    output :answer, :string, desc: "A direct factual answer."
  end
end

Inline string-form signatures are also supported via from_string/2 and may be passed directly to the Module DSL predictor entity:

predictor :answer, Dsxir.Predictor.Predict, signature: "question -> answer"

The grammar mirrors DSPy's: inputs -> outputs with optional name: type annotations.

Options

  • :extensions (list of module that adopts Spark.Dsl.Extension) - A list of DSL extensions to add to the Spark.Dsl

  • :otp_app (atom/0) - The otp_app to use for any application configurable options

  • :fragments (list of module/0) - Fragments to include in the Spark.Dsl. See the fragments guide for more.

Summary

Functions

from_inline_blob(blob)

Build a Dsxir.Signature.Compiled from an inline JSON-ish blob carrying a list of "fields" and an optional "instruction". Each field map carries "name", "type" (string in the same grammar as from_string/2), "kind" ("input" or "output"), and an optional "desc". Used by Dsxir.RuntimeProgram.from_map/2 when a runtime payload inlines its signature rather than naming a module.

from_string(source, opts \\ [])

Compile a string-form signature into a Dsxir.Signature.Compiled{}.

from_string!(source, opts \\ [])

Compile a string-form signature, raising Dsxir.Errors.Invalid.Signature on parse failure.

Functions

from_inline_blob(blob)

@spec from_inline_blob(map()) :: Dsxir.Signature.Compiled.t()

Build a Dsxir.Signature.Compiled from an inline JSON-ish blob carrying a list of "fields" and an optional "instruction". Each field map carries "name", "type" (string in the same grammar as from_string/2), "kind" ("input" or "output"), and an optional "desc". Used by Dsxir.RuntimeProgram.from_map/2 when a runtime payload inlines its signature rather than naming a module.

Reuses from_string!/2 by reconstructing the equivalent inputs -> outputs string from the blob's fields, then attaching desc and an {:inline, blob} source tag.

from_string(source, opts \\ [])

@spec from_string(
  String.t(),
  keyword()
) :: {:ok, Dsxir.Signature.Compiled.t()} | {:error, term()}

Compile a string-form signature into a Dsxir.Signature.Compiled{}.

Returns {:ok, compiled} on success or {:error, reason} on parse failure. Use from_string!/2 for the raising variant.

from_string!(source, opts \\ [])

@spec from_string!(
  String.t(),
  keyword()
) :: Dsxir.Signature.Compiled.t()

Compile a string-form signature, raising Dsxir.Errors.Invalid.Signature on parse failure.