SDK Reference

Jev Harness v0.1.6 — Zero-dependency decision harness for AI coding agents. Prevents frontier token waste by classifying errors, breaking doom loops, and routing tasks to the cheapest effective model — all in 70–300 ms without autoregressive generation.

Python SDK

Installation

# Standard pip
pip install jev-harness

# Isolated global tool (recommended for agents / CI)
pipx install jev-harness

Full Import

from jev_harness import (
    # 5 semantic decision gates
    triage_test_failure,
    should_abort_trajectory,
    route_model_tier,
    verify_step_completion,
    modulate_reasoning_effort,
    # Return types
    TestTriageResult,
    AbortGateResult,
    ModelRouteResult,
    VerificationResult,
    ReasoningEffortResult,
    # HTTP client
    JevClient,
    # Question primitives (for low-level usage)
    ChoiceQuestion,
    ScoreQuestion,
    NoulQuestion,
)

JevClient

Zero-dependency HTTP client for the TypeSafe AI Jev System One API (POST https://api.typesafe.ai/v1/systemone). Falls back to an intelligent local heuristic simulation when no API key is configured or when force_mock=True.

class JevClient:
    def __init__(
        self,
        api_key: Optional[str] = None,         # Override resolved API key
        provider: Optional[str] = None,         # 'typesafe' | 'opencode' | 'openrouter'
        base_url: Optional[str] = None,         # Custom endpoint override
        model: Optional[str] = None,            # Override model (default: 'jev-latest')
        timeout: float = 15.0,                  # Request timeout in seconds
        force_mock: bool = False,               # Always use local simulation
    ): ...

Attributes after construction:

Attribute	Type	Description
`api_key`	`Optional[str]`	Resolved API key (from env, `.jev.json`, or `.env`)
`provider`	`str`	Active provider: `'typesafe'`, `'opencode'`, `'openrouter'`, or `'mock'`
`base_url`	`str`	Endpoint URL in use
`model`	`str`	Active model identifier
`timeout`	`float`	Timeout in seconds
`force_mock`	`bool`	Whether forced simulation is active
`is_live`	`bool`	`True` when a real API call will be made

Example:

from jev_harness import JevClient

client = JevClient(timeout=10.0)
print(f"Provider: {client.provider}")  # e.g. 'typesafe'
print(f"Model:    {client.model}")     # e.g. 'jev-latest'
print(f"Live:     {client.is_live}")   # True if key is resolved

`triage_test_failure()`

Evaluates a test error or stack trace to determine whether calling a frontier System 2 LLM is necessary, or if the failure can be resolved deterministically (install a dependency, retry, fix a typo).

def triage_test_failure(
    failure_log: str,            # Raw test output, traceback, or compiler error
    client: Optional[JevClient] = None,  # Uses a fresh JevClient() if omitted
) -> TestTriageResult: ...

TestTriageResult fields:

Field	Type	Description
`category`	`str`	`'env_missing'` · `'flaky_transient'` · `'syntax_trivial'` · `'test_redundant'` · `'deep_logic'`
`confidence`	`float`	Classifier confidence (0.0–1.0)
`skip_llm`	`bool`	`True` → resolve deterministically without LLM
`skip_llm_prob`	`float`	Probability that LLM call can be skipped
`severity_score`	`float`	Architectural severity 1–4 (1=trivial, 4=critical systemic)
`action_recommendation`	`str`	Human-readable action: AUTO-ACTION / LOW-COST / ESCALATE / PRUNE
`is_mock`	`bool`	`True` when response came from local simulation
`details`	`dict`	`{'model': str, 'usage': dict}`

Exit codes (CLI): 0 if skip_llm=True (deterministic fix), 1 if skip_llm=False (needs LLM).

Example:

from jev_harness import triage_test_failure

traceback = """
Traceback (most recent call last):
  File "test_runner.py", line 12, in <module>
    import redis
ModuleNotFoundError: No module named 'redis'
"""

result = triage_test_failure(traceback)

print(result.category)              # 'env_missing'
print(result.skip_llm)              # True
print(result.action_recommendation) # 'AUTO-ACTION: Install missing dependency...'
print(result.severity_score)        # 1.0

if result.skip_llm:
    # No LLM needed — handle deterministically
    import subprocess
    subprocess.run(["pip", "install", "redis"], check=True)
else:
    # Escalate to frontier model
    pass

Pipe usage (CI):

pytest 2>&1 | jev-harness test-gate
# exit 0 → skip_llm=True (fix deterministically)
# exit 1 → deep logic defect (call LLM)

`should_abort_trajectory()`

Early-abort guard that checks if an agent's proposed next step is circular, unviable, or headed toward a dead end — before burning tens of thousands of frontier tokens.

Automatically reads session history to detect repeated failure patterns even when recent_attempts_summary is omitted.

def should_abort_trajectory(
    proposed_step: str,                    # The next proposed plan or refactor direction
    recent_attempts_summary: str = "",     # Optional: summary of previous failed attempts
    client: Optional[JevClient] = None,
) -> AbortGateResult: ...

AbortGateResult fields:

Field	Type	Description
`should_abort`	`bool`	`True` → stop trajectory, ask user
`abort_probability`	`float`	Dead-end probability (0.0–1.0)
`action`	`str`	`'proceed'` · `'replan'` · `'abort_and_ask'`
`viability_score`	`float`	Technical viability 1–4 (1=hopeless, 4=highly viable)
`reasoning_summary`	`str`	Human-readable verdict
`is_mock`	`bool`	`True` when response came from local simulation

Exit codes (CLI): 0 if should_abort=False, 1 if should_abort=True.

Example:

from jev_harness import should_abort_trajectory

result = should_abort_trajectory(
    proposed_step="Rewrite the entire auth module from scratch without running tests",
    recent_attempts_summary=(
        "Attempt 1: timeout after 120s.\n"
        "Attempt 2: same circular import error.\n"
        "Attempt 3: identical circular import error."
    ),
)

print(result.should_abort)         # True
print(result.abort_probability)    # e.g. 0.88
print(result.action)               # 'abort_and_ask'
print(result.viability_score)      # e.g. 1.5
print(result.reasoning_summary)    # 'Abort recommended (prob=0.88)'

if result.should_abort:
    raise SystemExit("Trajectory aborted: ask user for new direction.")

`route_model_tier()`

Decides the most cost-effective intelligence tier for a given task, choosing among deterministic execution, lightweight flash model, or heavy frontier reasoning model.

def route_model_tier(
    task_description: str,              # Clear description of the task
    client: Optional[JevClient] = None,
) -> ModelRouteResult: ...

ModelRouteResult fields:

Field	Type	Description
`selected_tier`	`str`	`'deterministic'` · `'lightweight_system2'` · `'heavy_system2'`
`confidence`	`float`	Routing confidence (0.0–1.0)
`complexity_score`	`float`	Cognitive complexity 1–4
`rationale`	`str`	Explanation of the routing decision
`recommended_model`	`str`	Specific model recommendation with approximate cost
`is_mock`	`bool`	`True` when response came from local simulation

Tier mapping:

Tier	When	Example recommendation
`deterministic`	bash/regex/script/linter can solve it	Direct Python/Bash Script (0 LLM Tokens)
`lightweight_system2`	simple edit, doc, trivial test	Gemini 3.8 Flash (~$0.75 in / $3.75 out per 1M tokens)
`heavy_system2`	deep architecture, multi-file refactor	Claude Fable 5.1 / GPT-6 Astra (~$10.00 in / $50.00 out per 1M tokens)

Example:

from jev_harness import route_model_tier

result = route_model_tier("Fix a typo and reformat code with black")

print(result.selected_tier)      # 'deterministic'
print(result.recommended_model)  # 'Direct Python/Bash Script (0 LLM Tokens)'
print(result.complexity_score)   # 1.0

# Route accordingly
if result.selected_tier == "deterministic":
    import subprocess
    subprocess.run(["black", "."], check=True)
elif result.selected_tier == "lightweight_system2":
    call_flash_model(task)
else:
    call_frontier_model(task)

`verify_step_completion()`

Evaluates whether a code change or produced artifact actually satisfies acceptance criteria, before dispatching expensive additional review agents.

def verify_step_completion(
    acceptance_criteria: str,           # Requirements or definition of done
    produced_output: str,               # Evidence: test results, diff, output
    client: Optional[JevClient] = None,
) -> VerificationResult: ...

VerificationResult fields:

Field	Type	Description
`is_verified`	`bool`	`True` when `satisfaction_probability >= 0.80` and `rigor_score >= 2.5`
`satisfaction_probability`	`float`	Probability that output meets criteria (0.0–1.0)
`rigor_score`	`float`	Evidence rigor 1–4 (1=unverified, 4=exhaustively proven)
`confidence`	`float`	Classifier confidence (0.0–1.0)
`needs_rework`	`bool`	`True` when `is_verified=False`
`is_mock`	`bool`	`True` when response came from local simulation

Example:

from jev_harness import verify_step_completion

result = verify_step_completion(
    acceptance_criteria="All unit tests must pass with 100% success rate",
    produced_output="All 22 unit tests passed in 0.017s. Coverage: 98%.",
)

print(result.is_verified)              # True
print(result.satisfaction_probability) # e.g. 0.95
print(result.rigor_score)             # e.g. 3.5
print(result.needs_rework)            # False

if result.needs_rework:
    # Dispatch rework loop instead of declaring done
    pass

`modulate_reasoning_effort()`

Dynamically decides the optimal reasoning effort ('low', 'medium', 'high') for the immediate next generation step, and compiles the exact typed provider parameters to inject into the API call. Eliminates reasoning token waste on mechanical tool calls and cuts multi-minute delays.

def modulate_reasoning_effort(
    context: str,                       # The command, prompt, or next step to evaluate
    provider: str = "openai",           # Target provider: see table below
    model: Optional[str] = None,        # Optional model ID (detects non-reasoning models)
    session_context_tokens: int = 0,    # Active tokens in session (for cache-risk warning)
    client: Optional[JevClient] = None,
) -> ReasoningEffortResult: ...

ReasoningEffortResult fields:

Field	Type	Description
`effort`	`str`	`'low'` · `'medium'` · `'high'`
`confidence`	`float`	Decision confidence (0.0–1.0)
`complexity_score`	`float`	Cognitive depth 1–4
`rationale`	`str`	Provider-specific reasoning for the choice
`provider`	`str`	Provider that was used
`provider_params`	`dict`	Ready-to-inject API parameters
`is_reasoning_supported`	`bool`	`False` for direct models (avoids HTTP 400)
`cache_safe_recommendation`	`str`	Prompt cache / KV cache guidance
`is_mock`	`bool`	`True` when response came from local simulation

Supported providers and their provider_params output:

Provider value	Target models	`provider_params` (effort=`'high'`)
`openai` / `codex` / `azure`	GPT-6 Astra, o3, o4	`{"reasoning_effort": "high"}`
`anthropic` / `claude`	Claude Fable 5.1, Claude Opus 5	`{"thinking": {"type": "adaptive"}}`
`gemini` / `google`	Gemini 3.8 Flash Thinking, Gemini 3.5 Pro	`{"thinking_config": {"thinking_level": "high"}}`
`deepseek`	DeepSeek V4.1-Flash, V4-Pro, R1	`{"extra_body": {"thinking": {"type": "enabled"}}, "reasoning_effort": "high"}`
`qwen` / `alibaba` / `dashscope`	Qwen 3.8 Max (2.4T MoE), Qwen 3.8-Omni-Flash	`{"enable_thinking": true, "thinking_budget": 16384}`
`kimi` / `moonshot`	Kimi-k3	`{"reasoning_effort": "high"}`
`mimo` / `xiaomi`	MiMo-v2.6-pro, MiMo-v2-flash	`{"thinking": {"type": "enabled"}, "reasoning": {"effort": "high"}}`

Cache safety: Avoid toggling effort level across consecutive sub-steps — it invalidates the GPU prefix KV cache. Use cache_safe_recommendation to read the generated guidance.

Example — inject into Anthropic SDK:

import anthropic
from jev_harness import modulate_reasoning_effort

context = "Refactor the distributed lock manager to fix the deadlock under high concurrency"
result = modulate_reasoning_effort(context, provider="anthropic")

print(result.effort)          # 'high'
print(result.provider_params) # {'thinking': {'type': 'adaptive'}}

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=16000,
    messages=[{"role": "user", "content": context}],
    **result.provider_params,  # injects thinking={'type': 'adaptive'}
)

