structured-context 0.12.0 → 0.13.0

package/dist/judge/judge-node.d.ts

@@ -0,0 +1,27 @@
+import type { SpaceGraph } from '../space-graph';
+import type { Rule, RuleSeverity, SpaceNode } from '../types';
+import { type TrimReport } from './trim';
+import type { SemanticJudgeProvider } from '../types.js';
+export type NodeJudgement = {
+    rule: Rule;
+    /** True when the verdict fails the rule (it has a severity), or the provider errored. */
+    failed: boolean;
+    /** Severity of the failing verdict; unset for a judge error, which takes the rule's own severity. */
+    severity?: RuleSeverity;
+    verdict?: string;
+    /** User-facing guidance declared for the failing verdict. */
+    guidance?: string;
+    evidence?: string;
+    /** Set when the judge could not produce a verdict for this rule. */
+    error?: string;
+};
+/**
+ * Judge several nodes at once. A judge with `evaluateNodes` gets every input in one call and may fold them into
+ * fewer requests; any other judge is called once per input. A node's rules that share a context (related nodes
+ * and bodies) form one input; an input that cannot fit the per-node input cap is not sent. Results align with
+ * `items`, in rule order. A failure marks only the affected rules as errors.
+ */
+export declare function judgeNodes(judge: SemanticJudgeProvider, items: Array<{
+    node: SpaceNode;
+    rules: Rule[];
+}>, graph: SpaceGraph, report?: TrimReport): Promise<NodeJudgement[][]>;

package/dist/judge/judge-node.js

@@ -0,0 +1,122 @@
+import { judgeContext, ruleContext } from './context';
+import { trimToCap } from './trim';
+import { isJudgeError, resolveSemanticRule } from './verdicts';
+function resolveAll(rules) {
+    return rules.map(resolveSemanticRule);
+}
+function errorJudgements(rules, message) {
+    return rules.map((rule) => ({
+        rule,
+        failed: true,
+        evidence: `Error during evaluation: ${message}`,
+        error: message,
+    }));
+}
+function interpret(rules, resolved, results) {
+    return rules.map((rule, i) => {
+        const result = results[rule.id];
+        if (!result || isJudgeError(result)) {
+            const message = result ? result.error : 'Model provider returned no result for this rule';
+            return { rule, failed: true, evidence: `Error during evaluation: ${message}`, error: message };
+        }
+        const severity = resolved[i].severities[result.verdict];
+        if (severity === undefined && !(result.verdict in resolved[i].spec.verdicts)) {
+            const message = `Model provider returned unknown verdict "${result.verdict}" (allowed: ${Object.keys(resolved[i].spec.verdicts).join(', ')})`;
+            return { rule, failed: true, evidence: `Error during evaluation: ${message}`, error: message };
+        }
+        const failed = severity !== undefined;
+        return {
+            rule,
+            failed,
+            severity,
+            verdict: result.verdict,
+            guidance: failed ? resolved[i].guidance[result.verdict] : undefined,
+            evidence: result.evidence,
+        };
+    });
+}
+const errorMessage = (err) => (err instanceof Error ? err.message : String(err));
+const OVER_CAP_MESSAGE = 'input over the per-node cap after trimming content';
+/**
+ * Split each node's rules into inputs by the context they ask for, trimmed to the per-node input cap; rules that
+ * share a context share an input. Inputs that cannot fit go to `overCap`; trimmed ones are added to `report`.
+ */
+function planUnits(graph, items, report) {
+    const units = [];
+    const overCap = [];
+    items.forEach(({ node, rules }, item) => {
+        const groups = new Map();
+        rules.forEach((rule, position) => {
+            const context = ruleContext(rule);
+            const key = `${context.content}|${context.scope.join(',')}`;
+            const group = groups.get(key) ?? { context, positions: [] };
+            group.positions.push(position);
+            groups.set(key, group);
+        });
+        for (const { context, positions } of groups.values()) {
+            const unitRules = positions.map((p) => rules[p]);
+            const resolved = resolveAll(unitRules);
+            const fitted = trimToCap(judgeContext(graph, node, context));
+            if (!fitted) {
+                overCap.push({ item, positions, rules: unitRules });
+                continue;
+            }
+            if (fitted.trimmed && report) {
+                report.nodes.add(node.label);
+                for (const rule of unitRules)
+                    report.ruleIds.add(rule.id);
+            }
+            units.push({
+                item,
+                positions,
+                rules: unitRules,
+                resolved,
+                input: { ...fitted.input, rules: resolved.map((r) => r.spec) },
+            });
+        }
+    });
+    return { units, overCap };
+}
+/**
+ * Judge several nodes at once. A judge with `evaluateNodes` gets every input in one call and may fold them into
+ * fewer requests; any other judge is called once per input. A node's rules that share a context (related nodes
+ * and bodies) form one input; an input that cannot fit the per-node input cap is not sent. Results align with
+ * `items`, in rule order. A failure marks only the affected rules as errors.
+ */
+export async function judgeNodes(judge, items, graph, report) {
+    const { units, overCap } = planUnits(graph, items, report);
+    const out = items.map(({ rules }) => new Array(rules.length));
+    const place = (unit, judgements) => {
+        unit.positions.forEach((position, k) => {
+            out[unit.item][position] = judgements[k];
+        });
+    };
+    for (const slot of overCap)
+        place(slot, errorJudgements(slot.rules, OVER_CAP_MESSAGE));
+    if (!judge.evaluateNodes) {
+        for (const unit of units) {
+            try {
+                place(unit, interpret(unit.rules, unit.resolved, await judge.evaluate(unit.input)));
+            }
+            catch (err) {
+                place(unit, errorJudgements(unit.rules, errorMessage(err)));
+            }
+        }
+        return out;
+    }
+    if (units.length === 0)
+        return out;
+    let perInput;
+    try {
+        perInput = await judge.evaluateNodes(units.map((u) => u.input));
+    }
+    catch (err) {
+        for (const unit of units)
+            place(unit, errorJudgements(unit.rules, errorMessage(err)));
+        return out;
+    }
+    units.forEach((unit, k) => {
+        place(unit, interpret(unit.rules, unit.resolved, perInput[k] ?? {}));
+    });
+    return out;
+}

