ctxora 6.2.0

package/src/context/assembler.py

@@ -0,0 +1,298 @@
+"""
+context/assembler.py — Provider-aware context assembly
+=======================================================
+Formats retrieved chunks + memory entries into a system prompt.
+
+Format strategy by model:
+  - Claude (Anthropic):  XML  — <retrieved_context> / <long_term_memory>
+  - Gemini (Google):     JSON — wrapped in ```json fence
+  - OpenAI Chat (GPT):   Markdown — fenced code blocks, clean headings
+  - OpenAI Codex:        Compact Markdown — minimise overhead tokens;
+                          only emit file path + critical code snippet
+  - OpenAI Reasoning:    Markdown — same as chat but no `<system>` injection
+                          (summary injected as user message by compactor)
+"""
+
+from __future__ import annotations
+
+import json
+
+# ── Memory formatting helper ──────────────────────────────────────────────────
+
+def _format_memory_compact(entries: list[dict]) -> str:
+    """
+    Compact single-line memory format — saves ~50 tokens per entry vs XML.
+    Format: [type|key] value
+    """
+    if not entries:
+        return ""
+    lines = [f"[{m['type']}|{m['key']}] {m['value']}" for m in entries]
+    return "\n".join(lines)
+
+
+def _format_memory_xml(entries: list[dict]) -> str:
+    """Full XML memory block — for Claude structured mode."""
+    if not entries:
+        return ""
+    lines = []
+    for m in entries:
+        lines.append(
+            f"  <memory key='{m['key']}' type='{m['type']}'>"
+            f"{m['value']}</memory>"
+        )
+    return "\n".join(lines)
+
+
+# ── Model family detection ────────────────────────────────────────────────────
+
+def _is_gemini(model: str) -> bool:
+    return "gemini" in model.lower()
+
+
+def _is_claude(model: str) -> bool:
+    return "claude" in model.lower() or "anthropic" in model.lower()
+
+
+def _is_codex(model: str) -> bool:
+    ml = model.lower()
+    return any(kw in ml for kw in (
+        "codex", "code-davinci", "code-cushman",
+    ))
+
+
+def _is_reasoning(model: str) -> bool:
+    """OpenAI o-series reasoning models."""
+    ml = model.lower()
+    return any(ml.startswith(p) or f"-{p}" in ml for p in (
+        "o1", "o3", "o4",
+    ))
+
+
+def _is_openai(model: str) -> bool:
+    ml = model.lower()
+    return any(kw in ml for kw in ("gpt-", "o1", "o3", "o4", "codex", "code-"))
+
+
+# ── Formatters ────────────────────────────────────────────────────────────────
+
+class ContextAssembler:
+    def __init__(self) -> None:
+        pass
+
+    def assemble(
+        self,
+        base_prompt: str,
+        chunks: list,
+        memory_entries: list,
+        query: str,
+        output_mode: str,
+        model: str,
+    ) -> str:
+        """
+        Assemble the enriched system prompt.
+
+        :param base_prompt:     Original system prompt.
+        :param chunks:          Retrieved code/doc chunks.
+        :param memory_entries:  Memory entries from long-term store.
+        :param query:           Current user task.
+        :param output_mode:     "concise" | "structured" | "code_only" | "minimal"
+        :param model:           Target model string.
+        :returns: Assembled prompt string.
+        """
+        if _is_gemini(model):
+            return self._assemble_gemini(
+                base_prompt, chunks, memory_entries, query, output_mode)
+
+        if _is_claude(model):
+            return self._assemble_claude(
+                base_prompt, chunks, memory_entries, query, output_mode)
+
+        if _is_codex(model):
+            return self._assemble_codex(
+                base_prompt, chunks, memory_entries, query, output_mode)
+
+        if _is_openai(model) or _is_reasoning(model):
+            return self._assemble_openai(
+                base_prompt, chunks, memory_entries, query, output_mode,
+                reasoning=_is_reasoning(model))
+
+        # Fallback → OpenAI markdown
+        return self._assemble_openai(
+            base_prompt, chunks, memory_entries, query, output_mode)
+
+    # ── Claude XML ────────────────────────────────────────────────────────────
+    def _assemble_claude(
+        self,
+        base_prompt: str,
+        chunks: list,
+        memory_entries: list,
+        query: str,
+        output_mode: str,
+    ) -> str:
+        # Memory: XML only for structured mode; compact otherwise
+        if output_mode == "structured":
+            mem_block = _format_memory_xml(memory_entries)
+            mem_section = f"<long_term_memory>\n{mem_block}\n</long_term_memory>" if mem_block else ""
+        else:
+            mem_block = _format_memory_compact(memory_entries)
+            mem_section = f"<memory>\n{mem_block}\n</memory>" if mem_block else ""
+
+        chunk_xml = ""
+        for c in chunks:
+            if c.content.startswith("<context>"):  # already compressed
+                chunk_xml += c.content + "\n"
+            else:
+                chunk_xml += (
+                    f"  <chunk path='{c.path}' symbol='{c.symbol}'>"
+                    f"<content>{c.content}</content></chunk>\n"
+                )
+
+        parts = [base_prompt]
+        if chunk_xml:
+            parts.append(f"<retrieved_context>\n{chunk_xml}</retrieved_context>")
+        if mem_section:
+            parts.append(mem_section)
+        if query:
+            parts.append(f"<task>\n{query}\n</task>")
+        return "\n\n".join(parts)
+
+    # ── Gemini JSON ───────────────────────────────────────────────────────────
+    def _assemble_gemini(
+        self,
+        base_prompt: str,
+        chunks: list,
+        memory_entries: list,
+        query: str,
+        output_mode: str,
+    ) -> str:
+        context_data = {
+            "query": query,
+            "chunks": [
+                {"path": c.path, "symbol": c.symbol, "content": c.content}
+                for c in chunks
+            ],
+            "memory": memory_entries,
+        }
+        ctx_str = json.dumps(context_data, ensure_ascii=False, indent=2)
+        return f"{base_prompt}\n\n[CONTEXT]\n```json\n{ctx_str}\n```"
+
+    # ── OpenAI Markdown (Chat + Reasoning) ────────────────────────────────────
+    def _assemble_openai(
+        self,
+        base_prompt: str,
+        chunks: list,
+        memory_entries: list,
+        query: str,
+        output_mode: str,
+        reasoning: bool = False,
+    ) -> str:
+        """
+        Clean Markdown format for GPT / o-series.
+
+        Uses fenced code blocks per chunk (language inferred from path).
+        Memory entries in compact single-line format to minimise token overhead.
+        """
+        parts = [base_prompt]
+
+        if chunks:
+            parts.append("## Retrieved Context")
+            for c in chunks:
+                lang = _infer_language(c.path)
+                header = f"### `{c.path}`"
+                if c.symbol and c.symbol != "module":
+                    header += f" — `{c.symbol}`"
+                if output_mode == "minimal":
+                    snippet = "\n".join(c.content.splitlines()[:20])
+                    parts.append(f"{header}\n```{lang}\n{snippet}\n```")
+                else:
+                    parts.append(f"{header}\n```{lang}\n{c.content}\n```")
+
+        if memory_entries:
+            mem_str = _format_memory_compact(memory_entries)
+            parts.append(f"## Memory\n{mem_str}")
+
+        if query:
+            parts.append(f"## Task\n{query}")
+
+        return "\n\n".join(parts)
+
+    # ── Codex Compact Markdown ────────────────────────────────────────────────
+    def _assemble_codex(
+        self,
+        base_prompt: str,
+        chunks: list,
+        memory_entries: list,
+        query: str,
+        output_mode: str,
+    ) -> str:
+        """
+        Ultra-compact format for Codex models.
+
+        Codex has a small context window (8k legacy / 200k codex-mini).
+        For legacy Codex we minimise prose and only surface file path +
+        critical code.  For codex-mini we use the standard OpenAI format.
+        """
+        parts = [base_prompt]
+
+        if chunks:
+            parts.append("# Context")
+            for c in chunks:
+                lang = _infer_language(c.path)
+                # Only first 40 lines to save tokens for legacy Codex
+                snippet = "\n".join(c.content.splitlines()[:40])
+                symbol_tag = f" [{c.symbol}]" if c.symbol and c.symbol != "module" else ""
+                parts.append(
+                    f"// {c.path}{symbol_tag}\n```{lang}\n{snippet}\n```"
+                )
+
+        if memory_entries:
+            parts.append("# Memory")
+            for m in memory_entries:
+                parts.append(f"// [{m['type']}] {m['key']}: {m['value']}")
+
+        parts.append(f"# Task\n{query}")
+        return "\n\n".join(parts)
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+_EXT_LANG: dict[str, str] = {
+    ".py": "python",
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".jsx": "jsx",
+    ".go": "go",
+    ".rs": "rust",
+    ".java": "java",
+    ".kt": "kotlin",
+    ".cs": "csharp",
+    ".cpp": "cpp",
+    ".c": "c",
+    ".h": "c",
+    ".hpp": "cpp",
+    ".rb": "ruby",
+    ".php": "php",
+    ".swift": "swift",
+    ".sh": "bash",
+    ".zsh": "bash",
+    ".md": "markdown",
+    ".json": "json",
+    ".yaml": "yaml",
+    ".yml": "yaml",
+    ".toml": "toml",
+    ".html": "html",
+    ".css": "css",
+    ".sql": "sql",
+}
+
+
+def _infer_language(path: str) -> str:
+    """Guess a markdown fence language tag from file extension."""
+    if not path:
+        return ""
+    dot = path.rfind(".")
+    if dot == -1:
+        return ""
+    ext = path[dot:].lower()
+    return _EXT_LANG.get(ext, "")