Example — inject into OpenAI SDK:

from openai import OpenAI
from jev_harness import modulate_reasoning_effort

context = "Run git status and report the list of changed files"
result = modulate_reasoning_effort(context, provider="openai", model="gpt-6-astra")

print(result.effort)          # 'low'
print(result.provider_params) # {'reasoning_effort': 'low'}

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": context}],
    **result.provider_params,  # injects reasoning_effort='low'
)

Non-reasoning model guard: If model is set to a known direct model (e.g., gpt-4o, gemini-2.5-flash, claude-3-5-haiku), provider_params returns {} and is_reasoning_supported=False, preventing an HTTP 400 error.

Session Telemetry

Jev Harness automatically tracks cumulative token savings and ROI across agent turns. Data is persisted atomically at .jev/session.json (repo-local) or ~/.config/jev/session.json (global fallback).

from jev_harness.session import load_session, reset_metrics

session = load_session()

print(f"Total triage calls:        {session.total_triage_calls}")
print(f"LLM calls skipped:         {session.skipped_llm_calls}")
print(f"Abort guards triggered:    {session.abort_guards_triggered}")
print(f"Deterministic routes:      {session.deterministic_routes}")
print(f"Effort modulations:        {session.effort_modulations}")
print(f"Estimated tokens saved:    {session.estimated_tokens_saved:,}")
print(f"Estimated cost saved USD: ${session.estimated_cost_saved_usd:.2f}")

