Jev：为软件而生的
结构化决策模型

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.

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<'EOF'
  {
    "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.",
    "model": "jev-latest",
    "questions": {
      "urgency": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }
EOF

{
  "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.",
  "model": "jev-latest",
  "questions": {
    "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"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": { "technical": 0.85, "sales": 0.0, "billing": 0.15 }
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "confidence": 1.0,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language"
      },
      "probabilities": { "0": 0.0, "1": 1.0, "2": 0.0 }
    },
    "is_urgent": { "type": "noul", "noul": 1.0 }
  },
  "usage": { "input_tokens": 392, "output_tokens": 65 }
}

pip install typesafe-sdk      # 要求 Python >= 3.10
# 或
uv add typesafe-sdk

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()   # 读取环境变量 TYPESAFE_API_KEY，默认模型 jev-latest

ticket = "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."

response = client.system_one(
    state=ticket,
    questions={
        "department": Choice(
            instructions="Which team should handle this",
            criteria={
                "billing": "Payment or subscription issues",
                "technical": "Bugs or integration problems",
                "sales": "Pricing or account questions",
            },
        ),
        "frustration": Score(
            instructions="How frustrated the customer appears",
            criteria=[
                "Calm, just stating facts",
                "Frustrated but civil",
                "Very angry, strong language",
            ],
        ),
        "is_urgent": Noul(
            instructions="The message conveys urgency or time-sensitivity",
        ),
    },
)

print(response.answers["department"].choice)   # "technical"
print(response.answers["frustration"].score)   # 1.0
print(response.answers["is_urgent"].noul)      # 1.0

# Claude Code
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

# 其他智能体（交互式选择）
npx skills add typesafe-ai/skills --skill typesafe-ai      # 加 -g 全局安装

Let's build a simple CLI that uses the TypeSafe API to evaluate a set of supplied
documents on multiple dimensions. Use the TypeSafe skill to understand how to use the
TypeSafe API and how to structure the system. Ask me questions about what kinds of
documents I want to evaluate and on what dimensions.

{
  "ticket": {
    "subject": "Duplicate charge",
    "messages": [
      {"from": "customer", "text": "I was charged twice for order A-104. Please refund the duplicate."},
      {"from": "support",  "text": "We are checking the charges."}
    ]
  },
  "order": {
    "id": "A-104",
    "charges": [
      {"amount_usd": 49, "status": "captured"},
      {"amount_usd": 49, "status": "captured"}
    ]
  },
  "refund_policy": "Duplicate charges are eligible for a refund."
}

questions = {
    "refund_requested": {
        "type": "noul",
        "instructions": "Does `ticket.messages[0].text` request a refund?",
    },
    "policy_supports_refund": {
        "type": "noul",
        "instructions": (
            "Does `refund_policy` support the refund requested "
            "in `ticket.messages[0].text`, given `order.charges`?"
        ),
    },
}

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

state = {
    "ticket_message": "My flight was cancelled. Can I get a refund?",
    "refund_policy": "Cancelled flights are eligible for a full refund.",
}

with TypeSafeClient() as client:
    response = client.system_one(
        state=state,
        questions={
            "refund_requested": Noul(
                instructions="Does `ticket_message` request a refund?",
            ),
            "request_type": Choice(
                instructions="What is the main request in `ticket_message`?",
                criteria={
                    "refund": "The customer wants money returned.",
                    "rebooking": "The customer wants a replacement flight.",
                    "information": "The customer is asking for information only.",
                },
            ),
            "frustration": Score(
                instructions="How frustrated does the customer appear in `ticket_message`?",
                criteria=[
                    "Calm and neutral.",
                    "Concerned but civil.",
                    "Very angry or using strong language.",
                ],
            ),
        },
    )

print(response.answers["refund_requested"].noul)
print(response.answers["request_type"].choice)
print(response.answers["frustration"].score)

response = client.system_one(
    state=user_message,
    questions={
        "action": Choice(
            instructions="What is the user trying to do?",
            criteria={
                "check_balance": "View account balance",
                "approve_transfer": "Approve the pending withdrawal request",
                "support": "Get help with an issue",
            },
        ),
    },
)

