feat(evaluation): add evaluation summary endpoint from trace aggregates

Author: kernelshard

app/api/router.py

@@ -7,6 +7,7 @@
 from app.retrieval.api import router as retrival_router
 from app.ingestion.api import router as ingestion_router
 from app.generation.api import router as generation_router
+from app.evaludation.api import router as evaluation_router
 
 
 router = APIRouter(prefix="/api/v1", tags=["api"])
@@ -22,3 +23,4 @@ async def ping() -> dict[str, Any]:
 router.include_router(retrival_router)
 router.include_router(ingestion_router)
 router.include_router(generation_router)
+router.include_router(evaluation_router)

app/evaludation/aggregate.py

@@ -0,0 +1,48 @@
+import json
+from pathlib import Path
+
+
+TRACE_FILE = Path(__file__).parent.parent.parent / "var/traces" / "rage_trace.jsonl"
+
+
+def aggregate_traces() -> dict:
+    """
+    Aggregate traces from the JSONL trace file.
+    Read the file line by line, parse each JSON record, and compute
+    average metrics like recall_k and faithfulness.
+
+    :return: Aggregated trace records.
+    :rtype: dict
+    """
+
+    total = 0
+    recall_k_sum = 0.0
+    recall_n = 0  # recall_k_count
+    faithfulness_sum = 0.0
+    faithfulness_n = 0  # faithfulness_count
+
+    if not TRACE_FILE.exists():
+        return {
+            "runs": 0,
+            "avg_recall_k": None,
+            "avg_faithfulness": None,
+        }
+
+    with TRACE_FILE.open("r", encoding="utf-8") as f:
+        for line in f:
+            total += 1
+            r = json.loads(line)
+            if r.get("recall_k") is not None:
+                recall_k_sum += r["recall_k"]
+                recall_n += 1
+            if r.get("faithfulness") is not None:
+                faithfulness_sum += r["faithfulness"]
+                faithfulness_n += 1
+
+    return {
+        "runs": total,
+        "avg_recall_k": round(recall_k_sum / recall_n, 4) if recall_n > 0 else None,
+        "avg_faithfulness": round(faithfulness_sum / faithfulness_n, 4)
+        if faithfulness_n > 0
+        else None,
+    }

app/evaludation/api.py

@@ -0,0 +1,11 @@
+from fastapi import APIRouter
+
+from app.evaludation.aggregate import aggregate_traces
+
+
+router = APIRouter(prefix="/eval", tags=["evaluation"])
+
+
+@router.get("/summary")
+async def evaluation_summary() -> dict:
+    return aggregate_traces()

app/generation/service.py

@@ -5,7 +5,7 @@
 from app.generation.prompt_builder import build_prompt
 
 from app.core.interfaces import BaseGenerator, BaseRetriever
-from app.generation.trace_writer import write_trace
+from app.evaludation.trace_writer import write_trace
 
 
 logger = get_logger(__name__)