jev-mcp-python 0.1.0__py3-none-any.whl

jev_mcp/tools/classify.py

@@ -0,0 +1,187 @@
+"""jev_classify: batch-assign items to classes from a shared catalog (`index.ts:398-526`)."""
+
+from typing import Any
+
+from jev_mcp.domain import ChoiceQuestion, Question
+from jev_mcp.limits import CLASSIFY
+from jev_mcp.policy import DEFAULT_CLASSIFY_AUTO_ACCEPT, DEFAULT_MINIMUM_MARGIN
+from jev_mcp.tools.base import JevTool, Runtime, ToolError, ToolResult, caller_actions, define, frame, headline
+from jev_mcp.tools.observed import classification_decision, validate_choice
+from jev_mcp.validation import margin, top_probability
+from jev_mcp.validation.caps import CapLedger, classify_budget_error, exceeds
+
+DEFAULT_PURPOSE = "Assign each item to exactly one class."
+
+DEFINITION = define(
+    "jev_classify",
+    "Classify items against a shared label set",
+    "Assign each item to one class from a shared catalog with TypeSafe Jev, in one batched request: the class "
+    "catalog is sent once and every item becomes an independent Choice question. Returns per item: the chosen "
+    "class, the full distribution, confidence, winner-to-runner-up margin, and an auto-versus-review decision. Auto "
+    "requires both a high top probability (default 0.85) and a clear margin (default 0.50); everything else is "
+    "flagged for review. Include a manual_review class in the catalog if you want an explicit escape hatch; the tool "
+    "never invents one.",
+    {
+        "type": "object",
+        "properties": {
+            "items": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {"id": {"type": "string"}, "text": {"type": "string"}},
+                    "required": ["text"],
+                    "additionalProperties": False,
+                },
+                "minItems": CLASSIFY.items_min,
+                "maxItems": CLASSIFY.items_max,
+                "description": f"Items to classify. Text is truncated at {CLASSIFY.item_units} characters; send "
+                "bounded excerpts, not whole documents.",
+            },
+            "classes": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {"id": {"type": "string"}, "description": {"type": "string"}},
+                    "required": ["description"],
+                    "additionalProperties": False,
+                },
+                "minItems": CLASSIFY.classes_min,
+                "maxItems": CLASSIFY.classes_max,
+                "description": "Shared class catalog. Strong descriptions carry the decision: a precise definition, "
+                "what belongs, what does not, precedence over overlapping classes, and a short example.",
+            },
+            "purpose": {"type": "string", "description": "What this classification is for; shared across all items."},
+            "context": {
+                "anyOf": [{"type": "string"}, {"type": "object", "additionalProperties": {}}],
+                "description": "Shared context available to every item's judgment: policies, catalogs, anything "
+                "stable.",
+            },
+            "auto_accept": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum top probability for auto. Default 0.85.",
+            },
+            "minimum_margin": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum winner-to-runner-up gap for auto. Default 0.5.",
+            },
+        },
+        "required": ["items", "classes"],
+        "additionalProperties": False,
+    },
+)
+
+
+def _opaque(
+    raw: list[dict[str, str]], kind: str, key_prefix: str, text_key: str, cap: int, ledger: CapLedger
+) -> list[tuple[str, str, str]]:
+    """`(external id, wire key, capped text)` per entry. Caller ids are kept verbatim and must be unique;
+    an omitted id becomes `{kind}{index}`, unchecked against supplied ones, as in the reference."""
+    seen: set[str] = set()
+    out: list[tuple[str, str, str]] = []
+    for index, entry in enumerate(raw):
+        supplied = entry.get("id")
+        if supplied is not None:
+            if supplied in seen:
+                raise ToolError(f"Duplicate {kind} id: {supplied}")
+            seen.add(supplied)
+        external = supplied if supplied is not None else f"{kind}{index}"
+        out.append((external, f"{key_prefix}{index}", ledger.text(entry[text_key], cap, "item")))
+    return out
+
+
+async def handle(args: dict[str, Any], runtime: Runtime) -> ToolResult:
+    auto_accept: float = args.get("auto_accept", DEFAULT_CLASSIFY_AUTO_ACCEPT)
+    minimum_margin: float = args.get("minimum_margin", DEFAULT_MINIMUM_MARGIN)
+
+    # Opaque wire keys (i0, c0) so sanitizing can never rename or collide caller ids.
+    ledger = CapLedger()
+    items = _opaque(args["items"], "item", "i", "text", CLASSIFY.item_units, ledger)
+    classes = _opaque(args["classes"], "class", "c", "description", CLASSIFY.class_description_units, ledger)
+    if exceeds(len(items) * len(classes), CLASSIFY.item_class_pairs):
+        raise ToolError(classify_budget_error(len(items), len(classes), CLASSIFY.item_class_pairs))
+
+    # The catalog is sent once in state; each question carries only its own item.
+    state = {
+        "purpose": args.get("purpose", DEFAULT_PURPOSE),
+        "context": args.get("context"),
+        "classes": [{"id": key, "description": description} for _, key, description in classes],
+    }
+    class_keys = [key for _, key, _ in classes]
+    criteria = dict.fromkeys(class_keys)
+    questions: dict[str, Question] = {
+        key: ChoiceQuestion(
+            {"task": "Which class does this item belong to?", "item": {"id": key, "text": text}}, criteria
+        )
+        for _, key, text in items
+    }
+    evaluation = await runtime.ask(state, questions)
+
+    key_to_external = {key: external for external, key, _ in classes}
+    results: list[dict[str, object]] = []
+    for external, key, _ in items:
+        answer = validate_choice(evaluation.answers.get(key), class_keys)
+        if answer is None:
+            results.append(
+                {
+                    "id": external,
+                    "status": "invalid_response",
+                    "classification": None,
+                    "probabilities": None,
+                    "confidence": None,
+                    "margin": None,
+                    "decision": "review",
+                }
+            )
+            continue
+        gap = margin(answer.probabilities)
+        top = top_probability(answer)
+        results.append(
+            {
+                "id": external,
+                "classification": key_to_external.get(answer.choice, answer.choice),
+                "probabilities": {
+                    class_external: answer.probabilities.get(class_key, 0) for class_external, class_key, _ in classes
+                },
+                "confidence": answer.confidence,
+                "margin": gap,
+                "top_probability": top,
+                "decision": classification_decision(top, gap, auto_accept, minimum_margin),
+            }
+        )
+
+    by_class: dict[str, int] = {}
+    for result in results:
+        classification = result["classification"]
+        if isinstance(classification, str):
+            by_class[classification] = by_class.get(classification, 0) + 1
+
+    item_actions = caller_actions(r["decision"] for r in results)
+    return ToolResult(
+        frame(
+            "jev_classify",
+            evaluation,
+            {
+                "summary": {
+                    "items": len(results),
+                    "auto": sum(1 for r in results if r["decision"] == "auto"),
+                    "review": sum(
+                        1 for r in results if r["decision"] == "review" and r.get("status") != "invalid_response"
+                    ),
+                    "invalid_response": sum(1 for r in results if r.get("status") == "invalid_response"),
+                    "by_class": by_class,
+                },
+                "thresholds": {"auto_accept": auto_accept, "minimum_margin": minimum_margin},
+                "results": results,
+            },
+        ),
+        action=headline(item_actions),
+        item_actions=item_actions,
+        truncated=ledger.scopes,
+    )
+
+
+TOOL = JevTool(DEFINITION, handle)