action = response.answers["action"]
confidence = action.confidence

if confidence < 0.5:
    # 模型真的不确定，不要猜
    route_to_human(user_message)

elif action.choice == "check_balance":
    # 低风险：显示错页面是可以恢复的
    show_balance(account_id)

elif action.choice == "approve_transfer":
    if confidence > 0.9:
        # 高风险 + 高置信度：确认后执行
        confirm_then_execute(account_id)
    else:
        # 高风险 + 中等置信度：先验证
        ask_user_to_confirm(account_id)

"What programming language is this code written in"
  → options: python, javascript, typescript, go, rust, other

"What type of meeting is this based on the title and description"
  → options: standup, planning, retrospective, one on one, brainstorm, none of the above

"Which product category does this item belong to"
  → options: electronics, clothing, home garden, food and beverage

from typesafe_sdk import Choice, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="My running shoes arrived in the wrong size. Can I swap them for a size 10?",
        questions={
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={
                    "returns": "Exchanges, wrong or damaged items",
                    "shipping": "Delivery status, delays, lost packages",
                    "billing": "Charges, invoices, payment problems",
                },
            ),
        },
    )

    print(response.answers["department"].choice)   # "returns"

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice", "choice": "returns", "confidence": 0.42,
      "probabilities": { "shipping": 0.04, "billing": 0.35, "returns": 0.61 }
    },
    "return_reason": {
      "type": "choice", "choice": "wrong_size", "confidence": 1.0,
      "probabilities": { "other": 0.0, "wrong_size": 1.0, "changed_mind": 0.0, "damaged": 0.0, "wrong_item": 0.0 }
    },
    "shipping_issue": {
      "type": "choice", "choice": "delayed", "confidence": 0.67,
      "probabilities": { "wrong_address": 0.0, "other": 0.26, "not_delivered": 0.0, "damaged_in_transit": 0.0, "delayed": 0.74 }
    },
    "requested_resolution": {
      "type": "choice", "choice": "refund", "confidence": 0.2,
      "probabilities": { "replacement": 0.34, "refund": 0.4, "information": 0.02, "exchange": 0.24 }
    },
    "tone": {
      "type": "choice", "choice": "frustrated", "confidence": 0.76,
      "probabilities": { "frustrated": 0.84, "angry": 0.16, "calm": 0.0 }
    }
  },
  "usage": { "input_tokens": 589, "output_tokens": 212 }
}

def triage(ticket: str) -> None:
    with TypeSafeClient() as client:
        response = client.system_one(state=ticket, questions=TRIAGE_QUESTIONS)
    answers = response.answers

    department = answers["department"]
    if department.confidence < 0.3:
        # 不清楚给哪个团队，让人决定
        send_to_manual_triage(ticket)
        return

    if department.choice == "returns":
        # return_reason 的答案只在这里使用
        assign(ticket, team="returns", issue=answers["return_reason"].choice)
    elif department.choice == "shipping":
        assign(ticket, team="shipping", issue=answers["shipping_issue"].choice)
    else:
        assign(ticket, team="billing")

    # 概率占比真实的第二个团队也收到副本
    for team, probability in department.probabilities.items():
        if team != department.choice and probability > 0.25:
            notify(ticket, team=team)

    resolution = answers["requested_resolution"]
    if resolution.confidence < 0.5:
        # 客户没说要什么。去问，不要猜。
        ask_customer_what_they_want(ticket)
    elif resolution.choice == "refund":
        flag_for_refund_approval(ticket)

    if answers["tone"].choice == "angry":
        flag_for_senior_agent(ticket)

from typesafe_sdk import Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="The export button crashes the settings page in Safari. It works in Chrome, but a few of our customers only use Safari.",
        questions={
            "bug_severity": Score(
                instructions="How severe is the reported issue?",
                criteria=[
                    "Cosmetic; no impact to functionality",
                    "Broken or degraded feature, but workaround exists",
                    "Blocking issue; no workaround exists",
                ],
            ),
        },
    )

    print(response.answers["bug_severity"].score)   # 1.43

