failure-forensics 0.1.1__py3-none-any.whl

failure_forensics/__init__.py

@@ -0,0 +1,5 @@
+from .trace import trace
+from .dashboard import render as dashboard
+from .regression_guard import check_regression as regression_guard
+
+__all__ = ["trace", "dashboard", "regression_guard"]

failure_forensics/ab_report.py

@@ -0,0 +1,116 @@
+"""
+ab_report.py — İki prompt versiyonunu karşılaştıran A/B raporu üretir.
+Adım bazında breakdown, kazanan versiyon, fark yüzdesi.
+data/ab_report.json'a kaydeder ve terminale tablo olarak basar.
+"""
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from failure_forensics.versioning import compare_versions, version_stats
+from failure_forensics.logger import read_logs
+from failure_forensics.config import AB_REPORT_FILE
+
+STEP_ORDER = ["retrieval", "reranking", "generation", "citation"]
+
+
+def generate_ab_report(v1: str = "v1", v2: str = "v2") -> dict:
+    """
+    v1 ve v2 versiyonları için A/B raporu üretir.
+    Raporu AB_REPORT_FILE'a kaydeder.
+
+    Returns:
+        Tam rapor dict'i
+    """
+    logs = read_logs()
+    comparison = compare_versions(v1, v2, logs)
+    stats = version_stats(logs)
+
+    v1_data = stats.get(v1, {})
+    v2_data = stats.get(v2, {})
+
+    # Adım bazında karşılaştırma
+    step_comparison = {}
+    all_steps = set(
+        list(v1_data.get("steps", {}).keys()) +
+        list(v2_data.get("steps", {}).keys())
+    )
+    for step in all_steps:
+        s1 = v1_data.get("steps", {}).get(step, {"total": 0, "failed": 0, "rate": 0.0})
+        s2 = v2_data.get("steps", {}).get(step, {"total": 0, "failed": 0, "rate": 0.0})
+        delta = s1["rate"] - s2["rate"]
+        step_winner = v1 if s1["rate"] < s2["rate"] else (v2 if s2["rate"] < s1["rate"] else "tie")
+        step_comparison[step] = {
+            v1: s1,
+            v2: s2,
+            "delta_pct": round(delta * 100, 2),
+            "step_winner": step_winner,
+        }
+
+    report = {
+        "summary": {
+            "v1": v1,
+            "v2": v2,
+            "winner": comparison["winner"],
+            "v1_failure_rate": comparison["v1_rate"],
+            "v2_failure_rate": comparison["v2_rate"],
+            "improvement_pct": comparison["improvement_pct"],
+            "v1_runs": comparison["v1_runs"],
+            "v2_runs": comparison["v2_runs"],
+        },
+        "step_breakdown": step_comparison,
+        "raw_stats": {v1: v1_data, v2: v2_data},
+    }
+
+    # Kaydet
+    os.makedirs(os.path.dirname(AB_REPORT_FILE), exist_ok=True)
+    with open(AB_REPORT_FILE, "w", encoding="utf-8") as f:
+        json.dump(report, f, indent=2, ensure_ascii=False)
+
+    return report
+
+
+def print_ab_report(v1: str = "v1", v2: str = "v2"):
+    """Terminale formatlanmış A/B raporu tablo olarak basar."""
+    report = generate_ab_report(v1, v2)
+    summary = report["summary"]
+    steps = report["step_breakdown"]
+
+    print("\n" + "=" * 62)
+    print("  📊 A/B RAPORU — Prompt Versiyon Karşılaştırması")
+    print("=" * 62)
+
+    # Özet
+    winner = summary["winner"]
+    winner_icon = "🏆"
+    print(f"\n  Karşılaştırma  : {v1}  vs  {v2}")
+    print(f"  {v1} çalışma sayısı : {summary['v1_runs']}")
+    print(f"  {v2} çalışma sayısı : {summary['v2_runs']}")
+    print(f"\n  {'Metrik':<30} {v1:>10} {v2:>10} {'Fark':>10}")
+    print(f"  {'-'*60}")
+    v1r = summary["v1_failure_rate"]
+    v2r = summary["v2_failure_rate"]
+    diff = (v1r - v2r) * 100
+    print(f"  {'Genel Failure Rate':<30} {v1r:>9.1%} {v2r:>10.1%} {diff:>+9.1f}pp")
+
+    # Adım bazında tablo
+    print(f"\n  {'Adım':<16} {v1+' fail':>12} {v2+' fail':>12} {'Kazanan':>10}")
+    print(f"  {'-'*55}")
+
+    for step in STEP_ORDER:
+        if step not in steps:
+            continue
+        sc = steps[step]
+        r1 = sc[v1]["rate"]
+        r2 = sc[v2]["rate"]
+        sw = sc["step_winner"]
+        icon = winner_icon if sw != "tie" else "="
+        print(f"  {step:<16} {r1:>11.1%} {r2:>12.1%}  {icon} {sw:>6}")
+
+    print(f"\n  {winner_icon} KAZANAN: {winner.upper()} "
+          f"— {summary['improvement_pct']:.1f} pp iyileşme")
+    print(f"\n  📁 Detaylı rapor: {AB_REPORT_FILE}")
+    print("=" * 62)
+
+    return report

