Build AI apps that are cheap, fast & reliable

00Quick start: the 10-minute checklist

Follow this in order. Every step was run and checked on a real Mac while writing this guide.

• Sign up at console.typesafe.ai (Google or email).
• Create an API key at console.typesafe.ai/keys.
• Save the key permanently so every new terminal has it:

  echo 'export TYPESAFE_API_KEY="paste-your-key-here"' >> ~/.zshrc
  source ~/.zshrc

• Make your first call with curl (no install needed): bash examples/first_call.sh
• Create a Python virtual environment and install the SDK:

  cd ~/typesafe-easy-guide
  python3 -m venv .venv
  source .venv/bin/activate
  pip install typesafe-sdk

• Run the full example: python examples/support_triage.py
• Optional, for Claude Code users: install the agent skill (see section 5).
• Optional, only when your app must write text: add a Groq key (see section 11).

01The 30-second idea

02How Jev works

What happens between sending a request and getting numbers back.

The request and response, field by field

// REQUEST
{
  "model": "jev-latest",          // alias → jev-1.13.0
  "state": "Hi, I've been trying to
    connect my Stripe account for 3
    days ... Please help ASAP.",
  "questions": {
    "is_urgent": {                // your ID
      "type": "noul",
      "instructions": "The message conveys
        urgency or time-sensitivity"
    },
    "department": {
      "type": "choice",
      "instructions": "Which team should
        handle this",
      "criteria": {
        "billing":   "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales":     "Pricing or account questions"
      }
    }
  }
}

// RESPONSE (a real run, Sept 2026)
{
  "model": "jev-1.13.0",          // exact version
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.99                // P(yes)
    },
    "department": {
      "type": "choice",
      "choice": "technical",      // top option
      "confidence": 0.78,         // how peaked
      "probabilities": {
        "technical": 0.85,
        "billing":   0.15,
        "sales":     0.0
      }
    }
  },
  "usage": {
    "input_tokens": 376,          // billed
    "output_tokens": 57           // free
  }
}

Model facts (jev-1.13, as of Sept 2026)

03The 3 tools you'll use

Every Jev question is one of these three types. That's all there is to learn.

Writing good questions

04Confidence: how sure is Jev?

Thresholds should scale with risk

action = r.choices["action"]
if action.confidence < 0.5:
    route_to_human(msg)                   # genuinely unsure: don't guess
elif action.choice == "check_balance":
    show_balance()                        # low stakes, easy to undo
elif action.choice == "approve_transfer":
    if action.confidence > 0.9:
        confirm_then_execute()            # high stakes needs high confidence
    else:
        ask_user_to_confirm()

05How /typesafe:typesafe-ai works

The Claude Code skill that makes Claude an expert TypeSafe builder.

Install it (Claude Code)

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

# later, to update:
claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai      # then restart or run /reload-plugins

Using another agent (Codex, Cursor…)? Run npx skills add typesafe-ai/skills --skill typesafe-ai and say "use the TypeSafe skill" in your prompt.

Prompts that work well

06Step by step: your first app

We'll build a support-ticket sorter: it reads a customer message and decides the team, the urgency, and whether to flag a refund.

1. Sign up

   Go to console.typesafe.ai and continue with Google or email.

   

2. Play first, with no code

   Open the Playground. Paste a message as the state:

   Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.

   Add a noul question: Does this message express urgency?. Then add a Choice and a Score and watch all the answers come back together.

   🎯 Reword your questions here until the answers look right. It's the cheapest place to experiment.

3. Get an API key and save it permanently

   Dashboard → Keys. Adding it to ~/.zshrc means every new terminal has it:

   echo 'export TYPESAFE_API_KEY="paste-your-key-here"' >> ~/.zshrc
   source ~/.zshrc
   
   # check it's set (prints the length, not the key)
   [ -n "$TYPESAFE_API_KEY" ] && echo "key set (${#TYPESAFE_API_KEY} chars)" || echo "key NOT set"

   🔒 Never put the key in website or mobile frontend code. Call TypeSafe from your server.