# Reset for a new project sprint
reset_metrics()

Via CLI:

jev-harness metrics

ROI assumptions (per saved event):

Event	Tokens saved	Cost saved
`skip_llm=True` (triage)	~26,200	~$0.31
`should_abort=True`	~80,000	~$1.20
`tier='deterministic'`	~5,000	~$0.05
`effort='low'`	~7,000	~$0.21

Provider Configuration

Environment variables (highest priority):

# TypeSafe AI (primary — native Jev System One)
export TYPESAFE_API_KEY="ts-..."

# OpenCode Zen (alternative endpoint)
export OPENCODE_API_KEY="oc-..."
# Force OpenCode even when TYPESAFE_API_KEY is set:
export JEV_PROVIDER="opencode"

# OpenRouter (fallback — translates to OpenAI-compatible format)
export OPENROUTER_API_KEY="sk-or-..."

Credential resolution priority (4 levels):

Environment variables — JEV_PROVIDER, TYPESAFE_API_KEY, OPENCODE_API_KEY, OPENROUTER_API_KEY
Local repo config — .jev.json or .env in current working directory (or up to 3 parent directories)
Global user config — ~/.config/jev/credentials.env
Offline mock simulation — deterministic heuristic simulation, sub-500µs, no network, no API key required

.jev.json format:

