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 state plus 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 as chrismarchant/mistral-code-router, but for decision offload instead of generation offload.

Zero dependencies (Node ≥ 18 standard library only). MIT licensed.

Documentation

Related MCP server: mewcp-jev

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

1. Fan-out by default. Every question that shares a state goes 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_workstreams and jev_fan_out do this for you; jev_batch is for items that each have their own state.

2. 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.

3. 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 confidence only to decide whether to act at all (below ~0.5, escalate). See docs/confidence-and-thresholds.md.

Tools at a glance

Full reference: docs/tools.md.

Guardrails

• Never send secrets — API keys stay in the environment, never in state/questions/draft prompts.

• Keep state lean (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.