TypeSafeAPI.SystemOne (TypeSafe AI v0.1.0-alpha.3)

Copy Markdown View Source

Layer 2 for the evaluation endpoint: typed questions in, typed answers out.

This module is the seam between the caller's structs and TypeSafeAPI.HTTP. It validates questions locally, records the caller's keys, encodes the body, posts it, and decodes the answers back under the caller's keys. Everything that can fail before the network does so with a :validation error and no request is sent: a malformed question, a per-call option this library does not accept, and a state that has no JSON representation all fail the same way. Nothing in this path raises.

prepare/1 and evaluate_prepared/4 split the work so TypeSafeAPI.evaluate_many/4 can validate and encode a question set once and reuse it for every state. evaluate/4 also takes a TypeSafeAPI.SystemOne.Prepared in place of a question set, so a caller holding one does not have to reach for a second function name.

Summary

Types

state()

The state to evaluate: text, or JSON-shaped structured data.

Functions

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

Evaluates state against questions.

evaluate_prepared(client, state, prepared, opts \\ [])

Evaluates state against a question set from prepare/1.

options_schema()

Per-call options accepted by evaluate/4.

path()

The evaluation endpoint path.

prepare(questions)

Validates and encodes a question set once, for reuse across many states.

Types

state()

@type state() :: String.t() | map() | list()

The state to evaluate: text, or JSON-shaped structured data.

Functions

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

@spec evaluate(
  TypeSafeAPI.Client.t(),
  state(),
  TypeSafeAPI.Question.input() | TypeSafeAPI.SystemOne.Prepared.t(),
  keyword()
) :: {:ok, TypeSafeAPI.Result.t()} | {:error, TypeSafeAPI.Error.t()}

Evaluates state against questions.

questions is a question set (see TypeSafeAPI.Question.normalize/1) or an already-prepared one from prepare/1, which is passed straight through without being validated and encoded again.

See TypeSafeAPI.evaluate/4 for the public entry point and examples.

evaluate_prepared(client, state, prepared, opts \\ [])

@spec evaluate_prepared(
  TypeSafeAPI.Client.t(),
  state(),
  TypeSafeAPI.SystemOne.Prepared.t(),
  keyword()
) ::
  {:ok, TypeSafeAPI.Result.t()} | {:error, TypeSafeAPI.Error.t()}

Evaluates state against a question set from prepare/1.

options_schema()

@spec options_schema() :: NimbleOptions.t()

Per-call options accepted by evaluate/4.

  • :model (String.t/0) - Model for this call; defaults to the client's model.

  • :timeout (pos_integer/0) - Timeout in milliseconds for this call.

  • :retry - Retry policy for this call; see TypeSafeAPI.Retry.new/1.

  • :req_options (keyword/0) - Extra Req options for this call.

  • :telemetry (map/0) - Extra metadata merged into telemetry events.

path()

@spec path() :: String.t()

The evaluation endpoint path.

prepare(questions)

@spec prepare(TypeSafeAPI.Question.input()) ::
  {:ok, TypeSafeAPI.SystemOne.Prepared.t()} | {:error, TypeSafeAPI.Error.t()}

Validates and encodes a question set once, for reuse across many states.