{
  "provider": "typesafe",
  "api_key": "ts-your-key-here"
}

.env format:

TYPESAFE_API_KEY=ts-your-key-here
# or
JEV_PROVIDER=opencode
OPENCODE_API_KEY=oc-your-key-here

Framework Integrations

LangChain

from langchain_core.tools import tool
from jev_harness import triage_test_failure, should_abort_trajectory

@tool
def jev_triage(failure_log: str) -> dict:
    """Triage a test failure before calling expensive LLM tools."""
    result = triage_test_failure(failure_log)
    return {
        "category": result.category,
        "skip_llm": result.skip_llm,
        "action": result.action_recommendation,
    }

@tool
def jev_abort_check(proposed_step: str, history: str = "") -> dict:
    """Check if the proposed agent step is circular or unviable."""
    result = should_abort_trajectory(proposed_step, recent_attempts_summary=history)
    return {
        "should_abort": result.should_abort,
        "action": result.action,
    }

# Add to your LangChain agent tools list
tools = [jev_triage, jev_abort_check, ...]

LlamaIndex

from llama_index.core.tools import FunctionTool
from jev_harness import route_model_tier, verify_step_completion

def jev_route(task: str) -> str:
    r = route_model_tier(task)
    return f"tier={r.selected_tier}, model={r.recommended_model}"

def jev_verify(criteria: str, output: str) -> str:
    r = verify_step_completion(criteria, output)
    return f"verified={r.is_verified}, rework={r.needs_rework}"

route_tool = FunctionTool.from_defaults(fn=jev_route, name="jev_route_task")
verify_tool = FunctionTool.from_defaults(fn=jev_verify, name="jev_verify_step")

CrewAI

from crewai import Agent, Task, Crew
from crewai.tools import BaseTool
from jev_harness import triage_test_failure

class JevTriageTool(BaseTool):
    name: str = "jev_triage_test_failure"
    description: str = "Triage test failure logs to skip unnecessary LLM calls"

    def _run(self, failure_log: str) -> str:
        result = triage_test_failure(failure_log)
        return (
            f"category={result.category}, skip_llm={result.skip_llm}, "
            f"action={result.action_recommendation}"
        )

triage_agent = Agent(
    role="Test Analyst",
    goal="Classify failures and route to cheapest fix",
    tools=[JevTriageTool()],
    verbose=True,
)

AutoGen

import autogen
from jev_harness import should_abort_trajectory, route_model_tier

def jev_abort_fn(proposed_step: str, history: str = "") -> dict:
    r = should_abort_trajectory(proposed_step, recent_attempts_summary=history)
    return {"should_abort": r.should_abort, "action": r.action}

def jev_route_fn(task: str) -> dict:
    r = route_model_tier(task)
    return {"tier": r.selected_tier, "model": r.recommended_model}

# Register as AutoGen function tools
assistant = autogen.AssistantAgent(
    name="jev_orchestrator",
    llm_config={
        "functions": [
            {
                "name": "jev_abort_check",
                "description": "Check if proposed step is circular or dead-end",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "proposed_step": {"type": "string"},
                        "history": {"type": "string"},
                    },
                    "required": ["proposed_step"],
                },
            }
        ]
    },
)

TypeScript / Node.js SDK

Installation

# npm
npm install @ismaelsoilet/jev-harness

# bun
bun add @ismaelsoilet/jev-harness

# yarn
yarn add @ismaelsoilet/jev-harness

# pnpm
pnpm add @ismaelsoilet/jev-harness

# One-shot (no install)
npx @ismaelsoilet/jev-harness test-gate

ESM Import

import {
  JevClient,
  triageTestFailure,
  shouldAbortTrajectory,
  routeModelTier,
  verifyStepCompletion,
  modulateReasoningEffort,
  // Types
  type TestTriageResult,
  type AbortGateResult,
  type ModelRouteResult,
  type VerificationResult,
  type ReasoningEffortResult,
  type JevClientOptions,
} from "@ismaelsoilet/jev-harness";

JevClientOptions:

interface JevClientOptions {
  apiKey?: string;       // Override resolved API key
  provider?: string;     // 'typesafe' | 'opencode' | 'openrouter'
  baseUrl?: string;      // Custom endpoint override
  model?: string;        // Override model identifier
  timeoutMs?: number;    // Request timeout in ms (default: 15000)
  forceMock?: boolean;   // Always use local simulation
}

`triageTestFailure()`

async function triageTestFailure(
  failureLog: string,
  client?: JevClient,
): Promise<TestTriageResult>

TestTriageResult:

interface TestTriageResult {
  category: "env_missing" | "flaky_transient" | "syntax_trivial" | "test_redundant" | "deep_logic" | string;
  confidence: number;
  skipLlm: boolean;
  skipLlmProb: number;
  severityScore: number;
  actionRecommendation: string;
  isMock: boolean;
}

Example:

import { triageTestFailure } from "@ismaelsoilet/jev-harness";

const traceback = `
Error: Cannot find module 'redis'
Require stack:
- /app/src/cache.js
    at Function.Module._resolveFilename (node:internal/modules/cjs/loader:1039:15)
`;

const result = await triageTestFailure(traceback);

console.log(result.category);              // 'env_missing'
console.log(result.skipLlm);              // true
console.log(result.actionRecommendation); // 'AUTO-ACTION: Install missing dependency...'

if (result.skipLlm) {
  // No LLM needed — install the package
  await execa("npm", ["install", "redis"]);
} else {
  // Escalate to frontier model
  await callFrontierLLM(traceback);
}

`shouldAbortTrajectory()`

async function shouldAbortTrajectory(
  proposedStep: string,
  recentAttemptsSummary?: string,
  client?: JevClient,
): Promise<AbortGateResult>

AbortGateResult:

interface AbortGateResult {
  shouldAbort: boolean;
  abortProbability: number;
  action: "proceed" | "replan" | "abort_and_ask" | string;
  viabilityScore: number;
  reasoningSummary: string;
  isMock: boolean;
}

Example:

import { shouldAbortTrajectory } from "@ismaelsoilet/jev-harness";

const result = await shouldAbortTrajectory(
  "Rewrite the entire database schema without backup",
  "Attempt 1: migration failed. Attempt 2: identical migration error.",
);

console.log(result.shouldAbort);     // true
console.log(result.action);          // 'abort_and_ask'
console.log(result.viabilityScore);  // e.g. 1.0

if (result.shouldAbort) {
  throw new Error(`Trajectory aborted: ${result.reasoningSummary}`);
}

`routeModelTier()`

async function routeModelTier(
  taskDescription: string,
  client?: JevClient,
): Promise<ModelRouteResult>

ModelRouteResult:

interface ModelRouteResult {
  selectedTier: "deterministic" | "lightweight_system2" | "heavy_system2" | string;
  confidence: number;
  complexityScore: number;
  recommendedModel: string;
  rationale: string;
  isMock: boolean;
}

Example:

import { routeModelTier } from "@ismaelsoilet/jev-harness";

const result = await routeModelTier("Add a JSDoc comment to the getUserById function");

console.log(result.selectedTier);     // 'lightweight_system2'
console.log(result.recommendedModel); // 'Gemini 3.8 Flash...'
console.log(result.complexityScore);  // e.g. 1.5

switch (result.selectedTier) {
  case "deterministic":
    await runScript();
    break;
  case "lightweight_system2":
    await callFlashModel(task);
    break;
  case "heavy_system2":
    await callFrontierModel(task);
    break;
}

`verifyStepCompletion()`

async function verifyStepCompletion(
  acceptanceCriteria: string,
  producedOutput: string,
  client?: JevClient,
): Promise<VerificationResult>

VerificationResult:

interface VerificationResult {
  isVerified: boolean;
  satisfactionProbability: number;
  rigorScore: number;
  confidence: number;
  needsRework: boolean;
  isMock: boolean;
}

Example:

import { verifyStepCompletion } from "@ismaelsoilet/jev-harness";

const result = await verifyStepCompletion(
  "All TypeScript types must be strict with no 'any' usage",
  "tsc --strict exited 0. ESLint: 0 errors. No 'any' found in grep scan.",
);

console.log(result.isVerified);              // true
console.log(result.satisfactionProbability); // e.g. 0.93
console.log(result.needsRework);             // false

`modulateReasoningEffort()`

async function modulateReasoningEffort(
  context: string,
  options?: {
    provider?: string;             // Default: 'openai'
    model?: string;
    sessionContextTokens?: number;
    client?: JevClient;
  },
): Promise<ReasoningEffortResult>

ReasoningEffortResult:

interface ReasoningEffortResult {
  effort: "low" | "medium" | "high";
  confidence: number;
  complexityScore: number;
  rationale: string;
  provider: string;
  providerParams: Record<string, any>;  // Inject directly into API call
  isReasoningSupported: boolean;
  cacheSafeRecommendation: string;
  isMock: boolean;
}