package/dist/judge/prompt.d.ts

@@ -0,0 +1,10 @@
+import type { SemanticJudgeInput, SemanticJudgeResult, SemanticRuleSpec } from '../types.js';
+/** System prompt: a strict judge that answers with one verdict from a closed set, as JSON. */
+export declare function buildJudgeSystemPrompt(): string;
+/** User prompt for one rule on one node. */
+export declare function buildJudgeUserPrompt({ node, related }: Pick<SemanticJudgeInput, 'node' | 'related'>, rule: SemanticRuleSpec): string;
+/**
+ * Parse judge output into a verdict from the rule's allowed set.
+ * Handles clean JSON, markdown-wrapped JSON, and a regex fallback for surrounding text.
+ */
+export declare function parseJudgeResponse(rawText: string, allowed: string[]): SemanticJudgeResult;

package/dist/judge/prompt.js

@@ -0,0 +1,92 @@
+function verdictList(rule) {
+    return Object.entries(rule.verdicts).map(([name, description]) => `- "${name}": ${description}`);
+}
+/** System prompt: a strict judge that answers with one verdict from a closed set, as JSON. */
+export function buildJudgeSystemPrompt() {
+    return [
+        'You are a strict, objective evaluation judge for structured planning and knowledge documents.',
+        'Your task is to choose the one verdict that best describes whether a node satisfies a rule.',
+        '',
+        'You must respond ONLY with a JSON object in this exact format:',
+        '{',
+        '  "verdict": "<exactly one of the allowed verdicts>",',
+        '  "confidence": <number from 0 to 1>,',
+        '  "evidence": "concise explanation citing specific quotes, phrases, or absent details from the node"',
+        '}',
+        '',
+        'Guidelines:',
+        '1. "verdict" must be one of the allowed verdicts listed for the rule, spelled exactly.',
+        '2. "confidence" is how sure you are of the verdict.',
+        '3. "evidence" must directly cite or quote relevant parts of the node, explaining the reasoning concisely.',
+        '4. Do not include markdown code block formatting, intro text, or outro text. Respond only with the JSON object.',
+    ].join('\n');
+}
+/** User prompt for one rule on one node. */
+export function buildJudgeUserPrompt({ node, related = [] }, rule) {
+    const rubric = rule.rubric || rule.description;
+    const lines = [
+        '# Rule to Evaluate',
+        `- ID: ${rule.id}`,
+        `- Category: ${rule.category}`,
+        `- Rubric: ${rubric}`,
+        '',
+        '## Allowed verdicts',
+        ...verdictList(rule),
+        '',
+        '# Node Under Evaluation',
+        `- File / Label: ${node.label}`,
+        `- Title: ${node.title}`,
+        `- Type: ${node.type} (resolved: ${node.resolvedType})`,
+    ];
+    if (node.resolvedParents && node.resolvedParents.length > 0) {
+        lines.push(`- Parents: ${node.resolvedParents.map((p) => p.title).join(', ')}`);
+    }
+    lines.push('', '## Node Content & Frontmatter:', '```json', JSON.stringify(node.schemaData, null, 2), '```', '');
+    if (related.length > 0) {
+        lines.push('# Related Nodes', 'Each is listed with its relation to the node under evaluation.', '');
+        for (const r of related) {
+            lines.push(`## ${r.title}`, `- Relation: ${r.relations.join(', ')}`, `- Type: ${r.type}`, '```json', JSON.stringify(r.data, null, 2), '```', '');
+        }
+    }
+    lines.push('Evaluate this node against the rule. Return only JSON with "verdict", "confidence" and "evidence".');
+    return lines.join('\n');
+}
+/**
+ * Parse judge output into a verdict from the rule's allowed set.
+ * Handles clean JSON, markdown-wrapped JSON, and a regex fallback for surrounding text.
+ */
+export function parseJudgeResponse(rawText, allowed) {
+    let cleaned = rawText.trim();
+    cleaned = cleaned.replace(/^```(?:json)?\s*/, '').replace(/\s*```$/, '');
+    let verdict;
+    let confidence;
+    let evidence;
+    try {
+        const parsed = JSON.parse(cleaned);
+        if (typeof parsed.verdict === 'string')
+            verdict = parsed.verdict.trim();
+        if (typeof parsed.confidence === 'number')
+            confidence = parsed.confidence;
+        if (typeof parsed.evidence === 'string')
+            evidence = parsed.evidence.trim();
+    }
+    catch {
+        const verdictMatch = /"verdict"\s*:\s*"((?:[^"\\]|\\.)*)"/i.exec(cleaned);
+        const confidenceMatch = /"confidence"\s*:\s*([0-9.]+)/i.exec(cleaned);
+        const evidenceMatch = /"evidence"\s*:\s*"((?:[^"\\]|\\.)*)"/i.exec(cleaned);
+        verdict = verdictMatch?.[1]?.trim();
+        confidence = confidenceMatch ? Number(confidenceMatch[1]) : undefined;
+        evidence = evidenceMatch?.[1]?.replace(/\\"/g, '"').replace(/\\n/g, '\n').trim();
+    }
+    if (verdict === undefined || !allowed.includes(verdict)) {
+        return {
+            error: `Model provider returned ${verdict === undefined ? 'no verdict' : `unknown verdict "${verdict}"`} (allowed: ${allowed.join(', ')}): ${rawText.slice(0, 200)}`,
+        };
+    }
+    return {
+        verdict,
+        ...(confidence !== undefined &&
+            Number.isFinite(confidence) && { confidence: Math.min(1, Math.max(0, confidence)) }),
+        ...(evidence && { evidence }),
+    };
+}

