File size: 29,852 Bytes
f9bc0c1 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 | """Recognizer admission decision artifacts."""
from __future__ import annotations
import json
import math
from dataclasses import dataclass, field
from pathlib import Path
from typing import Any
from .errors import ValidationError
@dataclass(slots=True)
class FailedAdmissionGate:
baseline: str
metric: str
slices: list[str] = field(default_factory=list)
pairs: int | None = None
candidate_mean: float | None = None
baseline_mean: float | None = None
absolute_improvement: float | None = None
relative_improvement: float | None = None
win_count: int | None = None
loss_count: int | None = None
tie_count: int | None = None
reason: str | None = None
def to_dict(self) -> dict[str, Any]:
return {
"baseline": self.baseline,
"metric": self.metric,
"slices": self.slices,
"pairs": self.pairs,
"candidate_mean": self.candidate_mean,
"baseline_mean": self.baseline_mean,
"absolute_improvement": self.absolute_improvement,
"relative_improvement": self.relative_improvement,
"win_count": self.win_count,
"loss_count": self.loss_count,
"tie_count": self.tie_count,
"reason": self.reason,
}
@dataclass(slots=True)
class RecognizerAdmissionDecision:
validation_report: str
decision: str
claim_status: str
passed: bool
sample_count: int | None
missing_requirements: list[str] = field(default_factory=list)
failed_gates: list[FailedAdmissionGate] = field(default_factory=list)
next_actions: list[str] = field(default_factory=list)
decision_path: str | None = None
markdown_path: str | None = None
def to_dict(self) -> dict[str, Any]:
return {
"validation_report": self.validation_report,
"decision": self.decision,
"claim_status": self.claim_status,
"passed": self.passed,
"sample_count": self.sample_count,
"missing_requirements": self.missing_requirements,
"failed_gates": [gate.to_dict() for gate in self.failed_gates],
"next_actions": self.next_actions,
"decision_path": self.decision_path,
"markdown_path": self.markdown_path,
}
@dataclass(slots=True)
class RecognizerFailureRun:
source_path: str
validation_report: str | None
model_card: str | None
model_id: str
backend: str
base_model: str
decision: str
claim_status: str
passed: bool
sample_count: int | None
failed_gate_count: int
total_pairs: int
total_wins: int
total_losses: int
total_ties: int
failed_slices: list[str]
failed_metrics: list[str]
def to_dict(self) -> dict[str, Any]:
return {
"source_path": self.source_path,
"validation_report": self.validation_report,
"model_card": self.model_card,
"model_id": self.model_id,
"backend": self.backend,
"base_model": self.base_model,
"decision": self.decision,
"claim_status": self.claim_status,
"passed": self.passed,
"sample_count": self.sample_count,
"failed_gate_count": self.failed_gate_count,
"total_pairs": self.total_pairs,
"total_wins": self.total_wins,
"total_losses": self.total_losses,
"total_ties": self.total_ties,
"failed_slices": self.failed_slices,
"failed_metrics": self.failed_metrics,
}
@dataclass(slots=True)
class RecognizerFailureFamily:
family_key: str
backend: str
base_model: str
run_count: int
rejected_count: int
admitted_count: int
total_failed_gates: int
total_pairs: int
total_wins: int
total_losses: int
total_ties: int
failed_slices: list[str]
failed_metrics: list[str]
recommendation: str
rationale: list[str] = field(default_factory=list)
def to_dict(self) -> dict[str, Any]:
return {
"family_key": self.family_key,
"backend": self.backend,
"base_model": self.base_model,
"run_count": self.run_count,
"rejected_count": self.rejected_count,
"admitted_count": self.admitted_count,
"total_failed_gates": self.total_failed_gates,
"total_pairs": self.total_pairs,
"total_wins": self.total_wins,
"total_losses": self.total_losses,
"total_ties": self.total_ties,
"failed_slices": self.failed_slices,
"failed_metrics": self.failed_metrics,
"recommendation": self.recommendation,
"rationale": self.rationale,
}
@dataclass(slots=True)
class RecognizerFailureReview:
admission_decisions: list[str]
validation_reports: list[str]
model_cards: list[str]
min_rejections_to_stop: int
runs: list[RecognizerFailureRun]
families: list[RecognizerFailureFamily]
next_actions: list[str]
review_path: str | None = None
markdown_path: str | None = None
def to_dict(self) -> dict[str, Any]:
return {
"admission_decisions": self.admission_decisions,
"validation_reports": self.validation_reports,
"model_cards": self.model_cards,
"min_rejections_to_stop": self.min_rejections_to_stop,
"runs": [run.to_dict() for run in self.runs],
"families": [family.to_dict() for family in self.families],
"next_actions": self.next_actions,
"review_path": self.review_path,
"markdown_path": self.markdown_path,
}
def decide_recognizer_admission(validation_report: str | Path, output_dir: str | Path) -> RecognizerAdmissionDecision:
report_path = Path(validation_report)
try:
payload = json.loads(report_path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise ValidationError(f"admission validation report does not exist: {report_path}") from exc
except json.JSONDecodeError as exc:
raise ValidationError(f"invalid admission validation JSON {report_path}: {exc}") from exc
if not isinstance(payload, dict):
raise ValidationError(f"admission validation report must be a JSON object: {report_path}")
claim_status = str(payload.get("claim_status") or "")
passed = bool(payload.get("passed"))
decision = "admit" if claim_status == "validated" and passed else "reject"
failed_gates = _failed_gates(payload)
missing_requirements = _missing_requirements(payload)
next_actions = _next_actions(decision, failed_gates, missing_requirements)
sample_count_value = payload.get("sample_count")
sample_count = int(sample_count_value) if isinstance(sample_count_value, int | float) and not isinstance(sample_count_value, bool) else None
out = Path(output_dir)
out.mkdir(parents=True, exist_ok=True)
decision_path = out / "recognizer-admission-decision.json"
markdown_path = out / "recognizer-admission-decision.md"
decision_report = RecognizerAdmissionDecision(
validation_report=str(report_path),
decision=decision,
claim_status=claim_status or "not_run",
passed=passed,
sample_count=sample_count,
missing_requirements=missing_requirements,
failed_gates=failed_gates,
next_actions=next_actions,
decision_path=str(decision_path),
markdown_path=str(markdown_path),
)
decision_path.write_text(json.dumps(decision_report.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
_write_markdown(markdown_path, decision_report)
return decision_report
def review_recognizer_failures(
admission_decisions: list[str | Path],
validation_reports: list[str | Path],
output_dir: str | Path,
*,
model_cards: list[str | Path] | None = None,
min_rejections_to_stop: int = 3,
) -> RecognizerFailureReview:
if min_rejections_to_stop < 1:
raise ValidationError("min_rejections_to_stop must be >= 1")
if not admission_decisions and not validation_reports:
raise ValidationError("recognizer failure review requires at least one admission decision or validation report")
cards = [Path(path) for path in (model_cards or [])]
card_payloads = [_read_json_object(path, "model card") for path in cards]
runs: list[RecognizerFailureRun] = []
for index, path_value in enumerate(admission_decisions):
path = Path(path_value)
decision_payload = _read_json_object(path, "recognizer admission decision")
validation_payload = _read_optional_validation_payload(decision_payload, path)
model_identity = _model_identity_for_run(index, card_payloads, cards, validation_payload, path)
runs.append(_failure_run_from_decision(path, decision_payload, model_identity))
offset = len(runs)
for index, path_value in enumerate(validation_reports):
path = Path(path_value)
validation_payload = _read_json_object(path, "admission validation report")
decision_payload = _decision_payload_from_validation(path, validation_payload)
model_identity = _model_identity_for_run(offset + index, card_payloads, cards, validation_payload, path)
runs.append(_failure_run_from_decision(path, decision_payload, model_identity))
families = _failure_families(runs, min_rejections_to_stop=min_rejections_to_stop)
next_actions = _failure_review_next_actions(families)
out = Path(output_dir)
out.mkdir(parents=True, exist_ok=True)
review_path = out / "recognizer-failure-review.json"
markdown_path = out / "recognizer-failure-review.md"
review = RecognizerFailureReview(
admission_decisions=[str(Path(path)) for path in admission_decisions],
validation_reports=[str(Path(path)) for path in validation_reports],
model_cards=[str(path) for path in cards],
min_rejections_to_stop=min_rejections_to_stop,
runs=runs,
families=families,
next_actions=next_actions,
review_path=str(review_path),
markdown_path=str(markdown_path),
)
review_path.write_text(json.dumps(review.to_dict(), ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
_write_failure_review_markdown(markdown_path, review)
return review
def stopped_recognizer_family_reasons(failure_review: str | Path, *, backend: str, base_model: str) -> list[str]:
review_path = Path(failure_review)
payload = _read_json_object(review_path, "recognizer failure review")
families = payload.get("families")
if not isinstance(families, list):
raise ValidationError(f"recognizer failure review missing families list: {review_path}")
canonical_base = _canonical_recognizer_base_model(base_model)
reasons: list[str] = []
for item in families:
if not isinstance(item, dict):
continue
family_backend = str(item.get("backend") or "")
family_base = _canonical_recognizer_base_model(str(item.get("base_model") or ""))
if family_backend != backend or family_base != canonical_base:
continue
if item.get("recommendation") != "stop_family":
continue
reasons.append(
"recognizer family is stopped by {review}: family={family} rejected_runs={rejected} "
"wins/losses/ties={wins}/{losses}/{ties}".format(
review=review_path,
family=item.get("family_key") or f"{family_backend}::{family_base}",
rejected=item.get("rejected_count"),
wins=item.get("total_wins"),
losses=item.get("total_losses"),
ties=item.get("total_ties"),
)
)
return reasons
def assert_recognizer_family_not_stopped(failure_review: str | Path, *, backend: str, base_model: str) -> None:
reasons = stopped_recognizer_family_reasons(failure_review, backend=backend, base_model=base_model)
if reasons:
raise ValidationError("; ".join(reasons))
def _missing_requirements(payload: dict[str, Any]) -> list[str]:
value = payload.get("missing_requirements")
if not isinstance(value, list):
return []
return [str(item) for item in value if isinstance(item, str) and item]
def _failed_gates(payload: dict[str, Any]) -> list[FailedAdmissionGate]:
gates = payload.get("gates")
if not isinstance(gates, list):
return []
failed: list[FailedAdmissionGate] = []
for item in gates:
if not isinstance(item, dict) or item.get("passed") is True:
continue
gate = item.get("gate")
gate_payload = gate if isinstance(gate, dict) else {}
failed.append(
FailedAdmissionGate(
baseline=str(gate_payload.get("baseline") or ""),
metric=str(gate_payload.get("metric") or ""),
slices=_gate_slices(gate_payload),
pairs=_int_or_none(item.get("pairs")),
candidate_mean=_float_or_none(item.get("candidate_mean")),
baseline_mean=_float_or_none(item.get("baseline_mean")),
absolute_improvement=_float_or_none(item.get("absolute_improvement")),
relative_improvement=_float_or_none(item.get("relative_improvement")),
win_count=_int_or_none(item.get("win_count")),
loss_count=_int_or_none(item.get("loss_count")),
tie_count=_int_or_none(item.get("tie_count")),
reason=str(item.get("reason")) if item.get("reason") else None,
)
)
return failed
def _gate_slices(gate: dict[str, Any]) -> list[str]:
value = gate.get("slices")
if isinstance(value, list):
return [str(item) for item in value if str(item)]
single = gate.get("slice")
return [str(single)] if single else []
def _float_or_none(value: Any) -> float | None:
if isinstance(value, bool) or not isinstance(value, int | float):
return None
as_float = float(value)
return as_float if math.isfinite(as_float) else None
def _int_or_none(value: Any) -> int | None:
if isinstance(value, bool) or not isinstance(value, int | float):
return None
as_float = float(value)
if not math.isfinite(as_float):
return None
return int(as_float)
def _next_actions(decision: str, failed_gates: list[FailedAdmissionGate], missing_requirements: list[str]) -> list[str]:
if decision == "admit":
return [
"Attach this admission report to the model card and run claim preflight with --require-model-admission.",
"Promote the recognizer only through the full document SOTA portfolio; admission is not a final SOTA claim.",
]
actions: list[str] = []
failed_slices = {slice_name.lower() for gate in failed_gates for slice_name in gate.slices}
failed_metrics = {gate.metric for gate in failed_gates}
losses = sum((gate.loss_count or 0) for gate in failed_gates)
wins = sum((gate.win_count or 0) for gate in failed_gates)
if "english" in failed_slices or "en" in failed_slices or "line_crop" in failed_slices:
actions.append("Do not train another Devanagari-only recognizer branch until English preservation is explicitly designed and gated.")
if "nepali" in failed_slices:
actions.append("Investigate the Nepali recognizer path separately; the current branch does not clear the Devanagari admission slice.")
if "cer" in failed_metrics or "wer" in failed_metrics:
actions.append("Prioritize recognizer correctness before document-structure integration; OCR gates are failing upstream.")
if losses > 0 and wins == 0:
actions.append("Stop this exact model family for engine promotion; it has no paired wins in the admission failure gates.")
if not actions and missing_requirements:
actions.append("Fix the missing validation requirements before spending more GPU time.")
if not actions:
actions.append("Treat this branch as rejected until a new validation report passes the admission gate.")
return actions
def _write_markdown(path: Path, decision: RecognizerAdmissionDecision) -> None:
lines = [
"# Recognizer Admission Decision",
"",
f"Validation report: `{decision.validation_report}`",
f"Decision: `{decision.decision}`",
f"Claim status: `{decision.claim_status}`",
f"Passed: `{'yes' if decision.passed else 'no'}`",
f"Samples: `{decision.sample_count if decision.sample_count is not None else 'unknown'}`",
"",
"## Missing Requirements",
"",
]
lines.extend(f"- {item}" for item in decision.missing_requirements) if decision.missing_requirements else lines.append("- none")
lines.extend(
[
"",
"## Failed Gates",
"",
"| baseline | metric | slices | pairs | candidate | baseline mean | abs improvement | wins | losses | ties | reason |",
"| --- | --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- |",
]
)
if decision.failed_gates:
for gate in decision.failed_gates:
lines.append(
"| {baseline} | {metric} | {slices} | {pairs} | {candidate} | {baseline_mean} | {absolute} | {wins} | {losses} | {ties} | {reason} |".format(
baseline=gate.baseline,
metric=gate.metric,
slices=",".join(gate.slices),
pairs="" if gate.pairs is None else gate.pairs,
candidate=_format_optional_float(gate.candidate_mean),
baseline_mean=_format_optional_float(gate.baseline_mean),
absolute=_format_optional_float(gate.absolute_improvement),
wins="" if gate.win_count is None else gate.win_count,
losses="" if gate.loss_count is None else gate.loss_count,
ties="" if gate.tie_count is None else gate.tie_count,
reason=(gate.reason or "").replace("|", "\\|"),
)
)
else:
lines.append("| none | | | | | | | | | | |")
lines.extend(["", "## Next Actions", ""])
lines.extend(f"- {item}" for item in decision.next_actions) if decision.next_actions else lines.append("- none")
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
def _read_json_object(path: Path, label: str) -> dict[str, Any]:
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except FileNotFoundError as exc:
raise ValidationError(f"{label} does not exist: {path}") from exc
except json.JSONDecodeError as exc:
raise ValidationError(f"invalid {label} JSON {path}: {exc}") from exc
if not isinstance(payload, dict):
raise ValidationError(f"{label} must be a JSON object: {path}")
return payload
def _read_optional_validation_payload(decision_payload: dict[str, Any], decision_path: Path) -> dict[str, Any] | None:
value = decision_payload.get("validation_report")
if not isinstance(value, str) or not value:
return None
path = Path(value)
if not path.is_absolute() and not path.exists():
path = decision_path.parent / path
if not path.exists():
return None
return _read_json_object(path, "admission validation report")
def _decision_payload_from_validation(path: Path, payload: dict[str, Any]) -> dict[str, Any]:
claim_status = str(payload.get("claim_status") or "")
passed = bool(payload.get("passed"))
return {
"validation_report": str(path),
"decision": "admit" if claim_status == "validated" and passed else "reject",
"claim_status": claim_status or "not_run",
"passed": passed,
"sample_count": payload.get("sample_count"),
"failed_gates": [gate.to_dict() for gate in _failed_gates(payload)],
}
def _model_identity_for_run(
index: int,
card_payloads: list[dict[str, Any]],
cards: list[Path],
validation_payload: dict[str, Any] | None,
source_path: Path,
) -> tuple[str, str, str, str | None]:
if index < len(card_payloads):
payload = card_payloads[index]
return (
str(payload.get("model_id") or "unknown"),
str(payload.get("backend") or "unknown"),
str(payload.get("base_model") or "unknown"),
str(cards[index]),
)
if validation_payload:
candidate_path = _candidate_model_config_path(validation_payload, source_path)
if candidate_path and candidate_path.exists():
payload = _read_json_object(candidate_path, "candidate model card")
return (
str(payload.get("model_id") or "unknown"),
str(payload.get("backend") or "unknown"),
str(payload.get("base_model") or "unknown"),
str(candidate_path),
)
return ("unknown", "unknown", "unknown", None)
def _candidate_model_config_path(validation_payload: dict[str, Any], source_path: Path) -> Path | None:
provenance = validation_payload.get("provenance")
if not isinstance(provenance, dict):
return None
candidate = provenance.get("candidate_model_config")
if not isinstance(candidate, dict):
return None
path_value = candidate.get("path")
if not isinstance(path_value, str) or not path_value:
return None
path = Path(path_value)
if path.is_absolute() or path.exists():
return path
relative = source_path.parent / path
return relative if relative.exists() else path
def _failure_run_from_decision(path: Path, payload: dict[str, Any], model_identity: tuple[str, str, str, str | None]) -> RecognizerFailureRun:
gates = payload.get("failed_gates")
failed_gates = [_failed_gate_from_payload(item) for item in gates if isinstance(item, dict)] if isinstance(gates, list) else []
model_id, backend, base_model, model_card = model_identity
return RecognizerFailureRun(
source_path=str(path),
validation_report=str(payload.get("validation_report")) if payload.get("validation_report") else None,
model_card=model_card,
model_id=model_id,
backend=backend,
base_model=base_model,
decision=str(payload.get("decision") or "unknown"),
claim_status=str(payload.get("claim_status") or "not_run"),
passed=bool(payload.get("passed")),
sample_count=_int_or_none(payload.get("sample_count")),
failed_gate_count=len(failed_gates),
total_pairs=sum(gate.pairs or 0 for gate in failed_gates),
total_wins=sum(gate.win_count or 0 for gate in failed_gates),
total_losses=sum(gate.loss_count or 0 for gate in failed_gates),
total_ties=sum(gate.tie_count or 0 for gate in failed_gates),
failed_slices=sorted({slice_name for gate in failed_gates for slice_name in gate.slices}),
failed_metrics=sorted({gate.metric for gate in failed_gates if gate.metric}),
)
def _failed_gate_from_payload(payload: dict[str, Any]) -> FailedAdmissionGate:
return FailedAdmissionGate(
baseline=str(payload.get("baseline") or ""),
metric=str(payload.get("metric") or ""),
slices=[str(item) for item in payload.get("slices", []) if str(item)] if isinstance(payload.get("slices"), list) else [],
pairs=_int_or_none(payload.get("pairs")),
candidate_mean=_float_or_none(payload.get("candidate_mean")),
baseline_mean=_float_or_none(payload.get("baseline_mean")),
absolute_improvement=_float_or_none(payload.get("absolute_improvement")),
relative_improvement=_float_or_none(payload.get("relative_improvement")),
win_count=_int_or_none(payload.get("win_count")),
loss_count=_int_or_none(payload.get("loss_count")),
tie_count=_int_or_none(payload.get("tie_count")),
reason=str(payload.get("reason")) if payload.get("reason") else None,
)
def _failure_families(runs: list[RecognizerFailureRun], *, min_rejections_to_stop: int) -> list[RecognizerFailureFamily]:
grouped: dict[tuple[str, str], list[RecognizerFailureRun]] = {}
for run in runs:
grouped.setdefault((run.backend, _canonical_recognizer_base_model(run.base_model)), []).append(run)
families: list[RecognizerFailureFamily] = []
for (backend, base_model), family_runs in sorted(grouped.items()):
rejected = [run for run in family_runs if run.decision == "reject"]
admitted = [run for run in family_runs if run.decision == "admit"]
total_wins = sum(run.total_wins for run in family_runs)
total_losses = sum(run.total_losses for run in family_runs)
recommendation = "continue_with_new_gate"
rationale: list[str] = []
if len(rejected) >= min_rejections_to_stop and total_wins == 0 and total_losses > 0:
recommendation = "stop_family"
rationale.append(f"{len(rejected)} rejected runs meet the stop threshold of {min_rejections_to_stop}")
rationale.append("failed admission gates have zero paired wins")
elif rejected:
recommendation = "do_not_promote"
rationale.append(f"{len(rejected)} rejected runs remain unresolved")
else:
recommendation = "no_failure_guardrail"
rationale.append("no rejected runs were provided for this family")
families.append(
RecognizerFailureFamily(
family_key=f"{backend}::{base_model}",
backend=backend,
base_model=base_model,
run_count=len(family_runs),
rejected_count=len(rejected),
admitted_count=len(admitted),
total_failed_gates=sum(run.failed_gate_count for run in family_runs),
total_pairs=sum(run.total_pairs for run in family_runs),
total_wins=total_wins,
total_losses=total_losses,
total_ties=sum(run.total_ties for run in family_runs),
failed_slices=sorted({slice_name for run in family_runs for slice_name in run.failed_slices}),
failed_metrics=sorted({metric for run in family_runs for metric in run.failed_metrics}),
recommendation=recommendation,
rationale=rationale,
)
)
return families
def _canonical_recognizer_base_model(base_model: str) -> str:
value = base_model.strip()
lowered = value.lower()
if "devanagari_pp-ocrv3_mobile_rec" in lowered:
return "PaddlePaddle/devanagari_PP-OCRv3_mobile_rec"
return value or "unknown"
def _failure_review_next_actions(families: list[RecognizerFailureFamily]) -> list[str]:
if any(family.recommendation == "stop_family" for family in families):
return [
"Do not spend more GPU time on stopped recognizer families without a different base architecture or training objective.",
"Move engine work toward measurable document parsing with admitted recognizer components or a document-native model.",
"Keep these negative runs in the paper as ablation evidence, not as promoted model results.",
]
if any(family.recommendation == "do_not_promote" for family in families):
return [
"Do not promote rejected recognizers into the engine until a new admission report passes.",
"Add more runs or model-card bindings before declaring a family stopped.",
]
return ["No rejected recognizer family was strong enough to trigger a stop recommendation."]
def _write_failure_review_markdown(path: Path, review: RecognizerFailureReview) -> None:
lines = [
"# Recognizer Failure Review",
"",
f"Admission decisions: `{len(review.admission_decisions)}`",
f"Validation reports: `{len(review.validation_reports)}`",
f"Model cards: `{len(review.model_cards)}`",
f"Stop threshold: `{review.min_rejections_to_stop}` rejected runs with zero paired wins",
"",
"## Families",
"",
"| family | runs | rejected | admitted | failed gates | pairs | wins | losses | slices | recommendation |",
"| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | --- | --- |",
]
for family in review.families:
lines.append(
"| {family} | {runs} | {rejected} | {admitted} | {failed_gates} | {pairs} | {wins} | {losses} | {slices} | {recommendation} |".format(
family=family.family_key.replace("|", "\\|"),
runs=family.run_count,
rejected=family.rejected_count,
admitted=family.admitted_count,
failed_gates=family.total_failed_gates,
pairs=family.total_pairs,
wins=family.total_wins,
losses=family.total_losses,
slices=",".join(family.failed_slices),
recommendation=family.recommendation,
)
)
lines.extend(["", "## Runs", ""])
for run in review.runs:
family = f"{run.backend}::{_canonical_recognizer_base_model(run.base_model)}"
lines.append(
f"- `{run.source_path}`: decision=`{run.decision}` model=`{run.model_id}` family=`{family}` wins/losses/ties=`{run.total_wins}/{run.total_losses}/{run.total_ties}`"
)
lines.extend(["", "## Next Actions", ""])
lines.extend(f"- {item}" for item in review.next_actions)
path.write_text("\n".join(lines) + "\n", encoding="utf-8")
def _format_optional_float(value: float | None) -> str:
return "" if value is None else f"{value:.6f}"
|