Unofficial Elixir client for the TypeSafe AI API. Not affiliated with or endorsed by TypeSafe AI.

TypeSafe's System One API answers typed questions about a piece of state: a yes/no probability (noul/2), one option from a set (choice/2), or a position on an ordered scale (score/2). This module is the whole public surface for everyday use; the modules it delegates to hold the details.

client = TypeSafe.new(api_key: "...")

{:ok, result} =
  TypeSafe.evaluate(client, "Help! My payouts have been failing for 3 days.",
    urgent: TypeSafe.noul("Does this convey urgency?"),
    dept:
      TypeSafe.choice("Which team should handle this?",
        billing: "Payments, invoicing, refunds",
        technical: "Bugs, outages, integrations",
        sales: nil
      ),
    anger: TypeSafe.score("How frustrated is the customer?", ["Calm", "Frustrated", "Very angry"])
  )

result.answers.dept.choice   #=> :technical
result.answers.anger.label   #=> "Very angry"
result.usage.input_tokens    #=> 312

The same example, run against TypeSafe.Test stubs instead of the network (this block is a doctest):

iex> client =
...>   TypeSafe.Test.client()
...>   |> TypeSafe.Test.stub(
...>     urgent: {:noul, 0.92},
...>     dept: {:choice, :technical, 0.82},
...>     anger: {:score, 2, 0.65}
...>   )
iex> {:ok, result} =
...>   TypeSafe.evaluate(client, "Help! My payouts have been failing for 3 days.",
...>     urgent:
...>       TypeSafe.noul("Does this convey urgency?",
...>         true: "Explicitly time-sensitive",
...>         false: "No urgency expressed"
...>       ),
...>     dept:
...>       TypeSafe.choice("Which team should handle this?",
...>         billing: "Payments, invoicing, refunds",
...>         technical: "Bugs, outages, integrations",
...>         sales: nil
...>       ),
...>     anger: TypeSafe.score("How frustrated is the customer?", ["Calm", "Frustrated", "Very angry"])
...>   )
iex> result.model
"jev-latest"
iex> result.answers.urgent
%TypeSafe.Answer.Noul{id: :urgent, noul: 0.92}
iex> {result.answers.dept.choice, result.answers.dept.confidence}
{:technical, 0.82}
iex> Map.keys(result.answers.dept.probabilities) |> Enum.sort()
[:billing, :sales, :technical]
iex> {result.answers.anger.level, result.answers.anger.label}
{2, "Very angry"}
iex> Enum.map(result.answers.anger.levels, &elem(&1, 0))
["Calm", "Frustrated", "Very angry"]
iex> TypeSafe.Answer.gate(result.answers.dept, act: 0.8, review: 0.5)
:act
iex> TypeSafe.Answer.gate(result.answers.anger, act: 0.8, review: 0.5)
:review
iex> TypeSafe.Answer.yes?(result.answers.urgent)
true

Question ids and Choice option keys come back exactly as you gave them: atoms stay atoms, strings stay strings. See TypeSafe.Keys for why.

Questions are validated locally on every call, so a malformed one fails with a :validation error before anything is sent. To catch the mistake at the line that wrote it instead, wrap the constructor in TypeSafe.Question.validate!/1, which raises ArgumentError and returns the question unchanged. That is the eager-validation path for questions built once in a module attribute or at application start.

Two layers

TypeSafe.HTTP is the raw layer: maps in, maps out, with auth, retries and telemetry handled. Everything above it (questions, answers, results) is the typed layer. If the API adds something this library does not model yet, the raw layer still works.