jev-router
An agent- and harness-agnostic router that opens up parallel workstreams whose decisions are offloaded to TypeSafe's Jev System One model (POST https://api.typesafe.ai/v1/systemone) β using its speculative fan-out pattern (many typed questions answered in parallel in one request, https://docs.typesafe.ai/patterns/fan-out) and its Box primitive for image localization (https://docs.typesafe.ai/primitives/box).
Jev is a System One decision model, not a chat LLM: it does not write code or prose. It takes a
stateplus typed questions (noul/choice/score/box) and returns structured answers β probabilities, choices, scores, bounding boxes β that your code branches on. So this router offloads the routing, triage, prioritization, conflict detection and verification of parallel workstreams to Jev, while your agent (Claude Code, Mistral Vibe, Codex, β¦) still executes the work itself. Same spirit aschrismarchant/mistral-code-router, but for decision offload instead of generation offload.
Zero dependencies (Node β₯ 18 standard library only). MIT licensed.
Documentation
| Page | Contents |
|---|---|
| docs/installation.md | Install in Mistral Vibe, Claude Code, Codex/skills.sh, any MCP client, or plain CLI |
| docs/architecture.md | Repo layout, data flow, MCP transport, retries, plugin packaging |
| docs/tools.md | Reference for all 9 jev_* MCP tools / CLI commands (args, returns, examples) |
| docs/cli.md | CLI commands, flags, @file convention, exit codes |
| docs/configuration.md | Every environment variable |
| docs/primitives.md | How the router uses noul / choice / score / box (+ structured questions) |
| docs/patterns.md | TypeSafe patterns β where each is implemented in the router |
| docs/confidence-and-thresholds.md | How confidence works, noul bands, probability vs confidence, the router's thresholds |
| docs/limitations.md | Jev's limits (AI primer, model jaggedness, model limits) and how they are encoded |
| docs/examples.md | End-to-end walkthroughs with sample output |
| docs/development.md | Tests, scripts/verify.sh, committing/releasing |
Quick start
# 1. key (https://console.typesafe.ai/keys, or the Vercel AI gateway)
export TYPESAFE_API_KEY=...
# 2. run from a checkout of this repo (no npm install needed β zero deps)
node bin/jev-router.js models
# 3. plan parallel workstreams for a task β ONE fan-out request to Jev
node bin/jev-router.js plan \
--task @examples/task.txt \
--candidates @examples/plan-candidates.json \
--files '["src/server.js"]'
Or install it into your agent β see docs/installation.md β and call the jev_* MCP tools directly.
The 60-second mental model
- Fan-out by default. Every question that shares a
stategoes in one request; Jev evaluates them all in parallel (no question-count limit β only context limits), and your code keeps the answers it needs.jev_plan_workstreamsandjev_fan_outdo this for you;jev_batchis for items that each have their own state. - Jev decides, you execute. Jev never generates text, does math, or compares dates β closed option sets are drafted by a small LLM (
jev_draft_options, default mistral-small-latest) and Jev only picks; arithmetic/ordering happens in your code. - Threshold responsibly. Nouls: >0.7 yes, <0.3 no, between = its own outcome. Choices: threshold the probability of the option you'll act on; use
confidenceonly to decide whether to act at all (below ~0.5, escalate). See docs/confidence-and-thresholds.md.
Tools at a glance
| MCP tool | CLI | One-liner |
|---|---|---|
jev_models | models | List available Jev models + limits |
jev_ask | ask | One POST /v1/systemone: state + typed questions β answers |
jev_fan_out | fan-out | Many questions in ONE request (default mode) + optional confidence discard |
jev_plan_workstreams | plan | Decompose a task into scored/routed parallel workstreams (one fan-out request) |
jev_route | route | Route an item: choice + companion noul + probability threshold + confidence floor |
jev_review | review | Verify an output against acceptance criteria (three-band nouls) |
jev_batch | batch | Many items with their own states, parallel bounded pool |
jev_box | box | Locate something in an image (Box + present noul; Jev 1.14+) |
jev_draft_options | draft-options | Draft closed option sets with mistral-small-latest (Jev only picks) |
Full reference: docs/tools.md.
Guardrails
- Never send secrets β API keys stay in the environment, never in
state/questions/draft prompts. - Keep
statelean (Jev suffers context rot); request bodies β€ 32 MiB, nesting β€ 64. - 401 β bad key; 422 β malformed question (error names the field); 429/529/5xx β auto-retried with backoff.
- On tool failure inside an agent loop: retry once, then decide locally β never block the workstream.
Development
node --test test/*.test.js # 36 tests against mock APIs (no keys needed)
bash scripts/verify.sh # syntax + MCP handshake + tools/list + missing-key + optional live test
See docs/development.md.
License
MIT β see LICENSE.