@geravant/sinain 1.11.0 → 1.13.0

package/sinain-memory/eval/benchmarks/meeting_runner.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Meeting Memory Benchmark runner — evaluates a captured knowledge-graph.db.
+
+Standalone script: does NOT modify or import runner.py.
+Reuses shared infrastructure: query, judge, evaluate, report.
+
+Usage:
+    python3 eval/benchmarks/meeting_runner.py \
+        --db /tmp/sinain-bench-XXXX/knowledge-graph.db \
+        --conditions sinain-memory,full-context
+
+    # Quick test (3 questions):
+    python3 eval/benchmarks/meeting_runner.py \
+        --db /tmp/sinain-bench-XXXX/knowledge-graph.db \
+        --subset 3
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+# Add sinain-memory to path
+_koog_dir = str(Path(__file__).resolve().parent.parent.parent)
+if _koog_dir not in sys.path:
+    sys.path.insert(0, _koog_dir)
+
+from eval.benchmarks.config import DATA_DIR, RESULTS_DIR, QA_MODEL, JUDGE_MODEL
+from eval.benchmarks.meeting_adapter import MeetingMemoryAdapter
+from eval.benchmarks.query import answer_question, _get_retrieved_facts, compute_content_recall
+from eval.benchmarks.evaluate import token_f1, aggregate_results
+from eval.benchmarks.judges.qa_judge import judge_qa
+from eval.benchmarks.report import generate_markdown, generate_json
+
+
+def run_meeting_benchmark(
+    db_path: str,
+    conditions: list[str],
+    *,
+    subset: int | None = None,
+    meeting_filter: str | None = None,
+    qa_model: str = QA_MODEL,
+    judge_model: str = JUDGE_MODEL,
+    output_dir: Path = RESULTS_DIR,
+    data_dir: Path = DATA_DIR,
+    resume: bool = False,
+) -> tuple[dict, list[dict]]:
+    """Run meeting benchmark against a captured knowledge-graph.db."""
+
+    adapter = MeetingMemoryAdapter()
+    instances = adapter.load_dataset(str(data_dir))
+
+    if meeting_filter:
+        instances = [i for i in instances if meeting_filter in i.id]
+        print(f"[meeting] filtered to {len(instances)} meeting(s) matching '{meeting_filter}'")
+
+    if not instances:
+        print("[meeting] no meeting data found — check data/meeting/ directory")
+        return {"error": "no data"}, []
+
+    # Validate DB exists for sinain-memory condition
+    if "sinain-memory" in conditions:
+        if not db_path or not Path(db_path).exists():
+            print(f"[meeting] ERROR: --db path does not exist: {db_path}")
+            print("  Run the capture pipeline first (see plan Part 1)")
+            sys.exit(1)
+
+    print(f"\n{'='*60}")
+    print(f"  Meeting Memory Benchmark")
+    print(f"  Conditions: {', '.join(conditions)}")
+    print(f"  DB: {db_path or '(none)'}")
+    print(f"  QA model: {qa_model}")
+    print(f"  Judge model: {judge_model}")
+    print(f"{'='*60}\n")
+
+    # Flatten questions
+    all_questions = []
+    for inst in instances:
+        for q in inst.questions:
+            all_questions.append((inst, q))
+
+    if subset:
+        all_questions = all_questions[:subset]
+
+    total = len(all_questions)
+    print(f"[meeting] evaluating {total} questions\n")
+
+    # Resume support
+    resume_path = output_dir / "meeting_progress.jsonl"
+    completed: dict[str, dict] = {}
+    if resume and resume_path.exists():
+        for line in resume_path.read_text().strip().split("\n"):
+            if line:
+                entry = json.loads(line)
+                completed[entry["id"]] = entry
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    details: list[dict] = []
+
+    for idx, (inst, question) in enumerate(all_questions):
+        qid = question.id
+
+        if qid in completed:
+            details.append(completed[qid])
+            continue
+
+        print(f"[{idx+1}/{total}] {qid} [{question.category}]")
+        print(f"  Q: {question.text[:80]}...")
+
+        full_context = adapter.format_full_context(inst)
+
+        # Retrieval metrics
+        retrieval = {}
+        if db_path and "sinain-memory" in conditions:
+            retrieved_facts = _get_retrieved_facts(db_path, question.text)
+            retrieval = compute_content_recall(retrieved_facts, question.gold_answer)
+
+        # Generate answers per condition
+        answers = {}
+        for cond in conditions:
+            if cond == "sinain-memory" and not db_path:
+                answers[cond] = {"text": "(no DB)", "score": 1, "f1": 0.0}
+                continue
+
+            print(f"  [{cond}] generating answer...")
+            answer_text = answer_question(
+                question, cond,
+                db_path=db_path,
+                full_context=full_context,
+                model=qa_model,
+            )
+
+            f1 = token_f1(answer_text, question.gold_answer)
+
+            judge_result = judge_qa(
+                question.text, question.gold_answer, answer_text,
+                condition=cond, model=judge_model,
+            )
+            score = judge_result["score"] if judge_result else None
+            reasoning = judge_result["reasoning"] if judge_result else None
+
+            answers[cond] = {
+                "text": answer_text[:500],
+                "score": score,
+                "f1": round(f1, 4),
+                "reasoning": reasoning,
+            }
+            print(f"    score={score}/5 f1={f1:.2f}")
+
+        entry = {
+            "id": qid,
+            "question": question.text,
+            "gold_answer": question.gold_answer,
+            "category": question.category,
+            "retrieval": retrieval,
+            "answers": answers,
+        }
+        details.append(entry)
+
+        # Save progress
+        with open(resume_path, "a") as f:
+            f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    summary = aggregate_results(details)
+    return summary, details
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Meeting Memory Benchmark")
+    parser.add_argument("--db", required=False, default=None,
+                        help="Path to knowledge-graph.db from capture run")
+    parser.add_argument("--conditions", default="sinain-memory,full-context",
+                        help="Comma-separated conditions (sinain-memory, full-context)")
+    parser.add_argument("--subset", type=int, default=None,
+                        help="Run only first N questions")
+    parser.add_argument("--meeting", default=None,
+                        help="Filter to specific meeting by stem (e.g. al-futaim-prep-5min)")
+    parser.add_argument("--qa-model", default=QA_MODEL)
+    parser.add_argument("--judge-model", default=JUDGE_MODEL)
+    parser.add_argument("--output-dir", type=Path, default=RESULTS_DIR)
+    parser.add_argument("--data-dir", type=Path, default=DATA_DIR)
+    parser.add_argument("--format", default="json,markdown")
+    parser.add_argument("--resume", action="store_true")
+    args = parser.parse_args()
+
+    conditions = [c.strip() for c in args.conditions.split(",")]
+    formats = [f.strip() for f in args.format.split(",")]
+
+    summary, details = run_meeting_benchmark(
+        args.db, conditions,
+        subset=args.subset,
+        meeting_filter=args.meeting,
+        qa_model=args.qa_model,
+        judge_model=args.judge_model,
+        output_dir=args.output_dir,
+        data_dir=args.data_dir,
+        resume=args.resume,
+    )
+
+    # Write outputs
+    args.output_dir.mkdir(parents=True, exist_ok=True)
+
+    if "json" in formats:
+        json_path = args.output_dir / "meeting_results.json"
+        json_path.write_text(generate_json("meeting", summary, details))
+        print(f"\n[output] JSON: {json_path}")
+
+    if "markdown" in formats:
+        md_path = args.output_dir / "meeting_results.md"
+        md_path.write_text(generate_markdown("meeting", summary, details))
+        print(f"[output] Markdown: {md_path}")
+
+    # Print summary
+    print(f"\n{'='*60}")
+    print(f"  Meeting Memory Benchmark — Summary")
+    print(f"{'='*60}")
+    ipr = summary.get("ipr")
+    if ipr:
+        print(f"  IPR: {ipr:.1%}")
+    for cond, data in summary.get("conditions", {}).items():
+        print(f"  {cond}: {data['mean_score']:.2f}/5 (n={data['n']})")
+    for k, v in summary.get("retrieval", {}).items():
+        print(f"  {k}: {v:.1%}")
+    print()
+
+
+if __name__ == "__main__":
+    main()