jev_mcp/tools/common.py

@@ -0,0 +1,96 @@
+"""Schema fragments and helpers shared by several tools (`index.ts:88-116`, `lib.ts:363-374`)."""
+
+from collections.abc import Mapping
+from typing import Any, cast
+
+from jev_mcp.ids import ensure_unique_ids
+from jev_mcp.limits import CANDIDATES, VERIFY
+
+EVIDENCE_SCHEMA: dict[str, Any] = {
+    "anyOf": [
+        {"type": "string", "description": "A single evidence document."},
+        {
+            "type": "object",
+            "properties": {
+                "id": {"type": "string", "description": "Short identifier for this evidence item."},
+                "text": {"type": "string", "description": "The evidence text."},
+            },
+            "required": ["text"],
+            "additionalProperties": False,
+            "description": "A single evidence item.",
+        },
+        {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "description": "Short identifier for this evidence item (e.g. 'site-html', 'rfc-4.1.3').",
+                    },
+                    "text": {"type": "string", "description": "The evidence text."},
+                },
+                "required": ["text"],
+                "additionalProperties": False,
+            },
+            "minItems": VERIFY.evidence_min,
+            "description": "Multiple evidence items; each claim is also matched to the item it rests on.",
+        },
+    ]
+}
+"""`evidenceSchema` (`index.ts:88-103`): one string, one `{id?, text}`, or a non-empty array of them."""
+
+
+def candidates_schema(description: str) -> dict[str, Any]:
+    """`candidatesSchema` (`index.ts:105-116`), shared by jev_find and jev_rerank."""
+    return {
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+                "id": {
+                    "type": "string",
+                    "description": "Short identifier for this candidate (e.g. a file path, note name, or line id).",
+                },
+                "text": {"type": "string", "description": "The candidate's text."},
+            },
+            "required": ["text"],
+            "additionalProperties": False,
+        },
+        "minItems": CANDIDATES.min_items,
+        "maxItems": CANDIDATES.max_items,
+        "description": description,
+    }
+
+
+def evidence_items(raw: object) -> list[dict[str, object]]:
+    """Parsed `evidence` as a list of `{id?, text}` items: a string is one item with id `evidence`."""
+    if isinstance(raw, str):
+        return [{"id": "evidence", "text": raw}]
+    if isinstance(raw, list):
+        return cast(list[dict[str, object]], raw)
+    return [cast(dict[str, object], raw)]
+
+
+def normalize_evidence(raw: object) -> list[dict[str, object]]:
+    """`normalizeEvidence` (`lib.ts:363-368`): evidence items with safe, unique ids."""
+    return ensure_unique_ids(evidence_items(raw), "evidence").items
+
+
+_JS_WHITESPACE = "".join(
+    map(chr, (0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x20, 0xA0, 0x1680, *range(0x2000, 0x200B), 0x2028, 0x2029, 0x202F))
+) + "".join(map(chr, (0x205F, 0x3000, 0xFEFF)))
+"""ECMAScript WhiteSpace and LineTerminator, what `String.prototype.trim` strips. Python's `strip()` differs."""
+
+
+def js_trim(text: str) -> str:
+    return text.strip(_JS_WHITESPACE)
+
+
+def has_non_empty_evidence(items: list[dict[str, object]]) -> bool:
+    """`hasNonEmptyEvidence` (`lib.ts:371-374`)."""
+    return any(js_trim(str(item["text"])) for item in items)
+
+
+def text_of(item: Mapping[str, object]) -> str:
+    return str(item["text"])

