SystemOneClient behaviour (SystemOneClient v0.1.0)

Copy Markdown View Source

Client for System One decision models: TypeSafe Jev, Cloudflare Clef, OpenRouter's decisions endpoint, and any self-hosted /v1/systemone server such as CLM.

Ask typed questions (noul, choice, score) about arbitrary JSON state and get typed answers back with their full probability distributions. SystemOneClient.HTTP talks to a provider (see SystemOneClient.Provider); SystemOneClient.Stub returns canned answers for tests. Question maps follow the API wire shape verbatim; this library does not invent its own schema for them.

{:ok, answers, meta} = SystemOneClient.evaluate(state, questions, provider: :cloudflare)
answers["tool"].probabilities

Summary

Types

answers()
meta()

Callbacks

evaluate(state, questions, opts)

Functions

evaluate(state, questions, opts \\ [])

Evaluates questions with the configured client (opts[:client], else app env :client, else HTTP).

validate_questions(questions)

Checks every question has a known type. Ids may be atoms or strings.

Types

answers()

@type answers() :: %{required(String.t()) => SystemOneClient.Answer.t()}

meta()

@type meta() :: %{
  optional(:provider) => atom(),
  model: String.t() | nil,
  usage: map() | nil,
  latency_ms: non_neg_integer()
}

Callbacks

evaluate(state, questions, opts)

@callback evaluate(state :: term(), questions :: map(), opts :: keyword()) ::
  {:ok, answers(), meta()} | {:error, term()}

Functions

evaluate(state, questions, opts \\ [])

@spec evaluate(term(), map(), keyword()) ::
  {:ok, answers(), meta()} | {:error, term()}

Evaluates questions with the configured client (opts[:client], else app env :client, else HTTP).

validate_questions(questions)

@spec validate_questions(map()) ::
  :ok | {:error, {:invalid_question, String.t(), :unknown_type | :not_a_map}}

Checks every question has a known type. Ids may be atoms or strings.