## What is Arbitype?
Arbitype is an MCP-native typed decision layer for AI agents, powered by
[TypeSafe Jev](https://typesafe.ai). It turns probabilistic judgments into
structured decision primitives that an agent or program can consume directly.
Arbitype is available on PyPI and the official MCP Registry.
> [!NOTE]
> Arbitype is an independent open-source project. It is not an official
> TypeSafe AI product or an official integration for any particular agent host.
## Quick Start
The fastest way to connect an MCP host is a local STDIO server launched by
uvx:
~~~bash
export TYPESAFE_API_KEY="your-key"
uvx arbitype
~~~
For a pinned, reproducible launch:
~~~bash
uvx --from 'arbitype==0.7.0' arbitype
~~~
Or install the package into the current environment:
~~~bash
python -m pip install arbitype
arbitype
~~~
The API key stays in the process environment. It is not an MCP argument and
is never printed to standard output.
### Host setup
Inspect detected hosts before writing anything:
~~~bash
arbitype setup --detect --dry-run
~~~
Then apply a reviewed plan:
~~~bash
arbitype setup codex
arbitype doctor --json
~~~
The setup flow is plan → unified diff → confirmation → backup → apply.
Use claude, cursor, or vscode in place of codex. Detailed host formats,
secret forwarding, --yes, --remove, ownership, and non-interactive behavior
are documented in [docs/HOST_SETUP.md](https://github.com/Renwang-Huang/typesafe-mcp/blob/HEAD/docs/HOST_SETUP.md).
### Configuration
At minimum, set TYPESAFE_API_KEY. To select a model explicitly:
~~~bash
export TYPESAFE_API_KEY="your-key"
export TYPESAFE_MODEL="jev-latest"
~~~
See the [full configuration reference](https://github.com/Renwang-Huang/typesafe-mcp/blob/HEAD/docs/CONFIGURATION.md) for endpoints,
timeouts, retries, and request/response limits.
### Compatibility
arbitype is the canonical distribution, Python package, and CLI. Existing
TypeSafe MCP users should migrate to Arbitype; see
[docs/REGISTRY_MIGRATION.md](https://github.com/Renwang-Huang/typesafe-mcp/blob/HEAD/docs/REGISTRY_MIGRATION.md).
For the safe migration from the historical distribution:
~~~bash
python -m pip uninstall typesafe-mcp
python -m pip install arbitype
~~~
| Surface | Canonical | Legacy compatibility |
| --- | --- | --- |
| PyPI / CLI | arbitype | typesafe-mcp, typesafe-codex-mcp |
| Python imports | arbitype | typesafe_mcp, typesafe_codex_mcp |
| MCP tools | route, review | codex_route, codex_review |
## Why Arbitype?
Arbitype is designed around contracts and bounded decisions rather than
free-form prose:
| Principle | What it means |
| --- | --- |
| **Contract-first** | Requests and provider responses are validated before they reach the agent. |
| **Safe by default** | Credentials stay out of MCP tool arguments and generated host configuration. |
| **Agent-oriented** | Purpose-built classify, verify, gate, route, review, and score primitives. |
| **Portable** | Zero third-party runtime dependencies and standard MCP STDIO. |
| **Measured** | Public tool-selection and decision-stability evaluation assets. |
The decision flow is:
~~~text
free-form state
↓
TypeSafe Jev
↓
probabilistic judgment
↓
Arbitype
↓
typed decision + probability
↓
agent / code branch
~~~
## Real Use Cases
Start with one of the small, runnable fixtures:
| Scenario | Tool | What it demonstrates |
| --- | --- | --- |
| [Support routing](https://github.com/Renwang-Huang/typesafe-mcp/blob/HEAD/examples/support-routing/) | route | Choose one next action without executing it. |
| [PR verification](https://github.com/Renwang-Huang/typesafe-mcp/blob/HEAD/examples/pr-verification/) | verify | Check several claims independently. |
| [Release review](https://github.com/Renwang-Huang/typesafe-mcp/blob/HEAD/examples/release-review/) | review / gate | Separate holistic review from thresholded checks. |
| [Agent next step](https://github.com/Renwang-Huang/typesafe-mcp/blob/HEAD/examples/agent-next-step/) | route | Keep the next workflow action bounded. |
The example outputs are illustrative fixtures. They are not live model results,
accuracy claims, or authorization decisions.
## Tools
Arbitype advertises nine read-only, idempotent MCP tools:
| Tool | Use when | Result |
| --- | --- | --- |
| evaluate | You need a custom typed Jev question set. | Raw typed Jev response. |
| classify | You need one choice from unordered labels. | Choice and probability distribution. |
| score | You need one ordered rating or level. | Weighted score and distribution. |
| check | You need a probability for one bounded criterion. | Noul yes/no probability. |
| verify | You need several named claims checked independently. | Noul answer per claim. |
| gate | You need checks and thresholds transformed into a signal. | pass, review, or fail. |
| route | You need one suggested next action. | One action; no action execution. |
| review | You need a holistic quality or risk assessment. | Review decision and evidence. |
| health | You need local diagnostics or an explicit live check. | Configuration and optional provider health. |
### Tool Selection Guide
| Need | Use | Do not substitute |
| --- | --- | --- |
| One unordered label | classify | route, which selects an action |
| One ordered rating | score | classify, which has no order |
| One bounded proposition | check | verify, which handles multiple claims |
| Several named claims | verify | review, which assesses a whole object |
| Checks plus thresholds | gate | review, which is holistic |
| One next action | route | classify, which returns a category |
| Whole diff, plan, release, or report | review | verify, which answers claim by claim |
Tool descriptions also state USE WHEN and DO NOT USE WHEN boundaries so hosts
can select a primitive without hidden prompt conventions.
Probabilities and confidence are model signals, not proof. gate and review
are advisory decision transformations, not authorization systems, security
boundaries, or approval engines.
## Architecture
~~~mermaid
flowchart LR
host["AI Agent / MCP Host