{
  "model": "jev-1.13.0",
  "answers": {
    "bug_severity": {
      "type": "score",
      "score": 1.43,
      "confidence": 0.35,
      "legend": {
        "0": "Cosmetic; no impact to functionality",
        "1": "Broken or degraded feature, but workaround exists",
        "2": "Blocking issue; no workaround exists"
      },
      "probabilities": { "0": 0.0, "1": 0.57, "2": 0.43 }
    }
  },
  "usage": { "input_tokens": 332, "output_tokens": 18 }
}

def normalized(answers, question_id: str) -> float:
    """把 score 除以最高等级编号，压到 0–1。"""
    top_level = len(TRIAGE_QUESTIONS[question_id].criteria) - 1
    return answers[question_id].score / top_level


def priority(ticket: str) -> float:
    with TypeSafeClient() as client:
        response = client.system_one(state=ticket, questions=TRIAGE_QUESTIONS)
    answers = response.answers

    severity       = normalized(answers, "severity")         # 0.62
    frustration    = normalized(answers, "frustration")      # 0.64
    report_quality = normalized(answers, "report_quality")   # 1.00

    # 详细的复现步骤有助于工程师排查，因此略微提升优先级
    return 0.6 * severity + 0.3 * frustration + 0.1 * report_quality
    # → 0.6 × 0.62 + 0.3 × 0.64 + 0.1 × 1.0 = 0.664

"criteria": [
  { "what": "Cosmetic; no impact to functionality",
    "examples": ["typo in a label", "misaligned icon"] },
  { "what": "Broken or degraded feature, but workaround exists",
    "examples": ["export fails in one browser but works in another"] },
  { "what": "Blocking issue; no workaround exists",
    "examples": ["cannot log in", "data loss"] }
]

from typesafe_sdk import Noul, NoulCriteria, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        model="jev-latest",
        state="I have asked three times now. Can I please just talk to a real person?",
        questions={
            "is_human_escalation": Noul(
                instructions="Is the customer asking for a human agent?",
            ),
            "is_repeat_contact": Noul(
                instructions="Has the customer contacted support about this before?",
                criteria=NoulCriteria(
                    true="Mentions a prior attempt, ticket, or that they have asked before",
                    false="No sign of any previous contact",
                ),
            ),
        },
    )

    print(response.answers["is_human_escalation"].noul)   # 0.99
    print(response.answers["is_repeat_contact"].noul)     # 0.93

YES = 0.8
NO  = 0.2

def route(message: str) -> None:
    with TypeSafeClient() as client:
        response = client.system_one(
            model="jev-latest", state=message, questions=SUPPORT_QUESTIONS
        )
    answers = response.answers

    wants_human = answers["is_human_escalation"].noul
    repeat      = answers["is_repeat_contact"].noul

    if NO < wants_human < YES or NO < repeat < YES:
        # 模型两边都不确定，让人决定
        send_to_review(message)
        return

    priority = "high" if repeat > YES else "normal"
    if wants_human > YES:
        route_to_agent(message, priority=priority)
    else:
        route_to_bot(message, priority=priority)

SAME_PERSON = "Is the resume for the same person as `potential_duplicate`?"

def duplicate_questions(candidates: list[dict]) -> dict[str, Noul]:
    """每个候选库记录一个 Noul，问同一个问题，全部打包进一次请求。"""
    return {
        f"same_as_record_{candidate['id']}": Noul(
            instructions={
                "potential_duplicate": {
                    "name": candidate["name"],
                    "location": candidate["location"],
                    "last_employer": candidate["last_employer"],
                },
                "question": SAME_PERSON,
            },
        )
        for candidate in candidates
    }

{
  "return_topic": {
    "type": "choice",
    "instructions": "What is this ticket about?",
    "criteria": {
      "return_policy": {
        "what": "Asks how returns work: the window, condition rules, who pays shipping",
        "not_for": "A question about the state of an already-opened return",
        "examples": ["What is your return window?", "Do I pay return shipping?"]
      },
      "return_status": {
        "what": "Asks about a specific in-flight return: where it is, when refund lands",
        "not_for": "General questions about how the policy works",
        "examples": ["Where is my return?", "When will my refund arrive?"]
      }
    }
  }
}

