Upload agents/utils.py with huggingface_hub

agents/utils.py

@@ -0,0 +1,105 @@
+"""FORENSIQ — Shared utilities for all agents."""
+
+import numpy as np
+from typing import List, Dict, Any
+
+
+def compute_agent_confidence(scores: List[float]) -> float:
+    """
+    Compute agent confidence using agreement-vs-cancellation logic.
+    Backported from semantic agent to ALL signal agents.
+    
+    Returns a confidence value between 0.1 and 1.0 that reflects:
+    - High confidence when scores agree in direction and have high magnitude
+    - Low confidence when scores cancel each other out
+    - Low confidence when all scores are near zero (no signal)
+    """
+    if not scores:
+        return 0.1
+    
+    avg = float(np.mean(scores))
+    
+    # Classify each score's direction
+    signs = [1 if s > 0.05 else (-1 if s < -0.05 else 0) for s in scores]
+    n_pos = sum(1 for s in signs if s > 0)
+    n_neg = sum(1 for s in signs if s < 0)
+    n_neu = sum(1 for s in signs if s == 0)
+    
+    if n_pos > 0 and n_neg > 0:
+        # Scores cancel — low confidence
+        agreement = max(n_pos, n_neg) / (n_pos + n_neg)
+        return min(1.0, 0.15 + 0.5 * abs(avg) * agreement)
+    elif n_neu == len(signs):
+        # All genuinely neutral — low confidence
+        return 0.2
+    else:
+        # Scores agree — confidence scales with magnitude
+        return min(1.0, 0.3 + 0.6 * abs(avg))
+
+
+def compute_failure_prob(n_ran: int, n_total: int, n_insufficient: int = 0) -> float:
+    """
+    Compute agent failure probability.
+    Accounts for both crashed tests AND tests returning insufficient data.
+    
+    n_ran: tests that returned a score (including insufficient-data ones)
+    n_total: total tests attempted
+    n_insufficient: tests that returned score=0 due to insufficient data
+    """
+    n_effective = n_ran - n_insufficient  # tests that actually produced signal
+    return max(0.0, 1.0 - n_effective / max(n_total, 1))
+
+
+def run_agent_tests(tests, img, agent_name):
+    """
+    Shared test runner for all signal-processing agents.
+    Handles: running tests, tagging insufficient-data, computing confidence properly.
+    """
+    findings, scores = [], []
+    n_insufficient = 0
+    
+    for fn in tests:
+        try:
+            r = fn(img)
+            findings.append(r)
+            
+            sc = r.get("score", 0)
+            note = r.get("note", "")
+            
+            # P7: Detect insufficient-data results — tag as not_applicable
+            is_insufficient = (sc == 0.0 and any(kw in note.lower() for kw in 
+                ["insufficient", "too small", "no data", "not available", "few ", "no "]))
+            
+            if is_insufficient:
+                r["not_applicable"] = True
+                n_insufficient += 1
+            
+            scores.append(sc)
+        except Exception as e:
+            findings.append({"test": fn.__name__, "error": str(e), "score": 0})
+    
+    # Filter out not_applicable scores for averaging
+    active_scores = [s for s, f in zip(scores, findings) 
+                     if not f.get("not_applicable", False)]
+    
+    avg = float(np.mean(active_scores)) if active_scores else 0.0
+    conf = compute_agent_confidence(active_scores)
+    fail = compute_failure_prob(len(scores), len(tests), n_insufficient)
+    
+    # Build rationale
+    viol = [f["test"] for f in findings if f.get("score", 0) > 0.2 and not f.get("not_applicable")]
+    comp = [f["test"] for f in findings if f.get("score", 0) < -0.1 and not f.get("not_applicable")]
+    
+    domain = agent_name.replace(" Agent", "")
+    if viol:
+        rat = f"{domain} violations: {', '.join(viol)}."
+    elif comp:
+        rat = f"{domain} consistent: {', '.join(comp)}."
+    else:
+        rat = f"{domain} inconclusive."
+    
+    for f in findings:
+        if f.get("note") and not f.get("not_applicable"):
+            rat += f" [{f['test']}]: {f['note']}."
+    
+    return findings, avg, conf, fail, rat