failure_forensics/alerts.py

@@ -0,0 +1,100 @@
+"""
+alerts.py — Slack webhook bildirimleri.
+Tetiklenme koşulları:
+  1. Failure rate eşiği aşıldığında
+  2. Anomali tespit edildiğinde
+  3. Belirli bir adım 3 üst üste başarısız olduğunda
+
+Webhook URL boşsa konsola yazar.
+"""
+import os
+import sys
+import json
+from datetime import datetime, timezone
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from failure_forensics.config import SLACK_WEBHOOK_URL, FAILURE_RATE_THRESHOLD, CONSECUTIVE_FAILURE_THRESHOLD
+
+try:
+    import requests as _requests
+    _HAS_REQUESTS = True
+except ImportError:
+    _HAS_REQUESTS = False
+
+
+def _send(message: str, level: str = "WARNING"):
+    """Mesajı Slack'e veya konsola gönderir."""
+    icon = {"WARNING": "⚠️", "CRITICAL": "🔴", "INFO": "ℹ️"}.get(level, "⚠️")
+    full_msg = f"{icon} *[Failure Forensics]* {message}"
+
+    if SLACK_WEBHOOK_URL and _HAS_REQUESTS:
+        try:
+            _requests.post(
+                SLACK_WEBHOOK_URL,
+                json={"text": full_msg},
+                timeout=5,
+            )
+            print(f"[ALERT → Slack] {full_msg}")
+        except Exception as e:
+            print(f"[ALERT → Console (Slack failed: {e})] {full_msg}")
+    else:
+        ts = datetime.now(timezone.utc).strftime("%H:%M:%S")
+        print(f"[ALERT {ts}] {full_msg}")
+
+
+def check_failure_rate(failure_rate: float, context: str = ""):
+    """Failure rate eşiği aşılırsa alert gönderir."""
+    if failure_rate > FAILURE_RATE_THRESHOLD:
+        _send(
+            f"Failure rate eşiği aşıldı: {failure_rate:.1%} "
+            f"(eşik: {FAILURE_RATE_THRESHOLD:.1%}). {context}",
+            level="CRITICAL",
+        )
+        return True
+    return False
+
+
+def check_anomaly(anomaly_result: dict):
+    """Anomali tespit edildiyse alert gönderir."""
+    if anomaly_result.get("anomaly"):
+        today = anomaly_result["today_rate"]
+        avg = anomaly_result["avg_7d"]
+        delta = anomaly_result["delta"]
+        _send(
+            f"Anomali tespit edildi! Bugün: {today:.1%}, "
+            f"7g ort: {avg:.1%}, fark: +{delta:.1%}",
+            level="CRITICAL",
+        )
+        return True
+    return False
+
+
+def check_consecutive_failures(logs: list[dict], step_name: str = None) -> bool:
+    """
+    Belirli bir adımda (veya herhangi bir adımda) arka arkaya
+    CONSECUTIVE_FAILURE_THRESHOLD kadar hata varsa alert gönderir.
+    """
+    if not logs:
+        return False
+
+    # İsteğe bağlı filtre
+    filtered = [r for r in logs if step_name is None or r.get("step_name") == step_name]
+
+    # Son N kaydı kontrol et
+    recent = filtered[-CONSECUTIVE_FAILURE_THRESHOLD:]
+    if len(recent) < CONSECUTIVE_FAILURE_THRESHOLD:
+        return False
+
+    if all(not r.get("success", True) for r in recent):
+        step_label = step_name or "herhangi bir adım"
+        _send(
+            f"'{step_label}' adımı {CONSECUTIVE_FAILURE_THRESHOLD} üst üste başarısız!",
+            level="CRITICAL",
+        )
+        return True
+    return False
+
+
+def send_summary(title: str, body: str):
+    """Genel özet bildirimi gönderir."""
+    _send(f"*{title}*\n{body}", level="INFO")

failure_forensics/baseline.py