package/dist/judge/provider/anthropic.d.ts

@@ -0,0 +1,17 @@
+import type { HydratedProvider, SemanticJudgeInput, SemanticJudgeResult, SemanticRuleSpec } from '../types';
+import { PerRuleJudgeProvider } from './per-rule';
+export interface AnthropicJudgeProviderOptions extends HydratedProvider {
+    /** The factory requires a resolved key before constructing a non-OpenAI provider. */
+    apiKey?: string;
+}
+export declare const RECOMMENDED_ANTHROPIC_MODEL = "claude-haiku-5-5";
+export declare const ANTHROPIC_MESSAGES_ENDPOINT = "https://api.anthropic.com/v1/messages";
+/** Judge provider for the Anthropic Messages API. Reads no environment: it takes hydrated values. */
+export declare class AnthropicJudgeProvider extends PerRuleJudgeProvider {
+    readonly name = "anthropic";
+    private apiKey;
+    private model;
+    private endpoint;
+    constructor(options: AnthropicJudgeProviderOptions);
+    protected judgeRule(input: SemanticJudgeInput, rule: SemanticRuleSpec): Promise<SemanticJudgeResult>;
+}

package/dist/judge/provider/anthropic.js

@@ -0,0 +1,43 @@
+import { buildJudgeSystemPrompt, buildJudgeUserPrompt, parseJudgeResponse } from '../prompt';
+import { PerRuleJudgeProvider } from './per-rule';
+export const RECOMMENDED_ANTHROPIC_MODEL = 'claude-haiku-5-5';
+export const ANTHROPIC_MESSAGES_ENDPOINT = 'https://api.anthropic.com/v1/messages';
+/** Judge provider for the Anthropic Messages API. Reads no environment: it takes hydrated values. */
+export class AnthropicJudgeProvider extends PerRuleJudgeProvider {
+    name = 'anthropic';
+    apiKey;
+    model;
+    endpoint;
+    constructor(options) {
+        super();
+        this.apiKey = options.apiKey ?? '';
+        this.model = options.model || RECOMMENDED_ANTHROPIC_MODEL;
+        this.endpoint = options.endpoint || ANTHROPIC_MESSAGES_ENDPOINT;
+    }
+    async judgeRule(input, rule) {
+        const res = await fetch(this.endpoint, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-api-key': this.apiKey,
+                'anthropic-version': '2023-06-01',
+            },
+            body: JSON.stringify({
+                model: this.model,
+                max_tokens: 1024,
+                system: buildJudgeSystemPrompt(),
+                messages: [{ role: 'user', content: buildJudgeUserPrompt(input, rule) }],
+            }),
+        });
+        if (!res.ok) {
+            const errorText = await res.text().catch(() => '');
+            throw new Error(`Anthropic API error (${res.status}): ${errorText}`);
+        }
+        const data = (await res.json());
+        const text = data.content?.find((c) => c.type === 'text')?.text;
+        if (!text) {
+            throw new Error('Anthropic API returned empty or missing text block in response.');
+        }
+        return parseJudgeResponse(text, Object.keys(rule.verdicts));
+    }
+}