Example — inject into Anthropic SDK:

import Anthropic from "@anthropic-ai/sdk";
import { modulateReasoningEffort } from "@ismaelsoilet/jev-harness";

const context = "Debug the distributed lock race condition under heavy concurrency";
const jev = await modulateReasoningEffort(context, { provider: "anthropic" });

console.log(jev.effort);          // 'high'
console.log(jev.providerParams);  // { thinking: { type: 'adaptive' } }

const anthropic = new Anthropic();
const response = await anthropic.messages.create({
  model: "claude-fable-5-1",
  max_tokens: 16000,
  messages: [{ role: "user", content: context }],
  ...jev.providerParams,  // spreads thinking: { type: 'adaptive' }
});

Example — inject into OpenAI SDK:

import OpenAI from "openai";
import { modulateReasoningEffort } from "@ismaelsoilet/jev-harness";

const context = "Check git status and list modified files";
const jev = await modulateReasoningEffort(context, { provider: "openai", model: "gpt-6-astra" });

console.log(jev.effort);          // 'low'
console.log(jev.providerParams);  // { reasoning_effort: 'low' }

const openai = new OpenAI();
const response = await openai.chat.completions.create({
  model: "gpt-6-astra",
  messages: [{ role: "user", content: context }],
  ...jev.providerParams,  // spreads reasoning_effort: 'low'
});

CLI Usage

All 5 gates are available as CLI commands via npx (no install required):

# Gate 1: Triage test failure
pytest 2>&1 | npx @ismaelsoilet/jev-harness test-gate
npm test 2>&1 | npx @ismaelsoilet/jev-harness test-gate
cargo test 2>&1 | npx @ismaelsoilet/jev-harness test-gate

# Gate 2: Abort trajectory check
npx @ismaelsoilet/jev-harness abort-check \
  --step "Rewrite auth module without tests" \
  --history "3 identical circular failures"

# Gate 3: Route model tier
npx @ismaelsoilet/jev-harness route \
  --task "Implement distributed consensus algorithm"

# Gate 4: Verify step completion
npx @ismaelsoilet/jev-harness verify \
  --criteria "All tests pass, coverage > 90%" \
  --output "22/22 tests passed, coverage: 94%"

# Gate 5: Modulate reasoning effort
npx @ismaelsoilet/jev-harness effort \
  --context "Run git diff and report changes" \
  --provider openai

# Start MCP server
npx @ismaelsoilet/jev-harness mcp

# Show session telemetry
npx @ismaelsoilet/jev-harness metrics

Exit codes: 0 = safe/deterministic action; 1 = needs LLM or abort; 2 = invalid arguments.

Bun & Deno

Bun — fully supported, no configuration required:

// Works identically with Bun's native fetch
import { triageTestFailure } from "@ismaelsoilet/jev-harness";
const result = await triageTestFailure(failureLog);

Deno — use the npm specifier:

import { triageTestFailure } from "npm:@ismaelsoilet/jev-harness";
const result = await triageTestFailure(failureLog);

The TypeScript package is pure native ESM with zero runtime dependencies, making it safe for any Node.js-compatible runtime.

Rust Crate

Cargo.toml

[dependencies]
jev-harness = "0.1.6"
tokio = { version = "1.38", features = ["macros", "rt-multi-thread"] }

Full Example

use jev_harness::{
    JevClient,
    triage_test_failure,
    should_abort_trajectory,
    route_model_tier,
    verify_step_completion,
    modulate_reasoning_effort,
};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Client auto-resolves credentials from env / .jev.json / ~/.config/jev/credentials.env
    let client = JevClient::default();
    println!("Provider: {}, Live: {}", client.provider, client.is_live());

    // Gate 1: Triage test failure
    let traceback = "error[E0463]: can't find crate for `serde`\n --> src/main.rs:1:5";
    let triage = triage_test_failure(traceback, Some(&client)).await?;
    println!("Category:  {}", triage.category);         // env_missing
    println!("Skip LLM:  {}", triage.skip_llm);         // true
    println!("Action:    {}", triage.action_recommendation);

    // Gate 2: Abort trajectory check
    let abort = should_abort_trajectory(
        "Retry identical approach for the 4th time",
        Some("3 identical failures with ECONNRESET"),
        Some(&client),
    ).await?;
    println!("Should abort: {}", abort.should_abort);   // true
    println!("Action:       {}", abort.action);          // abort_and_ask

    // Gate 3: Route model tier
    let route = route_model_tier(
        "Format source files with rustfmt",
        Some(&client),
    ).await?;
    println!("Tier:  {}", route.selected_tier);          // deterministic
    println!("Model: {}", route.recommended_model);

    // Gate 4: Verify step completion
    let verify = verify_step_completion(
        "All 122 tests must pass",
        "cargo test: 122 passed; 0 failed in 2.31s",
        Some(&client),
    ).await?;
    println!("Verified:     {}", verify.is_verified);    // true
    println!("Rigor score:  {}", verify.rigor_score);

    // Gate 5: Modulate reasoning effort (Astra-Jev)
    let effort = modulate_reasoning_effort(
        "Implement a lock-free concurrent queue using atomics",
        "openai",
        None,  // model
        0,     // session_context_tokens
        Some(&client),
    ).await?;
    println!("Effort: {}", effort.effort);               // 'high'
    println!("Params: {}", effort.provider_params);      // {"reasoning_effort":"high"}

    Ok(())
}