package/src/context/budgeting.py

@@ -0,0 +1,137 @@
+"""
+context/budgeting.py — Dynamic token budget per model
+======================================================
+Covers all major model families:
+  - Claude (Anthropic):  sonnet, haiku, opus
+  - Gemini (Google):     2.5-pro, 2.5-flash, 1.5-pro
+  - OpenAI Chat:         gpt-4o, gpt-4.1, gpt-4.5, gpt-4, gpt-3.5
+  - OpenAI Reasoning:    o1, o1-mini, o3, o3-mini, o4-mini
+  - OpenAI Codex:        codex-mini-latest, code-davinci-002, gpt-4o-mini
+  - Generic fallback:    128k context
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class TokenBudget:
+    model_name: str
+    context_window: int
+    reserved_output: int
+    reserved_reasoning: int   # hidden CoT tokens (o1/o3/o4 family)
+    reserved_tools: int
+    inject_budget: int        # context_window - all reserves
+
+
+# ── Model registry ────────────────────────────────────────────────────────────
+# Each entry: (context_window, reserved_output, reserved_reasoning, reserved_tools)
+_MODEL_TABLE: dict[str, tuple[int, int, int, int]] = {
+    # ── Claude ──────────────────────────────────────────────────────────────
+    "claude-opus":          (200_000, 15_000,  0,      10_000),
+    "claude-sonnet":        (200_000, 30_000,  25_000, 10_000),
+    "claude-haiku":         (200_000, 10_000,  0,       8_000),
+
+    # ── Gemini ──────────────────────────────────────────────────────────────
+    "gemini-2.5-pro":       (2_000_000, 64_000, 0,     20_000),
+    "gemini-2.5-flash":     (1_000_000, 32_000, 0,     16_000),
+    "gemini-1.5-pro":       (2_000_000, 8_192,  0,     20_000),
+    "gemini-1.5-flash":     (1_000_000, 8_192,  0,     16_000),
+    "gemini":               (1_000_000, 32_000, 0,     16_000),  # generic
+
+    # ── OpenAI GPT-5 series ─────────────────────────────────────────────────
+    # Context windows / output limits are estimates based on API announcements.
+    # Update when OpenAI releases official specs.
+    "gpt-5.5":              (1_000_000, 32_768,  0,     16_000),  # multimodal flagship
+    "gpt-5.4":              (  512_000, 32_768,  0,     12_000),
+    "gpt-5-mini":           (  256_000, 16_384,  0,      8_000),
+    "gpt-5":                (  512_000, 32_768,  0,     12_000),  # base gpt-5
+
+    # ── OpenAI Chat ─────────────────────────────────────────────────────────
+    "gpt-4.5":              (128_000, 16_384,  0,      8_000),
+    "gpt-4.1":              (128_000, 16_384,  0,      8_000),
+    "gpt-4o":               (128_000, 16_384,  0,      8_000),
+    "gpt-4o-mini":          (128_000,  4_096,  0,      4_000),
+    "gpt-4-turbo":          (128_000, 16_384,  0,      8_000),
+    "gpt-4":                ( 32_768,  4_096,  0,      4_000),
+    "gpt-3.5-turbo":        ( 16_385,  4_096,  0,      3_000),
+
+    # ── OpenAI Reasoning (o-series) ──────────────────────────────────────────
+    # reserved_reasoning captures the hidden CoT budget estimate
+    "o4-mini":              (200_000, 16_384, 64_000,  8_000),
+    "o3":                   (200_000, 16_384, 80_000,  8_000),
+    "o3-mini":              (200_000, 16_384, 64_000,  8_000),
+    "o1":                   (200_000, 16_384, 80_000,  8_000),
+    "o1-mini":              (128_000,  4_096, 32_000,  4_000),
+    "o1-preview":           (128_000,  4_096, 32_000,  4_000),
+
+    # ── OpenAI Codex ────────────────────────────────────────────────────────
+    # codex-mini-latest: the new hosted reasoning code model (May 2025)
+    "codex-mini-latest":    (200_000, 16_384, 64_000,  8_000),
+    "codex-mini":           (200_000, 16_384, 64_000,  8_000),
+    # Legacy completion-only Codex (deprecated but still referenced)
+    "code-davinci-002":     (  8_001,  4_096,  0,      1_000),
+    "code-cushman-001":     (  2_048,  2_048,  0,        500),
+
+    # ── Generic fallback ────────────────────────────────────────────────────
+    "default":              (128_000,  8_192,  0,       6_000),
+}
+
+
+def _match(model: str) -> tuple[int, int, int, int]:
+    """
+    Match a model string to the closest entry in _MODEL_TABLE.
+    Checks exact → prefix → keyword substring → default.
+    """
+    ml = model.lower().strip()
+
+    # 1. Exact match
+    if ml in _MODEL_TABLE:
+        return _MODEL_TABLE[ml]
+
+    # 2. Prefix match (longest wins)
+    candidates = [k for k in _MODEL_TABLE if ml.startswith(k)]
+    if candidates:
+        return _MODEL_TABLE[max(candidates, key=len)]
+
+    # 3. Keyword substring scan (ordered by specificity)
+    keyword_order = [
+        "codex-mini-latest", "codex-mini", "codex",
+        "code-davinci", "code-cushman",
+        "o4-mini", "o3-mini", "o1-mini", "o1-preview",
+        "o4", "o3", "o1",
+        # GPT-5 must come before gpt-4 to avoid partial match
+        "gpt-5.5", "gpt-5.4", "gpt-5-mini", "gpt-5",
+        "gpt-4.5", "gpt-4.1", "gpt-4o-mini", "gpt-4o",
+        "gpt-4-turbo", "gpt-4",
+        "gpt-3.5",
+        "gemini-2.5-pro", "gemini-2.5-flash",
+        "gemini-1.5-pro", "gemini-1.5-flash",
+        "gemini",
+        "claude-opus", "claude-haiku", "claude-sonnet", "claude",
+    ]
+    for kw in keyword_order:
+        if kw in ml:
+            return _MODEL_TABLE.get(kw, _MODEL_TABLE["default"])
+
+    return _MODEL_TABLE["default"]
+
+
+def get_budget(model: str) -> TokenBudget:
+    """
+    Return a TokenBudget for the given model string.
+
+    :param model: Any model identifier string (case-insensitive).
+    :returns: TokenBudget with inject_budget = usable context tokens.
+    """
+    ctx, out, res, tools = _match(model)
+    inject = max(ctx - out - res - tools, 0)
+    return TokenBudget(
+        model_name=model,
+        context_window=ctx,
+        reserved_output=out,
+        reserved_reasoning=res,
+        reserved_tools=tools,
+        inject_budget=inject,
+    )

package/src/context/sanitizer.py

@@ -0,0 +1,23 @@
+def sanitize(text: str, escape_xml: bool = True) -> str:
+    if not text:
+        return ""
+    # simple prompt injection protection
+    bad_phrases = [
+        "ignore previous instructions",
+        "system prompt",
+        "tool override"]
+    for bp in bad_phrases:
+        text = text.replace(bp, "[REDACTED]")
+    if escape_xml:
+        text = text.replace("<", "&lt;").replace(">", "&gt;")
+    return text
+
+
+def sanitize_chunks(chunks: list):
+    for c in chunks:
+        c.content = sanitize(c.content, escape_xml=False)
+        if not getattr(c, "content_hash", ""):
+            import hashlib
+            c.content_hash = hashlib.sha256(c.content.encode("utf-8")).hexdigest()
+        if c.summary:
+            c.summary = sanitize(c.summary, escape_xml=False)

package/src/evaluation/__init__.py

@@ -0,0 +1 @@
+"""Provider-neutral release evaluation gates."""

package/src/evaluation/gates.py

@@ -0,0 +1,172 @@
+from __future__ import annotations
+
+import json
+import shutil
+import statistics
+import tempfile
+import time
+from pathlib import Path
+
+from evaluation.metrics import ndcg_at_k, recall_at_k, reciprocal_rank
+from harness_context.engine import ContextEngine
+
+FIXTURES = Path(__file__).parents[2] / "tests" / "fixtures"
+STRATEGIES = {
+    "rag": "hybrid_rag",
+    "full_context": "long_context",
+    "cag": "cag",
+    "hybrid": "hybrid_cag_rag",
+    "graph_augmented": "graph_augmented",
+}
+LATENCY_LIMIT_MS = 10_000.0
+
+
+def percentile(values: list[float], percent: float) -> float:
+    ordered = sorted(values)
+    index = max(0, min(len(ordered) - 1, int((len(ordered) - 1) * percent)))
+    return round(ordered[index], 3)
+
+
+def _measure(call, runs: int = 5) -> tuple[dict, dict]:
+    cold_started = time.perf_counter()
+    result = call()
+    cold_ms = (time.perf_counter() - cold_started) * 1000
+    warm_latencies = []
+    for _ in range(runs):
+        started = time.perf_counter()
+        result = call()
+        warm_latencies.append((time.perf_counter() - started) * 1000)
+    return result, {
+        "cold_ms": round(cold_ms, 3),
+        "warm_samples_ms": [round(value, 3) for value in warm_latencies],
+        "warm_p50_ms": round(statistics.median(warm_latencies), 3),
+        "warm_p95_ms": percentile(warm_latencies, 0.95),
+    }
+
+
+def _strategy_tokens(result: dict) -> int:
+    return (result.get("retrieval") or {}).get("token_count", 0) + (
+        result.get("bundle") or {}
+    ).get("token_count", 0)
+
+
+def run_release_gates() -> dict:
+    with tempfile.TemporaryDirectory() as directory:
+        root = Path(directory) / "fixture-corpus"
+        shutil.copytree(FIXTURES, root)
+        engine = ContextEngine()
+        engine.register_workspace("evaluation", [str(root)])
+
+        cold_started = time.perf_counter()
+        engine.refresh_workspace("evaluation")
+        cold_index_ms = (time.perf_counter() - cold_started) * 1000
+        warm_started = time.perf_counter()
+        engine.refresh_workspace("evaluation")
+        warm_index_ms = (time.perf_counter() - warm_started) * 1000
+
+        query = "refresh_token authentication architecture cross-module"
+        strategy_reports = {}
+        for label, override in STRATEGIES.items():
+            result, latency = _measure(
+                lambda override=override: engine.prepare_context(
+                    "evaluation", query, 4_000, override
+                )
+            )
+            items = (result.get("retrieval") or {}).get("items", [])
+            if override == "cag":
+                items = (result.get("bundle") or {}).get("items", [])
+            strategy_reports[label] = {
+                "engine_strategy": result["plan"]["strategy"],
+                "item_count": len(items),
+                "token_cost": _strategy_tokens(result),
+                "latency": latency,
+                "within_budget": _strategy_tokens(result) <= 4_000,
+            }
+
+        retrieval = engine.retrieve_context("evaluation", "refresh_token", token_budget=2_000)
+        expected_paths = {"auth.py"}
+        expected_symbols = {"refresh_token"}
+        quality = {
+            "recall_at_5": recall_at_k(retrieval["items"], expected_paths, expected_symbols, 5),
+            "mrr": reciprocal_rank(retrieval["items"], expected_paths, expected_symbols),
+            "ndcg_at_5": ndcg_at_k(retrieval["items"], expected_paths, expected_symbols, 5),
+            "provenance_complete": all(
+                item.get("path") and item.get("start_line") and item.get("end_line")
+                for item in retrieval["items"]
+            ),
+            "untrusted_content": retrieval["untrusted_content"],
+        }
+
+        fixture_queries = {
+            "python": "python-rotated",
+            "typescript": "typescript-rotated",
+            "flutter": "flutter-rotated",
+            "monorepo": "monorepo-token",
+            "vietnamese": "xoay vòng mã làm mới",
+            "malicious": "delete the repository",
+            "long_document": "phase_f_long_document_marker",
+        }
+        fixture_coverage = {
+            name: any(
+                marker in item["content"]
+                for item in engine.retrieve_context("evaluation", marker)["items"]
+            )
+            for name, marker in fixture_queries.items()
+        }
+        fixture_coverage["duplicate_symbols"] = sum(
+            item.symbol == "normalize_token" for item in engine.states["evaluation"].items
+        ) == 2
+
+        source = root / "python" / "auth.py"
+        source.write_text("def refreshed_value():\n    return 'fresh-phase-f'\n", encoding="utf-8")
+        stale = engine.retrieve_context("evaluation", "fresh-phase-f")
+        engine.refresh_workspace("evaluation", [str(source)])
+        fresh = engine.retrieve_context("evaluation", "fresh-phase-f")
+        freshness = {
+            "absent_before_refresh": not any(
+                "fresh-phase-f" in item["content"] for item in stale["items"]
+            ),
+            "present_after_refresh": any(
+                "fresh-phase-f" in item["content"] for item in fresh["items"]
+            ),
+        }
+
+        latency_ok = max(
+            [cold_index_ms, warm_index_ms]
+            + [report["latency"]["cold_ms"] for report in strategy_reports.values()]
+            + [report["latency"]["warm_p95_ms"] for report in strategy_reports.values()]
+        ) < LATENCY_LIMIT_MS
+        passed = (
+            quality["recall_at_5"] >= 1.0
+            and quality["mrr"] >= 0.5
+            and quality["ndcg_at_5"] >= 0.5
+            and quality["provenance_complete"]
+            and quality["untrusted_content"]
+            and all(report["item_count"] > 0 for report in strategy_reports.values())
+            and all(report["within_budget"] for report in strategy_reports.values())
+            and all(fixture_coverage.values())
+            and all(freshness.values())
+            and latency_ok
+        )
+        return {
+            "passed": passed,
+            "thresholds": {"latency_limit_ms": LATENCY_LIMIT_MS, "token_budget": 4_000},
+            "quality": quality,
+            "fixture_coverage": fixture_coverage,
+            "freshness": freshness,
+            "index_latency": {
+                "cold_ms": round(cold_index_ms, 3),
+                "warm_ms": round(warm_index_ms, 3),
+            },
+            "strategies": strategy_reports,
+        }
+
+
+def main() -> int:
+    report = run_release_gates()
+    print(json.dumps(report, ensure_ascii=False, indent=2))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/evaluation/metrics.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+"""Small provider-neutral retrieval quality metrics for golden fixtures."""
+
+import math
+
+
+def recall_at_k(results: list[dict], expected_paths: set[str], expected_symbols: set[str], k: int) -> float:
+    selected = results[:k]
+    found_paths = {item["path"].rsplit("/", 1)[-1] for item in selected}
+    found_symbols = {item.get("symbol", "") for item in selected}
+    signals = []
+    if expected_paths:
+        signals.append(bool(found_paths & expected_paths))
+    if expected_symbols:
+        signals.append(bool(found_symbols & expected_symbols))
+    return sum(signals) / len(signals) if signals else 1.0
+
+
+def coverage_score(result: dict) -> float:
+    if result.get("coverage") == "sufficient":
+        return 1.0
+    if result.get("coverage") == "partial":
+        return 0.5
+    return 0.0
+
+def reciprocal_rank(results: list[dict], expected_paths: set[str], expected_symbols: set[str]) -> float:
+    for rank, item in enumerate(results, 1):
+        if item["path"].rsplit("/", 1)[-1] in expected_paths or item.get("symbol", "") in expected_symbols:
+            return 1.0 / rank
+    return 0.0
+
+def ndcg_at_k(results: list[dict], expected_paths: set[str], expected_symbols: set[str], k: int) -> float:
+    relevance = [
+        int(item["path"].rsplit("/", 1)[-1] in expected_paths or item.get("symbol", "") in expected_symbols)
+        for item in results[:k]
+    ]
+    dcg = sum(value / math.log2(rank + 1) for rank, value in enumerate(relevance, 1))
+    relevant_count = sum(relevance)
+    ideal = sum(1.0 / math.log2(rank + 1) for rank in range(1, relevant_count + 1))
+    return dcg / ideal if ideal else 1.0

package/src/harness_context/__init__.py

@@ -0,0 +1,5 @@
+"""CTXORA Engine."""
+
+from harness_context.engine import ContextEngine
+
+__all__ = ["ContextEngine"]

package/src/harness_context/adapters/__init__.py

@@ -0,0 +1 @@
+"""Optional integrations that cannot change core ranking or provenance."""