Spectre.Provider.Call (Spectre v0.3.0)

Copy Markdown View Source

Isolated timeout and crash boundary for external provider calls.

Calls run outside the requesting process. A small coordinator links the adapter worker to both the caller lifecycle and the configured timeout, so a timed-out call or dead caller terminates the local adapter worker. Remote work already handed to an external service can only be cancelled when that adapter supports cancellation itself. Route evaluation also uses this boundary as the canonical source of sanitized provider outcome and duration facts.

The same boundary is used for application callbacks executed by a turn. The callback contracts are:

KindSupported aritiesNormalized successTimeoutFailure policy
:run1, 2a Spectre.Result or visible reply value:run_timeout, 30sabort the handler turn
:renderer1, 2, 3a binary reply:renderer_timeout, 10sabort the handler turn
:hook0, 1, 2, 3:ok or {:ok, value}:hook_timeout, 10saggregate and report
:prompt0, 1, 2a boolean condition or binary context:prompt_timeout, 10sabort required operations, skip optional ones
:inputinit/1, call/3a valid pipeline transition:input_timeout, 10sabort the turn
:turn_handlerhandle_turn/2:cont or a typed reply:turn_handler_timeout, 30sabort the turn (fail closed)
:routerinit/1, call/2a valid pipeline transition:router_timeout, 120sabort the routing pipeline
:monitor0, 1, 2, 3callback-specific host data:monitor_timeout, 60senter or continue recovery

Model, classifier, embedding, semantic-cache, action, state, memory, and journal adapters use their existing provider-specific timeout keys. Every timeout accepts :infinity only when explicitly configured. Declared {:error, reason} replies are returned unchanged; exceptions, exits, throws, hard crashes, timeouts, and malformed envelopes become privacy-safe Spectre.Provider.Failure values. Calls are attempted exactly once.

Summary

Types

event()
result(value)

Functions

run(provider, fun, opts \\ [])

Runs one provider function under its configured timeout.

Types

event()

@type event() :: %{
  :provider => atom(),
  :outcome => atom(),
  :duration_us => non_neg_integer(),
  :invoked? => boolean(),
  optional(:purpose) => atom()
}

result(value)

@type result(value) :: {:ok, value} | {:error, term()}

Functions

run(provider, fun, opts \\ [])

@spec run(atom(), (-> result(term())), keyword()) :: result(term())

Runs one provider function under its configured timeout.

Provider-specific options override :provider_timeout:

  • :llm_timeout
  • :local_classifier_timeout or :classifier_timeout
  • :embedding_timeout
  • :semantic_cache_timeout
  • :run_timeout
  • :renderer_timeout
  • :hook_timeout
  • :input_timeout
  • :router_timeout
  • :monitor_timeout
  • :turn_handler_timeout

Application defaults may be configured under config :spectre, :provider.