@@ -0,0 +1,91 @@
+"""
+baseline.py — Günlük failure rate'i kaydeder, 7 günlük hareketli ortalama ve trend hesaplar.
+Trend: IMPROVING / STABLE / DEGRADING
+"""
+import json
+import os
+import sys
+from datetime import datetime, timezone
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from failure_forensics.config import BASELINE_FILE, TREND_IMPROVING_THRESHOLD, TREND_DEGRADING_THRESHOLD
+
+
+def _load() -> dict:
+    os.makedirs(os.path.dirname(BASELINE_FILE), exist_ok=True)
+    if not os.path.exists(BASELINE_FILE):
+        return {}
+    with open(BASELINE_FILE, "r", encoding="utf-8") as f:
+        try:
+            return json.load(f)
+        except json.JSONDecodeError:
+            return {}
+
+
+def _save(data: dict):
+    os.makedirs(os.path.dirname(BASELINE_FILE), exist_ok=True)
+    with open(BASELINE_FILE, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2)
+
+
+def record_daily_rate(date: str, failure_rate: float):
+    """Bir günün failure rate'ini baseline dosyasına kaydeder."""
+    data = _load()
+    data[date] = round(failure_rate, 6)
+    _save(data)
+
+
+def get_moving_average(days: int = 7) -> dict:
+    """
+    Son N günün hareketli ortalamasını döner.
+
+    Returns:
+        {
+          "dates": [...],
+          "rates": [...],
+          "moving_avg": float,
+          "trend": "IMPROVING" | "STABLE" | "DEGRADING",
+          "trend_delta": float
+        }
+    """
+    data = _load()
+    sorted_dates = sorted(data.keys())[-days:]
+    rates = [data[d] for d in sorted_dates]
+
+    moving_avg = sum(rates) / len(rates) if rates else 0.0
+
+    # Trend: ilk yarı ile ikinci yarıyı karşılaştır
+    if len(rates) >= 4:
+        mid = len(rates) // 2
+        first_half_avg = sum(rates[:mid]) / mid
+        second_half_avg = sum(rates[mid:]) / (len(rates) - mid)
+        trend_delta = second_half_avg - first_half_avg
+    elif len(rates) >= 2:
+        trend_delta = rates[-1] - rates[0]
+    else:
+        trend_delta = 0.0
+
+    if trend_delta <= TREND_IMPROVING_THRESHOLD:
+        trend = "IMPROVING"
+    elif trend_delta >= TREND_DEGRADING_THRESHOLD:
+        trend = "DEGRADING"
+    else:
+        trend = "STABLE"
+
+    return {
+        "dates": sorted_dates,
+        "rates": [round(r, 4) for r in rates],
+        "moving_avg": round(moving_avg, 4),
+        "trend": trend,
+        "trend_delta": round(trend_delta, 4),
+    }
+
+
+def sync_from_pattern(daily_rates: dict):
+    """
+    pattern.py'den gelen günlük failure rate'leri baseline'a yazar.
+    Her gün için record_daily_rate çağırır.
+    """
+    for date, day_data in daily_rates.items():
+        rate = day_data.get("failure_rate", 0.0)
+        record_daily_rate(date, rate)

failure_forensics/config.py

@@ -0,0 +1,36 @@
+"""
+config.py — Eşik değerleri, Slack webhook URL, adım bazında kalite eşikleri.
+"""
+
+# Failure rate eşiği — bu değeri aşarsa alert tetiklenir
+FAILURE_RATE_THRESHOLD = 0.25
+
+# Anomali eşiği — bugün 7 günlük ortalamayı bu kadar aşarsa ANOMALY flag'i
+ANOMALY_THRESHOLD = 0.20
+
+# Slack webhook URL — boş bırakılırsa konsola yazılır
+SLACK_WEBHOOK_URL = ""
+
+# Log dosyası
+LOG_FILE = "data/logs/requests.jsonl"
+
+# A/B rapor çıktısı
+AB_REPORT_FILE = "data/ab_report.json"
+
+# Baseline geçmiş dosyası
+BASELINE_FILE = "data/baseline.json"
+
+# Adım bazında kalite eşikleri (maksimum kabul edilebilir failure rate)
+STEP_THRESHOLDS = {
+    "retrieval":   0.20,
+    "reranking":   0.15,
+    "generation":  0.15,
+    "citation":    0.10,
+}
+
+# Trend hesabı için eşikler
+TREND_IMPROVING_THRESHOLD = -0.05   # %5 iyileşme → IMPROVING
+TREND_DEGRADING_THRESHOLD =  0.05   # %5 kötüleşme → DEGRADING
+
+# Kaç üst üste hata ALERT tetikler
+CONSECUTIVE_FAILURE_THRESHOLD = 3

