BUILD WITH JEV — AIHACKERS REFERENCE BRIEF
Reviewed: 2026-09-27
Article: https://aihackers.net/posts/jev-practical-builder-guide/
Evidence boundary: documentation research; AIHackers paid inference not-run.

Purpose
Jev is TypeSafe's hosted decision model. Use it for narrow semantic judgments
over supplied text and a bounded answer set. It does not browse, generate
explanations, or replace the coding agent's LLM. Application code owns the
workflow, exact calculations, permissions, validation, and side effects.

Read current primary sources before implementing
- Documentation index: https://docs.typesafe.ai/llms.txt
- Official skill: https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md
- Skill installation: https://docs.typesafe.ai/agent-skill
- Direct API: https://docs.typesafe.ai/api
- Question types: https://docs.typesafe.ai/primitives
- Confidence: https://docs.typesafe.ai/confidence
- Limits and version IDs: https://docs.typesafe.ai/models
- Known failures: https://docs.typesafe.ai/model-jaggedness/jev-1.13
- OpenRouter: https://openrouter.ai/typesafe/jev-1.13
- OpenRouter integration: https://openrouter.ai/blog/tutorials/how-to-use-jev/

Access snapshot (recheck before use)
Direct: POST https://api.typesafe.ai/v1/systemone
  key: TYPESAFE_API_KEY; pinned model: jev-1.13.0; alias: jev-latest
OpenRouter: POST https://openrouter.ai/api/alpha/decisions
  key: OPENROUTER_API_KEY; model: typesafe/jev-1.13
  alias: ~typesafe/jev-latest
The decision model does not use the ordinary chat-completions endpoint.
Do not confuse it with OpenRouter's separate typesafe/jev-router product.

Question/answer shapes
- choice: criteria map of allowed options; selected choice, probabilities,
  confidence. Include an explicit none/insufficient-evidence option.
- noul: yes/no proposition; noul probability in [0,1], no confidence field.
- score: ordered descriptive criteria; score, legend, probabilities,
  confidence. It is not a numeric extraction or a measurement.
Question IDs are code keys; write the entire question in instructions.
Independent questions share state. Dependent decisions need a later step.
Choice/Score confidence measures distribution concentration, not demonstrated
accuracy on your domain. Typed answers can still be wrong.

Good first experiments
1. Evidence triage: retrieve source excerpts, check identifiers and freshness
   in code, then classify a claim/excerpt relationship. Preserve source IDs.
2. Skill selection: retrieve a shortlist of approved skill IDs, judge fit,
   allow none, then load instructions without expanding permissions.
3. Personal opportunity research: compare individual requirements with an
   approved evidence profile. Missing information is unknown, not rejection.

Implementation brief
Choose one read-only queue. Keep questions and thresholds versioned. Validate
response types, allowed IDs and finite probability values. Timeouts, missing
answers, malformed responses and unavailable models go to a review fallback.
Bound retries and concurrency. Cache by evidence snapshot, rubric and model.
Record resolved model, evidence/rubric hashes, usage and latency. Do not log
credentials or publish sensitive source text.

Evaluate rules/retrieval alone, rules+Jev, and a small LLM on the same cases.
Use separate development and held-out sets. Report important cases missed,
false escalations, review load, p50/p95 latency, and total cost per accepted
result. Sample low-priority cases too. Start in shadow mode with a rollback
switch; paid experiments require an agreed spend cap.

Preserve exact checks and independent approval. Jev does not authenticate a
source, prove contract ownership, authorize a tool call, or establish that an
unseen real-world fact is true. Test adversarial text and domain edge cases.

The article's interactive workbench uses synthetic fixtures. It makes no API
calls and its threshold values are not calibrated recommendations.