Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
Fix get ans tool (#107)
Swati Ahujab90aca4b6b3e
diff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.pyindex 3f5e76d30..bea98610f 100644--- a/packages/cli/src/repowise/cli/main.py+++ b/packages/cli/src/repowise/cli/main.py@@ -47,3 +47,4 @@ cli.add_command(serve_command)cli.add_command(mcp_command)cli.add_command(reindex_command)cli.add_command(workspace_group)+diff --git a/packages/server/src/repowise/server/mcp_server/tool_answer.py b/packages/server/src/repowise/server/mcp_server/tool_answer.pyindex 492e15d32..c99084719 100644--- a/packages/server/src/repowise/server/mcp_server/tool_answer.py+++ b/packages/server/src/repowise/server/mcp_server/tool_answer.py@@ -48,10 +48,19 @@ from repowise.server.mcp_server._server import mcp# bounded payload._ENRICH_TOP_N_HITS = 2# How many symbols per enriched file. Bounded to keep the context block from-# growing unboundedly on dense files; the limit is sufficient to surface both-# foundational types and a representative function/method.+# growing unboundedly on dense files. We allocate more slots to the top hit+# (where the answer usually lives) and fewer to secondary hits.+_MAX_SYMBOLS_TOP_HIT = 10_MAX_SYMBOLS_PER_HIT = 4+# When a retrieved file contains symbols whose name matches an identifier+# from the question, we promote those to the top of the symbol list for that+# file, pass a longer docstring, and attach a source excerpt so the LLM+# actually sees the method body — not just a stub docstring. Without this,+# specific-method questions get hedged answers even on dominant retrievals.+_MATCHED_SYMBOL_DOC_CHARS = 400+_MATCHED_SYMBOL_SOURCE_LINES = 40+# Sort priority by symbol kind. Classes first because "what does X do" /# "which class inherits from Y" questions resolve at the class level. Then# top-level functions, then methods (which usually only matter once the@@ -71,6 +80,124 @@ _MAX_SYMBOL_DOC_CHARS = 120# (b) synthesis hallucination on tangential top hits._DOMINANCE_RATIO = 1.2_COVERAGE_THRESHOLD = 0.66++# Hedge-phrase markers that indicate the LLM refused to synthesize even though+# retrieval was dominant. When the answer contains any of these, we downgrade+# confidence to "low" and drop the retrieval payload — the hits aren't useful+# to a consumer that has already been told to go read the source, and letting+# them ride through the conversation cache inflates multi-turn cost.+_HEDGE_MARKERS = (+ "do not contain",+ "does not contain",+ "is not contained",+ "are not contained",+ "not contain sufficient",+ "not contain enough",+ "is not covered",+ "not covered in the",+ "not covered by the",+ "you should inspect",+ "you should consult",+ "consult the source",+ "inspect the source",+ "cannot be determined",+ "cannot determine",+ "is not clear",+ "insufficient information",+ "not enough information",+ "without more context",+ "without additional context",+ "didn't surface",+ "did not surface",+ "was not surfaced",+ "was not found in",+)+++def _extract_question_identifiers(question: str) -> set[str]:+ """Pull out Python-looking identifiers the question names explicitly.++ Targets: snake_case (``_local_reachability_density``), CamelCase+ (``NearestCentroid``), dotted paths (``BaseLabelPropagation.fit``).+ Filtered to ≥3 chars, non-stopwords, non-pure-lowercase-English (unless+ they contain an underscore or a digit — otherwise every common word+ matches). The result drives question-aware symbol promotion in+ ``_hydrate_symbols_for_hits``.+ """+ import re++ ids: set[str] = set()+ # Match bare identifiers and dotted paths: first char letter/underscore,+ # rest alnum/underscore, optionally with dotted continuations.+ for tok in re.findall(r"[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*", question):+ # Split dotted paths into both the full thing and the leaf.+ parts = tok.split(".")+ candidates = [tok] + parts+ for c in candidates:+ if len(c) < 3:+ continue+ if c.lower() in _STOPWORDS:+ continue+ # Heuristic: keep if it contains an uppercase letter anywhere+ # (covers CamelCase and sentence-initial capitalised nouns like+ # ``Version`` that are typically class names in Python), a+ # digit, or an underscore. Pure-lowercase English words like+ # ``method`` / ``class`` / ``dtype`` are dropped — they are+ # poor promotion signals and match too broadly.+ has_upper = any(ch.isupper() for ch in c)+ has_under = "_" in c+ has_digit = any(ch.isdigit() for ch in c)+ if has_upper or has_under or has_digit:+ ids.add(c)+ return ids+++def _read_symbol_source(+ repo_root: Path | None,+ file_path: str,+ start_line: int,+ end_line: int,+ max_lines: int = _MATCHED_SYMBOL_SOURCE_LINES,+) -> str | None:+ """Return the literal source body for a symbol, bounded to max_lines.++ The bounded source is the key ingredient for question-matched symbols.+ The LLM was already getting the file-level summary and a truncated+ docstring; what it was missing was the actual code. With 40 lines of+ the method body in front of it, the synthesis step can answer "how+ does X work" without hedging back to "you should inspect the source".+ """+ if repo_root is None or start_line < 1:+ return None+ try:+ abs_path = (repo_root / file_path).resolve()+ try:+ abs_path.relative_to(repo_root.resolve())+ except ValueError:+ return None+ text = abs_path.read_text(encoding="utf-8", errors="replace")+ except OSError:+ return None+ lines = text.splitlines()+ if start_line > len(lines):+ return None+ hi = end_line if end_line and end_line >= start_line else start_line + max_lines+ hi = min(hi, start_line + max_lines, len(lines))+ body = "\n".join(lines[start_line - 1:hi])+ return body+++def _answer_is_hedged(answer_text: str) -> bool:+ """True when the synthesized answer confesses it can't answer.++ Retrieval dominance alone doesn't tell you whether the LLM produced a+ usable answer — the underlying model happily admits insufficiency even+ on a top-scoring hit. Treat an admitted non-answer as low confidence,+ regardless of how dominant retrieval was.+ """+ low = (answer_text or "").lower()+ return any(marker in low for marker in _HEDGE_MARKERS)+# The dominance ratio threshold (top_score / second_score >= 1.2x) separates# reliable retrievals from ambiguous ones. This is a property of BM25-style# retrieval with a coverage re-ranker on top, not of any particular repository;@@ -128,11 +255,20 @@ def _hash_question(question: str) -> str:_log = __import__("logging").getLogger("repowise.mcp.answer")_SYSTEM_PROMPT = (- "You are a code-aware retrieval assistant. Given a developer question and "- "excerpts from a project wiki, answer in 2–5 sentences. Cite the source "- "files by relative path inline like (path/to/file.py). If the excerpts do "- "not contain enough information, say so explicitly and suggest which files "- "the developer should inspect. Never invent file paths."+ "You are a code-aware retrieval assistant. You are given a developer "+ "question plus excerpts from a project wiki — file summaries, symbol "+ "signatures with docstrings, and (for symbols whose name matches the "+ "question) the actual source body. Answer thoroughly and concretely, "+ "citing source files by relative path inline like (path/to/file.py) "+ "and line numbers when you have them. Prefer a structured answer "+ "(headings / bullets / short code block citing the symbol) over a "+ "paragraph when the question asks about mechanism or architecture. "+ "Aim for 150–400 words — enough to cover the asked aspects without "+ "padding. If a [question-match] symbol's source body is provided, "+ "you have enough material to answer — ground in that body. Only "+ "hedge (say 'inspect the source' / 'the excerpts do not contain…') "+ "when there is genuinely no relevant signature, docstring, or source "+ "body in the excerpts. Never invent file paths.")_USER_TEMPLATE = """\@@ -142,8 +278,11 @@ Project wiki excerpts (top {n} retrieval hits):{context}-Answer in 2–5 sentences. Cite file paths inline. If the excerpts are not-sufficient, say so and list the most likely files to inspect.+Answer thoroughly (150–400 words). Cite file paths inline and line+numbers when the excerpt provides them. Prefer a structured layout+(headings, bullets, short code block from the source body) on+mechanism / architecture questions. Only hedge if no signature,+docstring, or source body in the excerpts is relevant."""@@ -245,9 +384,11 @@ def _build_context_block(hits: list[dict], max_chars_per_hit: int = 800) -> str:Each hit includes:* file path + title + retrieval score* file-level summary (Page.summary, capped at max_chars_per_hit)- * up to _MAX_SYMBOLS_PER_HIT WikiSymbol entries (signature + truncated- docstring) — the critical addition that turns get_answer from a- navigator into a real synthesizer for symbol-level questions.+ * per-symbol signature + docstring; for question-matched symbols+ (flagged ``_matched`` by ``_hydrate_symbols_for_hits``) the+ docstring runs to 400 chars and we append up to 40 lines of the+ actual source body as a fenced code block. The source body is+ what lets the LLM answer "how does X work" instead of hedging."""parts = []for i, h in enumerate(hits, start=1):@@ -261,16 +402,22 @@ def _build_context_block(hits: list[dict], max_chars_per_hit: int = 800) -> str:symbols = h.get("symbols") or []if symbols:block.append(" symbols:")- for s in symbols[:_MAX_SYMBOLS_PER_HIT]:+ for s in symbols:sig = s.get("signature") or s.get("name") or ""kind = s.get("kind") or "?"+ matched = bool(s.get("_matched"))doc = (s.get("docstring") or "").strip()+ doc_cap = _MATCHED_SYMBOL_DOC_CHARS if matched else _MAX_SYMBOL_DOC_CHARS+ tag = " [question-match]" if matched else ""+ block.append(f" - [{kind}]{tag} {sig}")if doc:- doc_one_line = " ".join(doc.split())[:_MAX_SYMBOL_DOC_CHARS]- block.append(f" - [{kind}] {sig}")- block.append(f" {doc_one_line}")- else:- block.append(f" - [{kind}] {sig}")+ trimmed = " ".join(doc.split())[:doc_cap]+ block.append(f" docstring: {trimmed}")+ src = s.get("source_excerpt")+ if src:+ block.append(" source:")+ for line in src.splitlines():+ block.append(f" {line}")parts.append("\n".join(block))return "\n\n".join(parts)@@ -319,19 +466,30 @@ def _read_signature_from_source(async def _hydrate_symbols_for_hits(- session, repo_id: str, hits: list[dict], ctx: Any = None,+ session,+ repo_id: str,+ hits: list[dict],+ ctx: Any = None,+ question_ids: set[str] | None = None,) -> None:"""Mutate `hits` in place: attach `symbols` list to top-N file_page hits.- Only the top _ENRICH_TOP_N_HITS hits get enriched — others would just bloat- the cached prompt prefix on follow-up turns without changing the answer.-- For each enriched symbol we ALSO try to recover the real source-line- signature from disk (`_read_signature_from_source`) so base classes,- decorators, and full type annotations reach the LLM. WikiSymbol.signature- strips these at parse time, so the on-disk read is what gives the LLM a- faithful view of the symbol's interface.+ Question-aware promotion: if ``question_ids`` contains identifiers that+ match symbols in the retrieved files, those symbols move to the top of+ their file's symbol list, carry a longer docstring, and get a source+ excerpt (``source_excerpt``). This is the difference between the LLM+ seeing ``class LocalOutlierFactor`` at the file top (and hedging on a+ question about ``_local_reachability_density``) vs. seeing the actual+ method body and answering it.++ Top hit gets ``_MAX_SYMBOLS_TOP_HIT`` slots; secondaries get the smaller+ ``_MAX_SYMBOLS_PER_HIT``. Symbols not matching a question id carry the+ short 120-char docstring; matched symbols carry 400 chars + source body."""+ question_ids = question_ids or set()+ # Case-folded copy for matching.+ qids_lower = {q.lower() for q in question_ids}+# Identify the top file_page hits in retrieval-rank order. `hits` is# already sorted by descending score upstream.enrich_paths: list[str] = []@@ -359,28 +517,60 @@ async def _hydrate_symbols_for_hits(rich_sig = _read_signature_from_source(repo_root, row.file_path, row.start_line)- by_file.setdefault(row.file_path, []).append(- {- "name": row.name,- "kind": row.kind,- # Prefer the real source line (has bases / decorators / types)- # falling back to the stripped WikiSymbol.signature on failure.- "signature": rich_sig or row.signature,- "docstring": row.docstring or "",- "start_line": row.start_line,- }+ # Does the symbol name match any identifier from the question?+ name_lower = (row.name or "").lower()+ qname_lower = (row.qualified_name or "").lower()+ matched = bool(+ qids_lower+ and (+ name_lower in qids_lower+ or qname_lower in qids_lower+ or any(+ q in name_lower or q in qname_lower+ for q in qids_lower+ if len(q) >= 5 # avoid spurious substring matches on short tokens+ )+ ))- # Cap each list to _MAX_SYMBOLS_PER_HIT. Sort by start_line ASC —- # natural document order is the most general default. Kind-priority- # sorting (classes before functions before methods) is available via- # _KIND_PRIORITY but is not applied here, since reordering symbols away- # from source order can mislead the LLM about file structure.- for path, syms in by_file.items():- syms.sort(key=lambda s: s["start_line"])- by_file[path] = syms[:_MAX_SYMBOLS_PER_HIT]- for h in hits:- if h.get("target_path") in by_file:- h["symbols"] = by_file[h["target_path"]]+ entry: dict[str, Any] = {+ "name": row.name,+ "kind": row.kind,+ "signature": rich_sig or row.signature,+ "docstring": row.docstring or "",+ "start_line": row.start_line,+ "end_line": row.end_line,+ "_matched": matched,+ }+ if matched:+ src = _read_symbol_source(+ repo_root, row.file_path, row.start_line, row.end_line+ )+ if src:+ entry["source_excerpt"] = src+ by_file.setdefault(row.file_path, []).append(entry)++ # Sort: matched symbols first (document order within the match group),+ # then unmatched in start_line order. Cap per file — top hit gets more+ # slots than secondary hits.+ for i, h in enumerate(hits):+ path = h.get("target_path")+ if path not in by_file:+ continue+ syms = by_file[path]+ syms.sort(key=lambda s: (not s["_matched"], s["start_line"]))+ cap = _MAX_SYMBOLS_TOP_HIT if i == 0 else _MAX_SYMBOLS_PER_HIT+ # Guarantee at least one matched symbol survives the cap, even if+ # the file has more than `cap` symbols before it.+ kept: list[dict] = [s for s in syms if s["_matched"]][: cap]+ for s in syms:+ if s in kept:+ continue+ if len(kept) >= cap:+ break+ kept.append(s)+ # Sort final slice by start_line for natural reading order.+ kept.sort(key=lambda s: s["start_line"])+ h["symbols"] = keptdef _split_relational(question: str) -> list[str] | None:@@ -566,12 +756,22 @@ async def get_answer(if cached is not None:with contextlib.suppress(Exception):payload = _json.loads(cached.payload_json)- payload["_meta"] = _build_meta(- timing_ms=(time.perf_counter() - t0) * 1000,- cached=True,- hint=_answer_hint(payload.get("confidence", "low"), len(payload.get("retrieval", []))),- )- return payload+ # Bypass-on-hedged: if the cached answer hedged, the retrieval ++ # symbol pipeline has since been upgraded (question-aware symbol+ # promotion, source-body excerpts). Give synthesis another shot+ # with the new context rather than pinning the bad answer.+ if _answer_is_hedged(payload.get("answer", "")):+ _log.info("Bypassing hedged cache entry for re-synthesis")+ else:+ payload["_meta"] = _build_meta(+ timing_ms=(time.perf_counter() - t0) * 1000,+ cached=True,+ hint=_answer_hint(+ payload.get("confidence", "low"),+ len(payload.get("retrieval", [])),+ ),+ )+ return payload# --- Retrieval (FTS) ---------------------------------------------------raw_hits: list[Any] = []@@ -630,14 +830,17 @@ async def get_answer(# Always cap retrieval hits at 5 for the response payload.hits = hits[:5]- # Enrich each file_page hit with its top-N WikiSymbol rows. This is the- # critical fix for symbol-level questions — without it the LLM only sees- # file-level summaries and consistently refuses to identify specific- # classes/functions named in the question.+ # Enrich each file_page hit with its top-N WikiSymbol rows. Question-+ # aware: identifiers extracted from the question promote matching+ # symbols and attach a source-body excerpt — the difference between a+ # hedged answer on a specific-method question and a grounded one.+ question_ids = _extract_question_identifiers(question)if hits:with contextlib.suppress(Exception):async with get_session(ctx.session_factory) as session:- await _hydrate_symbols_for_hits(session, repo_id, hits, ctx)+ await _hydrate_symbols_for_hits(+ session, repo_id, hits, ctx, question_ids=question_ids+ )fallback_targets = [h["target_path"] for h in hits if h.get("target_path")@@ -750,7 +953,7 @@ async def get_answer(provider.generate(system_prompt=_SYSTEM_PROMPT,user_prompt=user_prompt,- max_tokens=512,+ max_tokens=1024,temperature=0.2,),timeout=30.0,@@ -792,20 +995,62 @@ async def get_answer(else:confidence = "medium"- payload = {- "answer": answer_text,- "citations": citations,- "confidence": confidence,- "fallback_targets": fallback_targets,- "retrieval": hits,- }- # When confidence is high, document the signal strength for the consumer.- if confidence == "high":- payload["note"] = (- "High confidence: top retrieval result clearly dominates "- f"(dominance ratio {_ratio:.2f}x). This answer is likely accurate, "- "but verify cited file paths exist before acting on them."+ # Second gate: downgrade when the LLM's own answer admits insufficiency.+ # Retrieval dominance only tells us we indexed the right file; it does+ # not mean the synthesized text is usable. Shipping a hedged answer with+ # confidence="high" misleads the consumer AND drags the full retrieval+ # payload (~10k chars) through the conversation cache for no benefit.+ hedged = _answer_is_hedged(answer_text)+ if hedged:+ confidence = "low"++ # Third gate — identifier-citation gate: when the question explicitly+ # names identifiers (classes / methods / snake_case / CamelCase) and+ # NONE of the top retrieval hits contain any of those identifiers as a+ # hydrated symbol, retrieval may be pointing at plausible-but-wrong+ # files (same module family, similar vocabulary). Downgrade high→medium+ # so the consumer Reads the `fallback_targets`. Only applies when the+ # question actually names identifiers — mechanism-descriptive questions+ # (no symbol names) are unaffected.+ if confidence == "high" and question_ids:+ top_n = [h for h in hits[:_ENRICH_TOP_N_HITS] if h.get("symbols")]+ has_match = any(+ s.get("_matched") for h in top_n for s in (h.get("symbols") or []))+ if not has_match:+ confidence = "medium"++ if hedged:+ # Hedged answers: drop the retrieval payload. The consumer has been+ # told to read the source — the symbol-docstring blob that helped+ # synthesis doesn't help them, and keeping it in the response bloats+ # every follow-up turn's prompt cache.+ payload = {+ "answer": answer_text,+ "citations": citations,+ "confidence": "low",+ "fallback_targets": fallback_targets[:3],+ "retrieval": [],+ "note": (+ "Synthesis hedged: the LLM could not ground the question in "+ "the indexed wiki. Read one of fallback_targets to answer."+ ),+ }+ else:+ payload = {+ "answer": answer_text,+ "citations": citations,+ "confidence": confidence,+ "fallback_targets": fallback_targets,+ "retrieval": hits,+ }+ if confidence == "high":+ payload["note"] = (+ "High confidence: top retrieval result clearly dominates "+ f"(dominance ratio {_ratio:.2f}x) AND the synthesized answer "+ "is direct (no hedging). Cite this answer; do not re-read the "+ "source unless a specific detail is missing."+ )# Persist to cache. Best-effort: cache failures must NEVER block the# response (we already have the answer in hand).