failure_forensics/dashboard.py

@@ -0,0 +1,104 @@
+"""
+dashboard.py — Terminal ASCII dashboard.
+Gösterir:
+  - Son 7 günün failure rate grafiği (ASCII bar chart)
+  - Adım bazında hata dağılımı
+  - Aktif anomaliler
+  - Son 5 başarısız run ve kök nedenleri
+  - Trend durumu (IMPROVING / STABLE / DEGRADING)
+"""
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from failure_forensics.pattern import daily_failure_rates, detect_anomaly, step_breakdown_report
+from failure_forensics.baseline import get_moving_average, sync_from_pattern
+from failure_forensics.forensics import get_failed_runs
+
+BAR_WIDTH = 30
+TREND_ICONS = {
+    "IMPROVING": "📈 IMPROVING ↓ (failure azalıyor)",
+    "STABLE":    "➡️  STABLE    — (kararlı)",
+    "DEGRADING": "📉 DEGRADING ↑ (failure artıyor)",
+}
+
+
+def _bar(rate: float, width: int = BAR_WIDTH) -> str:
+    """0.0-1.0 arası failure rate'i ASCII bar'a dönüştürür."""
+    filled = int(rate * width)
+    empty = width - filled
+    color = "█" * filled + "░" * empty
+    return f"[{color}] {rate:.1%}"
+
+
+def render(clear: bool = False):
+    """Terminal dashboard'ı render eder."""
+    if clear:
+        os.system("cls" if os.name == "nt" else "clear")
+
+    daily = daily_failure_rates(7)
+    sync_from_pattern(daily)
+    anomaly = detect_anomaly(daily)
+    step_report = step_breakdown_report(daily)
+    baseline = get_moving_average(7)
+    failed_runs = get_failed_runs(5)
+
+    W = 65
+    print("\n" + "═" * W)
+    print("  🔬  FAILURE FORENSICS — Terminal Dashboard")
+    print("═" * W)
+
+    # ── 1. 7 Günlük Failure Rate Grafiği ─────────────────────────
+    print("\n  📅 SON 7 GÜNÜN FAILURE RATE GRAFİĞİ")
+    print("  " + "─" * (W - 2))
+    if not daily:
+        print("  (henüz veri yok)")
+    else:
+        for date, data in sorted(daily.items()):
+            rate = data["failure_rate"]
+            bar = _bar(rate)
+            marker = " ⚠️ " if rate > 0.25 else "    "
+            print(f"  {date}  {bar}{marker}")
+
+    # ── 2. Adım Bazında Hata Dağılımı ────────────────────────────
+    print(f"\n  🔍 ADIM BAZINDA HATA DAĞILIMI (son 7 gün)")
+    print("  " + "─" * (W - 2))
+    if not step_report:
+        print("  (veri yok)")
+    else:
+        for step, sd in sorted(step_report.items(), key=lambda x: -x[1]["rate"]):
+            rate = sd["rate"]
+            bar = _bar(rate, width=20)
+            print(f"  {step:<12}  {bar}  ({sd['failed']}/{sd['total']} hatalı)")
+
+    # ── 3. Anomali Durumu ─────────────────────────────────────────
+    print(f"\n  ⚡ ANOMALİ DURUMU")
+    print("  " + "─" * (W - 2))
+    print(f"  {anomaly['message']}")
+    if anomaly["anomaly"]:
+        print(f"  → Bugün: {anomaly['today_rate']:.1%}  |  7g ort: {anomaly['avg_7d']:.1%}  |  Delta: +{anomaly['delta']:.1%}")
+
+    # ── 4. Trend ──────────────────────────────────────────────────
+    print(f"\n  📊 TREND & BASELINE (7 günlük hareketli ort.)")
+    print("  " + "─" * (W - 2))
+    trend = baseline.get("trend", "STABLE")
+    avg = baseline.get("moving_avg", 0.0)
+    delta = baseline.get("trend_delta", 0.0)
+    print(f"  {TREND_ICONS.get(trend, trend)}")
+    print(f"  Hareketli Ort: {avg:.1%}  |  Trend Delta: {delta:+.1%}")
+
+    # ── 5. Son 5 Başarısız Run ────────────────────────────────────
+    print(f"\n  ❌ SON 5 BAŞARISIZ RUN & KÖK NEDENLER")
+    print("  " + "─" * (W - 2))
+    if not failed_runs:
+        print("  Başarısız run bulunamadı. 🎉")
+    else:
+        for i, run in enumerate(failed_runs[:5], 1):
+            rid = run["run_id"]
+            cat = run["category"]
+            steps = ", ".join(run["failed_steps"]) or "-"
+            print(f"  {i}. run_id={rid}  [{cat}]")
+            print(f"     Başarısız adımlar: {steps}")
+            print(f"     → {run['description'][:80]}")
+
+    print("\n" + "═" * W + "\n")

