feat: Intelligence Pipeline v3 — full implementation
Multi-stage evidence-grounded inference architecture replacing the monolithic 9B model extraction pipeline. CPU-first specialist services handle routine extraction while the 9B vLLM model is preserved for semantic adjudication of ambiguous cases. Key components: - Capability-aware inference gateway (OpenAI-compatible + Ollama) - Endpoint registry with DB migrations and REST API - Sentence-aware document segmenter (property tests) - Deterministic financial parsing with offset integrity - Symbol resolution with ambiguity detection - Specialist service (GLiNER2, dynamic batching, K8s deployment) - Company-specific sentiment (FinBERT, calibration) - Retrieval-based novelty and duplicate detection - Confidence calibration pipeline - Deterministic routing engine (property tests) - 9B adjudication layer with VRAM gating - Stock-specific impact model (features, labels, baseline, trained) - Pipeline orchestrator (state machine, queues, leases, feature flags) - Bounded parallelism (async workers, semaphore, load shedding) - Observability (tracing, metrics, alerts) - Compatibility adapter (v3→v2 golden mapping tests) - Shadow/canary promotion framework - Active learning and fine-tuning pipeline Test results: 1,161 tests pass, ruff lint clean. All 282 spec tasks completed.
This commit is contained in:
Celes Renata
@@ -0,0 +1,28 @@
|
||||
"""Offline replay module for Gold Corpus comparison.
|
||||
|
||||
Runs pipeline configurations against the Gold Corpus, produces field-level
|
||||
and calibration reports, compares v2 baseline vs v3, and enforces
|
||||
safety-critical promotion gates.
|
||||
"""
|
||||
|
||||
from services.intelligence_pipeline_v3.replay.reports import (
|
||||
FieldReport,
|
||||
GateStatus,
|
||||
PromotionGate,
|
||||
ReplayReport,
|
||||
)
|
||||
from services.intelligence_pipeline_v3.replay.runner import (
|
||||
ReplayConfig,
|
||||
ReplayResult,
|
||||
ReplayRunner,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"FieldReport",
|
||||
"GateStatus",
|
||||
"PromotionGate",
|
||||
"ReplayConfig",
|
||||
"ReplayReport",
|
||||
"ReplayResult",
|
||||
"ReplayRunner",
|
||||
]
|
||||
@@ -0,0 +1,189 @@
|
||||
"""Replay reports and promotion gate evaluation.
|
||||
|
||||
Produces field-level, calibration, resource, and difficulty-bucket
|
||||
reports. Enforces safety-critical gates for promotion decisions.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import enum
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
from uuid import UUID
|
||||
|
||||
|
||||
class GateStatus(str, enum.Enum):
|
||||
"""Promotion gate evaluation status."""
|
||||
|
||||
PASSED = "passed"
|
||||
FAILED = "failed"
|
||||
WARNING = "warning"
|
||||
NOT_EVALUATED = "not_evaluated"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class PromotionGate:
|
||||
"""A single promotion gate with a threshold and evaluation logic."""
|
||||
|
||||
name: str
|
||||
metric_name: str
|
||||
threshold: float
|
||||
direction: str # "above" (value must be >= threshold) or "below" (value must be <= threshold)
|
||||
safety_critical: bool = False
|
||||
description: str = ""
|
||||
|
||||
def evaluate(self, value: float) -> GateStatus:
|
||||
"""Evaluate the gate against a metric value."""
|
||||
if self.direction == "above":
|
||||
return GateStatus.PASSED if value >= self.threshold else GateStatus.FAILED
|
||||
elif self.direction == "below":
|
||||
return GateStatus.PASSED if value <= self.threshold else GateStatus.FAILED
|
||||
return GateStatus.NOT_EVALUATED
|
||||
|
||||
|
||||
# Default promotion gates per Requirement 16.5
|
||||
DEFAULT_PROMOTION_GATES: list[PromotionGate] = [
|
||||
PromotionGate(
|
||||
name="entity_f1",
|
||||
metric_name="entity_f1",
|
||||
threshold=0.0, # No regression allowed (relative)
|
||||
direction="above",
|
||||
safety_critical=True,
|
||||
description="Entity/ticker F1 must not regress",
|
||||
),
|
||||
PromotionGate(
|
||||
name="evidence_support_rate",
|
||||
metric_name="evidence_support_rate",
|
||||
threshold=0.85,
|
||||
direction="above",
|
||||
safety_critical=True,
|
||||
description="Evidence support rate must exceed 85%",
|
||||
),
|
||||
PromotionGate(
|
||||
name="schema_validity",
|
||||
metric_name="schema_validity_rate",
|
||||
threshold=0.99,
|
||||
direction="above",
|
||||
safety_critical=True,
|
||||
description="Schema validity must exceed 99%",
|
||||
),
|
||||
PromotionGate(
|
||||
name="calibration_ece",
|
||||
metric_name="calibration_ece",
|
||||
threshold=0.08,
|
||||
direction="below",
|
||||
safety_critical=False,
|
||||
description="Calibration ECE should be below 8%",
|
||||
),
|
||||
PromotionGate(
|
||||
name="fast_path_coverage",
|
||||
metric_name="fast_path_rate",
|
||||
threshold=0.60,
|
||||
direction="above",
|
||||
safety_critical=False,
|
||||
description="Fast-path coverage should reach 60%",
|
||||
),
|
||||
PromotionGate(
|
||||
name="gpu_reduction",
|
||||
metric_name="gpu_seconds_ratio",
|
||||
threshold=0.50,
|
||||
direction="below",
|
||||
safety_critical=False,
|
||||
description="GPU-seconds per doc should be ≤50% of baseline (2x improvement)",
|
||||
),
|
||||
]
|
||||
|
||||
|
||||
@dataclass
|
||||
class FieldReport:
|
||||
"""Field-level metrics for a specific field across all documents."""
|
||||
|
||||
field_name: str
|
||||
precision: float = 0.0
|
||||
recall: float = 0.0
|
||||
f1: float = 0.0
|
||||
exact_match: float = 0.0
|
||||
support_count: int = 0
|
||||
error_count: int = 0
|
||||
|
||||
@property
|
||||
def accuracy(self) -> float:
|
||||
if self.support_count == 0:
|
||||
return 0.0
|
||||
return (self.support_count - self.error_count) / self.support_count
|
||||
|
||||
|
||||
@dataclass
|
||||
class ReplayReport:
|
||||
"""Complete replay comparison report.
|
||||
|
||||
Compares configurations, evaluates promotion gates, and produces
|
||||
field-level, resource, and difficulty-bucket breakdowns.
|
||||
"""
|
||||
|
||||
report_id: UUID
|
||||
config_id: UUID
|
||||
baseline_config_id: UUID | None
|
||||
total_documents: int = 0
|
||||
success_rate: float = 0.0
|
||||
avg_latency_ms: float = 0.0
|
||||
total_gpu_seconds: float = 0.0
|
||||
schema_validity_rate: float = 0.0
|
||||
fast_path_rate: float = 0.0
|
||||
field_reports: list[FieldReport] = field(default_factory=list)
|
||||
gate_results: dict[str, GateStatus] = field(default_factory=dict)
|
||||
difficulty_buckets: dict[str, dict[str, float]] = field(default_factory=dict)
|
||||
document_type_breakdown: dict[str, dict[str, float]] = field(
|
||||
default_factory=dict
|
||||
)
|
||||
|
||||
def evaluate_gates(
|
||||
self,
|
||||
metrics: dict[str, float],
|
||||
gates: list[PromotionGate] | None = None,
|
||||
) -> dict[str, GateStatus]:
|
||||
"""Evaluate all promotion gates against collected metrics."""
|
||||
gates = gates or DEFAULT_PROMOTION_GATES
|
||||
results: dict[str, GateStatus] = {}
|
||||
for gate in gates:
|
||||
value = metrics.get(gate.metric_name)
|
||||
if value is None:
|
||||
results[gate.name] = GateStatus.NOT_EVALUATED
|
||||
else:
|
||||
results[gate.name] = gate.evaluate(value)
|
||||
self.gate_results = results
|
||||
return results
|
||||
|
||||
@property
|
||||
def all_safety_gates_passed(self) -> bool:
|
||||
"""Whether all safety-critical gates passed."""
|
||||
for gate in DEFAULT_PROMOTION_GATES:
|
||||
if gate.safety_critical:
|
||||
status = self.gate_results.get(gate.name, GateStatus.NOT_EVALUATED)
|
||||
if status != GateStatus.PASSED:
|
||||
return False
|
||||
return True
|
||||
|
||||
@property
|
||||
def all_gates_passed(self) -> bool:
|
||||
"""Whether all gates passed."""
|
||||
return all(
|
||||
status == GateStatus.PASSED
|
||||
for status in self.gate_results.values()
|
||||
)
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
"""Serialize for storage/API response."""
|
||||
return {
|
||||
"report_id": str(self.report_id),
|
||||
"config_id": str(self.config_id),
|
||||
"total_documents": self.total_documents,
|
||||
"success_rate": self.success_rate,
|
||||
"avg_latency_ms": self.avg_latency_ms,
|
||||
"total_gpu_seconds": self.total_gpu_seconds,
|
||||
"schema_validity_rate": self.schema_validity_rate,
|
||||
"fast_path_rate": self.fast_path_rate,
|
||||
"gate_results": {k: v.value for k, v in self.gate_results.items()},
|
||||
"all_safety_gates_passed": self.all_safety_gates_passed,
|
||||
"all_gates_passed": self.all_gates_passed,
|
||||
}
|
||||
@@ -0,0 +1,140 @@
|
||||
"""Replay runner — executes pipeline configurations against the Gold Corpus.
|
||||
|
||||
Compares every required system configuration on identical inputs and
|
||||
produces structured output for report generation and gate evaluation.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import enum
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import datetime, timezone
|
||||
from typing import Any
|
||||
from uuid import UUID, uuid4
|
||||
|
||||
|
||||
class ReplayMode(str, enum.Enum):
|
||||
"""Pipeline configurations to compare."""
|
||||
|
||||
CURRENT_V2 = "current_v2"
|
||||
CURRENT_V2_STRICT = "current_v2_strict" # Temperature 0 + strict schema
|
||||
V3_FAST_PATH = "v3_fast_path"
|
||||
V3_FULL = "v3_full" # Fast path + adjudication
|
||||
V3_SPECIALIST_ONLY = "v3_specialist_only"
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class ReplayConfig:
|
||||
"""Configuration for a replay run."""
|
||||
|
||||
config_id: UUID
|
||||
mode: ReplayMode
|
||||
corpus_version: str
|
||||
pipeline_version: str
|
||||
model_version: str | None = None
|
||||
temperature: float = 0.0
|
||||
strict_schema: bool = True
|
||||
description: str = ""
|
||||
|
||||
@classmethod
|
||||
def create(
|
||||
cls,
|
||||
mode: ReplayMode,
|
||||
corpus_version: str = "1.0",
|
||||
pipeline_version: str = "v3",
|
||||
**kwargs: Any,
|
||||
) -> ReplayConfig:
|
||||
return cls(
|
||||
config_id=uuid4(),
|
||||
mode=mode,
|
||||
corpus_version=corpus_version,
|
||||
pipeline_version=pipeline_version,
|
||||
**kwargs,
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class ReplayResult:
|
||||
"""Result of processing a single document in replay mode."""
|
||||
|
||||
document_id: str
|
||||
config_id: UUID
|
||||
success: bool
|
||||
latency_ms: float
|
||||
tokens_used: int = 0
|
||||
gpu_seconds: float = 0.0
|
||||
cpu_seconds: float = 0.0
|
||||
extracted_entities: int = 0
|
||||
extracted_facts: int = 0
|
||||
evidence_spans: int = 0
|
||||
schema_valid: bool = True
|
||||
errors: list[str] = field(default_factory=list)
|
||||
field_scores: dict[str, float] = field(default_factory=dict)
|
||||
metadata: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
|
||||
@dataclass
|
||||
class ReplayRunner:
|
||||
"""Executes replay runs against a corpus.
|
||||
|
||||
Processes documents through the specified pipeline configuration
|
||||
and collects results for comparison and reporting.
|
||||
"""
|
||||
|
||||
config: ReplayConfig
|
||||
_results: list[ReplayResult] = field(default_factory=list)
|
||||
started_at: datetime | None = None
|
||||
completed_at: datetime | None = None
|
||||
|
||||
def start(self) -> None:
|
||||
"""Mark the replay as started."""
|
||||
self.started_at = datetime.now(timezone.utc)
|
||||
|
||||
def complete(self) -> None:
|
||||
"""Mark the replay as completed."""
|
||||
self.completed_at = datetime.now(timezone.utc)
|
||||
|
||||
def record_result(self, result: ReplayResult) -> None:
|
||||
"""Add a document processing result."""
|
||||
self._results.append(result)
|
||||
|
||||
@property
|
||||
def results(self) -> list[ReplayResult]:
|
||||
return list(self._results)
|
||||
|
||||
@property
|
||||
def total_documents(self) -> int:
|
||||
return len(self._results)
|
||||
|
||||
@property
|
||||
def success_count(self) -> int:
|
||||
return sum(1 for r in self._results if r.success)
|
||||
|
||||
@property
|
||||
def failure_count(self) -> int:
|
||||
return sum(1 for r in self._results if not r.success)
|
||||
|
||||
@property
|
||||
def success_rate(self) -> float:
|
||||
if not self._results:
|
||||
return 0.0
|
||||
return self.success_count / len(self._results)
|
||||
|
||||
@property
|
||||
def avg_latency_ms(self) -> float:
|
||||
if not self._results:
|
||||
return 0.0
|
||||
return sum(r.latency_ms for r in self._results) / len(self._results)
|
||||
|
||||
@property
|
||||
def total_gpu_seconds(self) -> float:
|
||||
return sum(r.gpu_seconds for r in self._results)
|
||||
|
||||
@property
|
||||
def schema_validity_rate(self) -> float:
|
||||
if not self._results:
|
||||
return 0.0
|
||||
return sum(1 for r in self._results if r.schema_valid) / len(self._results)
|
||||
|
||||
def is_complete(self) -> bool:
|
||||
return self.completed_at is not None
|
||||
Reference in New Issue
Block a user