package/dist/judge/provider/fake.d.ts

@@ -0,0 +1,26 @@
+import type { SemanticJudgeInput, SemanticJudgeProvider, SemanticJudgeResult, SemanticRuleSpec } from '../types';
+/** A fake answer: a full verdict, or the `{ pass }` shorthand mapped onto the default `pass`/`fail` verdicts. */
+export type FakeAnswer = SemanticJudgeResult | {
+    pass: boolean;
+    evidence?: string;
+};
+export type FakeJudgeHandler = (call: {
+    node: SemanticJudgeInput['node'];
+    rule: SemanticRuleSpec;
+}) => Promise<FakeAnswer> | FakeAnswer;
+type FakeConfig = FakeAnswer | FakeJudgeHandler | Map<string, FakeAnswer> | Record<string, FakeAnswer>;
+/**
+ * In-memory fake judge for offline, deterministic tests. Configure with a single answer, a handler,
+ * or answers keyed by `ruleId:title`, `ruleId:label` or `ruleId` (most specific wins). Unmatched calls get `pass`,
+ * or the rule's first declared verdict.
+ */
+export declare class FakeJudgeProvider implements SemanticJudgeProvider {
+    private config?;
+    readonly name = "fake";
+    callHistory: SemanticJudgeInput[];
+    constructor(config?: FakeConfig | undefined);
+    evaluate(input: SemanticJudgeInput): Promise<Record<string, SemanticJudgeResult>>;
+    private answer;
+    clearHistory(): void;
+}
+export {};

package/dist/judge/provider/fake.js

