Skip to content

armgit / laya

Public Imported from GitHub
0

Non-autoregressive System 1 decision engine. Typed choice, score and yes/no decisions over any text in a single forward pass, in 100+ languages, with a router that picks the right checkpoint per request.

feat: confidence-based abstention gating on answer_confidence (min_confidence) (#361)

Aashish0c6fc6a0df42
diff --git a/laya/__init__.py b/laya/__init__.py
index b6462e54..a3f42162 100644
--- a/laya/__init__.py
+++ b/laya/__init__.py
@@ -28,6 +28,8 @@ _LAZY_ATTRS = {
"ece_score": (".common", "ece_score"),
"answer_confidence": (".common", "answer_confidence"),
"confidence_from_probs": (".common", "confidence_from_probs"),
+ "check_min_confidence": (".confidence", "check_min_confidence"),
+ "flag_low_confidence": (".confidence", "flag_low_confidence"),
"render_options": (".common", "render_options"),
"QTYPES": (".common", "QTYPES"),
"QTYPE_NAMES": (".common", "QTYPE_NAMES"),
@@ -85,6 +87,8 @@ __all__ = [
"ece_score",
"answer_confidence",
"confidence_from_probs",
+ "check_min_confidence",
+ "flag_low_confidence",
"render_options",
"QTYPES",
"QTYPE_NAMES",
diff --git a/laya/agent.py b/laya/agent.py
index 1b58de6f..ee0f19ca 100644
--- a/laya/agent.py
+++ b/laya/agent.py
@@ -21,7 +21,9 @@ from .common import (
clamp_temperature,
collate_items,
answer_confidence,
+ check_min_confidence,
confidence_from_probs,
+ flag_low_confidence,
_resolve_noul_labels,
encode_text,
render_options,
@@ -822,7 +824,8 @@ class Agent(HookRegistry):
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
head_max_len: Optional[int] = None,
- sort_by_length: bool = False) -> List[Dict[str, Any]]:
+ sort_by_length: bool = False,
+ min_confidence: Optional[float] = None) -> List[Dict[str, Any]]:
"""Evaluate the same questions over many states, packing them into shared forward passes.
This is the throughput path. `system_one`/`predict` handle one state per forward pass; on a
@@ -857,6 +860,7 @@ class Agent(HookRegistry):
A list of per-state result dicts, each identical in shape to `system_one`'s output and
aligned with `states` by index.
"""
+ mc = check_min_confidence(min_confidence) if min_confidence is not None else None
active = compose_hooks(self.hooks, hooks, on_predict_start, on_predict_end)
raise_errors = self.hooks_raise if hooks_raise is None else bool(hooks_raise)
timeout = self.hooks_timeout if hooks_timeout is None else validate_timeout(hooks_timeout)
@@ -951,6 +955,8 @@ class Agent(HookRegistry):
ctx.error.__context__ = hook_exc
else:
raise
+ if mc is not None and ctx.results is not None:
+ flag_low_confidence(ctx.results, mc)
return ctx.results
def predict_long(self, state: Union[str, dict, list], questions: Dict[str, Dict[str, Any]],
@@ -1061,7 +1067,8 @@ class Agent(HookRegistry):
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
- head_max_len: Optional[int] = None) -> Dict[str, Any]:
+ head_max_len: Optional[int] = None,
+ min_confidence: Optional[float] = None) -> Dict[str, Any]:
"""Evaluate typed questions across state in a single, parallel forward pass.
Args:
@@ -1088,7 +1095,8 @@ class Agent(HookRegistry):
on_predict_start=on_predict_start,
on_predict_end=on_predict_end, hooks_raise=hooks_raise,
hooks_timeout=hooks_timeout,
- max_len=max_len, head_max_len=head_max_len)[0]
+ max_len=max_len, head_max_len=head_max_len,
+ min_confidence=min_confidence)[0]
def __enter__(self):
return self
@@ -1111,6 +1119,7 @@ class Agent(HookRegistry):
def decide(self, state: Union[str, dict, list], schema: Any = None, *,
questions: Optional[Dict[str, Any]] = None, return_details: bool = False,
+ min_confidence: Optional[float] = None,
**predict_kwargs) -> Any:
"""Answer `state` against a schema (JSON schema or pydantic model) and return typed values.
@@ -1119,7 +1128,7 @@ class Agent(HookRegistry):
"""
from .structured import decide as _decide
return _decide(self, state, schema, questions=questions,
- return_details=return_details, **predict_kwargs)
+ return_details=return_details, min_confidence=min_confidence, **predict_kwargs)
def __repr__(self) -> str:
return "Agent(model_id=%r, device=%s)" % (self.model_id, getattr(self, "device", None))
diff --git a/laya/common.py b/laya/common.py
index 91f702a5..9855fcda 100644
--- a/laya/common.py
+++ b/laya/common.py
@@ -388,6 +388,9 @@ def clamp_temperature(t, lo: float = TEMP_MIN, hi: float = TEMP_MAX) -> float:
return min(hi, max(lo, t))
+from .confidence import check_min_confidence, flag_low_confidence
+
+
def amp_dtype(name: Optional[str]) -> torch.dtype:
return torch.bfloat16 if name == "bf16" else torch.float16
diff --git a/laya/confidence.py b/laya/confidence.py
new file mode 100644
index 00000000..253329bf
--- /dev/null
+++ b/laya/confidence.py
@@ -0,0 +1,40 @@
+"""Confidence validation, calibrated thresholds, and abstention gating helpers (#361).
+
+Pure Python: safe to import without PyTorch so that Router and structured
+decisions stay lightweight and free of torch import overhead.
+"""
+import math
+from typing import Any, Dict, List
+
+
+def check_min_confidence(v: Any) -> float:
+ """Validate opt-in abstention threshold `min_confidence` (#361).
+
+ Must be a real number in [0.0, 1.0]. Booleans are rejected (even though `isinstance(True, int)`).
+ """
+ if isinstance(v, bool) or not isinstance(v, (int, float)) or not math.isfinite(v) or v < 0.0 or v > 1.0:
+ raise ValueError("min_confidence must be a float in [0.0, 1.0], got %r" % (v,))
+ return float(v)
+
+
+def flag_low_confidence(results: List[Dict[str, Any]], min_confidence: float) -> None:
+ """Opt-in abstention marker (#361): flag answers whose confidence falls below `min_confidence`.
+
+ Reads `answer_confidence` (the calibrated max(p) confidence, invariant to label count k),
+ falling back to `confidence` if `answer_confidence` is absent.
+ The raw answer and confidence stay intact; `low_confidence: True` is added.
+ """
+ if min_confidence == 0.0:
+ return
+ for res in results:
+ answers = res.get("answers") if isinstance(res, dict) else None
+ if not isinstance(answers, dict):
+ continue
+ for a in answers.values():
+ if not isinstance(a, dict):
+ continue
+ conf = a.get("answer_confidence")
+ if conf is None:
+ conf = a.get("confidence")
+ if isinstance(conf, (int, float)) and not isinstance(conf, bool) and math.isfinite(conf) and conf < min_confidence:
+ a["low_confidence"] = True
diff --git a/laya/integrations/langchain.py b/laya/integrations/langchain.py
index f7e5cb9b..3674e043 100644
--- a/laya/integrations/langchain.py
+++ b/laya/integrations/langchain.py
@@ -242,7 +242,9 @@ class LayaRouter(RunnableSerializable):
self.last_decision = res
ans = res["answers"][self.question_id]
choice = ans["choice"]
- confidence = ans.get("confidence", 1.0)
+ confidence = ans.get("answer_confidence")
+ if confidence is None:
+ confidence = ans.get("confidence", 1.0)
if self.confidence_threshold > 0.0 and confidence < self.confidence_threshold:
if self.fallback is not None:
diff --git a/laya/onnx_agent.py b/laya/onnx_agent.py
index 0f4a19f5..3c6a9414 100644
--- a/laya/onnx_agent.py
+++ b/laya/onnx_agent.py
@@ -26,6 +26,7 @@ from laya.common import (
TEMP_MAX,
clamp_temperature,
)
+from laya.confidence import check_min_confidence, flag_low_confidence
class ONNXAgent(HookRegistry):
@@ -229,12 +230,14 @@ class ONNXAgent(HookRegistry):
hooks_raise: Optional[bool] = None,
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
- head_max_len: Optional[int] = None) -> Dict[str, Any]:
+ head_max_len: Optional[int] = None,
+ min_confidence: Optional[float] = None) -> Dict[str, Any]:
"""Evaluate typed questions, running any opt-in hooks around the inference.
`lang` selects a per-language temperature override (see `lang_temperatures`), matching the
PyTorch `Agent.system_one` signature so either backend is a drop-in for the other.
"""
+ mc = check_min_confidence(min_confidence) if min_confidence is not None else None
active = compose_hooks(self.hooks, hooks, on_predict_start, on_predict_end)
raise_errors = self.hooks_raise if hooks_raise is None else bool(hooks_raise)
timeout = self.hooks_timeout if hooks_timeout is None else validate_timeout(hooks_timeout)
@@ -267,6 +270,8 @@ class ONNXAgent(HookRegistry):
ctx.error.__context__ = hook_exc
else:
raise
+ if mc is not None and ctx.results:
+ flag_low_confidence(ctx.results, mc)
return ctx.results[0]
def _infer(self, state: Union[str, dict, list], questions: Dict[str, Dict[str, Any]],
@@ -387,6 +392,7 @@ class ONNXAgent(HookRegistry):
def decide(self, state: Union[str, dict, list], schema: Any = None, *,
questions: Optional[Dict[str, Dict[str, Any]]] = None, return_details: bool = False,
+ min_confidence: Optional[float] = None,
**predict_kwargs) -> Any:
"""Answer `state` against a schema (JSON schema or pydantic model) and return typed values.
@@ -395,6 +401,6 @@ class ONNXAgent(HookRegistry):
"""
from laya.structured import decide as _decide
return _decide(self, state, schema, questions=questions,
- return_details=return_details, **predict_kwargs)
+ return_details=return_details, min_confidence=min_confidence, **predict_kwargs)
predict = system_one
diff --git a/laya/router.py b/laya/router.py
index 7dd999eb..ccfacda2 100644
--- a/laya/router.py
+++ b/laya/router.py
@@ -35,6 +35,7 @@ import time
from collections.abc import Sequence as SequenceABC
from typing import Any, Dict, List, Optional, Sequence, Union
+from .confidence import check_min_confidence, flag_low_confidence
from .hooks import (
HookRegistry, PredictContext, aggregate_usage, compose_hooks, dispatch, normalise_hooks,
validate_timeout,
@@ -563,6 +564,7 @@ class Router(HookRegistry):
hooks_timeout: Optional[float] = None,
max_len: Optional[int] = None,
head_max_len: Optional[int] = None,
+ min_confidence: Optional[float] = None,
) -> Dict[str, Any]:
"""Route, then answer every question in one forward pass on the chosen checkpoint.
@@ -571,6 +573,7 @@ class Router(HookRegistry):
and see `ctx.decision`; see `laya.hooks`. `max_len` / `head_max_len` override the agent
token budget for this call (a start hook may set `ctx.max_len` / `ctx.head_max_len`).
"""
+ mc = check_min_confidence(min_confidence) if min_confidence is not None else None
active = compose_hooks(self.hooks, hooks, on_predict_start, on_predict_end)
raise_errors = self.hooks_raise if hooks_raise is None else bool(hooks_raise)
timeout = self.hooks_timeout if hooks_timeout is None else validate_timeout(hooks_timeout)
@@ -597,12 +600,13 @@ class Router(HookRegistry):
overrides["max_len"] = ctx.max_len
if ctx.head_max_len is not None:
overrides["head_max_len"] = ctx.head_max_len
-
+
skip = _SKIP_DEFAULTS.set(True)
try:
result = agent.system_one(ctx.states[0], ctx.questions, lang=effective_lang, **overrides)
except TypeError as e:
if "unexpected keyword argument 'lang'" in str(e):
+ overrides.pop("lang", None)
result = agent.system_one(ctx.states[0], ctx.questions, **overrides)
else:
raise
@@ -634,10 +638,13 @@ class Router(HookRegistry):
ctx.error.__context__ = hook_exc
else:
raise
+ if mc is not None and ctx.results:
+ flag_low_confidence(ctx.results, mc)
return ctx.results[0]
def decide(self, state: Union[str, dict, list], schema: Any = None, *,
questions: Optional[Dict[str, Any]] = None, return_details: bool = False,
+ min_confidence: Optional[float] = None,
**predict_kwargs) -> Any:
"""Answer `state` against a schema (JSON schema or pydantic model) and return typed values.
@@ -646,7 +653,7 @@ class Router(HookRegistry):
"""
from .structured import decide as _decide
return _decide(self, state, schema, questions=questions,
- return_details=return_details, **predict_kwargs)
+ return_details=return_details, min_confidence=min_confidence, **predict_kwargs)
def __enter__(self):
return self
@@ -704,6 +711,7 @@ class Router(HookRegistry):
requests: Sequence[Dict[str, Any]],
batch_size: Optional[int] = None,
hooks_timeout: Optional[float] = None,
+ min_confidence: Optional[float] = None,
) -> List[Dict[str, Any]]:
"""Route and execute a heterogeneous request batch with minimal model churn.
@@ -733,6 +741,7 @@ class Router(HookRegistry):
Returns:
One normal Router prediction result per request, in the same order as the input.
"""
+ mc = check_min_confidence(min_confidence) if min_confidence is not None else None
decisions = self.route_batch(requests)
if not decisions:
return []
@@ -882,7 +891,10 @@ class Router(HookRegistry):
if any(result is None for result in results):
raise RuntimeError("internal error: batch execution did not produce every result")
- return [result for result in results if result is not None]
+ final = [result for result in results if result is not None]
+ if mc is not None:
+ flag_low_confidence(final, mc)
+ return final
predict_many = predict_batch
diff --git a/laya/structured.py b/laya/structured.py
index 61005c35..dc43dc3d 100644
--- a/laya/structured.py
+++ b/laya/structured.py
@@ -19,6 +19,8 @@ from __future__ import annotations
from dataclasses import dataclass, field
from typing import Any, Dict, List, Optional, Sequence, Tuple
+from .confidence import check_min_confidence, flag_low_confidence
+
MAX_PROPERTIES = 32
MAX_OPTIONS = 32
MAX_SCORE_LEVELS = 10
@@ -198,6 +200,9 @@ def _project(answers: Dict[str, Any], fields: Sequence[_Field]) -> Dict[str, Any
answer = answers.get(f.name)
if answer is None:
continue
+ if answer.get("low_confidence"):
+ values[f.name] = None
+ continue
if f.kind == "noul":
values[f.name] = bool(float(answer.get("noul", 0.0)) >= 0.5)
elif f.kind == "score":
@@ -245,7 +250,7 @@ def _details(values: Dict[str, Any], answers: Dict[str, Any], result: Dict[str,
def decide(runner, state: Any, schema: Any = None, *, questions: Optional[Dict[str, Any]] = None,
- return_details: bool = False, **predict_kwargs) -> Any:
+ return_details: bool = False, min_confidence: Optional[float] = None, **predict_kwargs) -> Any:
"""Answer `state` against a schema (or explicit questions) and return the decided values.
Pass exactly one of `schema` or `questions`. With `schema`, the values follow the schema
@@ -256,12 +261,27 @@ def decide(runner, state: Any, schema: Any = None, *, questions: Optional[Dict[s
if (schema is None) == (questions is None):
raise ValueError("pass exactly one of schema= or questions=")
+ mc = check_min_confidence(min_confidence) if min_confidence is not None else None
+ if mc is not None:
+ predict_kwargs["min_confidence"] = mc
+
fields: Optional[List[_Field]] = None
if schema is not None:
fields = plan_from_json_schema(_schema_of(schema))
questions = {f.name: f.question for f in fields}
- result = runner.predict(state, questions, **predict_kwargs)
+ try:
+ result = runner.predict(state, questions, **predict_kwargs)
+ except TypeError as e:
+ if mc is not None and "unexpected keyword argument 'min_confidence'" in str(e):
+ predict_kwargs.pop("min_confidence", None)
+ result = runner.predict(state, questions, **predict_kwargs)
+ else:
+ raise
+
+ if mc is not None and isinstance(result, dict):
+ flag_low_confidence([result], mc)
+
answers = result.get("answers", {}) or {}
values = _project(answers, fields) if fields is not None else dict(answers)
if return_details:
diff --git a/tests/test_confidence.py b/tests/test_confidence.py
index 2c750780..02dc784e 100644
--- a/tests/test_confidence.py
+++ b/tests/test_confidence.py
@@ -107,12 +107,56 @@ for probs, k in (([0.1, 0.9], 2), ([0.25] * 4, 4), ([0.7, 0.2, 0.1], 3)):
check_true("entropy/formula for k=%d" % k,
close(confidence_from_probs(p, k), float(np.clip(1 - ent / math.log(k), 0.0, 1.0))))
+# --------------------------------------------------------------- min_confidence validation & abstention (#361)
+from laya.confidence import check_min_confidence, flag_low_confidence # noqa: E402
+
+# check_min_confidence validates [0.0, 1.0] and rejects non-floats and bools
+for valid in (0.0, 0.5, 1.0, 0, 1, 0.85):
+ check("min_confidence/valid %.2f" % valid, check_min_confidence(valid), float(valid))
+
+for invalid in (True, False, -0.01, 1.01, -1.0, 2.0, float("nan"), float("inf"), float("-inf"), "0.5", None, [0.5]):
+ try:
+ check_min_confidence(invalid)
+ FAIL.append("min_confidence/should reject %r" % (invalid,))
+ except ValueError:
+ PASS.append("min_confidence/rejected %r" % (invalid,))
+
+# flag_low_confidence marks answers where answer_confidence < threshold
+sample_res = [{
+ "answers": {
+ "q_high": {"type": "choice", "choice": "a", "answer_confidence": 0.92, "confidence": 0.8},
+ "q_low": {"type": "score", "score": 1, "answer_confidence": 0.45, "confidence": 0.4},
+ "q_fallback": {"type": "choice", "choice": "b", "confidence": 0.3},
+ "q_exact": {"type": "choice", "choice": "c", "answer_confidence": 0.70},
+ }
+}]
+
+# min_confidence=0.0 is a no-op (default behavior untouched)
+flag_low_confidence(sample_res, 0.0)
+check_true("flag/0.0 is no-op", not any("low_confidence" in a for a in sample_res[0]["answers"].values()))
+
+# min_confidence=0.70: q_low (0.45) and q_fallback (0.3) flagged; q_high (0.92) and q_exact (0.70) NOT flagged
+flag_low_confidence(sample_res, 0.70)
+ans = sample_res[0]["answers"]
+check_true("flag/q_low flagged", ans["q_low"].get("low_confidence") is True)
+check_true("flag/q_fallback flagged", ans["q_fallback"].get("low_confidence") is True)
+check_true("flag/q_high unflagged", "low_confidence" not in ans["q_high"])
+check_true("flag/q_exact unflagged", "low_confidence" not in ans["q_exact"])
+check("flag/answer_confidence intact", ans["q_low"]["answer_confidence"], 0.45)
+check("flag/raw choice intact", ans["q_high"]["choice"], "a")
+
# --------------------------------------------------------------- exported
import laya # noqa: E402
check_true("export/answer_confidence is importable from laya", hasattr(laya, "answer_confidence"))
check_true("export/answer_confidence is in __all__", "answer_confidence" in laya.__all__)
check_true("export/answer_confidence is in dir()", "answer_confidence" in dir(laya))
+check_true("export/check_min_confidence is importable from laya", hasattr(laya, "check_min_confidence"))
+check_true("export/check_min_confidence is in __all__", "check_min_confidence" in laya.__all__)
+check_true("export/check_min_confidence is in dir()", "check_min_confidence" in dir(laya))
+check_true("export/flag_low_confidence is importable from laya", hasattr(laya, "flag_low_confidence"))
+check_true("export/flag_low_confidence is in __all__", "flag_low_confidence" in laya.__all__)
+check_true("export/flag_low_confidence is in dir()", "flag_low_confidence" in dir(laya))
print("\n%d passed, %d failed" % (len(PASS), len(FAIL)))
for f in FAIL:
diff --git a/tests/test_langchain.py b/tests/test_langchain.py
index 628876c0..caecc807 100644
--- a/tests/test_langchain.py
+++ b/tests/test_langchain.py
@@ -124,6 +124,30 @@ check("router/high_conf", router.invoke("I need an invoice refund"), "billing")
check("router/technical", router.invoke("Server crashed with error 500"), "technical")
# Confidence fallback gating
check("router/fallback_on_low_confidence", router.invoke("lowconf question"), "human_agent")
+
+# answer_confidence precedence over entropy confidence (#361)
+# Entropy confidence 0.50 is below threshold 0.75, but answer_confidence 0.85 is above threshold
+def mock_answer_conf_response(state, questions):
+ return {
+ "model": "mock",
+ "answers": {
+ "route": {
+ "type": "choice",
+ "choice": "billing",
+ "confidence": 0.50,
+ "answer_confidence": 0.85,
+ }
+ },
+ }
+
+router_ac = LayaRouter(
+ criteria={"billing": "invoices", "technical": "bugs"},
+ confidence_threshold=0.75,
+ fallback="human_agent",
+ agent=MockLayaAgent(mock_answer_conf_response),
+)
+check("router/uses_answer_confidence_over_entropy", router_ac.invoke("refund please"), "billing")
+
# LangGraph callable protocol
check("router/callable_protocol", router({"messages": [DummyMessage("human", "refund please")]}), "billing")
diff --git a/tests/test_router_batch.py b/tests/test_router_batch.py
index 8677a9a6..afd521f5 100644
--- a/tests/test_router_batch.py
+++ b/tests/test_router_batch.py
@@ -306,3 +306,50 @@ def test_predict_and_predict_batch_pass_the_same_lang(monkeypatch):
calls.clear()
router.predict_batch([request("a", model="english", lang="de")])
assert calls[-1]["lang"] == via_predict == "de"
+
+
+def test_router_predict_and_predict_batch_min_confidence(monkeypatch):
+ """`min_confidence` gates answers below threshold on both predict and predict_batch (#361)."""
+ import laya.agent
+
+ class Agent:
+ def __init__(self, repo, *, device, token, subfolder):
+ pass
+
+ def system_one(self, state, questions, **overrides):
+ return {
+ "model": "fake",
+ "answers": {
+ "q1": {"type": "choice", "choice": "yes", "answer_confidence": 0.95},
+ "q2": {"type": "choice", "choice": "no", "answer_confidence": 0.60},
+ },
+ }
+
+ def predict_batch(self, states, questions, batch_size=None, **overrides):
+ return [self.system_one(s, questions, **overrides) for s in states]
+
+ monkeypatch.setattr(laya.agent, "Agent", Agent)
+ router = Router(max_loaded=1, default="english")
+
+ # Default min_confidence=None: no low_confidence flags
+ res_default = router.predict("hello", {"q1": {}}, model="english")
+ assert "low_confidence" not in res_default["answers"]["q1"]
+ assert "low_confidence" not in res_default["answers"]["q2"]
+
+ # min_confidence=0.80 on predict: q2 flagged, q1 unflagged
+ res_gated = router.predict("hello", {"q1": {}}, model="english", min_confidence=0.80)
+ assert "low_confidence" not in res_gated["answers"]["q1"]
+ assert res_gated["answers"]["q2"]["low_confidence"] is True
+
+ # min_confidence=0.80 on predict_batch: q2 flagged, q1 unflagged
+ batch_res = router.predict_batch([request("hello", model="english")], min_confidence=0.80)
+ assert "low_confidence" not in batch_res[0]["answers"]["q1"]
+ assert batch_res[0]["answers"]["q2"]["low_confidence"] is True
+
+ # Rejection of invalid thresholds
+ with pytest.raises(ValueError):
+ router.predict("hello", {"q1": {}}, min_confidence=1.5)
+ with pytest.raises(ValueError):
+ router.predict("hello", {"q1": {}}, min_confidence=True)
+ with pytest.raises(ValueError):
+ router.predict_batch([request("hello", model="english")], min_confidence=-0.1)
diff --git a/tests/test_structured.py b/tests/test_structured.py
index 6bc73eb4..24a09253 100644
--- a/tests/test_structured.py
+++ b/tests/test_structured.py
@@ -173,6 +173,53 @@ runner = FakeRunner(ANSWERS)
decide(runner, "s", schema=SCHEMA, hooks_raise=False)
check("decide/forwards predict kwargs", runner.calls[0]["kwargs"], {"hooks_raise": False})
+# --------------------------------------------------------------- min_confidence abstention (#361)
+# Default behavior unchanged: all fields project normally when min_confidence is omitted
+runner_default = FakeRunner(ANSWERS)
+out_default = decide(runner_default, "s", schema=SCHEMA)
+check("decide/default department unchanged", out_default["department"], "billing")
+check("decide/default urgency unchanged", out_default["urgency"], 2)
+check("decide/default needs_human unchanged", out_default["needs_human"], True)
+check("decide/default priority unchanged", out_default["priority"], 2)
+check_true("decide/default has no low_confidence flags",
+ not any(a.get("low_confidence") for a in ANSWERS.values()))
+
+# With min_confidence=0.85: answers below 0.85 project as None, raw confidence preserved
+runner_gated = FakeRunner({k: dict(v) for k, v in ANSWERS.items()})
+out_gated = decide(runner_gated, "s", schema=SCHEMA, min_confidence=0.85)
+check("decide/gated high-confidence field kept", out_gated["department"], "billing")
+check("decide/gated low-confidence score becomes None", out_gated["urgency"], None)
+check("decide/gated low-confidence noul becomes None", out_gated["needs_human"], None)
+check("decide/gated low-confidence choice becomes None", out_gated["priority"], None)
+
+# With return_details=True, details keep raw confidence and answers dict
+runner_det = FakeRunner({k: dict(v) for k, v in ANSWERS.items()})
+det = decide(runner_det, "s", schema=SCHEMA, min_confidence=0.85, return_details=True)
+check("decide/details values has None for low conf", det.values["urgency"], None)
+check("decide/details raw confidence preserved", det.confidence["urgency"], 0.5)
+check_true("decide/details answers flag set", det.answers["urgency"].get("low_confidence") is True)
+check("decide/details high conf value kept", det.values["department"], "billing")
+check_true("decide/details high conf flag unset", det.answers["department"].get("low_confidence") is not True)
+
+# Direct projection with low_confidence: True in answer
+answers_with_flag = {
+ "department": {"type": "choice", "choice": "billing", "confidence": 0.4, "low_confidence": True},
+ "urgency": {"type": "score", "score": 2.0, "confidence": 0.9, "probabilities": {"0": 0.0, "1": 0.1, "2": 0.9}, "legend": {}},
+}
+proj = answers_to_json(answers_with_flag, SCHEMA)
+check("project/flagged answer becomes None", proj["department"], None)
+check("project/unflagged answer keeps value", proj["urgency"], 2)
+
+# Invalid min_confidence validation
+check_raises("decide/rejects min_confidence > 1", ValueError,
+ lambda: decide(runner, "s", schema=SCHEMA, min_confidence=1.2))
+check_raises("decide/rejects min_confidence < 0", ValueError,
+ lambda: decide(runner, "s", schema=SCHEMA, min_confidence=-0.1))
+check_raises("decide/rejects bool min_confidence", ValueError,
+ lambda: decide(runner, "s", schema=SCHEMA, min_confidence=True))
+check_raises("decide/rejects str min_confidence", ValueError,
+ lambda: decide(runner, "s", schema=SCHEMA, min_confidence="0.85"))
+
# --------------------------------------------------------------- pydantic (optional)
try: