Unofficial · evidence first · mock safe

Turn application state into typed decisions.

A small Python toolkit around TypeSafe Jev with frozen questions, deterministic policy, offline replay, provenance hashes, and explicit evidence boundaries.

Run an offline example Explore XYZ Forge

Clone repo

Jev makes a bounded judgment. Your code keeps control of permissions, actions, and fallbacks.

decision.json

{
  "approval_mode": {
    "type": "choice",
    "choice": "confirm",
    "confidence": 0.91
  },
  "risk_level": {
    "type": "score",
    "score": 2.4
  },
  "scope_matches": {
    "type": "noul",
    "noul": 0.62
  }
}

deterministic policyREQUEST CONFIRMATION

3typed primitives

2pinned transports

33offline tests

0live CI calls

What ships

A narrow decision layer with strong edges.

The toolkit packages the controls around a model call: validation before spend, typed projection after response, and deterministic policy before action.

Typed questions

Choice selects a label. Score returns a rubric value. Noul returns a yes probability. Frozen JSON and sidecar hashes keep wording reproducible.

Two pinned routes

Use direct TypeSafe with jev-1.13.0, or the dedicated OpenRouter Decisions route with typesafe/jev-1.13.

Offline by default

Ordered mocks, fixture replay, network-blocked tests, and explicit live flags let teams prove integration behavior before authorizing spend.

Evidence you can audit

Canonical request and response hashes, frozen manifests, per-answer checkpoints, append-only decision logs, and strict text boundaries.

Operating model

Model judgment stays inside ordinary software control.

01Normalize stateSend only approved fields.
02Apply hard rulesPermissions and denylists run first.
03Ask JevReceive bounded typed answers.
04Compose policyCombine answers with thresholds.
05Act or reviewLog the outcome without raw state.

Five minute start

Run the repository without an API key.

The harness uses only the Python standard library. These examples are offline and write to a new output directory.

python3 -m jev replay --fixture examples/fixtures/fresh-100 --out results/fresh

Live use is deliberately explicit. A live request needs a pinned manifest, a new output directory, an allowed public repository, the correct provider key, and --live. CI cannot make live calls.

Evidence, with boundaries

Recorded results are useful when read precisely.

The work-classification reference is a three-model consensus, not independent human gold. The cards preserve exact denominators and avoid transferring results to new tasks.

Fresh purpose sample

88/100 Recorded sample · macro-F1 0.6868

Confidence ≥ 0.8

73/75 Correct · coverage 75/100

Fresh area sample

60/94 Not ready for unattended use

No result transfers automatically.

New taxonomies, private data, future samples, and the three bounded judgment skill designs each need their own labels, frozen questions, and preregistered gate.

Read the evidence ledger

For app developers

Build one useful Jev function in your existing app.

The included agent skill finds one bounded decision, fits it to the app’s architecture, adds an offline mock, and leaves permissions and actions in deterministic code.

“Use jev-app-integration to add a function that [decision] in [app path].”

Open the integration skill

✓ One app-native function

✓ Frozen typed question

✓ Offline positive and negative controls

✓ Failure and low-confidence fallback

✓ Run and key-loading instructions

✓ Explicit model-quality limits

Flagship project

Coordinate the whole engineering system with XYZ Forge.

XYZ Forge is HiQS Labs’ local-first engineering operations system for coordinating multiple coding agents, collision-free work lanes, verification gates, and durable receipts.

Visit HiQS-Labs/XYZ-forge

Read deeper

Documentation by question.

Start and operateREADME→ Understand JevFAQ→ Run experimentsProtocol→ Judge evidenceUse cases→

Start locally

Clone the toolkit.

Run the offline examples and inspect every decision boundary in your own checkout.

Clone repo