Spectre.Input (Spectre v0.3.2)

Normalized inbound user turn.

Host applications can pass strings, atom-key maps, or string-key maps at the public boundary. Spectre immediately converts them into this struct so router checks, prompt rendering, and action execution do not depend on external payload shapes.

input = Spectre.Input.new(%{"text" => "Hello", "meta" => %{"locale" => "en"}})
input = Spectre.Input.put_meta(input, :channel, :web)

Summary

Types

t()

Functions

fetch_meta(input, key)

Fetches enriched metadata.

merge_meta(input, meta)

Merges enriched metadata onto the input.

new(input)

Normalizes raw inbound input into a Spectre input struct.

put_meta(input, key, value)

Stores enriched metadata on the input.

source_evidence(input)

Returns portable source evidence suitable for prompt/materialization metadata.

trust(input)

Returns the source trust class, defaulting missing legacy sources to untrusted.

validate(input)

Validates the normalized input shape without inspecting its raw transport.

Types

t()

@type t() :: %Spectre.Input{
  meta: map(),
  raw: term(),
  source: Spectre.Input.Source.t() | nil,
  text: String.t()
}

Functions

fetch_meta(input, key)

@spec fetch_meta(t(), atom() | String.t()) :: {:ok, term()} | :error

Fetches enriched metadata.

{:ok, "en"} = Spectre.Input.fetch_meta(input, :locale)

merge_meta(input, meta)

@spec merge_meta(t(), map() | keyword()) :: t()

Merges enriched metadata onto the input.

input = Spectre.Input.merge_meta(input, locale: "en", channel: :web)

new(input)

@spec new(t() | String.t() | map() | term()) :: t()

Normalizes raw inbound input into a Spectre input struct.

Spectre.Input.new("hello")
Spectre.Input.new(%{text: "hello", meta: %{tenant_id: 123}})

put_meta(input, key, value)

@spec put_meta(t(), atom() | String.t(), term()) :: t()

Stores enriched metadata on the input.

input = Spectre.Input.put_meta(input, :locale, "en")

source_evidence(input)

@spec source_evidence(t()) :: map()

Returns portable source evidence suitable for prompt/materialization metadata.

trust(input)

@spec trust(t()) :: :untrusted | :trusted | :system

Returns the source trust class, defaulting missing legacy sources to untrusted.

validate(input)

@spec validate(term()) :: :ok | {:error, term()}

Validates the normalized input shape without inspecting its raw transport.

Raw payloads are deliberately allowed here because they remain local to the inbound boundary and are removed by the Run checkpoint projection.