4. Install the SDK in a virtual environment

   On a Mac with Homebrew Python, a plain pip install is usually blocked with externally-managed-environment. A virtual environment (.venv) is the clean fix: it's a private box for this project's packages.

   cd ~/typesafe-easy-guide
   python3 -m venv .venv            # create the box (Python 3.10+)
   source .venv/bin/activate        # step into it: prompt shows (.venv)
   pip install typesafe-sdk         # install inside the box
   python -c "import typesafe_sdk; print('ok')"
   
   # JavaScript / TypeScript instead (Node 20+):
   npm install @typesafe-ai/sdk

   🔁 Run source .venv/bin/activate again in each new terminal before running Python examples. Python 3.13+ also puts a .gitignore inside .venv, so it never gets committed.

5. Ask everything in ONE call

   from typesafe_sdk import Choice, Noul, Score, TypeSafeClient
   
   with TypeSafeClient() as client:          # reads TYPESAFE_API_KEY
       r = client.system_one(
           state={"ticket": TICKET},
           questions={
               "team": Choice(
                   instructions="Which team should handle this ticket?",
                   criteria={
                       "billing":   "Payment or subscription issues",
                       "technical": "Bugs or integration problems",
                       "sales":     "Pricing or account questions",
                       "other":     "None of the above",
                   },
               ),
               "urgent": Noul(instructions="The message conveys urgency or time-sensitivity."),
               "refund": Noul(instructions="The customer asks for a refund."),
               "frustration": Score(
                   instructions="How frustrated does the customer appear?",
                   criteria=["Calm, just stating facts",
                             "Frustrated but civil",
                             "Very angry, strong language"],
               ),
           },
           model="jev-latest",
       )

6. Let code make the decision

   team = r.choices["team"]
   urgent = r.nouls["urgent"].noul
   frustration = r.scores["frustration"].score
   
   queue = team.choice if team.confidence >= 0.5 else "human-review"
   priority = "P1" if urgent > 0.8 or frustration >= 1.5 else "P2"
   refund_flag = r.nouls["refund"].noul > 0.7

   The AI provides the evidence (numbers), and your code sets the rules. You can change a rule at any time without paying for new AI calls. Full example: examples/support_triage.py.

7. Test, tune, ship

   Run 20–50 real messages. Where it's wrong, reword the question or make the option descriptions clearer. Pick thresholds from your results, not guesses. Log the model field from each response so you know which version produced each answer.

Troubleshooting

07A real session, start to finish

This is what setting up with /typesafe:typesafe-ai in Claude Code actually looked like. The outputs below are real.

① "Run the first-call script"

Claude read the script first, checked that the key was set without printing it, then ran it:

$ [ -n "$TYPESAFE_API_KEY" ] && echo "key set (len ${#TYPESAFE_API_KEY})"
key set (len 108)
$ bash examples/first_call.sh | jq .
{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent":  { "type": "noul", "noul": 0.99 },
    "department": { "type": "choice", "choice": "technical", "confidence": 0.78,
                    "probabilities": { "sales": 0.0, "technical": 0.85, "billing": 0.15 } }
  },
  "usage": { "input_tokens": 376, "output_tokens": 57 }
}
# 376 billed tokens × $0.042/1M ≈ $0.0000158 for this call

How to read it: urgency is almost certain. The ticket goes to technical, with a small billing share because Stripe is a payments service. Confidence (0.78) is lower than the top probability (0.85) because it measures how peaked the whole distribution is.

② "Is any other key missing?"