jev_mcp/tools/compare.py

@@ -0,0 +1,143 @@
+"""jev_compare: the fact relation between two passages, optionally per aspect (`index.ts:790-879`)."""
+
+from typing import Any
+
+from jev_mcp.domain import ChoiceQuestion, Question
+from jev_mcp.limits import COMPARE
+from jev_mcp.policy import DEFAULT_CLASSIFY_AUTO_ACCEPT, DEFAULT_MINIMUM_MARGIN
+from jev_mcp.tools.base import JevTool, Runtime, ToolResult, caller_actions, define, frame, headline
+from jev_mcp.tools.observed import classification_decision, validate_choice
+from jev_mcp.validation import margin, top_probability
+from jev_mcp.validation.caps import CapLedger
+
+COMPARE_RELATIONS = {
+    "same_fact": "Both passages state the same underlying fact or claim",
+    "contradicts": "The passages state opposing facts about the same subject",
+    "different_facts": "The passages discuss different subjects or make non-overlapping claims",
+}
+"""`COMPARE_RELATIONS` (`lib.ts:188-192`)."""
+
+ASPECT_RELATIONS = {
+    "same_fact": "Both passages make comparable assertions about this aspect and they agree",
+    "contradicts": "Both passages address this aspect and their assertions conflict",
+    "different_facts": "The passages do not both make a comparable assertion about this aspect: at least one does "
+    "not address it, or their mentions do not overlap",
+}
+"""`ASPECT_RELATIONS` (`lib.ts:199-204`): per aspect, the third outcome usually means one passage is silent."""
+
+DEFINITION = define(
+    "jev_compare",
+    "Compare two passages for factual agreement",
+    "Judge the relation between two passages with TypeSafe Jev: same_fact, contradicts, or different_facts, with "
+    "the full probability distribution, confidence, and an auto-versus-review decision. Optionally supply aspects "
+    "(price, date, method, …) and each gets an independent per-aspect judgment in the same single request. Use for "
+    "source reconciliation, changelog-vs-code drift, or merge sanity checks. The request supplies no evidence beyond "
+    "the two passages, so a same_fact verdict means they agree with each other, not that they are true.",
+    {
+        "type": "object",
+        "properties": {
+            "passage_a": {
+                "type": "string",
+                "minLength": COMPARE.passage_min,
+                "maxLength": COMPARE.passage_max,
+                "description": f"First passage. Rejected above {COMPARE.passage_max:,} characters.",
+            },
+            "passage_b": {
+                "type": "string",
+                "minLength": COMPARE.passage_min,
+                "maxLength": COMPARE.passage_max,
+                "description": f"Second passage. Rejected above {COMPARE.passage_max:,} characters.",
+            },
+            "aspects": {
+                "type": "array",
+                "items": {"type": "string", "minLength": COMPARE.aspect_min, "maxLength": COMPARE.aspect_max},
+                "maxItems": COMPARE.aspects_max,
+                "description": "Named aspects to judge independently (e.g. 'price', 'launch date'). Each tests one "
+                "property.",
+            },
+            "purpose": {"type": "string", "description": "What this comparison is for; helps disambiguate overlap."},
+            "auto_accept": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum top probability for auto. Default 0.85.",
+            },
+            "minimum_margin": {
+                "type": "number",
+                "minimum": 0,
+                "maximum": 1,
+                "description": "Minimum winner-to-runner-up gap for auto. Default 0.5.",
+            },
+        },
+        "required": ["passage_a", "passage_b"],
+        "additionalProperties": False,
+    },
+)
+
+
+async def handle(args: dict[str, Any], runtime: Runtime) -> ToolResult:
+    auto_accept: float = args.get("auto_accept", DEFAULT_CLASSIFY_AUTO_ACCEPT)
+    minimum_margin: float = args.get("minimum_margin", DEFAULT_MINIMUM_MARGIN)
+    aspects: list[str] = args.get("aspects", [])
+
+    questions: dict[str, Question] = {
+        "overall": ChoiceQuestion(
+            "Do the two passages state the same underlying fact, contradict each other, or discuss different facts?",
+            COMPARE_RELATIONS,
+        )
+    }
+    for i, aspect in enumerate(aspects):
+        questions[f"aspect_{i}"] = ChoiceQuestion(
+            f'Judging only the aspect "{aspect}" of the two passages in the state, which relation holds?',
+            ASPECT_RELATIONS,
+        )
+    # The schema rejects a passage over its cap first, so this ledger never records a cut.
+    ledger = CapLedger()
+    state = {
+        "purpose": args.get("purpose"),
+        "passage_a": ledger.text(args["passage_a"], COMPARE.passage_max, "context"),
+        "passage_b": ledger.text(args["passage_b"], COMPARE.passage_max, "context"),
+        "aspects": aspects,
+    }
+    evaluation = await runtime.ask(state, questions)
+
+    def judge(raw: object) -> dict[str, object]:
+        answer = validate_choice(raw, COMPARE_RELATIONS)
+        if answer is None:
+            return {
+                "relation": None,
+                "probabilities": None,
+                "confidence": None,
+                "margin": None,
+                "decision": "review",
+                "status": "invalid_response",
+            }
+        gap = margin(answer.probabilities)
+        return {
+            "relation": answer.choice,
+            "probabilities": answer.probabilities,
+            "confidence": answer.confidence,
+            "margin": gap,
+            "decision": classification_decision(top_probability(answer), gap, auto_accept, minimum_margin),
+        }
+
+    overall = judge(evaluation.answers.get("overall"))
+    return ToolResult(
+        frame(
+            "jev_compare",
+            evaluation,
+            {
+                "overall": overall,
+                "aspects": [
+                    {"aspect": aspect, **judge(evaluation.answers.get(f"aspect_{i}"))}
+                    for i, aspect in enumerate(aspects)
+                ],
+                "thresholds": {"auto_accept": auto_accept, "minimum_margin": minimum_margin},
+            },
+        ),
+        action=headline(caller_actions([overall["decision"]])),  # the aspects are not the headline
+        truncated=ledger.scopes,
+    )
+
+
+TOOL = JevTool(DEFINITION, handle)

