Decision Audit Trails with Jev: Every Answer Logged, Replayed, Explainable

import logging
import os

import requests

logger = logging.getLogger("decisions")

def decide_with_chat_model(customer_id: str, case: dict) -> str:
    resp = requests.post(
        "https://api.openai.com/v1/chat/completions",
        headers={"Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}"},
        json={
            "model": "gpt-4o-mini",
            "messages": [{
                "role": "user",
                "content": f"Decide this case under policy v3. Reply with the decision and a one-paragraph rationale.\nCase: {case}",
            }],
        },
        timeout=30,
    )
    decision_text = resp.json()["choices"][0]["message"]["content"]

    # What the audit log gets: a paragraph. It cannot be thresholded,
    # replayed, or explained — only re-read. Which prompt version made
    # this call? Was "likely approve" a 0.8 of confidence? The log
    # cannot say, because none of it was recorded.
    logger.info("decision for %s: %s", customer_id, decision_text)
    return decision_text

import hashlib
import json

import requests

JEV_ENDPOINT = "https://api.typesafe.ai/v1/jev/evaluate"
AUTO_EXECUTE_CONFIDENCE = 0.85  # >= gate AND reversibility <= 2 -> auto
HUMAN_CONFIDENCE = 0.60         # below this, or reversibility 4 -> human

QUESTIONS = {
    "decision": {
        "type": "choice",
        "instructions": "Decide the case under the published policy",
        "criteria": {
            "approve": "Meets every policy condition — no discretionary judgment",
            "refer": "Meets most conditions but a stated edge applies",
            "deny": "Fails a hard condition — name the failed criterion",
        },
    },
    "reversibility": {
        "type": "score",
        "instructions": "If wrong, how costly to reverse? 1 = trivial, 4 = irreversible harm to a person",
    },
    "needs_human_review": {
        "type": "noul",
        "instructions": "Should a human confirm before this decision takes effect?",
    },
}

def decide_and_record(subject_ref: str, state: dict) -> dict:
    payload = {"state": state, "questions": QUESTIONS}
    resp = requests.post(JEV_ENDPOINT, json=payload, timeout=5)
    resp.raise_for_status()
    data = resp.json()

    decision = data["decision"]
    reversibility = data["reversibility"]["answer"]
    if data["needs_human_review"]["answer"] or reversibility == 4:
        lane = "human_decision"
    elif decision["confidence"] >= AUTO_EXECUTE_CONFIDENCE and reversibility <= 2:
        lane = "auto_executed"
    else:
        lane = "review_queue"

    # The record is the audit trail: contract, answer, gate — one
    # fixed-size row, replayable under any future schema version.
    return {
        "subject_ref": subject_ref,
        "decision": decision["answer"],
        "confidence": decision["confidence"],
        "reversibility": reversibility,
        "lane": lane,
        "logic": {
            "schema_version": "audit-contract@1.3.0",
            "questions_hash": hashlib.sha256(
                json.dumps(payload["questions"], sort_keys=True).encode()
            ).hexdigest()[:16],
            "model_version": "jev-1.13",
        },
        "human_intervention_path": (
            "available_on_request"
            if lane == "auto_executed"
            else "mandatory_before_effect"
        ),
    }

import { z } from "zod";
import OpenAI from "openai";

const Decision = z.object({ decision: z.enum(["approve", "refer", "deny"]) });
const openai = new OpenAI();

export async function decideCase(caseData: unknown) {
  const resp = await openai.chat.completions.create({
    model: "gpt-4o-mini",
    response_format: { type: "json_object" },
    messages: [
      { role: "user", content: `Decide under policy v3: ${JSON.stringify(caseData)}` },
    ],
  });
  const { decision } = Decision.parse(
    JSON.parse(resp.choices[0].message.content!),
  );

  // The shape is guaranteed; the evidence is not. No confidence, no
  // schema version, no distribution — an audit six months from now
  // gets the what but never the why or the how-often-right.
  return { decision, auditRecord: { decision } };
}

const JEV_ENDPOINT = "https://api.typesafe.ai/v1/jev/evaluate";
const AUTO_EXECUTE_CONFIDENCE = 0.85; // gate AND reversibility <= 2
const HUMAN_CONFIDENCE = 0.6; // below, or reversibility 4 -> human

type Lane = "auto_executed" | "review_queue" | "human_decision";

const QUESTIONS = {
  decision: {
    type: "choice",
    instructions: "Decide the case under the published policy",
    criteria: {
      approve: "Meets every policy condition",
      refer: "A stated edge applies — queue with a reason",
      deny: "Fails a hard condition — name it",
    },
  },
  reversibility: {
    type: "score",
    instructions: "If wrong, how costly to reverse? 1 = trivial, 4 = irreversible harm",
  },
  needs_human_review: {
    type: "noul",
    instructions: "Should a human confirm before this takes effect?",
  },
} as const;

export async function decideAndRecord(subjectRef: string, state: object) {
  const resp = await fetch(JEV_ENDPOINT, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ state, questions: QUESTIONS }),
  });
  if (!resp.ok) throw new Error("Jev evaluate failed");
  const data = await resp.json();

  const { answer, confidence } = data.decision as {
    answer: string;
    confidence: number;
  };
  const reversibility = data.reversibility.answer as number;
  const lane: Lane =
    data.needs_human_review.answer || reversibility === 4
      ? "human_decision"
      : confidence >= AUTO_EXECUTE_CONFIDENCE && reversibility <= 2
        ? "auto_executed"
        : "review_queue";

  return {
    subject_ref: subjectRef,
    decision: answer,
    confidence,
    reversibility,
    lane,
    logic: { schema_version: "audit-contract@1.3.0", model_version: "jev-1.13" },
    human_intervention_path:
      lane === "auto_executed" ? "available_on_request" : "mandatory_before_effect",
  };
}
// Art. 22 record = this object. Replay = re-post the stored state under
// a new schema version and diff the lanes.