"""Stateless orchestration with bounded decoding and content-free failures.""" import base64 import binascii import math from time import monotonic from typing import Any from .contracts import NumericPolicy, RankedCandidate from .decision import decide from .digit_substitution import expand_nid_recovery_beams from .model_registry import ModelRegistry from .schema_ranker import rank_candidates MAX_IMAGE_BYTES = 6 * 1024 * 1024 def _compose_word_confidence(scores: list[float]) -> tuple[float | None, float | None, float | None]: if not scores: return None, None, None minimum = min(scores) mean = sum(scores) / len(scores) log_sum = sum(math.log(max(score, 1e-9)) for score in scores) geo = math.exp(log_sum / len(scores)) composed = min(1.0, max(minimum, geo)) return round(composed * 100, 3), round(mean * 100, 3), round(minimum * 100, 3) def _build_confidence_tree(normalized_text: str, characters: list[dict[str, Any]]) -> dict[str, Any]: char_nodes = [ { "text": item["character"], "confidence": item["confidence"], "evidence": "measured" if item.get("confidenceSource") == "engine" else "derived", "calibration": "uncalibrated", **({"alternatives": [{"text": alt["character"], "confidence": alt["probability"]} for alt in item.get("alternatives", [])]} if item.get("alternatives") else {}), } for item in characters ] probs = [item["confidence"] / 100 for item in characters if isinstance(item.get("confidence"), (int, float))] confidence, confidence_mean, confidence_min = _compose_word_confidence(probs) if len(probs) == len(characters) else (None, None, None) return { "version": 1, "words": [{ "text": normalized_text, "confidence": confidence, "confidenceMean": confidence_mean, "confidenceMin": confidence_min, "aggregation": "weighted-geometric-mean" if confidence is not None else "unavailable", "lexiconValid": None, "evidence": "measured", "characters": char_nodes, }], } class NumericInferenceService: def __init__(self, registry: ModelRegistry): self.registry = registry def recognize(self, request: dict[str, Any]) -> dict[str, Any]: return self.recognize_images([request])[0] def recognize_images(self, requests: list[dict[str, Any]]) -> list[dict[str, Any]]: started = monotonic() images = [self._image_bytes(request) for request in requests] try: recognizer = self.registry.require() raw_images = [bytes(image) for image in images] classes = [request["semanticClass"] for request in requests] batch = getattr(recognizer, "recognize_batch", None) if callable(batch): grouped = batch(raw_images, classes) else: grouped = [ recognizer.recognize(raw, semantic) for raw, semantic in zip(raw_images, classes, strict=True) ] if len(grouped) != len(requests): raise RuntimeError("numeric_batch_width_mismatch") return [self._finish(request, beams, started) for request, beams in zip(requests, grouped)] finally: for image in images: image[:] = b"\0" * len(image) def _image_bytes(self, request: dict[str, Any]) -> bytearray: raw = request.get("image") if isinstance(raw, bytearray): decoded = raw elif isinstance(raw, bytes): decoded = bytearray(raw) else: decoded = self._decode(request.get("imageBase64", "")) if not decoded or len(decoded) > MAX_IMAGE_BYTES: decoded[:] = b"\0" * len(decoded) raise ValueError("invalid_image_size") return decoded def _finish(self, request: dict[str, Any], beams: list, started: float) -> dict[str, Any]: semantic_class = request["semanticClass"] policy = NumericPolicy(semantic_class, request.get("expectedLength")) beams = expand_nid_recovery_beams(beams, semantic_class) ranked = rank_candidates(beams, policy) candidate = ranked[0] if ranked else None bound = self.registry.reliability.lower_bound(semantic_class) decision = decide( candidate, semantic_class, agreement=bool(request.get("independentAgreement")), reliability_lower_bound=bound, ) response = { "contractVersion": 1, "requestId": request["requestId"], "candidate": self._candidate(candidate), "decision": decision, "reliabilityLowerBound": round(bound, 6), "modelVersion": self.registry.version, "latencyMs": round((monotonic() - started) * 1000, 3), } if candidate is None: response["failureMode"] = "no_numeric_candidate" return response @staticmethod def _decode(encoded: str) -> bytearray: try: decoded = bytearray(base64.b64decode(encoded, validate=True)) except (binascii.Error, ValueError) as error: raise ValueError("invalid_image_payload") from error if not decoded or len(decoded) > MAX_IMAGE_BYTES: decoded[:] = b"\0" * len(decoded) raise ValueError("invalid_image_size") return decoded @staticmethod def _candidate(candidate: RankedCandidate | None) -> dict[str, Any] | None: if candidate is None: return None char_confidences = candidate.character_confidences sources = candidate.character_confidence_sources aligned = len(char_confidences) == len(candidate.normalized_text) valid_scores = aligned and all(math.isfinite(score) and 0 <= score <= 1 for score in char_confidences) valid_sources = len(sources) == len(char_confidences) and all(source in {"engine", "derived"} for source in sources) alt_rows = candidate.character_alternatives if valid_scores: effective_sources = sources if valid_sources else ("derived",) * len(char_confidences) characters = [] for index, (char, conf, source) in enumerate( zip(candidate.normalized_text, char_confidences, effective_sources) ): alts = alt_rows[index] if index < len(alt_rows) else () characters.append({ "character": char, "confidence": round(conf * 100, 3), "alternatives": [ {"character": alt_char, "probability": round(alt_prob * 100, 3)} for alt_char, alt_prob in alts[:3] ], "confidenceSource": source, }) else: character_confidence = candidate.min_character_confidence characters = [ {"character": char, "confidence": character_confidence, "alternatives": [], "confidenceSource": "derived"} for char in candidate.normalized_text ] variant = candidate.preprocessing_variant payload = { "normalizedText": candidate.normalized_text, "sourceScript": candidate.source_script, "calibratedConfidence": candidate.calibrated_confidence, "minCharacterConfidence": candidate.min_character_confidence, "beamMargin": candidate.beam_margin, "characters": characters, "schemaValid": candidate.schema_valid, "checksumValid": candidate.checksum_valid, "preprocessingVariant": variant, } payload["confidenceTree"] = _build_confidence_tree(candidate.normalized_text, characters) return payload