jev_mcp/tools/decide.py

@@ -0,0 +1,206 @@
+"""jev_decide: one bounded decision with escape hatches and requirement checks (`index.ts:531-671`)."""
+
+from typing import Any
+
+from jev_mcp.domain import ChoiceQuestion, Question
+from jev_mcp.limits import DECIDE
+from jev_mcp.policy import RequirementCheck
+from jev_mcp.tools.base import JevTool, Runtime, ToolError, ToolResult, define, frame
+from jev_mcp.tools.observed import contradicts_recommendation, validate_choice
+
+ESCAPE_HATCHES = {
+    "ask_user": "A consequential user preference or requirement is missing; ask instead of inventing it",
+    "investigate": "Gather missing technical or factual evidence before selecting a candidate",
+    "none": "None of the supplied candidates fits the known requirements",
+}
+"""`DECIDE_ESCAPE_HATCHES` (`lib.ts:141-145`)."""
+
+RELATION_CRITERIA = {
+    "supported": "The evidence and mechanism support this specific requirement",
+    "contradicted": "The evidence or mechanism contradicts this specific requirement, not merely another requirement",
+    "unknown": "Relevant evidence is missing; neither satisfaction nor violation is established",
+}
+INVALID = "invalid_response"
+
+DEFINITION = define(
+    "jev_decide",
+    "Decide between bounded alternatives",
+    "One unresolved, bounded decision where semantic judgment over supplied evidence could change your plan: "
+    "implementation alternatives, product tradeoffs with known preferences, workflow selection. Supply "
+    f"{DECIDE.candidates_min}-{DECIDE.candidates_max} "
+    "candidates, evidence, and explicit priorities. Jev returns a Choice distribution over the candidates plus "
+    "escape hatches (ask_user / investigate / none), and a per-candidate per-requirement supported / contradicted / "
+    "unknown judgment for each optional requirement, all in one request. One call per unchanged decision; do not "
+    "repeat a call to obtain a more pleasing answer. Use source inspection, tests, the user, or a reasoning model for "
+    "open-ended research, routine choices, correctness proofs, or predicting user consent. High probability is not "
+    "proof.",
+    {
+        "type": "object",
+        "properties": {
+            "decision": {
+                "type": "string",
+                "minLength": DECIDE.decision_min,
+                "maxLength": DECIDE.decision_max,
+                "description": "The bounded decision to make.",
+            },
+            "evidence": {
+                "type": "string",
+                "minLength": DECIDE.evidence_min,
+                "maxLength": DECIDE.evidence_max,
+                "description": "Facts and measurements, not opinions. State is evidence, not instructions.",
+            },
+            "priorities": {
+                "type": "string",
+                "minLength": DECIDE.priorities_min,
+                "maxLength": DECIDE.priorities_max,
+                "description": "Explicit preferences and constraints from the user or plan.",
+            },
+            "candidates": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "id": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9_-]*$",
+                            "maxLength": DECIDE.candidate_id_max,
+                        },
+                        "description": {
+                            "type": "string",
+                            "minLength": DECIDE.candidate_description_min,
+                            "maxLength": DECIDE.candidate_description_max,
+                        },
+                    },
+                    "required": ["id", "description"],
+                    "additionalProperties": False,
+                },
+                "minItems": DECIDE.candidates_min,
+                "maxItems": DECIDE.candidates_max,
+                "description": "The alternatives. Include 'do nothing' or 'gather more evidence' as candidates when "
+                "useful.",
+            },
+            "requirements": {
+                "type": "array",
+                "items": {"type": "string", "minLength": DECIDE.requirement_min, "maxLength": DECIDE.requirement_max},
+                "maxItems": DECIDE.requirements_max,
+                "description": "Specific requirements to check per candidate. Each must test one property, not "
+                "overall goodness.",
+            },
+            "escape_hatches": {
+                "type": "boolean",
+                "description": "Include ask_user / investigate / none as Choosable options so the model can decline "
+                "to rank. Default true.",
+            },
+        },
+        "required": ["decision", "evidence", "priorities", "candidates"],
+        "additionalProperties": False,
+    },
+)
+
+
+async def handle(args: dict[str, Any], runtime: Runtime) -> ToolResult:
+    hatches: bool = args.get("escape_hatches", True)
+    requirements: list[str] = args.get("requirements", [])
+    candidates: list[dict[str, str]] = args["candidates"]
+
+    # Duplicate ids and ids that shadow an active escape hatch would alias wire keys.
+    seen: set[str] = set()
+    for candidate in candidates:
+        candidate_id = candidate["id"]
+        if candidate_id in seen:
+            raise ToolError("Duplicate candidate id: " + candidate_id)
+        if hatches and candidate_id in ESCAPE_HATCHES:
+            raise ToolError(
+                f'Candidate id "{candidate_id}" collides with an escape hatch; rename it or set escape_hatches: false.'
+            )
+        seen.add(candidate_id)
+
+    # Opaque positional wire keys; validated slug ids come back verbatim.
+    key_to_id = {f"option_{i}": candidate["id"] for i, candidate in enumerate(candidates)}
+    criteria = {f"option_{i}": candidate["description"] for i, candidate in enumerate(candidates)}
+    if hatches:
+        criteria.update(ESCAPE_HATCHES)
+
+    questions: dict[str, Question] = {
+        "recommendation": ChoiceQuestion(
+            "Which candidate best fits the decision, evidence, and priorities? "
+            + ("Select a candidate or an escape hatch. " if hatches else "")
+            + "Do not invent missing facts, preferences, or approvals.",
+            criteria,
+        )
+    }
+    for i in range(len(candidates)):
+        for j in range(len(requirements)):
+            questions[f"check_{i}_{j}"] = ChoiceQuestion(
+                f"How does the mechanism in candidates[{i}] relate to requirements[{j}], using the evidence? Judge "
+                "only this property, not the candidate overall desirability. Missing evidence is not contradiction.",
+                RELATION_CRITERIA,
+            )
+    state = {
+        "decision": args["decision"],
+        "evidence": args["evidence"],
+        "priorities": args["priorities"],
+        "candidates": [
+            {"id": key, "description": candidate["description"]}
+            for key, candidate in zip(key_to_id, candidates, strict=True)
+        ],
+        "requirements": requirements,
+    }
+    evaluation = await runtime.ask(state, questions)
+    answers = evaluation.answers
+
+    rec = validate_choice(answers.get("recommendation"), criteria)
+    # Q3 (ADR-0012): a malformed check stays visible as invalid_response and never warns.
+    checks = [
+        RequirementCheck(candidate["id"], j, answer.choice if answer is not None else INVALID)
+        for i, candidate in enumerate(candidates)
+        for j in range(len(requirements))
+        for answer in [validate_choice(answers.get(f"check_{i}_{j}"), RELATION_CRITERIA)]
+    ]
+    contradicted = (
+        contradicts_recommendation([c for c in checks if c.answer != INVALID], key_to_id[rec.choice])
+        if rec is not None and rec.choice in key_to_id
+        else []
+    )
+
+    recommendation: dict[str, object]
+    if rec is None:
+        recommendation = {
+            "selected": None,
+            "escaped": None,
+            "confidence": None,
+            "probabilities": None,
+            "status": INVALID,
+        }
+    else:
+        recommendation = {
+            "selected": key_to_id.get(rec.choice, rec.choice),
+            "escaped": rec.choice not in key_to_id,
+            "confidence": rec.confidence,
+            "probabilities": {key_to_id.get(key, key): p for key, p in rec.probabilities.items()},
+        }
+    warnings: list[str] = []
+    if contradicted:
+        plural = "s" if len(contradicted) > 1 else ""
+        numbers = ", ".join(str(index + 1) for index in contradicted)
+        warnings.append(
+            f"Requirement{plural} {numbers} contradicted by the recommended candidate; inspect before acting"
+        )
+
+    return ToolResult(
+        frame(
+            "jev_decide",
+            evaluation,
+            {
+                "recommendation": recommendation,
+                "requirements_checked": len(requirements),
+                "checks": [
+                    {"candidate": c.candidate, "requirement": c.requirement, "answer": c.answer} for c in checks
+                ],
+                "warnings": warnings,
+            },
+        )
+    )
+
+
+TOOL = JevTool(DEFINITION, handle)