Jev Guide: Concepts, SDKs and Learning Path

Jev does not continue or generate prose. It receives state plus bounded questions and returns Choice, Score, or Noul answers that software can read. It fits tasks where the answer space is known, but the raw evidence cannot be resolved with exact if/else rules alone.

A reliable call has five layers. The application shapes evidence and declares questions; Jev returns probabilistic answers; application policy checks schema, thresholds, and risk; only then may ordinary code perform an action. The model never receives authority to refund, delete, or publish.

1. 1
   State

   Keep only evidence that can change this decision, with clear labels, units, and provenance.

2. 2
   Question

   Declare the answer shape and criteria with Choice, Score, or Noul.

3. 3
   Typed answer

   Read the winner, full distribution, or P(true); do not treat the result as prose.

4. 4
   Policy

   Validate option keys, confidence, business risk, and whether review is required.

5. 5
   Action

   Let application code act, and log the question version, model version, and final action.

Assume the input is a customer message. We need to choose a team and detect urgency. Routing is a Choice, urgency is a Noul, and the actual assignment remains an application decision.

{
  "message": "Stripe has failed for three days. Help ASAP.",
  "account_tier": "enterprise"
}

route   → billing | technical | human
urgent  → P(true)
policy  → automate | review

This separation matters: the model answers two small questions and policy combines them. Adding SLA, enterprise, or high-risk rules later does not require hiding business logic inside a long prompt.

The official Python client is typesafe-sdk. Keep the key in a server-side environment variable and begin with a reversible task that is easy to review manually.

from typesafe_sdk import Choice, Noul, TypeSafeClient

questions = {
    "route": Choice(
        instructions="Which team should handle this request?",
        criteria={
            "billing": "Payments or subscriptions",
            "technical": "Bugs or integrations",
            "human": "Ambiguous or sensitive cases",
        },
    ),
    "urgent": Noul(
        instructions="Does this message express urgency?"
    ),
}

with TypeSafeClient() as client:
    result = client.system_one(
        state={
            "message": "Stripe has failed for three days. Help ASAP.",
            "account_tier": "enterprise",
        },
        questions=questions,
    )

route = result.answers["route"]
urgent = result.answers["urgent"]

import math

# Demonstration threshold, not a calibrated production policy.
confidence = route.confidence
valid = (
    route.choice in {"billing", "technical", "human"}
    and isinstance(confidence, (int, float))
    and not isinstance(confidence, bool)
    and math.isfinite(confidence)
    and 0 <= confidence <= 1
)
if not valid or route.choice == "human" or confidence < 0.75:
    print("Human review required")
else:
    print("Suggested team:", route.choice)  # No real ticket is changed.

print(route.probabilities, urgent.noul)

Continue with the focused Python SDK tutorial →

Compare the three question types and result fields before designing your own contract →

LangChain’s official TypeSafe integration exposes TypeSafeClassifier as a Runnable. Both state and questions travel with each invoke call, so the complete request can participate in batching, async execution, callbacks, and tracing.

from math import isfinite
from langchain_typesafe import Choice, Noul, Score, TypeSafeClassifier


def classify_ticket(classifier):
    questions = {
        "route": Choice(instructions="Which team owns this incident?", criteria={
            "technical": "Bugs or integrations", "billing": "Invoices", "human": "Unclear ownership"}),
        "severity": Score(instructions="How blocked are customers?", criteria=[
            "Unaffected", "Workaround available", "Core workflow blocked"]),
        "urgent": Noul(instructions="Does the message describe an ongoing service disruption?"),
    }
    if not questions:
        raise ValueError("At least one question is required")
    response = classifier.invoke({
        "state": {"message": "Checkout fails for every customer.", "scope": "all customers"},
        "questions": questions,
    })
    route = response.choices["route"]
    valid = route.choice in {"technical", "billing", "human"} and isfinite(route.confidence) and 0 <= route.confidence <= 1
    # Teaching threshold only; calibrate with your independently labeled outcomes.
    return {"action": "review" if not valid or route.choice == "human" or route.confidence < 0.75 else "suggest",
            "team": route.choice, "severity": response.scores["severity"].score,
            "urgent_probability": response.nouls["urgent"].noul}


if __name__ == "__main__":
    try:
        print(classify_ticket(TypeSafeClassifier(model="jev-1.13.0", timeout=2)))
    except Exception:
        print({"action": "review", "reason": "provider_or_configuration_failure"})

Continue with the LangChain deep dive: branches, concurrency and offline tests →