# `TypeSafeAPI.SystemOne`
[🔗](https://github.com/typesend/typesafe_ai/blob/v0.1.0-alpha.3/lib/typesafe_api/system_one.ex#L1)

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.

# `state`

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

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

# `evaluate`

```elixir
@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`

```elixir
@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`

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

Per-call options accepted by `evaluate/4`.

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

* `:timeout` (`t:pos_integer/0`) - Timeout in milliseconds for this call.

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

* `:req_options` (`t:keyword/0`) - Extra `Req` options for this call.

* `:telemetry` (`t:map/0`) - Extra metadata merged into telemetry events.

# `path`

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

The evaluation endpoint path.

# `prepare`

```elixir
@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.

---

*Consult [api-reference.md](api-reference.md) for complete listing*