TypeSafe AI Explained: Structured Decisions for Software

⚡ TL;DR

TypeSafe AI is built for software that needs an AI judgment, not an AI-written paragraph. Its System One models evaluate typed questions against a state and return structured answers such as a selected category, a score, probabilities, and confidence. Your code can then branch, sort, route, or escalate without parsing generated prose.

🔍 What Is TypeSafe AI?

Most generative AI tools are designed to produce text for people. That is useful for drafting, summarizing, and conversation, but it creates friction when the output needs to drive a program. You ask for JSON or a label, hope the format holds, parse the response, and decide what to do when the model is uncertain or adds unexpected text.

TypeSafe takes a different approach. Its documentation describes three AI primitives: Choice, Score, and Noul. Each primitive represents a specific kind of question, and each returns a constrained result that software can consume directly.

The input is a state: text, JSON, or an array of text that contains the information to evaluate. You then define questions with an ID, a type, instructions, and, for Choice or Score, criteria. The model evaluates those questions and returns answers under the IDs you chose.

🧠 System One vs a Chatbot

TypeSafe calls its decision-oriented model family System One. The current flagship is Jev. The name signals a focus on fast, focused judgments rather than open-ended reasoning or text generation.

Need	Generative chatbot	TypeSafe System One
Output	Natural-language response	Typed answer and probabilities
Question shape	Usually expressed in a prompt	Choice, Score, or Noul
Application use	Parse or interpret the response	Branch, route, sort, or threshold directly
Uncertainty	Often implicit	Probabilities and confidence are returned for Choice and Score

This does not make TypeSafe a replacement for every LLM workflow. If you need a detailed explanation, a creative draft, or a multi-step research answer, a generative model may be the better tool. TypeSafe is aimed at the judgment inside a larger application.

🧩 The Three Question Types

Choice: select one option

Use Choice when the answer belongs to a known set of categories with no meaningful order. Examples include routing a support ticket to billing, technical support, or sales; identifying a document type; or choosing the next workflow branch.

The response includes the selected choice, a probability distribution across the options, and confidence.

Score: measure a position on a rubric

Use Score when the answer belongs on an ordered scale. You define the levels, such as "calm," "concerned," and "very angry" for customer frustration. A score can fall between levels, which makes it useful for thresholds and ranking.

Score responses include the numeric score, a legend containing the levels, probabilities, and confidence.

Noul: estimate whether a statement is true

Noul is for a yes-or-no judgment where the probability itself matters. For example: does a message request a refund, contain personally identifiable information, or express urgency?

A Noul answer is a value from 0 to 1 representing the probability that the statement is true. A value near 0.5 means uncertainty; it does not mean a medium score. Noul responses do not include a separate confidence field.

📊 Probabilities and Confidence

TypeSafe's structured answers expose more than a winner. For Choice and Score, the probability distribution shows how the model weighs the possible options or levels. A concentrated distribution suggests a clear result; a flatter distribution suggests ambiguity or insufficient evidence.

The confidence field summarizes that distribution as a value from 0 to 1. It is a convenient signal for application logic, but it is not a guarantee that an individual answer is correct. Use the full probabilities when your domain needs a more specific decision rule.

High confidence: act automatically when the action is low risk.
Medium confidence: ask for confirmation, gather more context, or send the case for review.
Low confidence: do not guess; escalate to a person or a different workflow.

There is no universal threshold. Approving a bank transfer should require a stricter policy than displaying a help article. The threshold belongs in your application and should be tested against real examples.

🔧 How a TypeSafe Workflow Works

A practical workflow separates model judgments from deterministic application logic:

Build the state. Include the message, relevant records, and policy text your questions need.
Define atomic questions. Ask one focused question per judgment instead of one prompt that combines many decisions.
Send related questions together. TypeSafe evaluates questions against the same state independently and in parallel.
Combine answers in code. Apply your business rules, thresholds, permissions, and safety checks outside the model.
Escalate uncertainty. Use probabilities and confidence to decide when a human should review the result.

For example, a refund workflow might ask separately whether the customer requested a refund, whether the transaction looks duplicated, and whether the policy supports a refund. Your code can then require all conditions, apply account rules, and route ambiguous cases to a support agent.

🚀 Getting Started

The official quick start offers three ways to try TypeSafe:

Playground: paste a state, add a Noul, Choice, or Score question, and inspect the result in the browser.
HTTP API: send a POST request to https://api.typesafe.ai/v1/systemone with an API key, state, model, and questions.
Python SDK: install typesafe-sdk, define typed question objects, and call client.system_one(...).

The documentation examples use the jev-latest model alias. Model names and availability can change, so check the current models documentation before hard-coding a model in production.

For details, start with the official TypeSafe quick start, then read the primitive reference and confidence guide.

⚠️ Limitations and Best Practices

Keep questions narrow. A question that requires long reasoning or several independent judgments should be decomposed.
Define criteria carefully. Ambiguous labels produce probabilities that are difficult to interpret.
Keep business logic in code. TypeSafe can supply judgments, but permissions, calculations, and irreversible actions still need deterministic checks.
Test thresholds on your data. Confidence is useful, but the right cutoff depends on the cost of false positives and false negatives.
Know the current input boundary. The System One documentation currently describes text, JSON objects, and arrays of text; image, audio, and video inputs are not supported yet.
Verify current product details. SDKs, model aliases, API behavior, and pricing can change as the service evolves.

❓ FAQ

Is TypeSafe an LLM chatbot?

No. It is designed for structured decisions that software can use. It can understand natural-language state, but its documented output is typed answers and probabilities rather than a generated reply.

Can I ask several questions in one request?

Yes. Questions that use the same state can be sent together and are evaluated independently. If one question genuinely depends on the result of another, make a second request only when your code needs that result to build the next state or question.

What is the difference between Score and Noul?

Score measures a position on ordered levels. Noul estimates the probability that a yes-or-no statement is true. A Noul value of 0.5 means uncertainty, not a middle score.

Should TypeSafe make the final decision?

That depends on the risk. For low-stakes routing, an automatic action may be appropriate after testing. For financial, legal, safety, or irreversible actions, combine the model result with deterministic rules, conservative thresholds, and human review.

🧭 TypeSafe's useful idea is simple: let the model make a small judgment, then let your code own the decision. That separation makes AI behavior easier to inspect, test, and compose.