java-codebase-rag 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

java_codebase_rag/lance_optimize.py

@@ -184,6 +184,24 @@ async def optimize_lance_tables(
 
                 if last_exc is None:
                     results[name] = "ok"
+                    # Best-effort FTS index at index time (PR-SEARCH-3) so hybrid
+                    # search works on all tables (java/sql/yaml) without a
+                    # first-query race. Failure is non-fatal — the lazy
+                    # ensure_text_fts_index in search_lancedb.py is the runtime
+                    # fallback — so it never alters the "ok" optimize status; we
+                    # only log the skip when verbose.
+                    try:
+                        from lancedb.index import FTS
+                        await table.create_index("text", config=FTS(), replace=True)
+                    except Exception as exc:
+                        low = str(exc).lower()
+                        if not any(
+                            w in low for w in ("exist", "duplicate", "already", "same name")
+                        ) and not quiet:
+                            print(
+                                f"java-codebase-rag: optimize: {name} fts skipped: {exc}",
+                                file=sys.stderr,
+                            )
                     if not quiet:
                         print(
                             f"java-codebase-rag: optimize: {name} ok",

java_codebase_rag/pipeline.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import asyncio
+import importlib.util
 import os
 import shutil
 import subprocess
@@ -200,6 +201,19 @@ def is_graph_preflight_blocker(proc: subprocess.CompletedProcess[str]) -> bool:
     return bool(proc.returncode in (126, 127) and len(getattr(proc, "args", ()) or ()) <= 1)
 
 
+def vector_stack_installed() -> bool:
+    """True when the optional vector stack (cocoindex/lancedb/sentence-transformers) is importable.
+
+    False on graph-only installs (macOS Intel), where PEP 508 markers exclude the trio.
+    Used to skip vector-only wizard steps (e.g. embedding-model selection) and to preflight
+    branching without spawning cocoindex. Probes all three since they are gated together.
+    """
+    return all(
+        importlib.util.find_spec(m) is not None
+        for m in ("cocoindex", "lancedb", "sentence_transformers")
+    )
+
+
 def _run_cocoindex_update_impl(
     env: dict[str, str],
     *,

{java_codebase_rag-0.8.0.dist-info → java_codebase_rag-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: java-codebase-rag
-Version: 0.8.0
+Version: 0.9.0
 Summary: MCP server for semantic + structural search over Java codebases
 Author: HumanBean17
 License-Expression: MIT
@@ -122,7 +122,7 @@ If you prefer manual configuration, see [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs
 
 ## Tools & commands at a glance
 
-Pick a surface once at install time — `java-codebase-rag install --surface mcp|cli` (default `mcp`). Both surfaces walk the same LanceDB vectors + LadybugDB graph.
+Pick a surface at install time — `java-codebase-rag install --surface mcp|cli` (default `cli`, recommended). Both surfaces walk the same LanceDB vectors + LadybugDB graph. Switch an existing install later with `java-codebase-rag update --surface mcp|cli`.
 
 **MCP surface — five tools over stdio**
 

{java_codebase_rag-0.8.0.dist-info → java_codebase_rag-0.9.0.dist-info}/RECORD

@@ -10,34 +10,34 @@ java_index_v1_common.py,sha256=nF1KrSqboF_RRvWerG9knRRFmWwsrG_CvhgnsoZ8KqA,1154
 java_ontology.py,sha256=ooqr8GucOINpzhdEQ3QzVe5A9GfiR0nUTlySDehn9GA,17129
 ladybug_queries.py,sha256=rVnVEHwWwE4USeX7tICYEl1SSiSxJGnBNe1VX66R3Xk,100531
 mcp_hints.py,sha256=zp-4cnOmbYD0YovmZiLS2oGcvWcWE7n8jKVz4_xifno,42512
-mcp_v2.py,sha256=_pSZrbbImgLOrq8RxBhggoaKHP8oOroUiqh3jz86gG0,66084
+mcp_v2.py,sha256=ABNHiZEEwQ76uPF9E5fQWncJ4JmmgtG3vmt5TDxBGVo,68901
 path_filtering.py,sha256=R--XzI51LXBu5IBKMCnJWbkNr6I5d-SDmltyQQnWco0,17674
 pr_analysis.py,sha256=zrmZZD5yotJtM02Kif6_jgI_oeformOao793akp0N6Y,18394
 resolve_service.py,sha256=tC5FQsGmqhqn0EOexVDlRq5egnzKDTrI7CMzk0nPpG8,25135
-search_lancedb.py,sha256=MKnrRpRQnZNbp5oAFHMBFILoKcQEMaJBouTXakXPSXM,37390
-server.py,sha256=o5TQTO76CEK0SngU5JwGfd8MPn1wyPQODf2zNfbfBTw,35406
+search_lancedb.py,sha256=1sGSZ6H8J9hGcKAwHpzB7F0_in3A_sEtOI5LvlZYIRI,43864
+server.py,sha256=yNpJX_0D1xXY1FHGGBrb4JMOg2THw4_2Ao8YCdijBp0,35944
 java_codebase_rag/__init__.py,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
 java_codebase_rag/_fdlimit.py,sha256=vkwjsPbZfxzZ2DZTPWO5DxtuNlLzOADzIq07iYX7GCU,2465
 java_codebase_rag/_stdio.py,sha256=TDNbpt2EP0_Zd622ihdlKwlMfxkKHWOfgLVcU6TcNbo,1458
-java_codebase_rag/cli.py,sha256=0W14fsod0ZJSfSD15BRE4A16V5f5hy_bZ_A1-jZPO4w,44738
+java_codebase_rag/cli.py,sha256=8WKk-_Zl1Sp7wHX4Y5f3bkIy8hHRH_QWrNuX_3WYTm4,45269
 java_codebase_rag/cli_format.py,sha256=CT7-xdwZ0bMCdP68_UOwkvm-mnLluU3LutlM-mDNk60,1839
 java_codebase_rag/cli_progress.py,sha256=q6Wh97yzLGs1B8UFk_WAKivfQu7Y5RnUUE-T2YHWkIs,3237
 java_codebase_rag/config.py,sha256=Yl7Nf0O_ZOZTPtyPMap83jRM7qNhWwfbVJTKSEdERi4,24916
-java_codebase_rag/installer.py,sha256=NgOdsML1BOmqIoIXyoDDLg4r3JxQ9hqqYGCwVW6FHQs,67582
-java_codebase_rag/jrag.py,sha256=K1_QNMO2mRWSeatJIEJ0esVZztraiA8VB6Pkphg6ITU,187655
-java_codebase_rag/jrag_envelope.py,sha256=mvAgoZm5XIpmV-J1ntlBzwJW62Fs71RGcpxFQa-l0lc,47484
+java_codebase_rag/installer.py,sha256=c-_tR1Ct_O3yhmruFRnDoM1Wilz-igD9qdkDPsNqLMI,79934
+java_codebase_rag/jrag.py,sha256=cVUWrKOtkwe2r4u1nknzmrMQMy16bdt1n-dZQpiSFWs,191811
+java_codebase_rag/jrag_envelope.py,sha256=5jD3p2O-p9acAKHqoif5FFoqgP7Q2ziCuKSiPCHoywc,47505
 java_codebase_rag/jrag_hints.py,sha256=k2PFE4s3lZgBYHMdZcTjx1-w28nfQcBtQEVsSxI_DvE,9262
-java_codebase_rag/jrag_render.py,sha256=tIKdOQOO1-uimS2MBxrLma5tjiid0nG0OcaPRgR7uEk,31611
-java_codebase_rag/lance_optimize.py,sha256=25Rwj7HNO8F-35MxhFK6naqgbjd3H-T0zKb3pXB4H0s,9268
-java_codebase_rag/pipeline.py,sha256=4o5SdvHC4z4PTtzkjnhmkolODXnlibndCorI6gDUyPI,15903
+java_codebase_rag/jrag_render.py,sha256=1nUyamL-MOOXDlKvssp-LsBgEtznUnGj_cPteSwuS90,31953
+java_codebase_rag/lance_optimize.py,sha256=_90eajcIpGUNm3GWtx6AYDERNHaMsaMZs7zu2KqNPEU,10347
+java_codebase_rag/pipeline.py,sha256=TkHb7DybFlpHje30aYbuFt5jWFSJBdCQ-7hc4jFaNhI,16481
 java_codebase_rag/progress.py,sha256=2IxdMALDM0wAQCyJrrfZ975zM_85C-4BfHxf4AtYifE,23212
-java_codebase_rag/install_data/agents/explorer-rag-cli.md,sha256=Ahjq39Kgyydgr_Vno-gFj02DZQQX-a65AvzEl1K1nss,12923
-java_codebase_rag/install_data/agents/explorer-rag-enhanced.md,sha256=O8twSh5aOVe2s_8HdwFKBTl_VxgwiVPm2YlyQAPXhh0,14614
-java_codebase_rag/install_data/skills/explore-codebase/SKILL.md,sha256=7SQSC0sHD_2F64QdEiwgSyVWHQXLxsOBxWWqJpIGPbk,12485
-java_codebase_rag/install_data/skills/explore-codebase-cli/SKILL.md,sha256=qSGsC90LpjTZSUV6v3YtgFSHVb_hd4S1QlOedKm2NnU,14319
-java_codebase_rag-0.8.0.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
-java_codebase_rag-0.8.0.dist-info/METADATA,sha256=VnPaESLzcc1V_ltQw6U1Ehyk6HV1TbTZjgGphLO6tWQ,19996
-java_codebase_rag-0.8.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-java_codebase_rag-0.8.0.dist-info/entry_points.txt,sha256=cj3QTc11UYVQnj9T3orc4daiIGaCYrXP149vKbH2R4U,168
-java_codebase_rag-0.8.0.dist-info/top_level.txt,sha256=8vC-VN3cMwz5vhkSTaeJ1a1bDeqLWEfrTks1CvEvIg0,273
-java_codebase_rag-0.8.0.dist-info/RECORD,,
+java_codebase_rag/install_data/agents/explorer-rag-cli.md,sha256=mMij_BIQM4agaYhGVYjC-fQSe3We1HFeBvc5JBjJj6A,10071
+java_codebase_rag/install_data/agents/explorer-rag-enhanced.md,sha256=gZsNFbuK0lSnOIlplbbS_muz2ozokJqvFUv65QM0NDM,10406
+java_codebase_rag/install_data/skills/explore-codebase/SKILL.md,sha256=A-v2dueVnxwBzBlxoRjZ2zOJk8DranLQ1TElwn94h0s,11529
+java_codebase_rag/install_data/skills/explore-codebase-cli/SKILL.md,sha256=V5gIKKGkgk2KlAFf9JqPareQDMt1iQOI7cwhfOqJL1c,11348
+java_codebase_rag-0.9.0.dist-info/licenses/LICENSE,sha256=gxvtiHtuviR_q8ZAjWw-QTcF3DyPzg6ZY-lQrr8OPpw,1068
+java_codebase_rag-0.9.0.dist-info/METADATA,sha256=pIQfvYY6sWdmq-PIXm0vOUzNobTUtW14Z-Zp-53qaf8,20088
+java_codebase_rag-0.9.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+java_codebase_rag-0.9.0.dist-info/entry_points.txt,sha256=cj3QTc11UYVQnj9T3orc4daiIGaCYrXP149vKbH2R4U,168
+java_codebase_rag-0.9.0.dist-info/top_level.txt,sha256=8vC-VN3cMwz5vhkSTaeJ1a1bDeqLWEfrTks1CvEvIg0,273
+java_codebase_rag-0.9.0.dist-info/RECORD,,

mcp_v2.py

@@ -466,6 +466,8 @@ class SearchHit(BaseModel):
     role: str | None = None
     filename: str | None = None
     start_line: int | None = None
+    score_components: dict[str, float] | None = None
+    chunks: int | None = None
 
 
 # NodeRef is now defined in graph_types.py and imported above
@@ -583,7 +585,7 @@ def _chunk_id_from_row(row: dict[str, Any]) -> str:
     return f"{filename}:{sb}:{eb}"
 
 
-def _row_to_search_hit(row: dict[str, Any]) -> SearchHit:
+def _row_to_search_hit(row: dict[str, Any], explain: bool = False) -> SearchHit:
     score = float(row.get("_rrf_score") or row.get("_score") or 0.0)
     filename = str(row.get("filename") or "") or None
     start_line: int | None = None
@@ -595,6 +597,8 @@ def _row_to_search_hit(row: dict[str, Any]) -> SearchHit:
                 start_line = int(ln)
             except (TypeError, ValueError):
                 start_line = None
+    chunks = row.get("_chunks_collapsed")
+    chunks_int = int(chunks) if chunks is not None and int(chunks) >= 2 else None
     return SearchHit(
         chunk_id=_chunk_id_from_row(row),
         symbol_id=_chunk_to_symbol_id(row),
@@ -606,6 +610,8 @@ def _row_to_search_hit(row: dict[str, Any]) -> SearchHit:
         role=str(row.get("role")) if row.get("role") else None,
         filename=filename,
         start_line=start_line,
+        score_components=row.get("_score_components") if explain else None,
+        chunks=chunks_int,
     )
 
 
@@ -820,7 +826,9 @@ def search_v2(
     offset: int = 0,
     path_contains: str | None = None,
     filter: NodeFilter | dict[str, Any] | str | None = None,
+    explain: bool = False,
     graph: LadybugGraph | None = None,
+    dedup: bool = True,
 ) -> SearchOutput:
     try:
         raw_filter = _coerce_filter(filter)
@@ -852,6 +860,17 @@ def search_v2(
                 limit=None,
                 offset=None,
             )
+        # hybrid + table='all' is unsupported (hybrid fuses vector+FTS on ONE
+        # table); fail fast with a clean envelope BEFORE loading the embedding
+        # model. run_search also guards this — this is the user-facing fast path.
+        if hybrid and table == "all":
+            return SearchOutput(
+                success=False,
+                message="hybrid search requires a single table; use java, sql, or yaml (not all)",
+                advisories=[],
+                limit=None,
+                offset=None,
+            )
         model_name = resolved_sbert_model_for_process_env(SBERT_MODEL)
         device = os.environ.get("SBERT_DEVICE") or None
         model = _get_sentence_transformer(model_name, device)
@@ -862,29 +881,66 @@ def search_v2(
         if not uri.startswith(("s3://", "gs://", "az://")) and uri_path.exists():
             uri = str(uri_path.resolve())
         table_keys = list(TABLES) if table == "all" else [table]
-        rows = run_search(
-            query,
-            uri=uri,
-            table_keys=table_keys,
-            hybrid=hybrid,
-            limit=limit,
-            offset=offset,
-            path_substring=path_contains,
-            model_name=model_name,
-            device=device,
-            model=model,
-            # Push the NodeFilter structural predicates into the LanceDB query so
-            # they apply BEFORE pagination (issue #353) — previously they were only
-            # a post-filter on the already-paginated page, which could shrink or
-            # empty filtered pages even when many matches existed deeper in the
-            # ranking. _node_matches_filter below still re-checks every row (it
-            # covers the non-pushdownable fields and is the contract guarantee).
-            role=nf.role if nf else None,
-            module=nf.module if nf else None,
-            microservice=nf.microservice if nf else None,
-            capability=nf.capability if nf else None,
-            exclude_roles=nf.exclude_roles if nf else None,
-        )
+
+        # Graceful fallback: if hybrid=True and FTS index is missing (old index),
+        # retry with hybrid=False and return vector-only results with an advisory.
+        advisories: list[str] = []
+        try:
+            rows = run_search(
+                query,
+                uri=uri,
+                table_keys=table_keys,
+                hybrid=hybrid,
+                limit=limit,
+                offset=offset,
+                path_substring=path_contains,
+                model_name=model_name,
+                device=device,
+                model=model,
+                # Push the NodeFilter structural predicates into the LanceDB query so
+                # they apply BEFORE pagination (issue #353) — previously they were only
+                # a post-filter on the already-paginated page, which could shrink or
+                # empty filtered pages even when many matches existed deeper in the
+                # ranking. _node_matches_filter below still re-checks every row (it
+                # covers the non-pushdownable fields and is the contract guarantee).
+                role=nf.role if nf else None,
+                module=nf.module if nf else None,
+                microservice=nf.microservice if nf else None,
+                capability=nf.capability if nf else None,
+                exclude_roles=nf.exclude_roles if nf else None,
+                dedup_by_fqn=dedup,
+            )
+        except Exception as exc:
+            # Check if this is a missing-FTS error (old index built before PR-SEARCH-3)
+            exc_text = str(exc).lower()
+            is_fts_missing = "full text search" in exc_text or "inverted index" in exc_text
+            if hybrid and is_fts_missing:
+                # Retry with vector-only search
+                rows = run_search(
+                    query,
+                    uri=uri,
+                    table_keys=table_keys,
+                    hybrid=False,  # Fallback to vector-only
+                    limit=limit,
+                    offset=offset,
+                    path_substring=path_contains,
+                    model_name=model_name,
+                    device=device,
+                    model=model,
+                    role=nf.role if nf else None,
+                    module=nf.module if nf else None,
+                    microservice=nf.microservice if nf else None,
+                    capability=nf.capability if nf else None,
+                    exclude_roles=nf.exclude_roles if nf else None,
+                    dedup_by_fqn=dedup,
+                )
+                advisories.append(
+                    f"hybrid unavailable on table '{table}' (FTS index missing on this index built before "
+                    f"PR-SEARCH-3); fell back to vector-only — reindex to enable hybrid"
+                )
+            else:
+                # Non-FTS error: surface as structured failure
+                raise
         hits: list[SearchHit] = []
         for row in rows:
             if path_contains and path_contains not in str(row.get("filename") or ""):
@@ -893,7 +949,7 @@ def search_v2(
                 row_kind = "symbol"
                 if not _node_matches_filter(row_kind, row, nf):
                     continue
-            hits.append(_row_to_search_hit(row))
+            hits.append(_row_to_search_hit(row, explain=explain))
         hint_payload = {
             "success": True,
             "results": [h.model_dump() for h in hits],
@@ -906,7 +962,7 @@ def search_v2(
             results=hits,
             limit=limit,
             offset=offset,
-            advisories=raw_advisories,
+            advisories=advisories + raw_advisories,  # Merge fallback + hints advisories
             hints_structured=_to_structured_hints(raw_struct),
         )
     except Exception as exc:

search_lancedb.py

@@ -41,6 +41,11 @@ JAVA_ENRICHED_COLUMNS: tuple[str, ...] = (
     "capabilities",
 )
 
+# Over-fetch multiplier for dedup: fetch 4x to absorb per-FQN chunk multiplicity
+# so that after collapsing by primary_type_fqn, a page stays full and the +1
+# truncation sentinel survives. The formula: need = max((limit + offset) * 4, limit + offset + 1)
+DEDUP_OVERFETCH = 4
+
 VECTOR_COLUMN = "embedding"
 _FTS_READY: set[tuple[str, str]] = set()
 _FTS_LOCK = threading.Lock()
@@ -201,6 +206,14 @@ _ROLE_SCORE_WEIGHTS: dict[str, float] = {
     "DTO": -0.08,
 }
 
+# Theoretical maximum for hybrid composite score (used for display normalization).
+# Hybrid sort metric: raw_rrf * (import_factor if import_heavy else 1)
+#                   + role_weight + symbol_bonus
+# where raw_rrf ≤ 2/(k+1) for 2-list RRF, role_weight ≤ max(_ROLE_SCORE_WEIGHTS),
+# and symbol_bonus ≤ _SYMBOL_MATCH_BONUS_CAP + _TYPE_MATCH_BONUS_CAP + _ACTION_VERB_BONUS.
+# The import factor is ≤ 1, so we use the raw max (2/61).
+_HYBRID_SCORE_MAX = (2.0 / 61.0) + max(_ROLE_SCORE_WEIGHTS.values()) + _SYMBOL_MATCH_BONUS_CAP + _TYPE_MATCH_BONUS_CAP + _ACTION_VERB_BONUS
+
 
 def _query_tokens(query: str) -> set[str]:
     """Lowercased alpha-only tokens from the query, minus stopwords, len >= 3.
@@ -353,7 +366,7 @@ def _hybrid_sort_key(r: dict) -> float:
     comps["hybrid_rrf"] = s
     if r.get("_hints", {}).get("import_heavy"):
         s *= _IMPORT_HYBRID_SCORE_FACTOR
-        comps["import_penalty"] = _IMPORT_HYBRID_SCORE_FACTOR
+        comps["import_penalty"] = 1.0 - _IMPORT_HYBRID_SCORE_FACTOR
     s += _role_weight(r)
     s += float(comps.get("symbol_bonus", 0.0))
     return -s
@@ -376,7 +389,8 @@ def explain_score_components(
         comps = {}
     parts: list[str] = []
     if hybrid:
-        rrf = comps.get("hybrid_rrf")
+        # Prefer rrf_raw (added by PR-SEARCH-1a) for explanation
+        rrf = comps.get("rrf_raw") or comps.get("hybrid_rrf")
         if rrf is not None:
             parts.append(f"rrf={float(rrf):.3f}")
     else:
@@ -403,6 +417,46 @@ def l2_distance_to_score(distance: float) -> float:
     return 1.0 - distance * distance / 2.0
 
 
+def _effective_distance(comps: dict[str, float]) -> float:
+    """Compute the adjusted distance used for sorting.
+
+    Matches _vector_sort_key logic: distance + import_penalty - role_weight - symbol_bonus.
+    """
+    d = comps.get("distance", 0.0)
+    d += comps.get("import_penalty", 0.0)
+    d -= comps.get("role_weight", 0.0)
+    d -= comps.get("symbol_bonus", 0.0)
+    return d
+
+
+def _clamp01(x: float) -> float:
+    """Clamp a value to the [0.0, 1.0] range."""
+    if x < 0.0:
+        return 0.0
+    if x > 1.0:
+        return 1.0
+    return x
+
+
+def _hybrid_post_sort_normalization(rows: list[dict]) -> None:
+    """Set honest displayed scores for hybrid search after sorting.
+
+    Reconstructs the composite score (raw_rrf * import_factor + role_weight + symbol_bonus)
+    and normalizes by _HYBRID_SCORE_MAX to ensure rank-monotonicity.
+
+    Mutates rows in-place, replacing _score with the normalized value.
+    """
+    for r in rows:
+        comps = r.setdefault("_score_components", {})
+        raw = comps.get("hybrid_rrf", 0.0)
+        comps["rrf_raw"] = raw  # preserve raw RRF for --explain. NOTE: when graph_expand + hybrid combine (Phase 2), _rrf_merge below overwrites this with graph-RRF, so --explain would show graph-RRF not hybrid-RRF.
+        s = raw
+        if r.get("_hints", {}).get("import_heavy"):
+            s *= _IMPORT_HYBRID_SCORE_FACTOR
+        s += comps.get("role_weight", 0.0) + comps.get("symbol_bonus", 0.0)
+        r["_score"] = _clamp01(s / _HYBRID_SCORE_MAX)
+
+
 def _escape_like_fragment(s: str) -> str:
     return s.replace("'", "''")
 
@@ -790,9 +844,72 @@ def _rrf_merge(
                 existing["_rrf_score"] = float(existing.get("_rrf_score", 0.0)) + contribution
     merged = list(pool.values())
     merged.sort(key=lambda r: -float(r.get("_rrf_score", 0.0)))
+    # Normalize displayed _rrf_score to [0,1] by theoretical max
+    # RRF max = Σ weight·1/(k+rank+1); theoretical max when all rows are rank 0
+    # with weight 1.0 = num_lists / (k + 1)
+    num_lists = len(lists)
+    max_rrf = num_lists / (k + 1)
+    for r in merged:
+        raw_score = float(r.get("_rrf_score", 0.0))
+        comps = r.setdefault("_score_components", {})
+        comps["rrf_raw"] = raw_score
+        r["_rrf_score"] = _clamp01(raw_score / max_rrf)
     return merged
 
 
+def _dedup_by_fqn(rows: list[dict], dedup_by_fqn: bool = True) -> list[dict]:
+    """Deduplicate rows by primary_type_fqn (java table only).
+
+    When dedup_by_fqn is True, collapses multiple chunks of the same
+    primary_type_fqn into one row (first-seen-wins, since rows are pre-sorted
+    so the first is the best chunk). Each survivor gets a _chunks_collapsed
+    field (>=1) counting how many rows were collapsed into it.
+
+    Rows without primary_type_fqn (sql/yaml tables) get a unique __id:<id>
+    key so they pass through unchanged (each row is unique).
+
+    When dedup_by_fqn is False, returns rows unchanged (regression guard).
+    """
+    if not dedup_by_fqn:
+        # Non-dedup path: return unchanged, byte-identical to prior behavior
+        return rows
+
+    deduped: list[dict] = []
+    seen_keys: dict[str, dict] = {}
+    collapsed_counts: dict[str, int] = {}
+
+    for row in rows:
+        # Build dedup key: primary_type_fqn for java rows, unique __id:<id> for sql/yaml
+        fqn = row.get("primary_type_fqn")
+        if fqn:
+            key = str(fqn)
+        else:
+            # sql/yaml rows have no primary_type_fqn → unique key per row
+            row_id = row.get("id") or id(row)
+            key = f"__id:{row_id}"
+
+        if key not in seen_keys:
+            # First occurrence: keep it
+            seen_keys[key] = row
+            collapsed_counts[key] = 1
+            deduped.append(row)
+        else:
+            # Duplicate: increment collapse count, discard this row
+            collapsed_counts[key] += 1
+
+    # Annotate each survivor with _chunks_collapsed
+    for row in deduped:
+        fqn = row.get("primary_type_fqn")
+        if fqn:
+            key = str(fqn)
+        else:
+            row_id = row.get("id") or id(row)
+            key = f"__id:{row_id}"
+        row["_chunks_collapsed"] = collapsed_counts[key]
+
+    return deduped
+
+
 def run_search(
     query: str,
     *,
@@ -819,6 +936,7 @@ def run_search(
     exclude_roles: list[str] | None = None,
     capability: str | None = None,
     capability_in: list[str] | None = None,
+    dedup_by_fqn: bool = False,
 ) -> list[dict]:
     effective_hybrid = hybrid
     effective_fts = fts_text
@@ -852,7 +970,16 @@ def run_search(
     fts_for_hybrid = effective_fts if effective_fts is not None else query
 
     db = lancedb.connect(uri)
-    need = max(limit + offset, 1)
+    if dedup_by_fqn:
+        # Over-fetch to absorb per-FQN chunk multiplicity: fetch 4x so that
+        # after collapsing, the page stays full and the +1 truncation sentinel survives.
+        # The 4× factor assumes typical per-FQN chunk multiplicity; a single type with
+        # many high-ranking chunks (e.g. generated/God classes) could starve the page or
+        # make the +1 truncation sentinel unreliable; Phase 1 may revisit adaptive over-fetch (plan risk #1).
+        need = max((limit + offset) * DEDUP_OVERFETCH, limit + offset + 1)
+    else:
+        # Non-dedup path: exact fetch as before
+        need = max(limit + offset, 1)
 
     extra_java = _build_extra_predicates(
         columns=_table_columns(uri, TABLES["java"], db),
@@ -887,8 +1014,15 @@ def run_search(
         _apply_symbol_bonus(rows, query_toks)
         if effective_hybrid:
             rows.sort(key=_hybrid_sort_key)
+            # Hybrid: set honest displayed score from composite sort metric, clamped to [0,1]
+            _hybrid_post_sort_normalization(rows)
         else:
             rows.sort(key=_vector_sort_key)
+            # Vector: set honest displayed score from adjusted distance, clamped to [0,1]
+            for r in rows:
+                comps = r.setdefault("_score_components", {})
+                effective_dist = _effective_distance(comps)
+                r["_score"] = _clamp01(l2_distance_to_score(effective_dist))
 
         if graph_expand and key == "java" and expand_depth > 0:
             rows = _graph_expand_merge(
@@ -902,6 +1036,9 @@ def run_search(
                 ladybug_path=ladybug_path,
             )
 
+        # Dedup by primary_type_fqn after all sorting/merging, before windowing
+        rows = _dedup_by_fqn(rows, dedup_by_fqn=dedup_by_fqn)
+
         window = rows[offset : offset + limit]
         if context_neighbors > 0 and key == "java":
             _attach_neighbor_context(window, db=db, neighbors=context_neighbors, uri=uri)
@@ -931,6 +1068,15 @@ def run_search(
             r["_skip_role_weight"] = True
     _apply_symbol_bonus(merged, query_toks)
     merged.sort(key=_vector_sort_key)
+    # Vector: set honest displayed score from adjusted distance, clamped to [0,1]
+    for r in merged:
+        comps = r.setdefault("_score_components", {})
+        effective_dist = _effective_distance(comps)
+        r["_score"] = _clamp01(l2_distance_to_score(effective_dist))
+
+    # Dedup by primary_type_fqn after all sorting/merging, before windowing
+    merged = _dedup_by_fqn(merged, dedup_by_fqn=dedup_by_fqn)
+
     window = merged[offset : offset + limit]
     if context_neighbors > 0:
         _attach_neighbor_context(window, db=db, neighbors=context_neighbors, uri=uri)

server.py

@@ -512,6 +512,7 @@ def create_mcp_server() -> FastMCP:
             "structured DSL inside `query`; structured predicates belong in `find`. "
             "For identifier-shaped lookups (FQN, id, route/client identifiers, …), use `resolve` first; "
             "use `search` for natural-language or ranked fuzzy discovery. "
+            "Set `explain=true` to include score breakdown per hit. "
             "Successful responses echo `limit`/`offset`."
         ),
     )
@@ -538,6 +539,14 @@ def create_mcp_server() -> FastMCP:
                 "predicate. Unknown keys or populated fields not applicable to symbols return success=false."
             ),
         ),
+        explain: bool = Field(
+            default=False,
+            description="If true, include score_components in each SearchHit (breakdown of distance/rrf, role, symbol, import_penalty).",
+        ),
+        chunks: bool = Field(
+            default=False,
+            description="If true, show every chunk (default collapses to one row per symbol/type).",
+        ),
     ) -> mcp_v2.SearchOutput:
         scoped_filter = _scope_manager.apply_auto_scope(filter) if _scope_manager else filter
         return await asyncio.to_thread(
@@ -549,7 +558,9 @@ def create_mcp_server() -> FastMCP:
             offset,
             path_contains,
             scoped_filter,
+            explain,
             None,
+            not chunks,  # dedup=True by default; chunks=True opts out
         )
 
     @mcp.tool(