Judgevet MCP Server

judgevet

A typed Python client for TypeSafe's Jev (System One) judgment model, with CLI and optional MCP entry points. Use it to ask structured questions about content—for example, whether a support ticket concerns billing.

The state is your content. A question describes what to evaluate. A typed answer contains the model's values, which your application can inspect or compare with a local acceptance policy.

Unofficial and not affiliated with TypeSafe. The official TypeSafe Python SDK also provides typed questions and synchronous and asynchronous clients. judgevet adds a shared library, CLI and MCP contract with local policy evaluation. The library and CLI install without the MCP runtime.

Documentation status: draft. Start below or follow the first-judgment tutorial for environment setup, checkpoints and recovery steps.

Install and ask one question

Use Python 3.12 or newer. In a virtual environment:

python -m pip install 'judgevet==0.15.0'
judgevet --help

Supply a TypeSafe API key through your process environment or secret provider. This example reads JEV_API__KEY and passes it explicitly to the library. Do not put real keys in source or command arguments. The installation guide covers other installation methods.

This call sends the state, questions and selected model to the configured service. Send only content you are authorized to disclose. Read the data and credential guidance before using sensitive content. The example uses a synthetic ticket:

import os

from judgevet import HTTPSystemOneAdapter, Noul

with HTTPSystemOneAdapter(api_key=os.environ["JEV_API__KEY"]) as client:
    response = client.system_one(
        state="I was charged twice. Please help today.",
        questions={"billing": Noul(instructions="Is this about billing?")},
    )

answer = response.nouls["billing"]
print(f"Probability of billing: {answer.noul}")
print(f"Resolved model: {response.model}")
print(f"Input tokens: {response.usage.input_tokens}")

The context manager closes the HTTP client after the call. The answer remains available. If the import or call fails, use the tutorial's recovery steps or the troubleshooting guide.

Read the answer and make a decision

A Noul value such as 0.85 reports the model's probability of yes. The actual value varies. It is not a boolean, a measured accuracy rate or an instruction to route the ticket. Noul has no separate confidence field. See the vendor's Noul definition.

The returned container also records the resolved model and token usage. Other question types let you select a label or evaluate an ordered rubric:

The vendor API reference defines those fields. The question-type explanation shows how to choose a type and distinguish score, confidence and probability.

A local policy can require a minimum value before your application accepts an answer. For example, 0.85 meets a minimum of 0.8 and fails one of 0.9. These are teaching thresholds, not production recommendations. A passing policy does not prove the model is correct or perform the application's next action. Try the first-policy tutorial with synthetic answers; it requires no key or network.

Choose your next task

The CLI uses the same library and can return JSON or a policy exit status. The optional MCP server exposes ask_noul, ask_choice, ask_score and evaluate_policy over stdio. Follow the connection guide to install the extra and configure a host. These are alternative entry points; you do not need MCP to use Python or the CLI.

Know the limits

Exact documentation examples run against isolated installations with synthetic answers. Those checks establish local wiring, not model quality or calibration. Live evidence covers only the observed cases and resolved jev-1.13.0 model. The 429/529 error bodies remain unseen; other models and untouched fields remain unverified. The verification explanation separates local tests, vendor statements and live observations.

Diagnostics are quiet by default. Debug metadata excludes state and question text, but protocol errors, CLI error envelopes and arbitrary tracebacks can contain sensitive content. Review them before sharing. The security policy describes credential, disclosure and diagnostic limits.

Maintainers

Read the contribution policy before proposing work. Use the maintainer procedures for documentation checks, package verification and releases. Repository contribution rules define gates and commits. The evidence ledger retains release records and the detailed live-verification table.