flash-context 0.3.0__tar.gz → 0.3.2__tar.gz

{flash_context-0.3.0 → flash_context-0.3.2}/CHANGELOG.md

@@ -4,6 +4,50 @@ User-visible changes and migration instructions for each release.
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-11-01
+
+### Fixed
+
+- Require whole, case-sensitive query tokens inside exact-symbol citations,
+  including read-derived fallback evidence. Reject plausible-home file citations
+  without matching source text and retain scoped Python preflight diagnostics.
+- Report `query symbol not found in verified evidence` when symbol lookups finish
+  without accepted evidence, rather than relying on generic termination warnings.
+
+### Migration
+
+- Exact-symbol queries may now return `NO_CITATIONS_FOUND` with empty citations
+  and snippets where previous versions returned unrelated files. Token presence
+  is lexical evidence, not proof of a definition or semantic relevance. Public
+  schemas, configuration, and CLI exit semantics are unchanged.
+
+### Changed
+
+- Condense the README overview and move safety and evidence-validation details
+  to the architecture documentation.
+
+## [0.3.1] - 2026-11-01
+
+### Fixed
+
+- Report the flash-context package version during MCP initialization instead of
+  the MCP SDK version.
+- Reuse repeated tool observations without discarding fresh searches in the same
+  batch; execute same-turn duplicates only once and stop all-repeat stalls.
+- Continue implementation searches after documentation-only citations within the
+  existing turn budget. Documentation-only fallbacks retain citations and snippets
+  with explicit incomplete-result metadata and warnings.
+
+### Changed
+
+- Describe deterministic lookup and delegated model search together in the README.
+
+### Migration
+
+- Implementation questions may use additional turns before returning documentation
+  evidence. These fallbacks set `truncated: true`; partial cited CLI results still
+  exit 0. Budgets, configuration keys, and result schemas are unchanged.
+
 ## [0.3.0] - 2026-11-01
 
 ### Fixed