@@ -0,0 +1,56 @@
+function isHandler(c) {
+    return typeof c === 'function';
+}
+function isAnswer(c) {
+    return 'pass' in c || 'verdict' in c || 'error' in c;
+}
+function normalise(answer) {
+    if ('pass' in answer) {
+        return { verdict: answer.pass ? 'pass' : 'fail', evidence: answer.evidence };
+    }
+    return answer;
+}
+/**
+ * In-memory fake judge for offline, deterministic tests. Configure with a single answer, a handler,
+ * or answers keyed by `ruleId:title`, `ruleId:label` or `ruleId` (most specific wins). Unmatched calls get `pass`,
+ * or the rule's first declared verdict.
+ */
+export class FakeJudgeProvider {
+    config;
+    name = 'fake';
+    callHistory = [];
+    constructor(config) {
+        this.config = config;
+    }
+    async evaluate(input) {
+        this.callHistory.push(input);
+        const results = {};
+        for (const rule of input.rules) {
+            results[rule.id] = normalise(await this.answer(input.node, rule));
+        }
+        return results;
+    }
+    async answer(node, rule) {
+        // The fake does not know severities: default to `pass`, else the first declared verdict.
+        const passing = { verdict: 'pass' in rule.verdicts ? 'pass' : (Object.keys(rule.verdicts)[0] ?? 'pass') };
+        const fallback = { ...passing, evidence: `Fake passed evaluation for rule "${rule.id}"` };
+        const config = this.config;
+        if (!config)
+            return fallback;
+        if (isHandler(config))
+            return await config({ node, rule });
+        if (config instanceof Map) {
+            return (config.get(`${rule.id}:${node.title}`) ??
+                config.get(`${rule.id}:${node.label}`) ??
+                config.get(rule.id) ??
+                fallback);
+        }
+        if (isAnswer(config))
+            return config;
+        const rec = config;
+        return rec[`${rule.id}:${node.title}`] ?? rec[`${rule.id}:${node.label}`] ?? rec[rule.id] ?? fallback;
+    }
+    clearHistory() {
+        this.callHistory = [];
+    }
+}

package/dist/judge/provider/jev.d.ts

@@ -0,0 +1,37 @@
+import type { HydratedProvider, SemanticJudgeInput, SemanticJudgeProvider, SemanticJudgeResult } from '../types';
+export interface JevJudgeProviderOptions extends HydratedProvider {
+    apiKey?: string;
+}
+export declare const JEV_LATEST = "jev-latest";
+export declare const OPENROUTER_DECISIONS_ENDPOINT = "https://openrouter.ai/api/alpha/decisions";
+/** Request packing limit: estimated input tokens (characters / 4) in one DecisionRequest's `state` plus `questions`. */
+export declare const JEV_REQUEST_PACKING_LIMIT_TOKENS = 32000;
+/** Request packing limit on the number of DecisionQuestions in one DecisionRequest. */
+export declare const JEV_REQUEST_PACKING_LIMIT_QUESTIONS = 40;
+/**
+ * Judge provider for TypeSafe's Jev decision model via OpenRouter's Decisions API.
+ *
+ * Each node is sent once as `state`, with one `choice` question per semantic rule whose criteria are
+ * the rule's closed verdict set. `evaluateNodes` shares one DecisionRequest between nodes with the same rule set. Jev returns the chosen verdict with confidence and probabilities,
+ * but no prose, so `evidence` is a summary of the distribution.
+ */
+export declare class JevJudgeProvider implements SemanticJudgeProvider {
+    readonly name = "jev";
+    private apiKey;
+    private model;
+    private endpoint;
+    constructor(options: JevJudgeProviderOptions);
+    evaluate(input: SemanticJudgeInput): Promise<Record<string, SemanticJudgeResult>>;
+    /**
+     * Judge many nodes with fewer DecisionRequests. Nodes that share the same semantic rule set form a
+     * NodeRulesetGroup, sent as one DecisionRequest,
+     * with every node under `state.nodes` and one DecisionQuestion per node and rule. A NodeRulesetGroup is split into DecisionRequests by
+     * `JEV_REQUEST_PACKING_LIMIT_TOKENS` and `JEV_REQUEST_PACKING_LIMIT_QUESTIONS`, never within a node. A node alone in its DecisionRequest, even
+     * one over the token limit, is sent whole as a plain single-node DecisionRequest; one with more rules than the question limit has its rules split
+     * across DecisionRequests. A failed DecisionRequest marks only its own nodes' rules
+     * as errors.
+     */
+    evaluateNodes(inputs: SemanticJudgeInput[]): Promise<Array<Record<string, SemanticJudgeResult>>>;
+    private evaluateDecisionRequest;
+    private post;
+}

package/dist/judge/provider/jev.js

