Skip to main content
Jev is a System One model that reads natural language but returns typed answers and calibrated probabilities instead of generated text. TypeSafeClassifier implements the LangChain Decisions API through BaseDecisionModel. It is a Runnable, so you can invoke, batch, or compose it with other runnables. It accepts strings, structured JSON, and LangChain message objects, and records traces and token usage in LangSmith. Use it for focused decisions such as routing a request, choosing a model, or checking whether a tool call is safe to run. Use TypeSafe decisions in LangChain middleware to control create_agent behavior at specific lifecycle points, including with custom middleware that classifies agent state. See Agent middleware for examples.

Setup

The examples require langchain-typesafe>=0.1.0 and Python 3.11 or later. This release uses the shared decision types in langchain_core.decisions.
Create an API key in the TypeSafe console and export it:
Optional: Set TYPESAFE_BASE_URL to use a compatible gateway, test server, or private deployment. The default is https://api.typesafe.ai.

Quickstart

Create a TypeSafeClassifier, then pass the state and named questions together in each invocation. Questions that share state are evaluated independently and in parallel in one request:
Earlier versions configured questions on TypeSafeClassifier and passed only the state to invoke. Pass both state and questions to invoke now.
Answers are keyed by the question IDs you supplied, and grouped by type on nouls, choices, scores, and boxes. The response also carries the model that answered, optional token usage, and the TypeSafe request_id. In version 0.1, usage is a dictionary rather than an object with token-count attributes. Check for None before reading it:
The request state can be a string, a JSON object or array, or LangChain messages. A BaseMessage or a sequence of messages is converted to role/content JSON, including when nested inside a larger object.

Decision types

Import question types from langchain_core.decisions. The langchain_typesafe re-exports remain available for compatibility. Each question is one of four primitives: Noul has no confidence, since the probability is the answer. Use Score rather than a Noul for a spectrum: a Noul of 0.5 means an even split between yes and no, not “medium”. TypeSafe accepts PNG and JPEG images as LangChain image content blocks containing base64 data or base64 data: URLs. Images can appear in state, question instructions, or criteria. Remote image URLs are not downloaded. For Box questions, read response.boxes[question_id].box; its top, bottom, left, and right edges range from 0 to 1.

Agent middleware

LangChain provides two decision-driven middleware that accept TypeSafeClassifier through classifier=.
These middleware are in beta and require langchain>=1.5.0. The imports from langchain_typesafe.experimental.middleware are deprecated in langchain-typesafe>=0.1.0. Import from langchain.agents.middleware and pass classifier=TypeSafeClassifier() instead.
The examples below use OpenAI models. Install LangChain and the OpenAI integration before using them:

Model routing

Classifies the latest human message across your named models and uses the selected one for every model call in the run. Each ModelChoice pairs a model with the criterion for picking it:

Tool-risk gating

Asks for the probability that a tool call is risky or insufficiently authorized. Calls that are determined risky return an error ToolMessage instead of running the tool. Only the tools you list are classified. Pass their names or tool objects:
Override instructions, or pass criteria=NoulCriteria(true=..., false=...) from langchain_core.decisions, to describe risk for your own tools.
Do not put secrets in tool arguments or conversation state unless sending them to TypeSafe is acceptable. This middleware refuses risky calls. It does not request approval. Pair it with human-in-the-loop middleware when you want a person to approve them.

Custom middleware

TypeSafeClassifier accepts LangChain message objects directly, so a custom middleware hook can classify an agent’s conversation state without converting it first. This example classifies the conversation once at the start of each run and stores the complete ChoiceAnswer in agent state:
Use any lifecycle hook that matches your decision point. For example, use before_model to reclassify after each tool result, or wrap_tool_call to classify a proposed action. See Custom middleware for all hooks and state patterns.

Tracing

TypeSafe classifications are traced in LangSmith, so you can inspect decisions, token usage, and spend alongside the rest of your agent.

See also