eduevidence 6.2.0 → 6.3.0

package/integrations/jev/__init__.py

@@ -0,0 +1,115 @@
+"""integrations.jev — Jev (TypeSafe System One) experimental Tier-0 package.
+
+Experimental only (`--experimental` / mode 1 or 3). Never a scientific gate
+replacement. Public API is re-exported here and via integrations/jev_mcp.py.
+
+Providers: freejev (FREEJEV_API_KEY + JEV_PROVIDER=freejev, MCP
+https://freejev.org/mcp, request_id never retried) or vercel (default).
+Fail-closed: invalid / provider errors escalate to the large model.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .approval import (
+    build_approval_record,
+    detect_jev_mcp,
+    is_approval_current,
+    load_approval,
+    require_jev_mcp,
+    write_approval,
+)
+from .cli import npx_mcp_guide
+from .config import (
+    DEFAULT_MODEL,
+    ESCALATE_TO_LLM,
+    JEV_APPROVAL_PATH,
+    JEV_APPROVAL_REQUIRED,
+    JEV_ENV_FILE,
+    JEV_INVALID_RESPONSE,
+    JEV_PROVIDER_ERROR,
+    JEV_UNAVAILABLE,
+    MCP_JEV_TOOLS,
+    MODE_HYBRID,
+    MODE_JEV_MCP,
+    MODE_SEMDECIDE,
+    MODE_STANDARD,
+    NPM_JEV_MCP,
+    THRESHOLDS,
+    TIER0_TOOLS,
+    VERCEL_TYPE_SAFE_BASE,
+    api_key,
+    model_id,
+    provider,
+    system_one_url,
+)
+from .gateway import system_one
+from .modes import resolve_experimental_mode
+from .tools_classify import classify
+from .tools_extract import extract
+from .tools_rerank import rerank
+from .tools_screen import screen
+from .tools_verify import verify
+
+# Map capability_id -> wrapper (engine/capabilities.py experimental set).
+CAPABILITY_TO_TOOL = {
+    "content_screen": screen,
+    "semantic_rerank": rerank,
+    "field_extract": extract,
+    "classify_check": classify,
+    "claim_verify": verify,
+}
+
+
+def safe_call(capability_id: str, *args: Any,
+              approval: dict[str, Any] | None = None,
+              **kwargs: Any) -> dict[str, Any]:
+    """Capability-routed Tier-0 call with the approval gate applied."""
+    fn = CAPABILITY_TO_TOOL.get(capability_id)
+    if fn is None:
+        return {"status": JEV_INVALID_RESPONSE,
+                "error": f"unknown capability {capability_id!r}",
+                "escalate": ESCALATE_TO_LLM}
+    kwargs.setdefault("approval", approval)
+    return fn(*args, **kwargs)
+
+
+__all__ = [
+    "CAPABILITY_TO_TOOL",
+    "DEFAULT_MODEL",
+    "ESCALATE_TO_LLM",
+    "JEV_APPROVAL_PATH",
+    "JEV_APPROVAL_REQUIRED",
+    "JEV_ENV_FILE",
+    "JEV_INVALID_RESPONSE",
+    "JEV_PROVIDER_ERROR",
+    "JEV_UNAVAILABLE",
+    "MCP_JEV_TOOLS",
+    "MODE_HYBRID",
+    "MODE_JEV_MCP",
+    "MODE_SEMDECIDE",
+    "MODE_STANDARD",
+    "NPM_JEV_MCP",
+    "THRESHOLDS",
+    "TIER0_TOOLS",
+    "VERCEL_TYPE_SAFE_BASE",
+    "api_key",
+    "build_approval_record",
+    "classify",
+    "detect_jev_mcp",
+    "extract",
+    "is_approval_current",
+    "load_approval",
+    "model_id",
+    "npx_mcp_guide",
+    "provider",
+    "require_jev_mcp",
+    "rerank",
+    "resolve_experimental_mode",
+    "safe_call",
+    "screen",
+    "system_one",
+    "system_one_url",
+    "verify",
+    "write_approval",
+]

package/integrations/jev/approval.py

@@ -0,0 +1,212 @@
+"""Availability detect + user approval gate (~/.eduevidence/jev_mcp_approval.json)."""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .config import (
+    JEV_APPROVAL_PATH,
+    JEV_APPROVAL_REQUIRED,
+    JEV_UNAVAILABLE,
+    MCP_JEV_TOOLS,
+    MODE_JEV_MCP,
+    NPM_JEV_MCP,
+    TIER0_TOOLS,
+    THRESHOLDS,
+    api_key,
+    model_id,
+    provider,
+    system_one_url,
+)
+
+
+def detect_jev_mcp() -> dict[str, Any]:
+    """Probe Jev gateway credentials and (optional) local MCP binary.
+
+    Providers: freejev (FREEJEV_API_KEY + JEV_PROVIDER=freejev; MCP
+    https://freejev.org/mcp; request_id never retried) or vercel (default).
+
+    States:
+      - available: provider key present and provider is supported
+      - mcp_documented: key missing but npx/node present (documented path only)
+      - unavailable: neither usable transport
+    """
+    key = api_key()
+    prov = provider()
+    reasons: list[str] = []
+    has_npx = any(
+        os.path.exists(os.path.join(d, "npx"))
+        for d in os.environ.get("PATH", "").split(os.pathsep) if d
+    )
+
+    if not key:
+        reasons.append("AI_GATEWAY_API_KEY not set in env or ~/.eduevidence/env")
+    if prov not in ("vercel", "typesafe", "compatible", "openrouter", "cloudflare",
+                    "freejev"):
+        reasons.append(f"unsupported JEV_PROVIDER={prov!r}")
+
+    if key and prov in ("vercel", "typesafe", "compatible", "openrouter", "cloudflare",
+                        "freejev"):
+        state = "available"
+        available = True
+        mode = "jev_gateway"
+        hint = ""
+    elif has_npx:
+        state = "mcp_documented"
+        available = False
+        mode = "mcp_documented"
+        hint = (f"Gateway key missing — register MCP server via `{NPM_JEV_MCP}` "
+                "in the host agent, or set AI_GATEWAY_API_KEY + JEV_PROVIDER=vercel "
+                "in ~/.eduevidence/env")
+    else:
+        state = "unavailable"
+        available = False
+        mode = "none"
+        hint = "Install Node 20+ for MCP path, or configure Vercel AI Gateway key"
+
+    return {
+        "available": available,
+        "state": state,
+        "mode": mode,
+        "provider": prov if key else None,
+        "model": model_id() if key else None,
+        "endpoint": system_one_url() if key else None,
+        "reason": "; ".join(reasons) or "gateway credentials present",
+        "reasons": reasons,
+        "hint": hint,
+        "tier0_tools": list(TIER0_TOOLS),
+        "mcp_alternate": {
+            "command": NPM_JEV_MCP,
+            "tools": dict(MCP_JEV_TOOLS),
+            "env": ["TYPESAFE_API_KEY or AI_GATEWAY_API_KEY", "JEV_PROVIDER"],
+        },
+        "thresholds": dict(THRESHOLDS),
+    }
+
+
+def require_jev_mcp() -> dict[str, Any]:
+    report = detect_jev_mcp()
+    if not report["available"]:
+        raise RuntimeError(JEV_UNAVAILABLE)
+    return report
+
+
+def _tools_hash(tools: tuple[str, ...] | list[str]) -> str:
+    payload = json.dumps(sorted(tools), ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def build_approval_record(
+    tools: list[str] | tuple[str, ...] = TIER0_TOOLS,
+    *,
+    provider_name: str | None = None,
+    model: str | None = None,
+    mode: int = MODE_JEV_MCP,
+) -> dict[str, Any]:
+    """Build the approval record the user confirms before any network call."""
+    selected = tuple(sorted({str(t) for t in tools if str(t) in TIER0_TOOLS}))
+    return {
+        "approved": True,
+        "approved_at": datetime.now(timezone.utc).isoformat(),
+        "mode": int(mode),
+        "provider": provider_name or provider(),
+        "model": model or model_id(),
+        "tools": list(selected),
+        "tools_hash": _tools_hash(selected),
+        "endpoint": system_one_url(),
+        "schema_version": 1,
+    }
+
+
+def write_approval(path: str | Path | None = None, **kwargs: Any) -> dict[str, Any]:
+    record = build_approval_record(**kwargs)
+    out = Path(os.path.expanduser(path or JEV_APPROVAL_PATH))
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(json.dumps(record, ensure_ascii=False, indent=2) + "\n",
+                   encoding="utf-8")
+    return record
+
+
+def load_approval(path: str | Path | None = None) -> dict[str, Any] | None:
+    try:
+        return json.loads(
+            Path(os.path.expanduser(path or JEV_APPROVAL_PATH)).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def is_approval_current(
+    approval: dict[str, Any] | None,
+    tools: list[str] | tuple[str, ...] = TIER0_TOOLS,
+    *,
+    provider_name: str | None = None,
+    model: str | None = None,
+    mode: int | None = None,
+    path: str | Path | None = None,
+) -> tuple[bool, list[str]]:
+    """True when the approval still matches the current proposal.
+
+    ``path`` names the approval file to re-read from disk; ``None`` means the
+    configured one (``~/.eduevidence/jev_mcp_approval.json`` or
+    ``JEV_APPROVAL_PATH``). An explicitly empty/missing path is never treated
+    as "current": the disk check below still fails closed, so an in-memory
+    record cannot pass because the file could not be read.
+    """
+    changes: list[str] = []
+    if not approval or not approval.get("approved"):
+        changes.append("approval missing or not approved")
+        return False, changes
+    stored = tuple(sorted(approval.get("tools") or []))
+    if approval.get("tools_hash") != _tools_hash(stored):
+        changes.append("approval file tampered (tools_hash mismatch)")
+    wanted = tuple(sorted({str(t) for t in tools if str(t) in TIER0_TOOLS}))
+    if wanted != stored:
+        changes.append("tool set changed")
+    if provider_name is not None and approval.get("provider") != provider_name:
+        changes.append("provider changed")
+    elif provider_name is None and approval.get("provider") != provider():
+        changes.append("provider changed")
+    if model is not None and approval.get("model") != model:
+        changes.append("model changed")
+    elif model is None and approval.get("model") != model_id():
+        changes.append("model changed")
+    if mode is not None and int(approval.get("mode", -1)) != int(mode):
+        changes.append("experimental mode changed")
+    disk = load_approval(path)
+    if not disk:
+        changes.append("approval file missing on disk")
+    elif disk.get("tools_hash") != approval.get("tools_hash"):
+        changes.append("approval file tampered (disk tools_hash mismatch)")
+    return (not changes), changes
+
+
+def _check_approval(approval: dict[str, Any] | None, tool: str) -> str | None:
+    """None when allowed, else JEV_APPROVAL_REQUIRED. Fail closed.
+
+    Accepts only records that still match the on-disk approval file.
+    In-memory forged dicts are rejected. Provider/endpoint must match live
+    config exactly — no vercel bypass.
+    """
+    if not approval or not approval.get("approved"):
+        return JEV_APPROVAL_REQUIRED
+    stored = tuple(sorted(approval.get("tools") or []))
+    if approval.get("tools_hash") != _tools_hash(stored):
+        return JEV_APPROVAL_REQUIRED
+    if tool not in TIER0_TOOLS or tool not in stored:
+        return JEV_APPROVAL_REQUIRED
+    disk = load_approval()
+    if not disk or not disk.get("approved"):
+        return JEV_APPROVAL_REQUIRED
+    if disk.get("tools_hash") != approval.get("tools_hash"):
+        return JEV_APPROVAL_REQUIRED
+    if tuple(sorted(disk.get("tools") or [])) != stored:
+        return JEV_APPROVAL_REQUIRED
+    if approval.get("provider") != provider():
+        return JEV_APPROVAL_REQUIRED
+    if approval.get("endpoint") and approval.get("endpoint") != system_one_url():
+        return JEV_APPROVAL_REQUIRED
+    return None

package/integrations/jev/cli.py

@@ -0,0 +1,84 @@
+"""CLI: --experimental / --approve / --mcp-guide (npx @jkudish/jev-mcp path)."""
+from __future__ import annotations
+
+import argparse
+import json
+from typing import Any
+
+from .approval import detect_jev_mcp, write_approval
+from .config import (
+    MCP_JEV_TOOLS,
+    MODE_HYBRID,
+    MODE_JEV_MCP,
+    MODE_STANDARD,
+    NPM_JEV_MCP,
+    TIER0_TOOLS,
+)
+from .modes import resolve_experimental_mode
+
+
+def npx_mcp_guide() -> dict[str, Any]:
+    """Documented alternate: host-registered @jkudish/jev-mcp MCP server."""
+    return {
+        "command": NPM_JEV_MCP,
+        "requires": ["Node.js >= 20", "TYPESAFE_API_KEY or AI_GATEWAY_API_KEY"],
+        "env": {
+            "AI_GATEWAY_API_KEY": "set in ~/.eduevidence/env — never commit",
+            "JEV_PROVIDER": "vercel | freejev",
+            "TYPESAFE_API_KEY": "optional direct TypeSafe key",
+            "FREEJEV_API_KEY": "FreeJev key when JEV_PROVIDER=freejev",
+        },
+        "freejev": {
+            "mcp": "https://freejev.org/mcp",
+            "decide": "https://freejev.org/api/v1/decide",
+            "request_id": "idempotency key — never retry the same request_id",
+        },
+        "client_snippets": {
+            "claude_code": "claude mcp add jev -- npx -y @jkudish/jev-mcp",
+            "generic_json": {
+                "mcpServers": {
+                    "jev": {
+                        "command": "npx",
+                        "args": ["-y", "@jkudish/jev-mcp"],
+                        "env": {"TYPESAFE_API_KEY": "<from ~/.eduevidence/env>"},
+                    }
+                }
+            },
+        },
+        "tools": dict(MCP_JEV_TOOLS),
+        "note": "MCP path is host-side; this module only documents it and does "
+                "not spawn or migrate jev-mcp implementation.",
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Jev experimental detect / approve / Tier-0 probe")
+    parser.add_argument("--experimental", nargs="?", const="1", default=None,
+                        metavar="MODE",
+                        help="enable experimental mode 0|1|2|3 (default 1) and "
+                             "print the resolved plan")
+    parser.add_argument("--approve", action="store_true",
+                        help="write ~/.eduevidence/jev_mcp_approval.json for "
+                             "the current provider/model/tools")
+    parser.add_argument("--mcp-guide", action="store_true",
+                        help="print the documented npx @jkudish/jev-mcp path")
+    args = parser.parse_args(argv)
+
+    out: dict[str, Any] = {"detect": detect_jev_mcp()}
+    mode = resolve_experimental_mode(args.experimental)
+    if args.experimental is not None:
+        out["experimental"] = {
+            "mode": mode,
+            "mode_name": {0: "standard", 1: "jev-mcp", 2: "semdecide",
+                          3: "hybrid"}.get(mode, str(mode)),
+            "enabled": mode != MODE_STANDARD,
+            "tier0_tools": list(TIER0_TOOLS) if mode in (MODE_JEV_MCP, MODE_HYBRID) else [],
+            "fail_closed": "uncertain / invalid / provider errors escalate to large model",
+        }
+    if args.approve:
+        out["approval"] = write_approval()
+    if args.mcp_guide:
+        out["mcp_alternate"] = npx_mcp_guide()
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+    return 0

package/integrations/jev/config.py

@@ -0,0 +1,112 @@
+"""Jev env / paths / constants (real env > ~/.eduevidence/env > default).
+
+Providers (Mode 1 / 3):
+  - freejev: FREEJEV_API_KEY + JEV_PROVIDER=freejev
+             Decide: https://freejev.org/api/v1/decide
+             MCP (documented only): https://freejev.org/mcp
+             request_id is an idempotency key — NEVER retry the same request_id;
+             fail-closed escalate this call (new ask => new request_id).
+  - vercel (default): AI_GATEWAY_API_KEY or TYPESAFE_API_KEY + JEV_PROVIDER=vercel
+             Decide: https://ai-gateway.vercel.sh/typesafe/v1/systemone
+             MCP (documented only): npx -y @jkudish/jev-mcp
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+JEV_ENV_FILE = os.environ.get("JEV_ENV_FILE", "~/.eduevidence/env")
+JEV_APPROVAL_PATH = os.environ.get(
+    "JEV_APPROVAL_FILE", "~/.eduevidence/jev_mcp_approval.json")
+
+JEV_UNAVAILABLE = "JEV_UNAVAILABLE"
+JEV_APPROVAL_REQUIRED = "JEV_APPROVAL_REQUIRED"
+JEV_INVALID_RESPONSE = "JEV_INVALID_RESPONSE"
+JEV_PROVIDER_ERROR = "JEV_PROVIDER_ERROR"
+ESCALATE_TO_LLM = "ESCALATE_TO_LLM"
+
+MODE_STANDARD = 0
+MODE_JEV_MCP = 1
+MODE_SEMDECIDE = 2
+MODE_HYBRID = 3
+
+TIER0_TOOLS = ("screen", "rerank", "extract", "classify", "verify")
+
+VERCEL_TYPE_SAFE_BASE = "https://ai-gateway.vercel.sh/typesafe"
+FREEJEV_DECIDE_URL = "https://freejev.org/api/v1/decide"
+FREEJEV_MCP_URL = "https://freejev.org/mcp"
+DEFAULT_MODEL = "typesafe-ai/jev"
+
+NPM_JEV_MCP = "npx -y @jkudish/jev-mcp"
+MCP_JEV_TOOLS = {
+    "screen": "jev_screen",
+    "rerank": "jev_rerank",
+    "extract": "jev_extract",
+    "classify": "jev_classify",
+    "verify": "jev_verify",
+}
+
+THRESHOLDS = {
+    "screen_block_at": 0.75,
+    "screen_review_at": 0.25,
+    "verify_auto_accept": 0.80,
+    "classify_auto_accept": 0.85,
+    "classify_minimum_margin": 0.50,
+    "extract_auto_accept": 0.80,
+    "extract_minimum_margin": 0.40,
+    "rerank_auto_accept": 0.70,
+}
+
+
+def _env_file_values(path: str | Path | None = None) -> dict[str, str]:
+    """Parse KEY=VALUE lines from ~/.eduevidence/env (best-effort)."""
+    try:
+        text = Path(os.path.expanduser(path or JEV_ENV_FILE)).read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    values: dict[str, str] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        if line.startswith("export "):
+            line = line[len("export "):]
+        key, _, value = line.partition("=")
+        values[key.strip()] = value.strip().strip("\"'")
+    return values
+
+
+_ENV_FILE_VALUES = _env_file_values()
+
+
+def _effective_env(key: str, default: str = "") -> str:
+    return os.environ.get(key) or _ENV_FILE_VALUES.get(key) or default
+
+
+def provider() -> str:
+    explicit = (_effective_env("JEV_PROVIDER") or "").lower()
+    if explicit:
+        return explicit
+    if _effective_env("FREEJEV_API_KEY") and not (
+            _effective_env("AI_GATEWAY_API_KEY")
+            or _effective_env("TYPESAFE_API_KEY")):
+        return "freejev"
+    return "vercel"
+
+
+def api_key() -> str:
+    """Gateway / provider key. Never log or commit this value."""
+    return (_effective_env("AI_GATEWAY_API_KEY")
+            or _effective_env("TYPESAFE_API_KEY")
+            or _effective_env("FREEJEV_API_KEY"))
+
+
+def model_id() -> str:
+    return _effective_env("JEV_MCP_MODEL", DEFAULT_MODEL) or DEFAULT_MODEL
+
+
+def system_one_url() -> str:
+    if provider() == "freejev":
+        return FREEJEV_DECIDE_URL
+    base = _effective_env("JEV_TYPE_SAFE_BASE", VERCEL_TYPE_SAFE_BASE).rstrip("/")
+    return f"{base}/v1/systemone"

package/integrations/jev/gateway.py

@@ -0,0 +1,128 @@
+"""System One transport (stdlib urllib only) + provider error mapping."""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Any
+
+from .approval import _check_approval, detect_jev_mcp, load_approval
+from .config import (
+    ESCALATE_TO_LLM,
+    JEV_APPROVAL_REQUIRED,
+    JEV_INVALID_RESPONSE,
+    JEV_PROVIDER_ERROR,
+    JEV_UNAVAILABLE,
+    api_key,
+    model_id,
+    system_one_url,
+)
+
+
+def _http_post_json(url: str, payload: dict[str, Any], *,
+                    timeout: float = 20.0) -> tuple[int, dict[str, Any] | None, str]:
+    """POST JSON with Bearer key. Returns (status, body|None, error)."""
+    key = api_key()
+    if not key:
+        return 0, None, "AI_GATEWAY_API_KEY missing"
+    data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+    req = urllib.request.Request(
+        url, data=data, method="POST",
+        headers={
+            "Authorization": f"Bearer {key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        },
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8", "replace")
+            try:
+                return resp.status, json.loads(raw), ""
+            except json.JSONDecodeError:
+                return resp.status, None, "response is not JSON"
+    except urllib.error.HTTPError as exc:
+        # Never echo Authorization / key fragments.
+        detail = ""
+        try:
+            detail = exc.read().decode("utf-8", "replace")[:400]
+        except OSError:
+            pass
+        return exc.code, None, f"HTTP {exc.code}: {detail}"
+    except (urllib.error.URLError, TimeoutError, OSError) as exc:
+        return 0, None, f"network error: {type(exc).__name__}"
+
+
+def _map_provider_error(status: int) -> str:
+    """Map HTTP status to a fail-closed JEV_* status code."""
+    return (JEV_PROVIDER_ERROR if status in (401, 403, 429, 529) or status >= 500
+            else JEV_INVALID_RESPONSE)
+
+
+def system_one(state: Any, questions: dict[str, Any], *,
+               approval: dict[str, Any] | None,
+               tool: str | None = None,
+               timeout: float = 20.0) -> dict[str, Any]:
+    """UNIFIED network entry. Business code MUST NOT POST directly.
+
+    Gate: approval exists -> tool approved -> credentials present -> POST.
+    Fail-closed: every transport / envelope problem returns a structured
+    error that callers must escalate to the large model (never invent answers).
+
+    FreeJev: any request_id is a one-shot idempotency key — never retry the
+    same request_id after timeout / 5xx / unknown outcome. Escalate instead;
+    a deliberate re-ask must mint a new request_id.
+    """
+    approval = approval if approval is not None else load_approval()
+    if tool is not None:
+        failure = _check_approval(approval, tool)
+        if failure is not None:
+            return {"status": failure, "tool": tool, "answers": None,
+                    "escalate": ESCALATE_TO_LLM}
+    elif not approval or not approval.get("approved"):
+        return {"status": JEV_APPROVAL_REQUIRED, "answers": None,
+                "escalate": ESCALATE_TO_LLM}
+
+    report = detect_jev_mcp()
+    if not report["available"]:
+        return {"status": JEV_UNAVAILABLE, "tool": tool, "answers": None,
+                "escalate": ESCALATE_TO_LLM, "hint": report.get("hint", "")}
+
+    payload = {
+        "model": model_id(),
+        "state": state,
+        "questions": questions,
+    }
+    status, body, err = _http_post_json(system_one_url(), payload, timeout=timeout)
+    if body is None:
+        code = _map_provider_error(status)
+        return {"status": code, "tool": tool, "http_status": status,
+                "error": err, "answers": None, "escalate": ESCALATE_TO_LLM}
+
+    answers = body.get("answers")
+    usage = body.get("usage") or {}
+    if not isinstance(answers, dict):
+        return {"status": JEV_INVALID_RESPONSE, "tool": tool,
+                "error": "missing or non-object answers envelope",
+                "answers": None, "escalate": ESCALATE_TO_LLM}
+    return {
+        "status": "ok",
+        "tool": tool,
+        "model": body.get("model") or model_id(),
+        "answers": answers,
+        "usage": {
+            "input_tokens": usage.get("input_tokens"),
+            "output_tokens": usage.get("output_tokens"),
+        },
+        "escalate": None,
+    }
+
+
+def _prob(value: Any) -> float | None:
+    try:
+        p = float(value)
+    except (TypeError, ValueError):
+        return None
+    if p != p or p < 0.0 or p > 1.0:  # NaN or out of range
+        return None
+    return p

package/integrations/jev/modes.py

@@ -0,0 +1,38 @@
+"""Experimental mode resolution (0|1|2|3)."""
+from __future__ import annotations
+
+from .config import (
+    MODE_HYBRID,
+    MODE_JEV_MCP,
+    MODE_SEMDECIDE,
+    MODE_STANDARD,
+    _effective_env,
+)
+
+
+def resolve_experimental_mode(flag: str | int | bool | None = None) -> int:
+    """Map --experimental / env to mode 0..3.
+
+    Accepts 0|1|2|3, True (=1), None (env EDU_EXPERIMENTAL_JEV, else 0).
+    """
+    if flag is None:
+        flag = _effective_env("EDU_EXPERIMENTAL_JEV", "") or _effective_env(
+            "EXPERIMENTAL", "")
+    if flag is True:
+        return MODE_JEV_MCP
+    if flag is False or flag is None or flag == "":
+        return MODE_STANDARD
+    text = str(flag).strip().lower()
+    if text in ("0", "standard", "off", "false", "none"):
+        return MODE_STANDARD
+    if text in ("1", "jev", "jev-mcp", "jev_mcp", "true", "on"):
+        return MODE_JEV_MCP
+    if text in ("2", "semdecide", "sem"):
+        return MODE_SEMDECIDE
+    if text in ("3", "hybrid"):
+        return MODE_HYBRID
+    try:
+        value = int(text)
+    except ValueError:
+        return MODE_STANDARD
+    return value if value in (0, 1, 2, 3) else MODE_STANDARD