> ## Documentation Index
> Fetch the complete documentation index at: https://tracevell.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeSafe AI Jev observability

> Trace every TypeSafe AI Jev call with its state, questions, typed answers, and token usage, all readable in Tracevell's transcript view.

## Overview

Tracevell is an open-source, OpenTelemetry-native observability platform for AI agents. Trace, debug, and monitor every TypeSafe AI Jev call your agent makes, with the state, the questions you asked, the typed answers, and token usage on each span, in both TypeScript and Python.

[Jev](https://typesafe.ai) is TypeSafe AI's System One model. Instead of generating text, it reads your application state and answers typed questions: a yes/no probability (`Noul`), a selected option (`Choice`), or a rubric score (`Score`). Agents use it for routing, guardrails, and scoring, so these are exactly the decisions you want visible in a trace. Tracevell auto-instruments the TypeSafe SDK: initialize Tracevell once and every System One call is traced.

## Getting Started

> [!NOTE]
>
> Jev is in early access: create your key in the [TypeSafe console](https://console.typesafe.ai). No account yet? Use an [OpenRouter](https://tracevell.com/docs/integrations/openrouter.md) API key with `TYPESAFE_BASE_URL=https://openrouter.ai/api` instead.

> [tab] TypeScript
>
> ### 1. Install Tracevell and the TypeSafe SDK
>
> ```bash theme={null}
> npm install @lmnr-ai/lmnr@latest @typesafe-ai/sdk
> ```
>
> ### 2. Set up your environment variables
>
> Store your API keys in a `.env` file:
>
> ```bash theme={null}
> # .env file
> LMNR_PROJECT_API_KEY=your-tracevell-project-api-key
> TYPESAFE_API_KEY=your-typesafe-api-key
> ```
>
> Then load them in your application using a package like [dotenv](https://www.npmjs.com/package/dotenv).
>
> ### 3. Initialize Tracevell
>
> `@typesafe-ai/sdk` is loaded as an ES module in most projects, so pass the client class to `instrumentModules` for Tracevell to patch it:
>
> ```typescript {5-7} theme={null}
> import { Tracevell } from '@lmnr-ai/lmnr';
> import { TypeSafeClient } from '@typesafe-ai/sdk';
> import 'dotenv/config';
>
> Laminar.initialize({
>   instrumentModules: { typesafe: TypeSafeClient },
> });
>
> const client = new TypeSafeClient({ defaultModel: 'jev-1.13.0' });
> ```
>
> ### 4. Use the TypeSafe SDK as usual
>
> ```typescript theme={null}
> import { choice, noul } from '@typesafe-ai/sdk';
>
> const result = await client.systemOne({
>   state:
>     'I was charged twice for my annual plan. Please refund one of the charges.',
>   questions: {
>     wants_refund: noul('Does the customer ask for money back?'),
>     queue: choice('Which team should handle this?', {
>       billing: 'Charges, invoices, refunds',
>       technical: 'Bugs and integration problems',
>       other: null,
>     }),
>   },
> });
>
> console.log(result.answers.wants_refund.noul);
> console.log(result.answers.queue.choice);
> ```
>
> All `systemOne` calls are now traced in Tracevell.

> [tab] Python
>
> ### 1. Install Tracevell and the TypeSafe SDK
>
> ```bash theme={null}
> pip install -U lmnr typesafe-sdk python-dotenv
> ```
>
> ### 2. Set up your environment variables
>
> Store your API keys in a `.env` file:
>
> ```bash theme={null}
> # .env file
> LMNR_PROJECT_API_KEY=your-tracevell-project-api-key
> TYPESAFE_API_KEY=your-typesafe-api-key
> ```
>
> ### 3. Initialize Tracevell
>
> Tracevell instruments the TypeSafe SDK automatically when the `typesafe-sdk` package is installed:
>
> ```python {8} theme={null}
> import os
>
> from dotenv import load_dotenv
> from lmnr import Tracevell
> from typesafe_sdk import TypeSafeClient
>
> load_dotenv()
>
> Laminar.initialize()
>
> client = TypeSafeClient(model="jev-1.13.0")
> ```
>
> ### 4. Use the TypeSafe SDK as usual
>
> ```python theme={null}
> from typesafe_sdk import Choice, Noul
>
> response = client.system_one(
>     state="I was charged twice for my annual plan. Please refund one of the charges.",
>     questions={
>         "wants_refund": Noul(instructions="Does the customer ask for money back?"),
>         "queue": Choice(
>             instructions="Which team should handle this?",
>             criteria={
>                 "billing": "Charges, invoices, refunds",
>                 "technical": "Bugs and integration problems",
>                 "other": None,
>             },
>         ),
>     },
> )
>
> print(response.answers["wants_refund"].noul)
> print(response.answers["queue"].choice)
> ```
>
> All `system_one` calls are now traced in Tracevell, including calls made with `AsyncTypeSafeClient`.

## What Tracevell captures

Each call becomes an LLM span named `typesafe.system_one`. Every span carries:

* The model that answered (`jev-1.13.0`, or the resolved default when you rely on `jev-latest`).
* The state you sent, shown as the span input.
* The full question set: instructions and criteria for every `Noul`, `Choice`, and `Score`.
* The typed answers, shown as the span output, with probabilities and confidence intact.
* Input and output token counts.

Failed calls (an unknown model name, an authentication error) are marked as errors on the span with the exception recorded, so a misconfigured guardrail shows up in the trace instead of disappearing into a retry loop.

![TypeSafe AI Jev trace in Tracevell with typed answers on the system\_one span](https://mintcdn.com/laminarai/JwW09UOUbkdN25Yz/images/integrations/typesafe-trace-view.png?fit=max\&auto=format\&n=JwW09UOUbkdN25Yz\&q=85\&s=eb8859c745e96d215769e9d55794ff4e)

A support agent trace: the selected Jev span carries the typed answers, with the chosen queue, urgency probability, and rubric score on the span output and the question set in the output schema. The drafted reply and a second Jev verification call sit inline in the same trace.

## See what happened in a trace

Open a trace in Tracevell and you land on the transcript view: Tracevell extracts the agent input, the model's turns, and any tool calls into a conversation, so you read what happened instead of clicking through a tree of span names. A Jev call sits inline with the LLM calls it routes or guards, so you can see the classification next to the action it triggered.

More on the trace UX: [Viewing traces](https://tracevell.com/docs/platform/viewing-traces.md).

## Track outcomes with Signals

Traces answer *what happened on this run*. **[Signals](https://tracevell.com/docs/signals/introduction.md) answer the cross-trace question**: *how often does the guardrail fire, which queue gets the most tickets, when does confidence drop below the threshold you tuned for*. A Signal pairs a plain-language instruction with a JSON output schema. Tracevell runs it live on new traces (Triggers) or backfills it across history (Jobs) and records a structured event every time it matches. From there you [query](https://tracevell.com/docs/platform/sql-editor.md), [cluster](https://tracevell.com/docs/signals/clusters.md), and [alert](https://tracevell.com/docs/signals/alerts.md) on events across every trace.

## Query across traces

* **[SQL editor](https://tracevell.com/docs/platform/sql-editor.md)** for ad-hoc queries across traces, spans, signals, and evals.
* **SQL API** for programmatic access from scripts and pipelines.
* **[CLI](https://tracevell.com/docs/platform/cli.md)** (`lmnr-cli sql query`) for terminal-driven queries and piping JSON into shell tools or coding agents.
* **[MCP server](https://tracevell.com/docs/platform/mcp.md)** to query Tracevell directly from Claude Code, Cursor, Codex, or any MCP-aware client.

## Enrich your TypeSafe traces

* Attach sessions, user IDs, metadata, and tags to TypeSafe spans via the [SDK reference](https://tracevell.com/docs/sdk/reference).
* Wrap the functions around your Jev calls with `observe` and mark them as [TOOL spans](https://tracevell.com/docs/tracing/structure/span-types.md) so they show up in the transcript.
* Set `LMNR_TRACE_CONTENT=false` to keep the model and token counts while omitting state, questions, and answers from spans.

## What's next

> [card] [Viewing traces](https://tracevell.com/docs/platform/viewing-traces.md)
>
> Read the transcript view, filter, and search across traces.

> [card] [Signals](https://tracevell.com/docs/signals/introduction.md)
>
> Detect behaviors and failures across every run, then query, cluster, and alert on them.

> [card] [SQL editor and MCP server](https://tracevell.com/docs/platform/sql-editor.md)
>
> Query traces programmatically from the UI, API, or your IDE.

> [card] [Tracing structure](https://tracevell.com/docs/tracing/structure/overview.md)
>
> Add sessions, metadata, and tags, and group calls under your own spans.

## Related integrations

> [card] [OpenAI](https://tracevell.com/docs/integrations/openai.md)
>
> Trace the OpenAI SDK directly in TypeScript and Python.

> [card] [Anthropic](https://tracevell.com/docs/integrations/anthropic.md)
>
> Trace the Anthropic SDK directly in TypeScript and Python.

> [card] [LiteLLM](https://tracevell.com/docs/integrations/litellm.md)
>
> One integration for every model LiteLLM routes to.

> [card] [OpenRouter](https://tracevell.com/docs/integrations/openrouter.md)
>
> Trace any model called through OpenRouter, Jev included.

> [card] [Gemini](https://tracevell.com/docs/integrations/gemini.md)
>
> Trace Gemini calls made with the Google Gen AI SDK.

> [card] [All integrations](https://tracevell.com/docs/integrations.md)
>
> Browse every provider, framework, coding agent, and browser integration Tracevell supports.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.