"instructions": {
  "question": "Does the claimed sender identity conflict with the sending domain?",
  "compare": ["ticket.sender.display_name", "ticket.sender.email"],
  "focus": "Compare the named organization with the email domain."
}

category     = response.answers["category"]
bug_severity = response.answers["bug_severity"]
bug_repro    = response.answers["has_reproducible_steps"]
refund       = response.answers["refund_requested"]
frustration  = response.answers["frustration"]

if category.choice == "bug_report":
    if bug_severity.score > 1.5 and bug_repro.noul > 0.6:
        escalate_to_engineering(ticket_id, severity="high")
    else:
        add_to_bug_backlog(ticket_id)

elif category.choice == "billing":
    if refund.noul > 0.7:
        route_to_billing_with_flag(ticket_id, refund_likely=True)
    else:
        route_to_billing(ticket_id)

elif category.choice == "feature_request":
    log_feature_request(ticket_id)

# Frustration 与分类无关，始终有用
if frustration.score > 1.5:
    flag_for_priority_response(ticket_id)

action = response.answers["intent"]

# 任何动作的置信度低于 0.6 → 转人工
if action.confidence < 0.6:
    route_to_support_agent(account_id)

elif action.choice == "check_balance":
    # 低风险：0.6 足够
    show_balance(account_id)

elif action.choice == "approve_transfer":
    if action.confidence > 0.85:
        # 高风险但高置信度：自动执行
        approve_transfer(account_id)
    else:
        # 高风险 + 中等置信度：先和用户确认
        ask_user_to_confirm("Just to confirm: you would like to approve this transfer, is that correct?")

else:
    route_to_support_agent(account_id)

py      = response.answers["python_depth"].score / 4
lead    = response.answers["team_leadership"].score / 4
arch    = response.answers["system_design"].score / 4
general = response.answers["generalist"].score / 4

# Senior IC 权重
ic_score = (0.40 * py) + (0.10 * lead) + (0.40 * arch) + (0.10 * general)

# Engineering Manager 权重
em_score = (0.15 * py) + (0.40 * lead) + (0.20 * arch) + (0.25 * general)

def route_ticket(ticket_id, response):
    intent     = response.answers["intent"]
    complexity = response.answers["complexity"]

    if intent.confidence < 0.5:
        # 连分类都没有足够把握 → 转人工
        return route_to_human_agent(ticket_id)

    if intent.choice == "order_status":
        handle_order_status(ticket_id)                        # 确定性代码，不碰 LLM

    elif intent.choice == "product_question":
        handle_with_llm(ticket_id, PRODUCT_SPECIALIST)

    elif intent.choice == "return_exchange":
        handle_with_llm(ticket_id, RETURNS_SPECIALIST)

    elif intent.choice == "complaint":
        low_confidence = complexity.confidence < 0.5
        # complexity.score 越高越倾向于「需要升级」
        if complexity.score > 1 or low_confidence:
            # 太复杂不适合安全自动化，或我们对复杂度也没把握 → 给人
            route_to_human_agent(ticket_id)
        else:
            handle_with_llm(ticket_id, COMPLAINT_RESOLUTION)

from typesafe_sdk import Choice, Noul, NoulCriteria, Score, TypeSafeClient