failure_forensics/eval_collector.py

@@ -0,0 +1,113 @@
+"""
+Katman 3 — eval_collector.py
+Başarısız sorgulardan otomatik eval seti büyütme.
+"""
+import os
+import sys
+import json
+from datetime import datetime, timezone, timedelta
+from collections import defaultdict
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), ".."))
+from failure_forensics.logger import read_logs
+from failure_forensics.forensics import ERROR_CATEGORY_MAP, STEP_CATEGORY_MAP
+
+EVAL_CANDIDATES_FILE = "data/eval_candidates/candidates.jsonl"
+
+def _ensure_dir():
+    os.makedirs(os.path.dirname(EVAL_CANDIDATES_FILE), exist_ok=True)
+
+def collect_candidates():
+    """Başarısız sorguları frekanslarına göre toplar ve candidates.jsonl dosyasına yazar."""
+    logs = read_logs()
+    
+    # query -> { failure_count, root_cause_category, first_seen, last_seen }
+    candidates = {}
+    
+    # run_id -> category mapping
+    # Hızlıca kategori bulmak için
+    run_categories = {}
+    
+    # Önce tüm başarısız run'ların kategorilerini bul
+    runs = defaultdict(list)
+    for record in logs:
+        runs[record.get("run_id", "unknown")].append(record)
+        
+    for rid, steps in runs.items():
+        failed_steps = [s for s in steps if not s.get("success", True)]
+        if failed_steps:
+            first_failure = failed_steps[0]
+            step_name = first_failure.get("step_name", "")
+            error_type = (first_failure.get("error_type") or "").lower()
+            
+            category = "UNKNOWN"
+            for key, cat in ERROR_CATEGORY_MAP.items():
+                if key in error_type:
+                    category = cat
+                    break
+            if category == "UNKNOWN":
+                category = STEP_CATEGORY_MAP.get(step_name, "UNKNOWN")
+            
+            run_categories[rid] = category
+            
+            # Input summary'den query al
+            query = first_failure.get("input_summary", "").strip()
+            if not query or query.startswith("Simulated"): # Simulate'deki fake query'leri atla
+                continue
+                
+            ts = first_failure.get("timestamp", "")
+            
+            # Query deduplication
+            if query not in candidates:
+                candidates[query] = {
+                    "query": query,
+                    "failure_count": 1,
+                    "root_cause_category": category,
+                    "first_seen": ts,
+                    "last_seen": ts,
+                    "auto_add_eligible": False
+                }
+            else:
+                candidates[query]["failure_count"] += 1
+                candidates[query]["last_seen"] = ts
+                if candidates[query]["failure_count"] >= 3:
+                    candidates[query]["auto_add_eligible"] = True
+                    
+    # Dosyaya yaz
+    _ensure_dir()
+    with open(EVAL_CANDIDATES_FILE, "w", encoding="utf-8") as f:
+        for query, data in candidates.items():
+            if data["failure_count"] >= 2: # En az 2 kez başarısız olanları kaydet
+                f.write(json.dumps(data, ensure_ascii=False) + "\n")
+                
+def weekly_summary() -> dict:
+    """Haftalık eval adayı özeti döner."""
+    collect_candidates() # Verileri güncelle
+    
+    if not os.path.exists(EVAL_CANDIDATES_FILE):
+        return {"total_candidates": 0, "eligible_count": 0, "message": "Aday bulunamadı."}
+        
+    candidates = []
+    with open(EVAL_CANDIDATES_FILE, "r", encoding="utf-8") as f:
+        for line in f:
+            if line.strip():
+                candidates.append(json.loads(line))
+                
+    one_week_ago = datetime.now(timezone.utc) - timedelta(days=7)
+    
+    recent_candidates = []
+    for c in candidates:
+        try:
+            ts = datetime.fromisoformat(c["last_seen"].replace("Z", "+00:00"))
+            if ts > one_week_ago:
+                recent_candidates.append(c)
+        except Exception:
+            pass
+            
+    eligible_count = sum(1 for c in recent_candidates if c.get("auto_add_eligible"))
+    
+    return {
+        "total_candidates": len(recent_candidates),
+        "eligible_count": eligible_count,
+        "message": f"Bu hafta {len(recent_candidates)} yeni eval adayı birikirdi, onaylamak ister misiniz? ({eligible_count} tanesi >=3 kez başarısız)"
+    }