ragfallback 2.0.2__tar.gz → 2.1.0__tar.gz

{ragfallback-2.0.2/ragfallback.egg-info → ragfallback-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragfallback
-Version: 2.0.2
+Version: 2.1.0
 Summary: Prevents silent RAG failures — chunk quality, retrieval fallback, adaptive querying, and answer evaluation in one library.
 Home-page: https://github.com/irfanalidv/ragfallback
 Author: Irfan Ali
@@ -11,7 +11,7 @@ Project-URL: Documentation, https://github.com/irfanalidv/ragfallback#readme
 Project-URL: Repository, https://github.com/irfanalidv/ragfallback
 Project-URL: Issues, https://github.com/irfanalidv/ragfallback/issues
 Keywords: rag,retrieval,llm,fallback,query-variations,langchain,bm25,hybrid-search
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.8
@@ -91,6 +91,12 @@ Requires-Dist: qdrant-client>=1.7.0; extra == "all"
 Requires-Dist: weaviate-client>=3.25.0; extra == "all"
 Requires-Dist: rank_bm25>=0.2.2; extra == "all"
 Requires-Dist: cohere>=4.0.0; extra == "all"
+Provides-Extra: mlops
+Requires-Dist: ragas>=0.2.0; extra == "mlops"
+Requires-Dist: mlflow>=2.10.0; extra == "mlops"
+Requires-Dist: locust>=2.20.0; extra == "mlops"
+Requires-Dist: aiohttp>=3.9.0; extra == "mlops"
+Requires-Dist: numpy>=1.24.0; extra == "mlops"
 Dynamic: author
 Dynamic: home-page
 Dynamic: license-file
@@ -99,15 +105,15 @@ Dynamic: requires-python
 # ragfallback
 
 [![GitHub license](https://img.shields.io/github/license/irfanalidv/ragfallback)](https://github.com/irfanalidv/ragfallback/blob/main/LICENSE)
-[![Python version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue.svg)](https://pypi.org/project/ragfallback/)
+[![Python version](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue.svg)](https://pypi.org/project/ragfallback/)
 [![PyPI](https://img.shields.io/pypi/v/ragfallback)](https://pypi.org/project/ragfallback/)
 [![Downloads](https://static.pepy.tech/badge/ragfallback)](https://pepy.tech/project/ragfallback)
 [![Tests](https://github.com/irfanalidv/ragfallback/actions/workflows/test.yml/badge.svg)](https://github.com/irfanalidv/ragfallback/actions/workflows/test.yml)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/irfanalidv/ragfallback/blob/main/ragfallback_colab.ipynb)
+[![MLOps](https://img.shields.io/badge/MLOps-RAGAS%20%2B%20CI%20Gate-blueviolet)](https://github.com/irfanalidv/ragfallback/tree/main/ragfallback/mlops)
 
 **ragfallback** prevents silent RAG failures across the full pipeline — from bad chunks at ingest, through retrieval outages at runtime, to invisible answer quality degradation in production.
 
-![ragfallback architecture](ragfallback_architecture.png?v=2)
-
 ---
 
 ## What it prevents
@@ -123,7 +129,8 @@ Dynamic: requires-python
 | 7  | Multi-step questions always fail single-shot RAG      | `MultiHopFallbackStrategy`                         | `uc6_multi_hop_demo.py`   |
 | 8  | Index serves stale data after document updates        | `StaleIndexDetector`                               | —                         |
 | 9  | Answer quality invisible in production                | `RAGEvaluator`                                     | `uc7_rag_evaluator.py`    |
-| 10 | Cross-boundary answers lost between adjacent chunks   | `OverlappingContextStitcher`                       | `uc8_context_stitcher.py` |
+| 10 | Cross-boundary answers lost between adjacent chunks   | `OverlappingContextStitcher`                       | `uc8_context_stitcher.py`        |
+| 11 | Metric regression after model/embedder/chunker change | `GoldenRunner` + `BaselineRegistry`                | `examples/ci_regression_gate.py` |
 
 ---
 
@@ -446,6 +453,9 @@ print(ev.batch_summary([score]))
 | Financial news RAG        | nickmuchi/financial-classification (Apache 2.0) | `python examples/financial_risk_analysis.py`    |
 | Legal contract RAG        | theatticusproject/cuad-qa (CC BY 4.0)           | `python examples/legal_document_analysis.py`    |
 | Medical abstract RAG      | qiaojin/PubMedQA (MIT)                          | `python examples/medical_research_synthesis.py` |
+| MLOps: build golden dataset | SQuAD (CC BY-SA 4.0) + SciQ (CC BY-NC 3.0)   | `python examples/build_golden_dataset.py`       |
+| MLOps: full demo            | SQuAD golden set, zero API keys                | `python examples/mlops_demo.py`                 |
+| MLOps: CI regression gate   | SQuAD golden set, committed baseline           | `python examples/ci_regression_gate.py`         |
 
 ---
 
@@ -483,6 +493,7 @@ pip install ragfallback[chroma,huggingface]          # golden path (no API keys)
 pip install ragfallback[faiss,huggingface]           # FAISS instead of Chroma
 pip install ragfallback[hybrid]                      # adds BM25 (rank_bm25)
 pip install ragfallback[real-data]                   # real dataset examples (HuggingFace datasets)
+pip install ragfallback[mlops]                       # MLOps eval layer (RAGAS + MLflow + Locust)
 ```
 
 | Extra         | Installs                               |
@@ -493,6 +504,7 @@ pip install ragfallback[real-data]                   # real dataset examples (Hu
 | `hybrid`      | rank_bm25, langchain-community         |
 | `real-data`   | datasets                               |
 | `openai`      | langchain-openai, openai               |
+| `mlops`       | ragas, mlflow, locust, aiohttp         |
 
 ---
 
@@ -509,6 +521,97 @@ from ragfallback.diagnostics import (
 from ragfallback.retrieval import SmartThresholdHybridRetriever, FailoverRetriever
 from ragfallback.strategies import QueryVariationsStrategy, MultiHopFallbackStrategy
 from ragfallback.evaluation import RAGEvaluator
+from ragfallback.mlops import (
+    RagasHook, RagasReport,
+    BaselineRegistry, RegressionError,
+    GoldenRunner, GoldenReport,
+    QuerySimulator, SimQuery,
+    MLflowLogger,
+    generate_locustfile,
+)
+```
+
+---
+
+## MLOps — Evaluation & Regression Gate
+
+ragfallback ships a complete MLOps evaluation layer for RAG pipelines.
+No API keys required — all metrics use local heuristics by default,
+with optional RAGAS + MLflow when installed.
+
+### Install
+
+```bash
+pip install ragfallback[chroma,huggingface,real-data,mlops]
+```
+
+### Full eval loop
+
+```python
+import asyncio
+from ragfallback.mlops import GoldenRunner, RagasHook, BaselineRegistry
+
+# 1 — Build evaluation hook (heuristic by default; RAGAS when installed)
+hook = RagasHook(llm=None, embeddings=embeddings)
+
+# 2 — Run against 75 real SQuAD QA pairs
+runner = GoldenRunner(
+    retriever=retriever,           # AdaptiveRAGRetriever instance
+    ragas_hook=hook,
+    dataset="examples/golden_qa.json",
+)
+report = asyncio.run(runner.run_async())
+
+print(f"Recall@3        : {report.recall_at_3:.3f}")
+print(f"Faithfulness    : {report.ragas.faithfulness:.3f}")
+print(f"Latency P95     : {report.latency_p95_ms:.0f}ms")
+print(f"Fallback rate   : {report.fallback_rate:.1%}")
+
+# 3 — Regression gate: fails if any metric drops > 5% vs baseline
+registry = BaselineRegistry("baselines.json")
+registry.compare_or_fail(report, dataset="my_dataset")   # raises RegressionError if degraded
+registry.update(report, dataset="my_dataset")             # save new baseline
+```
+
+### Adversarial query simulation
+
+```python
+from ragfallback.mlops import QuerySimulator
+
+sim = QuerySimulator()
+queries = ["What is the refund policy?", "How do API rate limits work?"]
+
+# 4 types: short_keyword, long_nl, ambiguous, out_of_domain
+mixed = sim.simulate(queries)
+
+# All 4 types for every query — for stress testing
+unhappy = sim.simulate_unhappy_paths(queries)
+```
+
+### Load testing
+
+```python
+from ragfallback.mlops import generate_locustfile
+
+generate_locustfile("locustfile.py", endpoint="http://localhost:8000")
+# Run: locust -f locustfile.py --host http://localhost:8000 --users 50
+```
+
+### CI regression gate (GitHub Actions)
+
+The included workflow (`mlops-regression-gate` job in `.github/workflows/test.yml`)
+runs on every push to main:
+
+1. Pulls 75 SQuAD samples from HuggingFace (open data, CC BY-SA 4.0)
+2. Indexes them in ChromaDB using `all-MiniLM-L6-v2` (no API key)
+3. Runs `GoldenRunner` async — computes recall@3, recall@5, latency P95
+4. Calls `compare_or_fail()` against `examples/baselines.json` (committed)
+5. Fails the pipeline if any metric regresses more than 5%
+
+```bash
+# Run the CI gate locally
+python examples/build_golden_dataset.py   # one-time setup
+python examples/ci_regression_gate.py    # exits 0 (pass) or 1 (fail)
 ```
 
 ---

{ragfallback-2.0.2 → ragfallback-2.1.0}/README.md

@@ -1,15 +1,15 @@
 # ragfallback
 
 [![GitHub license](https://img.shields.io/github/license/irfanalidv/ragfallback)](https://github.com/irfanalidv/ragfallback/blob/main/LICENSE)
-[![Python version](https://img.shields.io/badge/python-3.9%20%7C%203.10%20%7C%203.11-blue.svg)](https://pypi.org/project/ragfallback/)
+[![Python version](https://img.shields.io/badge/python-3.8%20%7C%203.9%20%7C%203.10%20%7C%203.11-blue.svg)](https://pypi.org/project/ragfallback/)
 [![PyPI](https://img.shields.io/pypi/v/ragfallback)](https://pypi.org/project/ragfallback/)
 [![Downloads](https://static.pepy.tech/badge/ragfallback)](https://pepy.tech/project/ragfallback)
 [![Tests](https://github.com/irfanalidv/ragfallback/actions/workflows/test.yml/badge.svg)](https://github.com/irfanalidv/ragfallback/actions/workflows/test.yml)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/irfanalidv/ragfallback/blob/main/ragfallback_colab.ipynb)
+[![MLOps](https://img.shields.io/badge/MLOps-RAGAS%20%2B%20CI%20Gate-blueviolet)](https://github.com/irfanalidv/ragfallback/tree/main/ragfallback/mlops)
 
 **ragfallback** prevents silent RAG failures across the full pipeline — from bad chunks at ingest, through retrieval outages at runtime, to invisible answer quality degradation in production.
 
-![ragfallback architecture](ragfallback_architecture.png?v=2)
-
 ---
 
 ## What it prevents
@@ -25,7 +25,8 @@
 | 7  | Multi-step questions always fail single-shot RAG      | `MultiHopFallbackStrategy`                         | `uc6_multi_hop_demo.py`   |
 | 8  | Index serves stale data after document updates        | `StaleIndexDetector`                               | —                         |
 | 9  | Answer quality invisible in production                | `RAGEvaluator`                                     | `uc7_rag_evaluator.py`    |
-| 10 | Cross-boundary answers lost between adjacent chunks   | `OverlappingContextStitcher`                       | `uc8_context_stitcher.py` |
+| 10 | Cross-boundary answers lost between adjacent chunks   | `OverlappingContextStitcher`                       | `uc8_context_stitcher.py`        |
+| 11 | Metric regression after model/embedder/chunker change | `GoldenRunner` + `BaselineRegistry`                | `examples/ci_regression_gate.py` |
 
 ---
 
@@ -348,6 +349,9 @@ print(ev.batch_summary([score]))
 | Financial news RAG        | nickmuchi/financial-classification (Apache 2.0) | `python examples/financial_risk_analysis.py`    |
 | Legal contract RAG        | theatticusproject/cuad-qa (CC BY 4.0)           | `python examples/legal_document_analysis.py`    |
 | Medical abstract RAG      | qiaojin/PubMedQA (MIT)                          | `python examples/medical_research_synthesis.py` |
+| MLOps: build golden dataset | SQuAD (CC BY-SA 4.0) + SciQ (CC BY-NC 3.0)   | `python examples/build_golden_dataset.py`       |
+| MLOps: full demo            | SQuAD golden set, zero API keys                | `python examples/mlops_demo.py`                 |
+| MLOps: CI regression gate   | SQuAD golden set, committed baseline           | `python examples/ci_regression_gate.py`         |
 
 ---
 
@@ -385,6 +389,7 @@ pip install ragfallback[chroma,huggingface]          # golden path (no API keys)
 pip install ragfallback[faiss,huggingface]           # FAISS instead of Chroma
 pip install ragfallback[hybrid]                      # adds BM25 (rank_bm25)
 pip install ragfallback[real-data]                   # real dataset examples (HuggingFace datasets)
+pip install ragfallback[mlops]                       # MLOps eval layer (RAGAS + MLflow + Locust)
 ```
 
 | Extra         | Installs                               |
@@ -395,6 +400,7 @@ pip install ragfallback[real-data]                   # real dataset examples (Hu
 | `hybrid`      | rank_bm25, langchain-community         |
 | `real-data`   | datasets                               |
 | `openai`      | langchain-openai, openai               |
+| `mlops`       | ragas, mlflow, locust, aiohttp         |
 
 ---
 
@@ -411,6 +417,97 @@ from ragfallback.diagnostics import (
 from ragfallback.retrieval import SmartThresholdHybridRetriever, FailoverRetriever
 from ragfallback.strategies import QueryVariationsStrategy, MultiHopFallbackStrategy
 from ragfallback.evaluation import RAGEvaluator
+from ragfallback.mlops import (
+    RagasHook, RagasReport,
+    BaselineRegistry, RegressionError,
+    GoldenRunner, GoldenReport,
+    QuerySimulator, SimQuery,
+    MLflowLogger,
+    generate_locustfile,
+)
+```
+
+---
+
+## MLOps — Evaluation & Regression Gate
+
+ragfallback ships a complete MLOps evaluation layer for RAG pipelines.
+No API keys required — all metrics use local heuristics by default,
+with optional RAGAS + MLflow when installed.
+
+### Install
+
+```bash
+pip install ragfallback[chroma,huggingface,real-data,mlops]
+```
+
+### Full eval loop
+
+```python
+import asyncio
+from ragfallback.mlops import GoldenRunner, RagasHook, BaselineRegistry
+
+# 1 — Build evaluation hook (heuristic by default; RAGAS when installed)
+hook = RagasHook(llm=None, embeddings=embeddings)
+
+# 2 — Run against 75 real SQuAD QA pairs
+runner = GoldenRunner(
+    retriever=retriever,           # AdaptiveRAGRetriever instance
+    ragas_hook=hook,
+    dataset="examples/golden_qa.json",
+)
+report = asyncio.run(runner.run_async())
+
+print(f"Recall@3        : {report.recall_at_3:.3f}")
+print(f"Faithfulness    : {report.ragas.faithfulness:.3f}")
+print(f"Latency P95     : {report.latency_p95_ms:.0f}ms")
+print(f"Fallback rate   : {report.fallback_rate:.1%}")
+
+# 3 — Regression gate: fails if any metric drops > 5% vs baseline
+registry = BaselineRegistry("baselines.json")
+registry.compare_or_fail(report, dataset="my_dataset")   # raises RegressionError if degraded
+registry.update(report, dataset="my_dataset")             # save new baseline
+```
+
+### Adversarial query simulation
+
+```python
+from ragfallback.mlops import QuerySimulator
+
+sim = QuerySimulator()
+queries = ["What is the refund policy?", "How do API rate limits work?"]
+
+# 4 types: short_keyword, long_nl, ambiguous, out_of_domain
+mixed = sim.simulate(queries)
+
+# All 4 types for every query — for stress testing
+unhappy = sim.simulate_unhappy_paths(queries)
+```
+
+### Load testing
+
+```python
+from ragfallback.mlops import generate_locustfile
+
+generate_locustfile("locustfile.py", endpoint="http://localhost:8000")
+# Run: locust -f locustfile.py --host http://localhost:8000 --users 50
+```
+
+### CI regression gate (GitHub Actions)
+
+The included workflow (`mlops-regression-gate` job in `.github/workflows/test.yml`)
+runs on every push to main:
+
+1. Pulls 75 SQuAD samples from HuggingFace (open data, CC BY-SA 4.0)
+2. Indexes them in ChromaDB using `all-MiniLM-L6-v2` (no API key)
+3. Runs `GoldenRunner` async — computes recall@3, recall@5, latency P95
+4. Calls `compare_or_fail()` against `examples/baselines.json` (committed)
+5. Fails the pipeline if any metric regresses more than 5%
+
+```bash
+# Run the CI gate locally
+python examples/build_golden_dataset.py   # one-time setup
+python examples/ci_regression_gate.py    # exits 0 (pass) or 1 (fail)
 ```
 
 ---

ragfallback-2.1.0/examples/build_golden_dataset.py

@@ -0,0 +1,230 @@
+"""
+Build Golden Dataset for ragfallback MLOps Evaluation
+======================================================
+Pulls 75 real QA pairs from SQuAD (Wikipedia, CC BY-SA 4.0) and formats
+them into golden_qa.json for use with GoldenRunner + BaselineRegistry.
+
+Also pulls 25 from SciQ for a mixed domain stress set (golden_qa_stress.json).
+
+Install : pip install ragfallback[real-data,chroma,huggingface]
+Run     : python examples/build_golden_dataset.py
+Output  : examples/golden_qa.json          (75 SQuAD samples)
+          examples/golden_qa_stress.json   (25 SQuAD + 25 SciQ mixed)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+# Allow running directly from repo root without pip install -e .
+_repo_root = Path(__file__).resolve().parent.parent
+if (_repo_root / "ragfallback").is_dir() and str(_repo_root) not in sys.path:
+    sys.path.insert(0, str(_repo_root))
+
+
+def _doc_id(text: str, prefix: str = "doc") -> str:
+    """Stable deterministic ID from content hash."""
+    h = hashlib.md5(text.encode()).hexdigest()[:8]
+    return f"{prefix}_{h}"
+
+
+def build_squad_samples(n: int = 75) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """
+    Load SQuAD validation split.
+
+    Returns:
+        (samples, docs_meta) where samples follow GoldenRunner format:
+        {"query", "ground_truth", "relevant_doc_ids"}
+        and docs_meta is a list of {"id", "text", "title"} for reference.
+    """
+    try:
+        from datasets import load_dataset  # type: ignore
+    except ImportError:
+        print("ERROR: pip install ragfallback[real-data]")
+        sys.exit(1)
+
+    print("  Downloading SQuAD validation split...")
+    ds = load_dataset("rajpurkar/squad", split="validation")
+
+    # Build passage registry: context_text → doc_id
+    passage_registry: Dict[str, str] = {}
+    samples: List[Dict[str, Any]] = []
+    docs_meta: List[Dict[str, Any]] = []
+
+    # We need good samples: has an answer, answer is in context, not too short
+    for row in ds:
+        if len(samples) >= n:
+            break
+
+        context = row["context"].strip()
+        question = row["question"].strip()
+        answers = row["answers"]["text"]
+
+        if not answers:
+            continue
+        ground_truth = answers[0].strip()
+
+        # Skip trivial answers (too short to be meaningful)
+        if len(ground_truth) < 3:
+            continue
+
+        # Register the passage
+        if context not in passage_registry:
+            doc_id = _doc_id(context, prefix="squad")
+            passage_registry[context] = doc_id
+            docs_meta.append(
+                {
+                    "id": doc_id,
+                    "text": context,
+                    "title": row["title"],
+                    "source": "squad",
+                }
+            )
+        else:
+            doc_id = passage_registry[context]
+
+        samples.append(
+            {
+                "query": question,
+                "ground_truth": ground_truth,
+                "relevant_doc_ids": [doc_id],  # the passage that contains the answer
+                "metadata": {
+                    "source": "squad",
+                    "title": row["title"],
+                    "doc_id": doc_id,
+                },
+            }
+        )
+
+    print(f"  SQuAD: {len(samples)} samples, {len(docs_meta)} unique passages")
+    return samples, docs_meta
+
+
+def build_sciq_samples(n: int = 25) -> Tuple[List[Dict[str, Any]], List[Dict[str, Any]]]:
+    """
+    Load SciQ test split — science domain, harder than SQuAD.
+
+    Returns same format as build_squad_samples.
+    """
+    try:
+        from datasets import load_dataset  # type: ignore
+    except ImportError:
+        print("ERROR: pip install ragfallback[real-data]")
+        sys.exit(1)
+
+    print("  Downloading SciQ test split...")
+    ds = load_dataset("allenai/sciq", split="test")
+
+    samples: List[Dict[str, Any]] = []
+    docs_meta: List[Dict[str, Any]] = []
+
+    for row in ds:
+        if len(samples) >= n:
+            break
+
+        support = (row.get("support") or "").strip()
+        question = row["question"].strip()
+        answer = row["correct_answer"].strip()
+
+        # SciQ: skip rows with no supporting passage
+        if len(support) < 50:
+            continue
+
+        doc_id = _doc_id(support, prefix="sciq")
+        docs_meta.append(
+            {
+                "id": doc_id,
+                "text": support,
+                "title": "SciQ",
+                "source": "sciq",
+            }
+        )
+
+        samples.append(
+            {
+                "query": question,
+                "ground_truth": answer,
+                "relevant_doc_ids": [doc_id],
+                "metadata": {
+                    "source": "sciq",
+                    "doc_id": doc_id,
+                },
+            }
+        )
+
+    print(f"  SciQ: {len(samples)} samples, {len(docs_meta)} unique passages")
+    return samples, docs_meta
+
+
+def write_dataset(samples: List[Dict[str, Any]], path: Path) -> None:
+    """Write samples to JSON file."""
+    # Remove metadata key from final output (GoldenRunner doesn't need it)
+    clean = []
+    for s in samples:
+        clean.append(
+            {
+                "query": s["query"],
+                "ground_truth": s["ground_truth"],
+                "relevant_doc_ids": s["relevant_doc_ids"],
+            }
+        )
+    path.write_text(json.dumps(clean, indent=2, ensure_ascii=False))
+    print(f"  Written: {path} ({len(clean)} samples)")
+
+
+def write_docs_registry(docs: List[Dict[str, Any]], path: Path) -> None:
+    """Write passage registry — useful for building vector store from same data."""
+    path.write_text(json.dumps(docs, indent=2, ensure_ascii=False))
+    print(f"  Written: {path} ({len(docs)} passages)")
+
+
+def main() -> None:
+    print("=" * 60)
+    print("ragfallback — Build Golden Dataset from Open Data")
+    print("=" * 60)
+
+    out_dir = Path(__file__).resolve().parent
+    squad_json = out_dir / "golden_qa.json"
+    stress_json = out_dir / "golden_qa_stress.json"
+    docs_registry = out_dir / "golden_docs_registry.json"
+
+    # --- SQuAD: primary golden dataset ---
+    print("\n[1/3] Building primary golden dataset (SQuAD, n=75)...")
+    squad_samples, squad_docs = build_squad_samples(n=75)
+    write_dataset(squad_samples, squad_json)
+
+    # --- SciQ: stress set ---
+    print("\n[2/3] Building stress golden dataset (SciQ, n=25)...")
+    sciq_samples, sciq_docs = build_sciq_samples(n=25)
+
+    # Stress set = 25 SQuAD + 25 SciQ (mixed domain)
+    stress_samples = squad_samples[:25] + sciq_samples
+    write_dataset(stress_samples, stress_json)
+
+    # --- Docs registry ---
+    print("\n[3/3] Writing passage registry (for vector store construction)...")
+    all_docs = squad_docs + sciq_docs
+    write_docs_registry(all_docs, docs_registry)
+
+    # --- Summary ---
+    print("\n" + "=" * 60)
+    print("DONE. Files written:")
+    print(f"  {squad_json.name:<35} — 75 SQuAD samples (primary eval)")
+    print(f"  {stress_json.name:<35} — 50 mixed samples (stress eval)")
+    print(f"  {docs_registry.name:<35} — passage registry")
+    print()
+    print("Next step:")
+    print("  python examples/mlops_demo.py")
+    print()
+    print("Licenses:")
+    print("  SQuAD : CC BY-SA 4.0  (https://huggingface.co/datasets/rajpurkar/squad)")
+    print("  SciQ  : CC BY-NC 3.0  (https://huggingface.co/datasets/allenai/sciq)")
+    print("=" * 60)
+
+
+if __name__ == "__main__":
+    main()