def triage_ticket(ticket, customer):
    # 1) 确定性状态不调用模型
    if ticket["status"] == "closed":
        return "no_action"

    open_orders = [
        order for order in customer["orders"] if order["status"] != "delivered"
    ]

    # 2) 只带上问题需要的结构化上下文
    state = {
        "ticket": {"message": ticket["message"], "sender": ticket["sender"], "links": ticket["links"]},
        "customer": {"plan": customer["plan"], "open_orders": open_orders},
        "policy": {"sensitive_credentials": ["password", "security code", "API key"]},
    }

    # 3) 结构化 + 原子问题，一次性并行
    questions = {
        "topic": Choice(
            instructions={
                "question": "Which team should handle `ticket.message`?",
                "focus": "Classify the customer's primary request.",
            },
            criteria={
                "billing": {
                    "what": "Charges, invoices, refunds, or subscriptions",
                    "not_for": "Order tracking or account access",
                    "examples": ["I was charged twice", "Where is my refund?"],
                },
                "orders": {
                    "what": "Order status, delivery, cancellation, or returns",
                    "not_for": "Charges or account access",
                    "examples": ["Where is my order?", "Cancel my shipment"],
                },
                "account": {
                    "what": "Login, profile, permissions, or security",
                    "not_for": "Charges or order tracking",
                    "examples": ["Reset my password", "I cannot sign in"],
                },
            },
        ),
        "requests_credentials": Noul(
            instructions={
                "question": "Does the message request a sensitive credential?",
                "compare": ["`ticket.message`", "`policy.sensitive_credentials`"],
                "focus": "Look for a request to disclose the credential itself.",
            },
            criteria=NoulCriteria(
                true={"what": "Asks the recipient to disclose a listed credential",
                      "examples": ["Reply with your password", "Send us your API key"]},
                false={"what": "Does not ask the recipient to disclose a credential",
                       "not_for": "A legitimate instruction to reset a credential",
                       "examples": ["Use this link to reset your password"]},
            ),
        ),
        "sender_identity_mismatch": Noul(
            instructions={
                "question": "Does the claimed sender identity conflict with its domain?",
                "compare": ["`ticket.sender.display_name`", "`ticket.sender.email`"],
                "focus": "Compare the named organization with the email domain.",
            },
            criteria=NoulCriteria(
                true={"what": "Claims an organization unrelated to the email domain",
                      "examples": ["Acme Payroll sent from claim-bonus.example"]},
                false={"what": "The identity and domain agree or make no conflicting claim",
                       "examples": ["Acme Payroll sent from acme.example"]},
            ),
        ),
        "unexpected_reward": Noul(
            instructions={
                "question": "Does the message announce an unexpected reward?",
                "inspect": "`ticket.message`",
                "focus": "Look for an unsolicited prize, payment, or reward claim.",
            },
            criteria=NoulCriteria(
                true={"what": "Announces an unrequested prize, payment, or reward",
                      "examples": ["You were selected for a $1,000 bonus"]},
                false={"what": "Contains no reward claim or discusses an expected payment",
                       "not_for": "A customer asking about a known refund or payroll deposit",
                       "examples": ["When will my approved refund arrive?"]},
            ),
        ),
        "frustration": Score(
            instructions={
                "question": "How frustrated does the customer appear?",
                "inspect": "`ticket.message`",
                "focus": "Judge expressed frustration, not issue severity.",
            },
            criteria=[
                {"what": "Calm and matter-of-fact",
                 "signals": ["Neutral wording", "No complaint about the experience"]},
                {"what": "Frustrated but civil",
                 "signals": ["Expresses annoyance", "Remains constructive"]},
                {"what": "Very angry or threatening to leave",
                 "signals": ["Hostile language", "Threatens cancellation or churn"]},
            ],
        ),
    }

    with TypeSafeClient() as client:
        response = client.system_one(state=state, questions=questions)

    answers = response.answers

    # 4) 加权组合 —— 权重由代码掌控
    spam_risk = (
        0.45 * answers["requests_credentials"].noul
        + 0.30 * answers["sender_identity_mismatch"].noul
        + 0.25 * answers["unexpected_reward"].noul
    )

    # 5) 不确定的判断升级，而不是硬猜
    spam_is_uncertain = 0.4 < spam_risk < 0.6
    if spam_is_uncertain or answers["topic"].confidence < 0.75:
        return route_to_human_review(ticket)
    if spam_risk >= 0.6:
        return quarantine_as_spam(ticket)

    # 6) 投机答案只在对应路径上使用
    if answers["topic"].choice == "billing":
        return route_to_billing(ticket, refund_requested=answers["refund_requested"].noul >= 0.7)
    if answers["topic"].choice == "orders":
        return route_to_orders(ticket, mentions_open_order=answers["mentions_open_order"].noul >= 0.7)

    priority = (
        "high"
        if answers["frustration"].confidence >= 0.7 and answers["frustration"].score >= 1.5
        else "normal"
    )
    return route_to_account_support(ticket, priority=priority)