{flash_context-0.3.0 → flash_context-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flash-context
-Version: 0.3.0
+Version: 0.3.2
 Summary: Read-only context exploration and retrieval for AI agents, starting with codebases and repositories.
 Project-URL: Repository, https://github.com/zyf0717/flash-context
 Project-URL: Issues, https://github.com/zyf0717/flash-context/issues
@@ -28,20 +28,16 @@ Description-Content-Type: text/markdown
 [![Python versions](https://img.shields.io/pypi/pyversions/flash-context)](https://pypi.org/project/flash-context/)
 [![License](https://img.shields.io/pypi/l/flash-context)](LICENSE)
 
-Read-only context exploration and retrieval for AI agents,
-available as a Python CLI and Model Context Protocol (MCP) server.
+A lightweight, model-agnostic repository explorer for AI agents, available as a
+Python CLI and Model Context Protocol (MCP) server. It combines deterministic
+lookup with search and reading delegated to a utility model through an
+OpenAI-compatible endpoint, returning compact, validated file-line citations and
+source snippets.
 
-Delegate recursive, repetitive file search and reading to a utility model
-behind an OpenAI-compatible endpoint. The calling agent receives validated
-file-line citations and source snippets to use in its main task.
-
-Codebases and repositories are the current focus; the same tools explore
-documentation, configuration, and other local text files. CLI and MCP share one
-exploration core with read-only tools, path safety, and resource limits.
-Scans and regex execution are bounded; partial results report truncation.
-Citation validation checks safe paths and existing line coverage, not semantic
-relevance or minimal ranges. Citation precision depends on the explorer model.
-Optional metadata-only trajectory logs must stay outside the inspected repository.
+CLI and MCP share a read-only core for exploring code, documentation,
+configuration, and other local text files with path safety and resource limits.
+See [safety and evidence validation](docs/architecture.md#safety-and-evidence-validation)
+for details and limitations.
 
 Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
 on separating repository exploration from task solving, using specialized models

{flash_context-0.3.0 → flash_context-0.3.2}/README.md

@@ -5,20 +5,16 @@
 [![Python versions](https://img.shields.io/pypi/pyversions/flash-context)](https://pypi.org/project/flash-context/)
 [![License](https://img.shields.io/pypi/l/flash-context)](LICENSE)
 
-Read-only context exploration and retrieval for AI agents,
-available as a Python CLI and Model Context Protocol (MCP) server.
-
-Delegate recursive, repetitive file search and reading to a utility model
-behind an OpenAI-compatible endpoint. The calling agent receives validated
-file-line citations and source snippets to use in its main task.
-
-Codebases and repositories are the current focus; the same tools explore
-documentation, configuration, and other local text files. CLI and MCP share one
-exploration core with read-only tools, path safety, and resource limits.
-Scans and regex execution are bounded; partial results report truncation.
-Citation validation checks safe paths and existing line coverage, not semantic
-relevance or minimal ranges. Citation precision depends on the explorer model.
-Optional metadata-only trajectory logs must stay outside the inspected repository.
+A lightweight, model-agnostic repository explorer for AI agents, available as a
+Python CLI and Model Context Protocol (MCP) server. It combines deterministic
+lookup with search and reading delegated to a utility model through an
+OpenAI-compatible endpoint, returning compact, validated file-line citations and
+source snippets.
+
+CLI and MCP share a read-only core for exploring code, documentation,
+configuration, and other local text files with path safety and resource limits.
+See [safety and evidence validation](docs/architecture.md#safety-and-evidence-validation)
+for details and limitations.
 
 Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
 on separating repository exploration from task solving, using specialized models

{flash_context-0.3.0 → flash_context-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flash-context"
-version = "0.3.0"
+version = "0.3.2"
 description = "Read-only context exploration and retrieval for AI agents, starting with codebases and repositories."
 readme = "README.md"
 requires-python = ">=3.13"

{flash_context-0.3.0 → flash_context-0.3.2}/src/flash_context/agent.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import json
 import re
 from concurrent.futures import ThreadPoolExecutor
-from dataclasses import dataclass, field
+from dataclasses import dataclass, field, replace
 from pathlib import Path
 from typing import Any, Literal, cast
 
@@ -62,11 +62,21 @@ EXACT_TEXT_RE = re.compile(r"[`'\"](?P<target>[^`'\"]{1,120})[`'\"]")
 TOKEN_RE = re.compile(r"\b(?P<token>[A-Za-z_][A-Za-z0-9_]*)\b")
 
 
+@dataclass(frozen=True, slots=True)
+class _DefinitionScan:
+    citations: tuple[Citation, ...]
+    status: Literal["unique", "missing", "ambiguous", "incomplete"]
+    warnings: tuple[str, ...]
+
+
 @dataclass(slots=True)
 class EvidenceState:
     reads: list[ToolObservation] = field(default_factory=list)
     citations: list[Citation] = field(default_factory=list)
-    seen_tool_calls: set[str] = field(default_factory=set)
+    observations: dict[str, ToolObservation] = field(default_factory=dict)
+    prefer_source: bool = False
+    symbol: str | None = None
+    definition_scan: _DefinitionScan | None = None
 
 
 def explore(
@@ -78,10 +88,15 @@ def explore(
     request.validate()
     repo_root = request.repo_root.resolve()
     validate_trajectory_dir(settings.traj_dir, repo_root)
+    evidence = EvidenceState(
+        prefer_source=_implementation_query(request.query),
+        symbol=_query_symbol(request.query),
+    )
     fast_result = _try_exact_fast_path(
         request,
         repo_root=repo_root,
         settings=settings,
+        evidence=evidence,
     )
     if fast_result is not None:
         return fast_result
@@ -98,12 +113,28 @@ def explore(
         limits=settings.limits,
     )
     messages = _initial_messages(request, file_sample, settings)
+    if evidence.definition_scan is not None:
+        scan = evidence.definition_scan
+        messages.append(
+            {
+                "role": "system",
+                "content": (
+                    f"Local Python .py/.pyi definition scan for {evidence.symbol}: "
+                    f"{scan.status}. "
+                    "A complete missing result means zero Python definition matches; "
+                    "assignments, imports, docs, and other languages may still "
+                    "contain the symbol. Never infer a plausible home file. "
+                    "Cited lines must contain the exact case-sensitive whole symbol."
+                ),
+            }
+        )
     tools = tool_schemas()
     # A capped file sample is expected; actual scan failures must reach callers.
     warnings = list(file_sample.warnings)
+    if evidence.definition_scan is not None:
+        warnings.extend(evidence.definition_scan.warnings)
     truncated = bool(warnings)
     last_content = ""
-    evidence = EvidenceState()
 
     try:
         for turn in range(1, effective_max_turns + 1):
@@ -145,6 +176,7 @@ def explore(
                 recorder.finish(result=result)
                 return result
             recorder.record_model_turn(turn, message)
+            needs_source = False
             content_text = str(message.get("content") or "").strip()
             if content_text:
                 last_content = content_text
@@ -157,6 +189,12 @@ def explore(
                 )
                 if citations:
                     evidence.citations = citations
+                    needs_source = evidence.prefer_source and _documentation_only(
+                        citations
+                    )
+                if needs_source:
+                    last_content = ""
+                if citations and not needs_source:
                     if _message_has_tool_calls(message):
                         _append_warning_once(
                             warnings,
@@ -178,6 +216,27 @@ def explore(
             tool_calls = _extract_tool_calls(message)
             if not tool_calls:
                 citations = _best_current_citations(evidence)
+                if evidence.symbol and content_text == NO_CITATIONS_FOUND:
+                    citations = []
+                elif evidence.symbol and not citations and turn < effective_max_turns:
+                    messages.append({"role": "assistant", "content": content_text})
+                    messages.append(
+                        {
+                            "role": "user",
+                            "content": (
+                                "No verified citation contains the exact query symbol. "
+                                "Search with fresh read-only calls, or return "
+                                "NO_CITATIONS_FOUND."
+                            ),
+                        }
+                    )
+                    last_content = ""
+                    continue
+                if evidence.prefer_source and _documentation_only(citations):
+                    last_content = ""
+                    messages.append({"role": "assistant", "content": content_text})
+                    messages.append(_source_feedback())
+                    continue
                 if request.citation and content_text != NO_CITATIONS_FOUND:
                     _append_warning_once(
                         warnings,
@@ -187,7 +246,7 @@ def explore(
                     request=request,
                     repo_root=repo_root,
                     settings=settings,
-                    answer=content_text,
+                    answer="" if needs_source else content_text,
                     citations=citations,
                     turns_used=turn,
                     truncated=truncated,
@@ -219,8 +278,12 @@ def explore(
                 recorder.finish(result=result)
                 return result
 
-            repeated_call = _first_repeated_tool_call(evidence, tool_calls)
-            if repeated_call is not None:
+            fresh_calls: dict[str, ToolCall] = {}
+            for tool_call in tool_calls:
+                fingerprint = _tool_call_fingerprint(tool_call)
+                if fingerprint not in evidence.observations:
+                    fresh_calls.setdefault(fingerprint, tool_call)
+            if not fresh_calls:
                 _append_warning_once(
                     warnings,
                     "repeated tool call stopped exploration",
@@ -238,17 +301,18 @@ def explore(
                 )
                 recorder.finish(result=result)
                 return result
-            for tool_call in tool_calls:
-                evidence.seen_tool_calls.add(_tool_call_fingerprint(tool_call))
-
             messages.append(_assistant_tool_message(message))
             observations = _execute_tool_calls_parallel(
-                tool_calls,
+                list(fresh_calls.values()),
                 repo_root=repo_root,
                 settings=settings,
             )
-            for tool_call, observation in zip(tool_calls, observations, strict=True):
-                observation.tool_call_id = tool_call.id
+            evidence.observations.update(zip(fresh_calls, observations, strict=True))
+            for tool_call in tool_calls:
+                observation = replace(
+                    evidence.observations[_tool_call_fingerprint(tool_call)],
+                    tool_call_id=tool_call.id,
+                )
                 payload = _model_observation_payload(
                     observation,
                     max_chars=settings.max_observation_chars,
@@ -262,7 +326,9 @@ def explore(
                     and observation.path
                     and observation.line_range
                 ):
-                    evidence.reads.append(observation)
+                    read = replace(observation, tool_call_id=None)
+                    if read not in evidence.reads:
+                        evidence.reads.append(read)
                 recorder.record_observation(turn, tool_call.name, observation)
                 messages.append(
                     {
@@ -275,6 +341,8 @@ def explore(
                         ),
                     }
                 )
+            if needs_source:
+                messages.append(_source_feedback())
         if last_content:
             citations = _validated_citations_from_content(
                 last_content,
@@ -286,6 +354,8 @@ def explore(
                 last_content,
                 evidence.reads,
             )
+            if evidence.symbol:
+                citations = _best_current_citations(evidence)
             _append_warning_once(warnings, "max turns exceeded after partial answer")
             if request.citation and not citations:
                 _append_warning_once(
@@ -417,7 +487,17 @@ def _finalize_result(
     truncated: bool,
     warnings: list[str],
 ) -> ExploreResult:
+    if _query_symbol(request.query) and not citations:
+        answer = NO_CITATIONS_FOUND
+        _append_warning_once(warnings, "query symbol not found in verified evidence")
     citations = _merge_adjacent_citations(citations)[:MAX_FINAL_CITATIONS]
+    if _implementation_query(request.query) and _documentation_only(citations):
+        truncated = True
+        answer = _citation_text(citations)
+        _append_warning_once(
+            warnings,
+            "implementation source not verified; returning documentation evidence",
+        )
     if request.citation or (not answer and citations):
         answer = _citation_text(citations)
     raw_locations = _extract_raw_locations(
@@ -551,6 +631,7 @@ def _try_exact_fast_path(
     *,
     repo_root: Path,
     settings: Settings,
+    evidence: EvidenceState,
 ) -> ExploreResult | None:
     bare_path = request.query.strip()
     if len(bare_path) >= 2 and bare_path[0] in "`'\"" and bare_path[-1] == bare_path[0]:
@@ -581,7 +662,6 @@ def _try_exact_fast_path(
             )
     if not _is_exact_lookup(request.query):
         return None
-    evidence = EvidenceState()
     warnings: list[str] = []
     citations = _validated_citations_from_content(
         request.query,
@@ -614,6 +694,13 @@ def _try_exact_fast_path(
             target=target,
             allow_assignment=True,
         )
+        citations = _validate_citations(
+            citations,
+            repo_root=repo_root,
+            settings=settings,
+            evidence=evidence,
+            warnings=warnings,
+        )
         if citations:
             return _finalize_result(
                 request=request,
@@ -630,25 +717,77 @@ def _try_exact_fast_path(
     symbol = _extract_pathless_symbol(request.query)
     if symbol is None:
         return None
-    citation = _unique_definition_citation(
+    scan = _scan_definitions(
         repo_root=repo_root,
         settings=settings,
         symbol=symbol,
     )
-    if citation is None:
+    evidence.definition_scan = scan
+    if scan.status != "unique":
         return None
     return _finalize_result(
         request=request,
         repo_root=repo_root,
         settings=settings,
         answer="",
-        citations=[citation],
+        citations=list(scan.citations),
         turns_used=0,
         truncated=False,
         warnings=[],
     )
 
 
+def _query_symbol(query: str) -> str | None:
+    if not _is_exact_lookup(query) or extract_citations(query):
+        return None
+    path = _extract_explicit_path(query)
+    target = (
+        _extract_exact_target(query, path) if path else _extract_pathless_symbol(query)
+    )
+    if target and re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", target):
+        return target
+    return None
+
+
+def _symbol_in_range(
+    citation: Citation,
+    reads: list[ToolObservation],
+    symbol: str | None,
+) -> bool:
+    if symbol is None:
+        return True
+    pattern = re.compile(rf"\b{re.escape(symbol)}\b")
+    for read in reads:
+        if not _citation_has_read_coverage(citation, [read]) or read.content is None:
+            continue
+        start, _ = _parse_line_range(read.line_range or "")
+        assert start is not None and citation.start_line is not None
+        assert citation.end_line is not None
+        lines = read.content.split("\n")
+        lines = [line + "\n" for line in lines[:-1]] + lines[-1:]
+        text = "".join(
+            lines[citation.start_line - start : citation.end_line - start + 1]
+        )
+        for match in pattern.finditer(text):
+            # A byte-capped trailing token has no verified right boundary.
+            if match.end() < len(text) or not read.truncated or text.endswith("\n"):
+                return True
+    return False
+
+
+def _eligible_reads(evidence: EvidenceState) -> list[ToolObservation]:
+    if evidence.symbol is None:
+        return evidence.reads
+    return [
+        read
+        for read in evidence.reads
+        if any(
+            _symbol_in_range(citation, [read], evidence.symbol)
+            for citation in _citations_from_reads([read])
+        )
+    ]
+
+
 def _is_exact_lookup(query: str) -> bool:
     # Admit a small lookup vocabulary; any unexplained intent goes to the model.
     paths = list(EXPLICIT_PATH_RE.finditer(query))
@@ -769,12 +908,12 @@ def _exact_matches_in_file(
     return citations if 0 < len(citations) <= MAX_FINAL_CITATIONS else []
 
 
-def _unique_definition_citation(
+def _scan_definitions(
     *,
     repo_root: Path,
     settings: Settings,
     symbol: str,
-) -> Citation | None:
+) -> _DefinitionScan:
     definition_pattern = rf"^\s*(?:async\s+def|def|class)\s+{re.escape(symbol)}\b"
     grep_result = repo_grep(
         repo_root=repo_root,
@@ -797,9 +936,16 @@ def _unique_definition_citation(
         for result in (grep_result, pyi_result)
         for hit in result.hits
     ]
-    if grep_result.truncated or pyi_result.truncated or len(citations) > 1:
-        return None
-    return citations[0] if len(citations) == 1 else None
+    status: Literal["unique", "missing", "ambiguous", "incomplete"]
+    if grep_result.truncated or pyi_result.truncated:
+        status = "incomplete"
+    elif len(citations) > 1:
+        status = "ambiguous"
+    else:
+        status = "unique" if citations else "missing"
+    return _DefinitionScan(
+        tuple(citations), status, tuple(grep_result.warnings + pyi_result.warnings)
+    )
 
 
 def _grep_exact_target(
@@ -890,7 +1036,8 @@ def _validate_citations(
         if normalized is None:
             continue
         if _citation_has_read_coverage(normalized, evidence.reads):
-            validated.append(normalized)
+            if _symbol_in_range(normalized, evidence.reads, evidence.symbol):
+                validated.append(normalized)
             continue
         verified = _verify_citation_by_read(
             normalized,
@@ -899,7 +1046,9 @@ def _validate_citations(
             evidence=evidence,
             warnings=warnings,
         )
-        if verified is not None:
+        if verified is not None and _symbol_in_range(
+            verified, evidence.reads, evidence.symbol
+        ):
             validated.append(verified)
     return _merge_adjacent_citations(_dedupe_citations(validated))[:MAX_FINAL_CITATIONS]
 
@@ -1016,9 +1165,23 @@ def _dedupe_citations(citations: list[Citation]) -> list[Citation]:
 
 
 def _best_current_citations(evidence: EvidenceState) -> list[Citation]:
+    reads = _eligible_reads(evidence)
+    if evidence.prefer_source:
+        source_reads = [
+            read for read in reads if not _documentation_path(read.path or "")
+        ]
+        source_citations = [
+            citation
+            for citation in evidence.citations
+            if not _documentation_path(citation.path)
+        ]
+        if source_citations or source_reads:
+            return source_citations[:MAX_FINAL_CITATIONS] or _citations_from_reads(
+                source_reads
+            )
     if evidence.citations:
         return evidence.citations[:MAX_FINAL_CITATIONS]
-    return _citations_from_reads(evidence.reads)
+    return _citations_from_reads(reads)
 
 
 def _citations_from_reads(observations: list[ToolObservation]) -> list[Citation]:
@@ -1070,7 +1233,7 @@ def _best_narrow_read_citation(
     evidence: EvidenceState,
     settings: Settings,
 ) -> Citation | None:
-    for citation in _citations_from_reads(evidence.reads):
+    for citation in _citations_from_reads(_eligible_reads(evidence)):
         for observation in evidence.reads:
             start, end = _parse_line_range(observation.line_range or "")
             if (
@@ -1120,17 +1283,44 @@ def _tool_call_fingerprint(tool_call: ToolCall) -> str:
     )
 
 
-def _first_repeated_tool_call(
-    evidence: EvidenceState,
-    tool_calls: list[ToolCall],
-) -> ToolCall | None:
-    batch_fingerprints: set[str] = set()
-    for tool_call in tool_calls:
-        fingerprint = _tool_call_fingerprint(tool_call)
-        if fingerprint in evidence.seen_tool_calls or fingerprint in batch_fingerprints:
-            return tool_call
-        batch_fingerprints.add(fingerprint)
-    return None
+def _implementation_query(query: str) -> bool:
+    if _is_exact_lookup(query) or re.search(
+        r"\b(?:docs?|documentation|markdown|readme)\b", query, re.IGNORECASE
+    ):
+        return False
+    return bool(
+        re.search(
+            r"\b(?:implement\w*|handl\w*|code|functions?|methods?|classes|class)\b",
+            query,
+            re.IGNORECASE,
+        )
+    )
+
+
+def _documentation_path(path: str) -> bool:
+    name = Path(path).name.lower()
+    return Path(name).suffix in {".md", ".mdx", ".rst", ".txt", ".adoc"} or name in {
+        "readme",
+        "changelog",
+        "contributing",
+        "license",
+        "authors",
+    }
+
+
+def _documentation_only(citations: list[Citation]) -> bool:
+    return bool(citations) and all(_documentation_path(c.path) for c in citations)
+
+
+def _source_feedback() -> dict[str, str]:
+    return {
+        "role": "user",
+        "content": (
+            "These citations only establish documentation evidence. Continue searching "
+            "for implementation source using fresh, focused read-only tool calls. "
+            "Do not repeat previous calls or bypass denied paths."
+        ),
+    }
 
 
 def _message_has_tool_calls(message: dict[str, Any]) -> bool:
@@ -1245,6 +1435,8 @@ def _initial_messages(
                 "tool calls in the same turn. "
                 "For exact symbol, function, or class names, use repo_grep "
                 "before reading broad file ranges. "
+                "Exact-symbol citations must contain the whole case-sensitive "
+                "query token inside the cited lines. "
                 "For implementation questions, prefer implementation source over "
                 "documentation or Markdown; use documentation when requested or "
                 "needed to support the answer. Cite the smallest line ranges "

{flash_context-0.3.0 → flash_context-0.3.2}/src/flash_context/mcp_server.py

@@ -6,6 +6,7 @@ from importlib import import_module
 from pathlib import Path
 from typing import Any
 
+from flash_context import __version__
 from flash_context.agent import explore
 from flash_context.config import Settings, SettingsOverrides, load_settings
 from flash_context.types import ExploreRequest, ExplorerError, ExploreResult
@@ -52,6 +53,8 @@ def create_server() -> Any:
         ) from exc
     fast_mcp = fastmcp_module.FastMCP
     server = fast_mcp("flash-context")
+    # FastMCP exposes no version argument; the low-level default is the SDK version.
+    server._mcp_server.version = __version__
 
     @server.tool()  # type: ignore[untyped-decorator]
     def explore_repository(