@@ -0,0 +1,169 @@
+import { estimateTokens } from '../trim';
+export const JEV_LATEST = 'jev-latest';
+export const OPENROUTER_DECISIONS_ENDPOINT = 'https://openrouter.ai/api/alpha/decisions';
+/** Request packing limit: estimated input tokens (characters / 4) in one DecisionRequest's `state` plus `questions`. */
+export const JEV_REQUEST_PACKING_LIMIT_TOKENS = 32_000;
+/** Request packing limit on the number of DecisionQuestions in one DecisionRequest. */
+export const JEV_REQUEST_PACKING_LIMIT_QUESTIONS = 40;
+/**
+ * Judge provider for TypeSafe's Jev decision model via OpenRouter's Decisions API.
+ *
+ * Each node is sent once as `state`, with one `choice` question per semantic rule whose criteria are
+ * the rule's closed verdict set. `evaluateNodes` shares one DecisionRequest between nodes with the same rule set. Jev returns the chosen verdict with confidence and probabilities,
+ * but no prose, so `evidence` is a summary of the distribution.
+ */
+export class JevJudgeProvider {
+    name = 'jev';
+    apiKey;
+    model;
+    endpoint;
+    constructor(options) {
+        this.apiKey = options.apiKey ?? '';
+        this.model = options.model || JEV_LATEST;
+        this.endpoint = options.endpoint || OPENROUTER_DECISIONS_ENDPOINT;
+    }
+    async evaluate(input) {
+        const { node, rules } = input;
+        const results = {};
+        // A node with more rules than one DecisionRequest allows is split by rule; the state is sent whole each time.
+        for (let start = 0; start < rules.length; start += JEV_REQUEST_PACKING_LIMIT_QUESTIONS) {
+            const part = rules.slice(start, start + JEV_REQUEST_PACKING_LIMIT_QUESTIONS);
+            const questions = {};
+            for (const rule of part)
+                questions[rule.id] = decisionQuestion(rule, rule.rubric || rule.description);
+            const data = await this.post(nodeState(node, input.related), questions);
+            for (const rule of part)
+                results[rule.id] = toResult(rule, data.answers?.[rule.id]);
+        }
+        return results;
+    }
+    /**
+     * Judge many nodes with fewer DecisionRequests. Nodes that share the same semantic rule set form a
+     * NodeRulesetGroup, sent as one DecisionRequest,
+     * with every node under `state.nodes` and one DecisionQuestion per node and rule. A NodeRulesetGroup is split into DecisionRequests by
+     * `JEV_REQUEST_PACKING_LIMIT_TOKENS` and `JEV_REQUEST_PACKING_LIMIT_QUESTIONS`, never within a node. A node alone in its DecisionRequest, even
+     * one over the token limit, is sent whole as a plain single-node DecisionRequest; one with more rules than the question limit has its rules split
+     * across DecisionRequests. A failed DecisionRequest marks only its own nodes' rules
+     * as errors.
+     */
+    async evaluateNodes(inputs) {
+        const results = inputs.map(() => ({}));
+        const nodeRulesetGroups = new Map();
+        inputs.forEach((input, i) => {
+            if (input.rules.length === 0)
+                return;
+            const key = JSON.stringify(input.rules);
+            nodeRulesetGroups.set(key, [...(nodeRulesetGroups.get(key) ?? []), i]);
+        });
+        for (const indices of nodeRulesetGroups.values()) {
+            for (const requestInputs of planDecisionRequests(indices, inputs)) {
+                try {
+                    if (requestInputs.length === 1) {
+                        results[requestInputs[0]] = await this.evaluate(inputs[requestInputs[0]]);
+                    }
+                    else {
+                        await this.evaluateDecisionRequest(requestInputs, inputs, results);
+                    }
+                }
+                catch (err) {
+                    const error = err instanceof Error ? err.message : String(err);
+                    for (const i of requestInputs) {
+                        results[i] = Object.fromEntries(inputs[i].rules.map((r) => [r.id, { error }]));
+                    }
+                }
+            }
+        }
+        return results;
+    }
+    async evaluateDecisionRequest(requestInputs, inputs, results) {
+        const nodes = {};
+        const questions = {};
+        requestInputs.forEach((inputIndex, k) => {
+            const input = inputs[inputIndex];
+            nodes[`n${k}`] = nodeState(input.node, input.related);
+            for (const rule of input.rules) {
+                questions[`${rule.id}__n${k}`] = decisionQuestion(rule, `For node \`nodes.n${k}\`: ${rule.rubric || rule.description}`);
+            }
+        });
+        const data = await this.post({ nodes }, questions);
+        requestInputs.forEach((inputIndex, k) => {
+            for (const rule of inputs[inputIndex].rules) {
+                results[inputIndex][rule.id] = toResult(rule, data.answers?.[`${rule.id}__n${k}`]);
+            }
+        });
+    }
+    async post(state, questions) {
+        const res = await fetch(this.endpoint, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${this.apiKey}` },
+            body: JSON.stringify({ model: this.model, state, questions }),
+        });
+        if (!res.ok) {
+            const errorText = await res.text().catch(() => '');
+            throw new Error(`Jev API error (${res.status}): ${errorText}`);
+        }
+        return (await res.json());
+    }
+}
+function nodeState(node, related = []) {
+    return {
+        title: node.title,
+        type: node.resolvedType,
+        parents: node.resolvedParents?.map((p) => p.title) ?? [],
+        ...node.schemaData,
+        ...(related.length > 0 && {
+            relatedNodes: related.map((r) => ({
+                relation: r.relations.join(', '),
+                title: r.title,
+                type: r.type,
+                ...r.data,
+            })),
+        }),
+    };
+}
+function decisionQuestion(rule, instructions) {
+    return { type: 'choice', instructions, criteria: rule.verdicts };
+}
+function toResult(rule, answer) {
+    if (!answer?.choice || !(answer.choice in rule.verdicts)) {
+        return { error: `Jev returned no valid verdict for rule "${rule.id}" (choice: ${answer?.choice})` };
+    }
+    return {
+        verdict: answer.choice,
+        confidence: answer.confidence,
+        probabilities: answer.probabilities,
+        evidence: describeDistribution(answer),
+    };
+}
+/** Plan the DecisionRequests for one NodeRulesetGroup (inputs sharing a rule set): runs of nodes, in order, never splitting a node. */
+function planDecisionRequests(indices, inputs) {
+    const requests = [];
+    let current = [];
+    let tokens = 0;
+    let questions = 0;
+    for (const i of indices) {
+        const input = inputs[i];
+        const cost = estimateTokens(nodeState(input.node, input.related)) + estimateTokens(input.rules);
+        const count = input.rules.length;
+        if (current.length > 0 &&
+            (tokens + cost > JEV_REQUEST_PACKING_LIMIT_TOKENS || questions + count > JEV_REQUEST_PACKING_LIMIT_QUESTIONS)) {
+            requests.push(current);
+            current = [];
+            tokens = 0;
+            questions = 0;
+        }
+        current.push(i);
+        tokens += cost;
+        questions += count;
+    }
+    if (current.length > 0)
+        requests.push(current);
+    return requests;
+}
+function describeDistribution(answer) {
+    const parts = Object.entries(answer.probabilities ?? {})
+        .sort(([, a], [, b]) => b - a)
+        .map(([verdict, p]) => `${verdict} ${p.toFixed(2)}`);
+    const confidence = answer.confidence !== undefined ? `confidence ${answer.confidence.toFixed(2)}` : undefined;
+    return `Jev chose "${answer.choice}"${[confidence, ...parts].filter(Boolean).length ? ` (${[confidence, ...parts].filter(Boolean).join('; ')})` : ''}`;
+}

package/dist/judge/provider/openai-decisions.d.ts

@@ -0,0 +1,21 @@
+import type { HydratedProvider, SemanticJudgeInput, SemanticJudgeProvider, SemanticJudgeResult } from '../types';
+export interface OpenAIDecisionsJudgeProviderOptions extends HydratedProvider {
+    apiKey?: string;
+}
+export declare const RECOMMENDED_OPENAI_DECISIONS_MODEL = "gpt-6-luna";
+export declare const OPENAI_DECISIONS_ENDPOINT = "https://api.openai.com/v1/decisions";
+/**
+ * Judge provider for OpenAI's Decisions API (https://developers.openai.com/api/docs/guides/decisions).
+ *
+ * Each node is sent once as the `input` text, with one `choice` question per semantic rule whose
+ * choices are the rule's closed verdict set. The API returns the chosen value with per-choice
+ * probabilities and a confidence, but no prose, so `evidence` is a summary of the distribution.
+ */
+export declare class OpenAIDecisionsJudgeProvider implements SemanticJudgeProvider {
+    readonly name = "openai-decisions";
+    private apiKey;
+    private model;
+    private endpoint;
+    constructor(options: OpenAIDecisionsJudgeProviderOptions);
+    evaluate(input: SemanticJudgeInput): Promise<Record<string, SemanticJudgeResult>>;
+}