Claude searched the guide for every *_KEY reference (there's only TYPESAFE_API_KEY) and checked the machine:

$ python3 --version
Python 3.14.6                                   # ✓ needs 3.10+
$ python3 -c "import typesafe_sdk"
ModuleNotFoundError: No module named 'typesafe_sdk'   # ✗ SDK missing
$ grep -l TYPESAFE_API_KEY ~/.zshrc
/Users/you/.zshrc                               # ✓ key saved permanently

Only the SDK was missing, so Claude gave the venv steps from section 6.

③ "I did all, please check"

$ .venv/bin/pip show typesafe-sdk | grep Version
Version: 0.7.1                                  # ✓
$ .venv/bin/python examples/support_triage.py
queue=technical priority=P1 refund_flag=False
raw: team=technical (0.86) urgent=0.98 refund=0.02 frustration=1.00

④ "Do I need Claude API keys too?"

No. The TypeSafe examples only call TypeSafe, and Claude Code uses your Claude login. An LLM key is only needed if your app must write text. Here the plan is Groq's free tier, which fits the "big LLM" slot (see section 11).

08How it saves money and tokens

Where the savings come from, with the maths.

The six token levers

Real numbers from this guide's own run

09Try it: cost calculator

Change the numbers and see why batching and Jev matter. The defaults reproduce TypeSafe's GDPR cookbook (≈11k-token document, 13 questions).

10The 7 golden rules for low cost + high speed

Rule 2 as a flowchart: which tool for which job?

Rule 4 as a picture: cheap first, expensive only if needed

11Where Groq (or any big LLM) fits

Jev never writes text. When your app needs a written reply, a summary or deep reasoning, call an LLM, but only for the cases that need it.

Set up Groq (only when you need it)

# 1. Create a key at https://console.groq.com/keys, then save it:
echo 'export GROQ_API_KEY="paste-key-here"' >> ~/.zshrc
source ~/.zshrc

# 2. Install the SDK in the same venv
cd ~/typesafe-easy-guide && source .venv/bin/activate
pip install groq

Template: Jev triages, Groq writes only when needed

from groq import Groq
from typesafe_sdk import Choice, Noul, TypeSafeClient

with TypeSafeClient() as ts:
    r = ts.system_one(
        state={"ticket": TICKET},
        questions={
            "team": Choice(instructions="Which team should handle this ticket?",
                           criteria={"billing": "Payment issues", "technical": "Bugs or integrations",
                                     "other": "None of the above"}),
            "needs_reply": Noul(instructions="The customer asks a question that needs a written answer."),
        },
        model="jev-latest",
    )

if r.nouls["needs_reply"].noul > 0.7:          # most tickets skip the LLM entirely
    groq = Groq()                                # reads GROQ_API_KEY
    draft = groq.chat.completions.create(
        model="llama-3.3-70b-versatile",         # pick a current model at console.groq.com
        messages=[
            {"role": "system", "content": f"You are a {r.choices['team'].choice} support agent. Reply briefly and kindly."},
            {"role": "user", "content": TICKET},
        ],
    ).choices[0].message.content
    print(draft)

12Known limits: where Jev stumbles, and the fix

From TypeSafe's own "Jev 1.13 jaggedness" page. Knowing these up front saves hours.

Full details: docs.typesafe.ai/model-jaggedness/jev-1.13

13The "optimal" app blueprint

14Real app ideas

All recipes: docs.typesafe.ai/cookbooks. With the skill installed, try /typesafe:typesafe-ai build the review analyzer idea in ~/development.

15Mistakes to avoid

16FAQ

17Cheat sheet

KEYS    TYPESAFE_API_KEY required · Claude key not needed · GROQ_API_KEY optional
SETUP   ~/.zshrc for keys · python3 -m venv .venv · pip install typesafe-sdk
SKILL   /typesafe:typesafe-ai <what you want>   (reads live docs, then builds)

CODE  does steps & rules        → $0
JEV   makes quick judgments     → $0.042 per 1M input tokens, output free, ~100 ms
LLM   writes / reasons deeply   → $$$ or rate-limited free tier, use rarely

Choice → pick one (+ probabilities, confidence)   · add "other"
Noul   → P(yes) 0..1                              · 0.5 = can't tell
Score  → position on 2-10 levels (+ confidence)   · levels describe concrete situations

1 call, many questions    → pay for your data once (≈N× cheaper)
Pick, don't generate      → cheaper + no made-up values
Cheap → check → escalate  → big-model quality, less $
Save raw scores           → change rules for free
Low confidence            → human / bigger model
Maths, dates, counting    → always in code

🔗 Docs · Docs index (llms.txt) · Console & Playground · Models & pricing · Agent skill · Batching proof · Cascade recipe · This guide on GitHub