from typesafe_sdk import Noul, TypeSafeClient

client = TypeSafeClient(model="jev-1.13")
YES = 0.5  # 阈值视你的场景而定

items = ["typesafe", "apple", "california", "banana", "likes", "calibration", "orange", "vertex"]

result = client.system_one(
    {"items": items},
    {
        f"item_{i}": Noul(instructions=f"Is `items[{i}]` the name of a fruit?")
        for i in range(len(items))
    },
)

count = sum(result.nouls[f"item_{i}"].noul > YES for i in range(len(items)))

curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

from typesafe_sdk import TypeSafeClient

with TypeSafeClient() as client:
    for model in client.models.list().models:
        print(model.name, model.release_date, model.description)

import { TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();
const models = await client.models.list();
for (const model of models) {
  console.log(model.name, model.release_date, model.description);
}

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer <API_KEY>
Content-Type: application/json

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

uv add typesafe-sdk
# 或
pip install typesafe-sdk

from typesafe_sdk import AsyncTypeSafeClient, Choice, Noul, Score

async def main() -> None:
    async with AsyncTypeSafeClient() as client:
        response = await client.system_one(
            state={"document": "I was charged twice. Please fix this ASAP."},
            questions={
                "billing": Noul(instructions="Is this ticket about billing?"),
                "tone": Choice(
                    instructions="What is the customer's tone?",
                    criteria={"calm": None, "frustrated": None, "angry": None},
                ),
                "urgency": Score(
                    instructions="How urgent is this ticket?",
                    criteria=["can wait", "this week", "today"],
                ),
            },
        )

    print(response.nouls["billing"].noul)
    print(response.choices["tone"].choice)
    print(response.scores["urgency"].score)

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state={"document": "I was charged twice. Please fix this ASAP."},
        questions={
            "billing": Noul(instructions="Is this ticket about billing?"),
            "tone": Choice(
                instructions="What is the customer's tone?",
                criteria={"calm": None, "frustrated": None, "angry": None},
            ),
            "urgency": Score(
                instructions="How urgent is this ticket?",
                criteria=["can wait", "this week", "today"],
            ),
        },
    )

print(response.nouls["billing"].noul)
print(response.choices["tone"].choice)
print(response.scores["urgency"].score)

from typesafe_sdk import RetryPolicy, TypeSafeClient

client = TypeSafeClient(
    retry=RetryPolicy(
        max_retries=3, timeout=10.0, http_statuses={429, 500, 502, 503, 504}
    )
)

npm install @typesafe-ai/sdk

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient();
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);

TypeSafeError                      # SDK 失败的基类
├── TypeSafeAPIError               # 不成功的 HTTP 响应，带 status / body / headers
├── TypeSafeAPIConnectionError     # 请求无法到达或无法读取服务端
└── TypeSafeAPITimeoutError        # 请求超过设定的超时

TypeSafeError
├── APIError                       # 基类；带 HTTP status 与 body
│   ├── BadRequestError
│   ├── AuthenticationError
│   ├── PermissionDeniedError
│   ├── NotFoundError
│   ├── RateLimitError
│   ├── UnprocessableEntityError
│   └── InternalServerError
├── APIConnectionError             # 请求/响应投递失败（DNS、TLS、连接关闭等）
│   └── APITimeoutError
└── APIUserAbortError              # 请求被用户主动中止

# Claude Code
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

# 其他智能体：交互式选择；默认项目局部安装，加 -g 全局安装
npx skills add typesafe-ai/skills --skill typesafe-ai

claude plugin marketplace update typesafe-ai
claude plugin update typesafe@typesafe-ai
# 重启 Claude Code 或运行 /reload-plugins
# 自动更新：/plugin → Marketplaces → typesafe-ai → Enable auto-update

# skills.sh 安装方式
npx skills update

Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.

Using the TypeSafe skill, run some experiments using the TypeSafe API key that I've
exported to `TYPESAFE_API_KEY`. Propose changes based on the most promising results.

Using the TypeSafe skill, analyze my code and see if there are any applicable
cookbooks (https://console.typesafe.ai/docs/cookbooks) that show how I could
refactor my code to be less fragile or complex.