package/sinain-memory/eval/benchmarks/query.py

@@ -0,0 +1,193 @@
+"""Query pipeline — benchmark questions → LLM answers under 3 conditions.
+
+Condition A (sinain-memory): answer from knowledge graph facts
+Condition B (full-context):  answer from full conversation history
+Condition C (knowledge-doc): answer from portable knowledge document
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Add sinain-memory to path
+_koog_dir = str(Path(__file__).resolve().parent.parent.parent)
+if _koog_dir not in sys.path:
+    sys.path.insert(0, _koog_dir)
+
+from common import call_llm  # noqa: E402
+
+from .base_adapter import BenchmarkQuestion
+from .config import QA_MODEL, MAX_FACTS_PER_QUERY
+
+
+def _extract_keywords(query: str) -> list[str]:
+    """Extract search keywords (reuses logic from retrieval_evaluator)."""
+    import re
+    words = re.findall(r"[a-zA-Z][a-zA-Z0-9-]+", query.lower())
+    stopwords = {
+        "the", "is", "in", "on", "for", "and", "or", "of", "to", "a", "an",
+        "it", "was", "not", "how", "what", "when", "does", "did", "do", "my",
+        "your", "their", "have", "has", "had", "are", "were", "been", "being",
+        "about", "from", "with", "that", "this", "which", "who", "whom",
+        "where", "why", "can", "could", "would", "should",
+    }
+    return [w for w in words if len(w) > 2 and w not in stopwords]
+
+
+def _get_all_facts_text(db_path: str) -> str:
+    """Dump ALL facts from the knowledge graph as formatted text.
+
+    Sinain triplestores are small (10-50 facts per session), so including
+    everything is feasible and avoids tag-matching failures.
+    """
+    from graph_query import query_top_facts, format_facts_text
+
+    facts = query_top_facts(db_path, limit=50)
+    if not facts:
+        return "(no knowledge available)"
+    return format_facts_text(facts, max_chars=6000)
+
+
+def _query_knowledge(db_path: str, question: str) -> str:
+    """Query sinain knowledge graph for facts relevant to a question.
+
+    Strategy: retrieve broadly, then re-rank by keyword overlap with the question.
+    This ensures specific facts (CTO background) beat generic ones (meeting schedule)
+    when the question asks about the CTO.
+    """
+    from graph_query import query_facts_hybrid, query_top_facts, format_facts_text
+
+    # Retrieve a broad candidate set
+    candidates = query_facts_hybrid(db_path, question, max_facts=30)
+    if not candidates:
+        candidates = query_top_facts(db_path, limit=30)
+    if not candidates:
+        return "(no knowledge available)"
+
+    # Re-rank by embedding similarity if available, fall back to keyword overlap
+    try:
+        from embed_client import rank_by_similarity
+        fact_texts = [str(f.get("value", "")) for f in candidates]
+        ranked_indices = rank_by_similarity(question, fact_texts)
+        if ranked_indices is not None:
+            ranked = [candidates[i] for i, _ in ranked_indices[:MAX_FACTS_PER_QUERY]]
+            return format_facts_text(ranked, max_chars=3000)
+    except Exception:
+        pass
+
+    # Fallback: keyword overlap ranking
+    q_keywords = set(_extract_keywords(question))
+    def _relevance(fact: dict) -> float:
+        value = str(fact.get("value", "")).lower()
+        entity = str(fact.get("entity", "")).lower()
+        fact_words = set(_extract_keywords(value + " " + entity))
+        if not q_keywords:
+            return 0.0
+        return len(q_keywords & fact_words) / len(q_keywords)
+
+    ranked = sorted(candidates, key=_relevance, reverse=True)
+    return format_facts_text(ranked[:MAX_FACTS_PER_QUERY], max_chars=3000)
+
+
+def _get_retrieved_facts(db_path: str, question: str, k: int = 10) -> list[dict]:
+    """Get facts retrieved for a question (for retrieval evaluation)."""
+    from graph_query import query_facts_hybrid, query_top_facts
+
+    facts = query_facts_hybrid(db_path, question, max_facts=k)
+    if facts:
+        return facts
+
+    # Fallback: top facts by confidence
+    return query_top_facts(db_path, limit=k)
+
+
+def compute_content_recall(
+    retrieved_facts: list[dict],
+    gold_answer: str,
+    k_values: list[int] | None = None,
+) -> dict:
+    """Content-based retrieval metric: do retrieved facts contain the answer?
+
+    Instead of matching entity IDs (which don't align between LongMemEval
+    session IDs and sinain entity IDs), we check whether the gold answer's
+    key terms appear in any retrieved fact's content.
+    """
+    from .config import K_VALUES
+    ks = k_values or K_VALUES
+
+    gold_terms = set(_extract_keywords(str(gold_answer)))
+    if not gold_terms:
+        return {f"content_recall@{k}": 0.0 for k in ks}
+
+    result = {}
+    for k in ks:
+        top_k = retrieved_facts[:k]
+        # Check if any fact in top-k contains gold answer terms
+        for fact in top_k:
+            fact_text = f"{fact.get('entity', '')} {fact.get('value', '')}".lower()
+            fact_terms = set(_extract_keywords(fact_text))
+            overlap = gold_terms & fact_terms
+            if len(overlap) >= max(1, len(gold_terms) // 2):  # ≥50% of gold terms
+                result[f"content_recall@{k}"] = 1.0
+                break
+        else:
+            result[f"content_recall@{k}"] = 0.0
+
+    return result
+
+
+def answer_question(
+    question: BenchmarkQuestion,
+    condition: str,
+    *,
+    db_path: str | None = None,
+    full_context: str | None = None,
+    knowledge_doc: str | None = None,
+    model: str | None = None,
+) -> str:
+    """Generate an answer for a benchmark question under a specific condition.
+
+    Returns the LLM's answer text.
+    """
+    qa_model = model or QA_MODEL
+
+    if condition == "sinain-memory":
+        assert db_path, "db_path required for sinain-memory condition"
+        facts = _query_knowledge(db_path, question.text)
+        system = (
+            "Answer the question using ONLY the provided knowledge facts. "
+            "If the facts don't contain enough information to answer, say \"I don't know.\""
+        )
+        user = f"## Knowledge Facts\n{facts}\n\n## Question\n{question.text}"
+
+    elif condition == "full-context":
+        assert full_context, "full_context required for full-context condition"
+        system = (
+            "Answer the question based on the conversation history below. "
+            "Be concise and specific."
+        )
+        # Truncate context if too large (some models have limits)
+        ctx = full_context[:100_000] if len(full_context) > 100_000 else full_context
+        user = f"## Conversation History\n{ctx}\n\n## Question\n{question.text}"
+
+    elif condition == "knowledge-doc":
+        assert knowledge_doc, "knowledge_doc required for knowledge-doc condition"
+        system = (
+            "Answer the question using ONLY the knowledge document provided. "
+            "If the document doesn't contain enough information, say \"I don't know.\""
+        )
+        user = f"## Knowledge Document\n{knowledge_doc}\n\n## Question\n{question.text}"
+
+    else:
+        raise ValueError(f"Unknown condition: {condition}")
+
+    try:
+        return call_llm(
+            system_prompt=system,
+            user_prompt=user,
+            model=qa_model,
+            max_tokens=300,
+        ).strip()
+    except Exception as e:
+        return f"(error: {e})"

package/sinain-memory/eval/benchmarks/report.py

@@ -0,0 +1,87 @@
+"""Report generation — markdown, JSON, and LaTeX output."""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+
+
+def generate_markdown(benchmark_name: str, summary: dict, details: list[dict]) -> str:
+    """Generate a publishable markdown report."""
+    lines = [
+        f"# Sinain Knowledge Graph — {benchmark_name} Results",
+        f"\nGenerated: {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}",
+        "",
+    ]
+
+    # Headline IPR
+    ipr = summary.get("ipr")
+    if ipr:
+        lines.append(f"**Information Preservation Rate (IPR)**: {ipr:.1%}")
+        lines.append("")
+
+    # Condition scores table
+    conditions = summary.get("conditions", {})
+    if conditions:
+        cond_names = sorted(conditions.keys())
+        header = "| Condition | Mean Score (1-5) | Mean F1 | N |"
+        sep = "|-----------|------------------|---------|---|"
+        lines.extend([header, sep])
+        for cond in cond_names:
+            c = conditions[cond]
+            lines.append(f"| {cond} | {c['mean_score']:.2f} | {c.get('mean_f1', 0):.2f} | {c['n']} |")
+        lines.append("")
+
+    # Retrieval metrics
+    retrieval = summary.get("retrieval", {})
+    if retrieval:
+        lines.append("## Retrieval Quality")
+        lines.append("| Metric | Score |")
+        lines.append("|--------|-------|")
+        for k, v in sorted(retrieval.items()):
+            lines.append(f"| {k} | {v:.1%} |")
+        lines.append("")
+
+    # Category breakdown
+    categories = summary.get("categories", {})
+    if categories:
+        lines.append("## By Category")
+        cond_names = sorted(set(c for cat in categories.values() for c in cat))
+        header = "| Category | " + " | ".join(cond_names) + " |"
+        sep = "|----------|" + "|".join(["------"] * len(cond_names)) + "|"
+        lines.extend([header, sep])
+        for cat in sorted(categories):
+            cells = []
+            for cond in cond_names:
+                if cond in categories[cat]:
+                    cells.append(f"{categories[cat][cond]['mean_score']:.2f} (n={categories[cat][cond]['n']})")
+                else:
+                    cells.append("-")
+            lines.append(f"| {cat} | " + " | ".join(cells) + " |")
+        lines.append("")
+
+    # Failures (worst questions)
+    if details:
+        sm_details = [d for d in details if d.get("answers", {}).get("sinain-memory", {}).get("score") is not None]
+        sm_details.sort(key=lambda d: d["answers"]["sinain-memory"]["score"])
+        if sm_details:
+            lines.append("## Hardest Questions for sinain-memory (bottom 5)")
+            for d in sm_details[:5]:
+                sm = d["answers"]["sinain-memory"]
+                fc = d["answers"].get("full-context", {})
+                lines.append(f"- **{d['id']}** [{d['category']}]: score={sm['score']}/5 "
+                             f"(full-context: {fc.get('score', '?')}/5)")
+                lines.append(f"  Q: {d['question'][:100]}...")
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def generate_json(benchmark_name: str, summary: dict, details: list[dict]) -> str:
+    """Generate JSON report."""
+    return json.dumps({
+        "benchmark": benchmark_name,
+        "timestamp": datetime.now(timezone.utc).isoformat(),
+        "summary": summary,
+        "details": details,
+    }, indent=2, ensure_ascii=False)