Standalone CLI Binaries

Install the two CLI binaries directly from crates.io:

cargo install jev-harness

This installs two binaries:

Binary	Alias for	Usage
`jev`	Short alias	`pytest 2>&1 \| jev test-gate`
`jev-harness`	Full name	`jev-harness abort-check --step "..."`

Both binaries support identical subcommands: test-gate, abort-check, route, verify, effort, mcp, metrics.

Tauri Backend Integration

// src-tauri/src/main.rs
use jev_harness::{JevClient, triage_test_failure};
use tauri::command;

#[command]
async fn triage_error(failure_log: String) -> Result<String, String> {
    let client = JevClient::default();
    let result = triage_test_failure(&failure_log, Some(&client))
        .await
        .map_err(|e| e.to_string())?;
    Ok(format!(
        "category={}, skip_llm={}, action={}",
        result.category, result.skip_llm, result.action_recommendation
    ))
}

fn main() {
    tauri::Builder::default()
        .invoke_handler(tauri::generate_handler![triage_error])
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

MCP Tools

Jev Harness exposes a stdio MCP server (JSON-RPC 2.0, protocol version 2024-11-05) compatible with Cursor, Claude Desktop, Antigravity IDE, Windsurf, Zed, OpenCode, and any MCP-compliant AI agent.

Start the MCP server:

# Python
jev-harness mcp

# TypeScript / npx
npx @ismaelsoilet/jev-harness mcp

# Rust binary
jev mcp

MCP config snippet (.cursor/mcp.json, claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "jev-harness": {
      "command": "npx",
      "args": ["-y", "@ismaelsoilet/jev-harness", "mcp"]
    }
  }
}

Tool 1: `jev_triage_test_failure`

Triages a test traceback, compile error, or runtime failure using Jev System One (70–300 ms, zero autoregressive generation). Returns root cause category, skip_llm flag, and immediate action recommendation.

Input schema:

{
  "type": "object",
  "properties": {
    "failure_log": {
      "type": "string",
      "description": "Raw test failure output, stack trace, or compiler error log."
    }
  },
  "required": ["failure_log"]
}

Response fields:

{
  "category": "env_missing",
  "confidence": 0.95,
  "skip_llm": true,
  "skip_llm_prob": 0.97,
  "severity_score": 1.0,
  "recommendation": "AUTO-ACTION: Install missing dependency or check environment configuration (Do NOT call LLM).",
  "is_mock": false
}

Tool 2: `jev_abort_check`

Guards against doom loops, dead-ends, circular retries, and destructive refactors. Evaluates the proposed plan against recent attempt history before burning frontier tokens.

Input schema:

{
  "type": "object",
  "properties": {
    "proposed_step": {
      "type": "string",
      "description": "The next proposed plan, code modification, or architectural direction."
    },
    "recent_attempts_summary": {
      "type": "string",
      "description": "Summary of previous failed attempts, errors encountered, or circular patterns."
    }
  },
  "required": ["proposed_step"]
}

Response fields:

{
  "should_abort": true,
  "abort_probability": 0.88,
  "action": "abort_and_ask",
  "viability_score": 1.0,
  "reasoning_summary": "Abort recommended (prob=0.88)",
  "is_mock": false
}

Tool 3: `jev_route_task`

Routes a programming task to the minimal sufficient model tier (deterministic script, lightweight flash model, or heavy frontier reasoning model) to optimize cost and latency.

Input schema:

{
  "type": "object",
  "properties": {
    "task_description": {
      "type": "string",
      "description": "Clear description of the task, bug to fix, or feature to implement."
    }
  },
  "required": ["task_description"]
}

Response fields:

{
  "selected_tier": "lightweight_system2",
  "confidence": 0.92,
  "complexity_score": 2.0,
  "recommended_model": "Gemini 3.8 Flash (~$0.75 in / $3.75 out per 1M tokens)",
  "rationale": "Task is bounded and straightforward; save frontier tokens.",
  "is_mock": false
}

Tool 4: `jev_verify_completion`

Calibrates step completion against acceptance criteria using typed rubric scoring. Checks if evidence is sufficient to declare done without launching expensive extra review loops.

Input schema:

{
  "type": "object",
  "properties": {
    "acceptance_criteria": {
      "type": "string",
      "description": "Explicit requirements, constraints, or definition of done."
    },
    "produced_output": {
      "type": "string",
      "description": "The evidence, test results, code diff, or output produced."
    }
  },
  "required": ["acceptance_criteria", "produced_output"]
}

Response fields:

{
  "is_verified": true,
  "satisfaction_probability": 0.94,
  "rigor_score": 3.5,
  "confidence": 0.91,
  "needs_rework": false,
  "is_mock": false
}

Tool 5: `jev_modulate_reasoning_effort`

Dynamically modulates reasoning effort (low, medium, high) for the immediate generation step. Maps exact parameters for OpenAI (GPT-6 Astra/o3), DeepSeek (V4.1-Flash/R1), Qwen (3.8 Max), Anthropic (Claude Fable 5.1), and Gemini (3.8 Thinking). Eliminates reasoning token waste and cuts multi-minute delays on mechanical tool calls.

Input schema:

{
  "type": "object",
  "properties": {
    "context": {
      "type": "string",
      "description": "The command, prompt, or next step to evaluate."
    },
    "provider": {
      "type": "string",
      "description": "Target provider (openai, deepseek, qwen, anthropic, gemini, kimi, mimo). Default: openai."
    },
    "model": {
      "type": "string",
      "description": "Optional model identifier to check for direct non-reasoning compatibility."
    },
    "session_context_tokens": {
      "type": "integer",
      "description": "Optional active prompt tokens in session context to evaluate prompt cache risk."
    }
  },
  "required": ["context"]
}

Response fields:

{
  "effort": "high",
  "confidence": 0.91,
  "complexity_score": 3.5,
  "rationale": "Configured Anthropic Adaptive Thinking (effort='high')...",
  "provider": "anthropic",
  "provider_params": { "thinking": { "type": "adaptive" } },
  "is_reasoning_supported": true,
  "cache_safe_recommendation": "Keep reasoning effort stable across related sub-steps to preserve Prompt Cache (KV Cache).",
  "is_mock": false
}

Tool 6: `jev_get_telemetry`

Returns cumulative session telemetry: total gate calls, LLM calls skipped, abort guards triggered, and estimated token/cost savings across the current agent session.

Input schema:

{
  "type": "object",
  "properties": {},
  "required": []
}

Response fields:

{
  "total_triage_calls": 14,
  "skipped_llm_calls": 11,
  "abort_guards_triggered": 2,
  "deterministic_routes": 5,
  "effort_modulations": 23,
  "estimated_tokens_saved": 487400,
  "estimated_cost_saved_usd": 6.47,
  "is_mock": false
}

Jev Harness v0.1.6 · MIT License · GitHub · PyPI · npm · Crates.io

Report a Bug | Discussions | AGENTS.md

⚡ Jev Harness

Navigation / Navegação

🇬🇧 English

🏠 Home

Getting Started

Gates Reference

Integrations

SDK Reference

CI/CD

📋 Changelog

🇧🇷 Português

🏠 Início

Começando

Referência dos Gates

Integrações

🔌 Todos os IDEs & Agentes

SDK

CI/CD

🔁 GitHub Actions

📋 Changelog

v0.1.6 — MIT License

SDK Reference

SDK Reference

Table of Contents

Python SDK

Installation

Full Import

JevClient

triage_test_failure()

should_abort_trajectory()

route_model_tier()

verify_step_completion()

modulate_reasoning_effort()

Session Telemetry

Provider Configuration

Framework Integrations

LangChain

LlamaIndex

CrewAI

AutoGen

TypeScript / Node.js SDK

Installation

ESM Import

triageTestFailure()

shouldAbortTrajectory()

routeModelTier()

verifyStepCompletion()

modulateReasoningEffort()

CLI Usage

Bun & Deno

Rust Crate

Cargo.toml

Full Example

Standalone CLI Binaries

Tauri Backend Integration

MCP Tools

Tool 1: jev_triage_test_failure

Tool 2: jev_abort_check

Tool 3: jev_route_task

Tool 4: jev_verify_completion

Tool 5: jev_modulate_reasoning_effort

Tool 6: jev_get_telemetry

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

⚡ Jev Harness

🇬🇧 English

🇧🇷 Português

Clone this wiki locally

`triage_test_failure()`

`should_abort_trajectory()`

`route_model_tier()`

`verify_step_completion()`

`modulate_reasoning_effort()`

`triageTestFailure()`

`shouldAbortTrajectory()`

`routeModelTier()`

`verifyStepCompletion()`

`modulateReasoningEffort()`

Tool 1: `jev_triage_test_failure`

Tool 2: `jev_abort_check`

Tool 3: `jev_route_task`

Tool 4: `jev_verify_completion`

Tool 5: `jev_modulate_reasoning_effort`

Tool 6: `jev_get_telemetry`