icdev 0.0.3__py3-none-any.whl

tools/project/validate_manifest.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+# CUI // SP-CTI
+"""Validate an sparkpilot.yaml manifest file.
+
+Thin CLI wrapper around manifest_loader.validate_manifest().
+Referenced in docs/dx/sparkpilot-yaml-spec.md.
+
+Usage:
+    python tools/project/validate_manifest.py --file sparkpilot.yaml
+    python tools/project/validate_manifest.py --file sparkpilot.yaml --json
+    python tools/project/validate_manifest.py --dir /path/to/project --json
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+BASE_DIR = Path(__file__).resolve().parent.parent.parent
+sys.path.insert(0, str(BASE_DIR))
+from tools.project.manifest_loader import load_manifest
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Validate an sparkpilot.yaml manifest file"
+    )
+    parser.add_argument("--file", help="Path to sparkpilot.yaml")
+    parser.add_argument("--dir", help="Directory containing sparkpilot.yaml")
+    parser.add_argument("--json", action="store_true", help="Output JSON")
+    args = parser.parse_args()
+
+    result = load_manifest(directory=args.dir, file_path=args.file)
+
+    if args.json:
+        print(json.dumps({
+            "valid": result["valid"],
+            "errors": result["errors"],
+            "warnings": result["warnings"],
+            "file_path": result["file_path"],
+        }, indent=2))
+    else:
+        for err in result["errors"]:
+            print(f"ERROR: {err}")
+        for warn in result["warnings"]:
+            print(f"WARNING: {warn}")
+        if result["valid"]:
+            print("Manifest is valid.")
+
+    sys.exit(0 if result["valid"] else 1)
+
+
+if __name__ == "__main__":
+    main()

tools/rag/corrective_rag.py

@@ -0,0 +1,582 @@
+# CUI // SP-CTI
+"""Corrective RAG pipeline for compliance retrieval (D-ARCH-11).
+
+Pattern: Retrieve -> Evaluate relevance -> Correct (re-query/refine/fallback) -> Generate.
+Deterministic pipeline -- no LLM calls in the critical path.
+
+Thresholds:
+    > 0.8  : direct   -- use document as-is
+    0.5-0.8: refined  -- expand terms and re-query
+    < 0.5  : decomposed -- split into sub-queries and merge results
+
+KARL-inspired enhancements (D-KARL-3):
+    - Parallel multi-strategy retrieval across GraphRAG + corrective RAG + source registry
+    - Generative aggregation via scanner-tier LLM (zero Claude tokens)
+    - ThreadPoolExecutor concurrency (matches D-SC-1 pattern)
+
+Usage:
+    python tools/rag/corrective_rag.py --query "AC-2 access control policy"
+    python tools/rag/corrective_rag.py --parallel --query "zero trust NIST compliance"
+    python tools/rag/corrective_rag.py --evaluate --query "AC-2" --document "text"
+    python tools/rag/corrective_rag.py --stats --json
+"""
+
+import argparse
+import json
+import math
+import re
+import sys
+import time
+from collections import Counter
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import Any, Dict, List, Optional, Tuple
+
+# Optional ICDEV imports
+_HAS_SOURCE_REGISTRY = False
+_HAS_HYBRID_SEARCH = False
+_HAS_GRAPH_RAG = False
+try:
+    from tools.rag.source_registry import search as source_search  # type: ignore
+    _HAS_SOURCE_REGISTRY = True
+except ImportError:
+    pass
+try:
+    from tools.memory.hybrid_search import hybrid_search  # type: ignore
+    _HAS_HYBRID_SEARCH = True
+except ImportError:
+    pass
+try:
+    from tools.knowledge_graph.graph_rag import graph_rag_query  # type: ignore
+    _HAS_GRAPH_RAG = True
+except ImportError:
+    pass
+
+# NIST SP 800-53 control family expansion map
+NIST_CONTROL_FAMILIES: Dict[str, str] = {
+    "AC": "Access Control", "AU": "Audit and Accountability",
+    "AT": "Awareness and Training", "CA": "Assessment and Authorization",
+    "CM": "Configuration Management", "CP": "Contingency Planning",
+    "IA": "Identification and Authentication", "IR": "Incident Response",
+    "MA": "Maintenance", "MP": "Media Protection",
+    "PE": "Physical and Environmental Protection", "PL": "Planning",
+    "PM": "Program Management", "PS": "Personnel Security",
+    "RA": "Risk Assessment", "SA": "System and Services Acquisition",
+    "SC": "System and Communications Protection",
+    "SI": "System and Information Integrity",
+    "SR": "Supply Chain Risk Management",
+}
+
+FRAMEWORK_EXPANSIONS: Dict[str, str] = {
+    "FedRAMP": "Federal Risk and Authorization Management Program",
+    "CMMC": "Cybersecurity Maturity Model Certification",
+    "NIST": "National Institute of Standards and Technology",
+    "STIG": "Security Technical Implementation Guide",
+    "POAM": "Plan of Action and Milestones", "SSP": "System Security Plan",
+    "ATO": "Authority to Operate", "cATO": "continuous Authority to Operate",
+    "CUI": "Controlled Unclassified Information",
+    "RMF": "Risk Management Framework",
+    "OSCAL": "Open Security Controls Assessment Language",
+    "SBOM": "Software Bill of Materials", "ZTA": "Zero Trust Architecture",
+    "SCRM": "Supply Chain Risk Management",
+}
+
+_CONTROL_ID_RE = re.compile(
+    r"\b([A-Z]{2})-(\d{1,2})(?:\((\d+)\))?(?:\.([a-z]))?(?:\s|$|,|;|\.|:)")
+_STRUCTURE_MARKERS = [
+    re.compile(r"^#{1,4}\s", re.MULTILINE),
+    re.compile(r"^\s*[-*]\s", re.MULTILINE),
+    re.compile(r"\bevidence\b", re.IGNORECASE),
+    re.compile(r"\bcontrol\b", re.IGNORECASE),
+    re.compile(r"\bimplementation\b", re.IGNORECASE),
+    re.compile(r"\bcompliance\b", re.IGNORECASE),
+]
+
+THRESHOLD_DIRECT = 0.8
+THRESHOLD_REFINED = 0.5
+
+_stats: Dict[str, Any] = {
+    "total_queries": 0,
+    "strategy_counts": {"direct": 0, "refined": 0, "decomposed": 0},
+    "total_relevance": 0.0, "relevance_count": 0, "cache_hits": 0,
+}
+_query_cache: Dict[str, Dict[str, Any]] = {}
+_CACHE_MAX = 256
+_STOP_WORDS = frozenset(
+    "a an and are as at be but by for from has have he her his how i if in "
+    "into is it its my not of on or our she so than that the their them then "
+    "there these they this to up was we what when where which who will with "
+    "you your do does did the".split())
+
+
+def _tokenize(text: str) -> List[str]:
+    """Lowercase token list with stop-word removal."""
+    return [t for t in re.findall(r"[a-zA-Z0-9][\w-]*", text.lower())
+            if t not in _STOP_WORDS]
+
+
+def _term_frequencies(tokens: List[str]) -> Dict[str, float]:
+    """Normalised term frequency vector."""
+    counts = Counter(tokens)
+    total = len(tokens) or 1
+    return {t: c / total for t, c in counts.items()}
+
+
+def _keyword_overlap(q_tokens: List[str], d_tokens: List[str]) -> float:
+    """Jaccard similarity on unique token sets."""
+    q, d = set(q_tokens), set(d_tokens)
+    if not q or not d:
+        return 0.0
+    return len(q & d) / len(q | d)
+
+
+def _control_id_score(query: str, document: str) -> float:
+    """Score based on NIST control ID matching between query and document."""
+    q_ids = set(_CONTROL_ID_RE.findall(query))
+    d_ids = set(_CONTROL_ID_RE.findall(document))
+    if not q_ids:
+        return 0.0
+    return len(q_ids & d_ids) / len(q_ids) if d_ids else 0.0
+
+
+def _framework_term_score(query: str, document: str) -> float:
+    """Score based on framework term presence in document."""
+    q_low, d_low = query.lower(), document.lower()
+    fws = [a.lower() for a, f in FRAMEWORK_EXPANSIONS.items()
+           if a.lower() in q_low or f.lower() in q_low]
+    if not fws:
+        return 0.5
+    return sum(1 for fw in fws if fw in d_low
+               or FRAMEWORK_EXPANSIONS.get(fw, "").lower() in d_low) / len(fws)
+
+
+def _structure_score(document: str) -> float:
+    """Score based on structural quality indicators."""
+    if not document.strip():
+        return 0.0
+    return min(sum(1 for p in _STRUCTURE_MARKERS if p.search(document))
+               / len(_STRUCTURE_MARKERS), 1.0)
+
+
+def _tfidf_cosine(query: str, document: str) -> float:
+    """Simplified TF-IDF cosine similarity."""
+    q_tok, d_tok = _tokenize(query), _tokenize(document)
+    if not q_tok or not d_tok:
+        return 0.0
+    q_tf, d_tf = _term_frequencies(q_tok), _term_frequencies(d_tok)
+    dot = mag_q = mag_d = 0.0
+    for term in set(q_tf) | set(d_tf):
+        idf = 1.0 + (1.0 if term in q_tf and term in d_tf else 0.0)
+        qw, dw = q_tf.get(term, 0.0) * idf, d_tf.get(term, 0.0) * idf
+        dot += qw * dw
+        mag_q += qw * qw
+        mag_d += dw * dw
+    return dot / (math.sqrt(mag_q) * math.sqrt(mag_d)) if mag_q and mag_d else 0.0
+
+
+def evaluate_relevance(query: str, document_text: str) -> float:
+    """Evaluate relevance of a document to a query (0-1 score).
+
+    Deterministic composite of keyword overlap (0.25), TF-IDF cosine (0.25),
+    control ID matching (0.20), framework terms (0.15), structure (0.15).
+    """
+    q_tok, d_tok = _tokenize(query), _tokenize(document_text)
+    composite = (0.25 * _keyword_overlap(q_tok, d_tok)
+                 + 0.25 * _tfidf_cosine(query, document_text)
+                 + 0.20 * _control_id_score(query, document_text)
+                 + 0.15 * _framework_term_score(query, document_text)
+                 + 0.15 * _structure_score(document_text))
+    return round(min(max(composite, 0.0), 1.0), 4)
+
+
+def refine_query(original_query: str, low_scoring_terms: Optional[List[str]] = None) -> str:
+    """Expand abbreviations and add synonyms to improve retrieval."""
+    expanded = original_query
+    for abbr, full in NIST_CONTROL_FAMILIES.items():
+        pat = re.compile(rf"\b{abbr}\b(?=\s*-?\s*\d{{0,2}})", re.IGNORECASE)
+        if pat.search(expanded) and full.lower() not in expanded.lower():
+            expanded = pat.sub(f"{abbr} ({full})", expanded, count=1)
+    for abbr, full in FRAMEWORK_EXPANSIONS.items():
+        pat = re.compile(rf"\b{re.escape(abbr)}\b", re.IGNORECASE)
+        if pat.search(expanded) and full.lower() not in expanded.lower():
+            expanded = pat.sub(f"{abbr} ({full})", expanded, count=1)
+    if low_scoring_terms:
+        for term in low_scoring_terms:
+            expanded = re.sub(rf"\b{re.escape(term)}\b", "", expanded, flags=re.IGNORECASE)
+        expanded = re.sub(r"\s{2,}", " ", expanded).strip()
+    return expanded
+
+
+def decompose_query(complex_query: str) -> List[str]:
+    """Split a compound query into atomic sub-queries."""
+    parts = [p.strip() for p in re.split(r"\band\b|\bor\b|[;,]", complex_query,
+                                          flags=re.IGNORECASE) if p.strip()]
+    if len(parts) > 1:
+        sub_queries = parts
+    else:
+        ctrl_matches = _CONTROL_ID_RE.findall(complex_query)
+        if len(ctrl_matches) > 1:
+            base = re.sub(r"\s{2,}", " ", _CONTROL_ID_RE.sub("", complex_query)).strip()
+            sub_queries = []
+            for m in ctrl_matches:
+                cid = f"{m[0]}-{m[1]}" + (f"({m[2]})" if m[2] else "") + (f".{m[3]}" if m[3] else "")
+                sub_queries.append(f"{cid} {base}".strip() if base else cid)
+        else:
+            return [complex_query]
+    seen: set = set()
+    return [sq for sq in sub_queries if sq.lower().strip() not in seen
+            and not seen.add(sq.lower().strip())]  # type: ignore[func-returns-value]
+
+
+def _retrieve_documents(query: str, top_k: int = 5) -> List[Dict[str, Any]]:
+    """Retrieve from available backends or return simulated results."""
+    for backend, avail, fn in [
+        ("hybrid_search", _HAS_HYBRID_SEARCH, lambda q, k: hybrid_search(query=q, limit=k)),
+        ("source_registry", _HAS_SOURCE_REGISTRY, lambda q, k: source_search(query=q, limit=k)),
+    ]:
+        if avail:
+            try:
+                results = fn(query, top_k)
+                if results:
+                    return [{"id": r.get("id", "unknown"),
+                             "text": r.get("content", r.get("text", "")),
+                             "source": backend, "score": r.get("score", 0.0)}
+                            for r in results[:top_k]]
+            except Exception:
+                pass
+    # Simulated fallback
+    ctrl = _CONTROL_ID_RE.findall(query)
+    docs = []
+    for i in range(min(top_k, 3)):
+        if ctrl:
+            fam, num = ctrl[0][0], ctrl[0][1]
+            txt = (f"## {fam}-{num} {NIST_CONTROL_FAMILIES.get(fam, 'Unknown')}\n\n"
+                   f"- Implementation: Organization implements {fam}-{num} controls.\n"
+                   f"- Evidence: Documented in SSP section {fam}-{num}.\n"
+                   f"- Baseline: FedRAMP Moderate\n")
+        else:
+            terms = _tokenize(query)[:3]
+            txt = (f"## Compliance Document (simulated)\n\n"
+                   f"- Topic: {' '.join(terms)}\n- Evidence: Simulated.\n")
+        docs.append({"id": f"sim-{i+1}", "text": txt, "source": "simulated",
+                      "score": round(1.0 - i * 0.15, 2)})
+    return docs
+
+
+def retrieve_and_evaluate(query: str, top_k: int = 5,
+                          min_relevance: float = 0.5) -> Dict[str, Any]:
+    """Retrieve documents and evaluate relevance.
+
+    Returns dict with documents, relevance_scores, strategy_used.
+    """
+    _stats["total_queries"] += 1
+    cache_key = f"{query}|{top_k}|{min_relevance}"
+    if cache_key in _query_cache:
+        _stats["cache_hits"] += 1
+        return _query_cache[cache_key]
+
+    docs = _retrieve_documents(query, top_k)
+    scored = [(d, evaluate_relevance(query, d.get("text", ""))) for d in docs]
+    avg_rel = sum(s for _, s in scored) / len(scored) if scored else 0.0
+    _stats["total_relevance"] += avg_rel
+    _stats["relevance_count"] += 1
+    strategy = ("direct" if avg_rel >= THRESHOLD_DIRECT
+                else "refined" if avg_rel >= THRESHOLD_REFINED else "decomposed")
+    _stats["strategy_counts"][strategy] += 1
+
+    result = {"documents": [d for d, _ in scored],
+              "relevance_scores": [s for _, s in scored],
+              "strategy_used": strategy, "query_used": query,
+              "avg_relevance": round(avg_rel, 4)}
+    if len(_query_cache) >= _CACHE_MAX:
+        del _query_cache[next(iter(_query_cache))]
+    _query_cache[cache_key] = result
+    return result
+
+
+def corrective_retrieve(query: str, context: Optional[str] = None,
+                        top_k: int = 5) -> Dict[str, Any]:
+    """Full corrective RAG pipeline: Retrieve -> Evaluate -> Correct -> Return.
+
+    Applies correction strategies based on relevance thresholds:
+        direct (>= 0.8), refined (0.5-0.8), decomposed (< 0.5).
+    """
+    start = time.monotonic()
+    initial = retrieve_and_evaluate(query, top_k=top_k)
+    strategy = initial["strategy_used"]
+    result: Dict[str, Any] = {"original_query": query, "context": context,
+                               "correction_applied": strategy != "direct",
+                               "strategy_used": strategy, "sub_queries": None}
+
+    if strategy == "direct":
+        result.update(final_query=query, documents=initial["documents"],
+                      relevance_scores=initial["relevance_scores"],
+                      avg_relevance=initial["avg_relevance"])
+    elif strategy == "refined":
+        rq = refine_query(query) + (f" {context}" if context else "")
+        rr = retrieve_and_evaluate(rq, top_k=top_k)
+        result.update(final_query=rq, documents=rr["documents"],
+                      relevance_scores=rr["relevance_scores"],
+                      avg_relevance=rr["avg_relevance"])
+    else:
+        sqs = decompose_query(query)
+        if context:
+            sqs = [f"{sq} {context}" for sq in sqs]
+        all_docs, all_scores, seen = [], [], set()
+        for sq in sqs:
+            sr = retrieve_and_evaluate(sq, top_k=max(2, top_k // len(sqs)))
+            for d, s in zip(sr["documents"], sr["relevance_scores"]):
+                if d.get("id") not in seen:
+                    seen.add(d.get("id"))
+                    all_docs.append(d)
+                    all_scores.append(s)
+        paired = sorted(zip(all_docs, all_scores), key=lambda x: x[1], reverse=True)[:top_k]
+        result.update(final_query=" | ".join(sqs),
+                      documents=[d for d, _ in paired],
+                      relevance_scores=[s for _, s in paired],
+                      avg_relevance=round(sum(s for _, s in paired) / len(paired)
+                                          if paired else 0.0, 4),
+                      sub_queries=sqs)
+
+    result["pipeline_time_ms"] = round((time.monotonic() - start) * 1000, 2)
+    return result
+
+
+def _aggregate_with_llm(
+    query: str,
+    strategy_results: Dict[str, Dict[str, Any]],
+) -> str:
+    """KARL-inspired generative aggregation (D-KARL-3).
+
+    Synthesizes a unified context from multiple retrieval strategies using
+    scanner-tier LLM (qwen3.5, zero Claude tokens). Can produce answers
+    better than any individual strategy (KARL reports 23.7% improvement).
+    Falls back to deterministic merge if LLM unavailable.
+    """
+    # Build input for aggregator
+    parts = [f"Query: {query}\n"]
+    for strategy_name, result in strategy_results.items():
+        parts.append(f"--- {strategy_name} results ---")
+        if strategy_name == "graph_rag":
+            parts.append(result.get("context", "No graph context"))
+        elif strategy_name == "corrective_rag":
+            docs = result.get("documents", [])
+            for i, d in enumerate(docs[:5]):
+                parts.append(f"  [{i+1}] {d.get('text', '')[:300]}")
+        elif strategy_name == "source_registry":
+            for i, r in enumerate(result[:5] if isinstance(result, list) else []):
+                text = r.get("content", r.get("text", ""))[:300]
+                parts.append(f"  [{i+1}] {text}")
+        parts.append("")
+
+    combined_input = "\n".join(parts)
+
+    try:
+        from tools.llm.router import invoke
+        prompt = (
+            f"You are a retrieval aggregator. Multiple search strategies returned "
+            f"results for the same query. Synthesize a unified, comprehensive context "
+            f"that combines the best information from all strategies.\n\n"
+            f"{combined_input}\n"
+            f"INSTRUCTIONS:\n"
+            f"- Merge overlapping information (don't repeat)\n"
+            f"- Preserve unique insights from each strategy\n"
+            f"- Prioritize graph-based relationships and structural gaps\n"
+            f"- Keep compliance control IDs and framework references\n"
+            f"- Output ONLY the synthesized context, no commentary"
+        )
+        result = invoke(
+            prompt=prompt,
+            function_name="kg_compress",  # Scanner tier, zero Claude tokens
+            max_tokens=2000,
+        )
+        if isinstance(result, dict):
+            text = result.get("content", result.get("text", ""))
+        else:
+            text = str(result)
+        if text and len(text) > 50:
+            return text
+    except Exception:
+        pass
+
+    # Deterministic fallback: concatenate top results from each strategy
+    return combined_input[:4000]
+
+
+def parallel_retrieve(
+    query: str,
+    *,
+    project_id: str = "sparkpilot",
+    top_k: int = 5,
+    context: Optional[str] = None,
+    profile: Optional[str] = None,
+    aggregate: bool = True,
+) -> Dict[str, Any]:
+    """KARL-inspired parallel multi-strategy retrieval (D-KARL-3).
+
+    Fires GraphRAG, corrective RAG, and source registry searches concurrently
+    via ThreadPoolExecutor (matches D-SC-1 pattern), then aggregates results
+    with a scanner-tier LLM (generative aggregation).
+
+    KARL showed that N independent retrieval paths + generative aggregation
+    produces answers better than any single path (23.7% improvement rate).
+
+    Args:
+        query: Search query text.
+        project_id: Project for GraphRAG graph lookup.
+        top_k: Max results per strategy.
+        context: Optional context to refine retrieval.
+        profile: GraphRAG scoring profile (auto-detected if None).
+        aggregate: If True, run generative aggregation on results.
+
+    Returns:
+        Dict with per-strategy results, aggregated context, and timing.
+    """
+    start = time.monotonic()
+    strategy_results: Dict[str, Dict[str, Any]] = {}
+    strategies_used: List[str] = []
+
+    def _run_corrective():
+        return ("corrective_rag", corrective_retrieve(
+            query, context=context, top_k=top_k,
+        ))
+
+    def _run_graph_rag():
+        if not _HAS_GRAPH_RAG:
+            return ("graph_rag", {"error": "GraphRAG not available"})
+        return ("graph_rag", graph_rag_query(
+            query, project_id=project_id, top_k=top_k,
+            profile=profile, compress=False,  # Compress after aggregation
+        ))
+
+    def _run_source_registry():
+        if not _HAS_SOURCE_REGISTRY:
+            return ("source_registry", {"error": "Source registry not available"})
+        try:
+            results = source_search(query=query, limit=top_k)
+            return ("source_registry", results or [])
+        except Exception as exc:
+            return ("source_registry", {"error": str(exc)})
+
+    # Fire all strategies in parallel (D-SC-1 ThreadPoolExecutor pattern)
+    futures = []
+    with ThreadPoolExecutor(max_workers=3) as executor:
+        futures.append(executor.submit(_run_corrective))
+        if _HAS_GRAPH_RAG:
+            futures.append(executor.submit(_run_graph_rag))
+        if _HAS_SOURCE_REGISTRY:
+            futures.append(executor.submit(_run_source_registry))
+
+        for future in as_completed(futures):
+            try:
+                name, result = future.result()
+                strategy_results[name] = result
+                if not (isinstance(result, dict) and result.get("error")):
+                    strategies_used.append(name)
+            except Exception:
+                pass
+
+    # Generative aggregation (D-KARL-3)
+    if aggregate and len(strategies_used) > 1:
+        aggregated_context = _aggregate_with_llm(query, strategy_results)
+    elif strategies_used:
+        # Single strategy — use its context directly
+        first = strategy_results.get(strategies_used[0], {})
+        aggregated_context = first.get("context", str(first)[:2000])
+    else:
+        aggregated_context = "No retrieval strategies produced results."
+
+    elapsed_ms = round((time.monotonic() - start) * 1000, 2)
+
+    return {
+        "query": query,
+        "strategies_used": strategies_used,
+        "strategy_count": len(strategies_used),
+        "strategy_results": strategy_results,
+        "aggregated_context": aggregated_context,
+        "aggregation_method": "generative" if aggregate and len(strategies_used) > 1 else "single",
+        "pipeline_time_ms": elapsed_ms,
+        "classification": "CUI // SP-CTI",
+    }
+
+
+def get_stats() -> Dict[str, Any]:
+    """Return pipeline statistics."""
+    avg = (round(_stats["total_relevance"] / _stats["relevance_count"], 4)
+           if _stats["relevance_count"] > 0 else 0.0)
+    return {"total_queries": _stats["total_queries"],
+            "strategy_counts": dict(_stats["strategy_counts"]),
+            "avg_relevance": avg, "cache_hits": _stats["cache_hits"]}
+
+
+def main() -> None:
+    """CLI entry point."""
+    p = argparse.ArgumentParser(
+        description="Corrective RAG pipeline for compliance retrieval (D-ARCH-11)")
+    p.add_argument("--query", type=str, help="Query text for retrieval")
+    p.add_argument("--evaluate", action="store_true",
+                   help="Evaluate relevance of --query against --document")
+    p.add_argument("--parallel", action="store_true",
+                   help="KARL parallel multi-strategy retrieval with aggregation")
+    p.add_argument("--document", type=str, help="Document text (with --evaluate)")
+    p.add_argument("--top-k", type=int, default=5)
+    p.add_argument("--context", type=str, default=None)
+    p.add_argument("--project-id", type=str, default="sparkpilot")
+    p.add_argument("--profile", type=str, default=None,
+                   help="GraphRAG scoring profile (compliance, exploratory, etc.)")
+    p.add_argument("--stats", action="store_true", help="Show pipeline statistics")
+    p.add_argument("--json", action="store_true", help="Output as JSON")
+    args = p.parse_args()
+
+    if args.stats:
+        s = get_stats()
+        if args.json:
+            print(json.dumps(s, indent=2))
+        else:
+            print("Corrective RAG Pipeline Statistics\n" + "=" * 40)
+            for k, v in s.items():
+                print(f"  {k}: {v}")
+        return
+    if args.parallel and args.query:
+        r = parallel_retrieve(
+            args.query, project_id=args.project_id,
+            top_k=args.top_k, context=args.context,
+            profile=args.profile,
+        )
+        if args.json:
+            print(json.dumps(r, indent=2, default=str))
+        else:
+            print(f"Strategies: {r['strategies_used']}  Time: {r['pipeline_time_ms']}ms")
+            print(f"Aggregation: {r['aggregation_method']}")
+            print(f"\n{r['aggregated_context'][:500]}")
+        return
+    if args.evaluate:
+        if not args.query or not args.document:
+            p.error("--evaluate requires --query and --document")
+        score = evaluate_relevance(args.query, args.document)
+        r = {"query": args.query, "document_preview": args.document[:200],
+             "relevance_score": score,
+             "classification": ("direct" if score >= THRESHOLD_DIRECT
+                                else "refined" if score >= THRESHOLD_REFINED
+                                else "decomposed")}
+        print(json.dumps(r, indent=2) if args.json else f"Relevance: {score} ({r['classification']})")
+        return
+    if args.query:
+        r = corrective_retrieve(query=args.query, context=args.context, top_k=args.top_k)
+        if args.json:
+            print(json.dumps(r, indent=2))
+        else:
+            print(f"Strategy: {r['strategy_used']}  Corrected: {r['correction_applied']}")
+            print(f"Avg relevance: {r['avg_relevance']}  Time: {r['pipeline_time_ms']}ms")
+            print(f"Documents: {len(r['documents'])}")
+            if r.get("sub_queries"):
+                print(f"Sub-queries: {r['sub_queries']}")
+            for i, (d, s) in enumerate(zip(r["documents"], r["relevance_scores"])):
+                print(f"  [{i+1}] id={d.get('id')} score={s} source={d.get('source')}")
+                print(f"      {d.get('text', '')[:100].replace(chr(10), ' ')}")
+        return
+    p.print_help()
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()