flash-context 0.3.1__tar.gz → 0.4.0__tar.gz

{flash_context-0.3.1 → flash_context-0.4.0}/.env.example

@@ -15,3 +15,8 @@ FLASH_CONTEXT_MAX_SCAN_BYTES=16777216
 FLASH_CONTEXT_MAX_SCAN_ENTRIES=10000
 FLASH_CONTEXT_TOOL_TIMEOUT_SECONDS=5
 FLASH_CONTEXT_MAX_TOOL_CALLS_PER_TURN=16
+
+# Controller-owned citation precision
+FLASH_CONTEXT_MAX_CITATION_LINES=120
+FLASH_CONTEXT_MAX_TOTAL_CITATION_LINES=240
+FLASH_CONTEXT_MAX_PARSE_BYTES=1048576

{flash_context-0.3.1 → flash_context-0.4.0}/CHANGELOG.md

@@ -4,6 +4,70 @@ User-visible changes and migration instructions for each release.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-11-01
+
+### Added
+
+- Bundled parsers for controller-owned symbol and line-anchor boundaries, with
+  citation precision metadata and an opt-in pinned quality benchmark.
+- Configurable per-citation, total-line and parser-byte limits (120, 240 and
+  1 MiB by default), supporting the existing configuration precedence.
+
+### Fixed
+
+- Keep citation repair feedback local to each model turn; successful repair after
+  a tool-only turn no longer reports a precision failure. Preserve overlapping
+  anchor mappings, LF/CRLF source lines, and snippet/metadata source snapshots.
+- Report parser input/deadline limits explicitly and use diagnostic identities
+  for truncation and CLI exit behavior.
+
+### Changed
+
+- Consolidate contracts under `docs/`, remove planning scaffolds and separate
+  agent instructions, and keep contributor guidance in `CONTRIBUTING.md`.
+  Simplify query routing, configuration, loop finalization, test fixtures,
+  live evaluation, and CI jobs.
+- Benchmark against independent reviewed ranges, recording package/parser
+  versions and effective settings. Live probes share the same pinned cases.
+
+### Migration
+
+- Models must propose symbol or single-line anchors; model-selected ranges receive
+  bounded correction feedback. Public line labels remain unchanged. Adjacent
+  definitions remain separate, and the final citation cap increases to twelve.
+- Unselected read observations no longer become final citations. Consumers should
+  accept the additive precision object. Explicit user ranges retain old behavior.
+- Parser dependencies ship with installation; exploration does not download grammars.
+- CLI `--no-citation` now enables prose; `--citation` remains the default.
+  Remove the previously ignored `explorer.citation` YAML key. Python callers
+  should stop passing the ignored `load_settings(repo_root=...)` argument or
+  the adapter-only `ExploreRequest.format` field. `Citation` now requires both
+  line bounds; typed warnings use `Diagnostic` members and serialize as strings.
+- Empty results after parser input/deadline exhaustion exit 6, matching scan
+  exhaustion. Ordinary syntax fallback and complete empty results still exit 0.
+
+## [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

{flash_context-0.3.1 → flash_context-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flash-context
-Version: 0.3.1
+Version: 0.4.0
 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
@@ -17,6 +17,8 @@ Requires-Python: >=3.13
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: regex>=2026.9.29
+Requires-Dist: tree-sitter-language-pack==0.13.0
+Requires-Dist: tree-sitter==0.25.2
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.13.0; extra == 'mcp'
 Description-Content-Type: text/markdown
@@ -28,24 +30,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)
 
-A lightweight, model-agnostic repository explorer that combines deterministic
-lookup with delegated LLM search to deliver compact, validated source evidence.
-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.
-Implementation queries continue past documentation-only citations within the turn budget; documentation-only
-fallbacks carry incomplete-result metadata and warnings. Build outputs such as
-`dist/` remain excluded; inspect a source checkout for implementation evidence.
-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/contracts.md#read-only-tools-and-safety)
+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
@@ -75,10 +69,10 @@ Default output is repository-relative citations:
 src/api/validation.py:42-88
 ```
 
-Use `--format json` for structured results with source snippets, or
+Use `--no-citation` for prose, `--format json` for results with snippets, or
 `--max-turns 6` to set the exploration limit. Exact path and unique symbol
 lookups can resolve locally without an endpoint. See the
-[CLI contract](specs/001-flash-context-explorer/contracts/cli.md) for options,
+[CLI contract](docs/cli.md) for options,
 output schemas, and exit codes.
 
 For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
@@ -89,6 +83,10 @@ Warnings go to stderr in both output formats. An empty result after scan-budget
 exhaustion exits **6** while preserving stdout; a complete empty search exits
 **0**. For large repositories, see [scan-budget tuning](docs/configuration.md#large-repositories).
 
+Models select symbol or line anchors; the controller resolves bounded syntax
+regions and returns structural precision metadata. See the
+[shared contract](docs/contracts.md) for evidence rules and limits.
+
 ## MCP
 
 ```bash
@@ -101,7 +99,7 @@ See [MCP integration](docs/mcp.md) for editor configuration and source launches.
 ## Documentation
 
 - [Configuration](docs/configuration.md): endpoint settings, precedence, and limits.
-- [Architecture and scope](docs/architecture.md): design, status, specs, and references.
+- [Architecture and scope](docs/architecture.md): shared core and module responsibilities.
 - [Contributing](CONTRIBUTING.md): development setup, tests, and pull requests.
 - [Changelog](CHANGELOG.md): release history and migration instructions.
 - [Releasing](docs/releasing.md): package checks and tag-driven TestPyPI/PyPI publishing.

{flash_context-0.3.1 → flash_context-0.4.0}/README.md

@@ -5,24 +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)
 
-A lightweight, model-agnostic repository explorer that combines deterministic
-lookup with delegated LLM search to deliver compact, validated source evidence.
-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.
-Implementation queries continue past documentation-only citations within the turn budget; documentation-only
-fallbacks carry incomplete-result metadata and warnings. Build outputs such as
-`dist/` remain excluded; inspect a source checkout for implementation evidence.
-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/contracts.md#read-only-tools-and-safety)
+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
@@ -52,10 +44,10 @@ Default output is repository-relative citations:
 src/api/validation.py:42-88
 ```
 
-Use `--format json` for structured results with source snippets, or
+Use `--no-citation` for prose, `--format json` for results with snippets, or
 `--max-turns 6` to set the exploration limit. Exact path and unique symbol
 lookups can resolve locally without an endpoint. See the
-[CLI contract](specs/001-flash-context-explorer/contracts/cli.md) for options,
+[CLI contract](docs/cli.md) for options,
 output schemas, and exit codes.
 
 For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
@@ -66,6 +58,10 @@ Warnings go to stderr in both output formats. An empty result after scan-budget
 exhaustion exits **6** while preserving stdout; a complete empty search exits
 **0**. For large repositories, see [scan-budget tuning](docs/configuration.md#large-repositories).
 
+Models select symbol or line anchors; the controller resolves bounded syntax
+regions and returns structural precision metadata. See the
+[shared contract](docs/contracts.md) for evidence rules and limits.
+
 ## MCP
 
 ```bash
@@ -78,7 +74,7 @@ See [MCP integration](docs/mcp.md) for editor configuration and source launches.
 ## Documentation
 
 - [Configuration](docs/configuration.md): endpoint settings, precedence, and limits.
-- [Architecture and scope](docs/architecture.md): design, status, specs, and references.
+- [Architecture and scope](docs/architecture.md): shared core and module responsibilities.
 - [Contributing](CONTRIBUTING.md): development setup, tests, and pull requests.
 - [Changelog](CHANGELOG.md): release history and migration instructions.
 - [Releasing](docs/releasing.md): package checks and tag-driven TestPyPI/PyPI publishing.

{flash_context-0.3.1 → flash_context-0.4.0}/config.yaml.example

@@ -1,6 +1,7 @@
 explorer:
   max_turns: 6
-  citation: true
+  max_citation_lines: 120
+  max_total_citation_lines: 240
   ignore:
     - ".git"
     - ".venv"
@@ -20,6 +21,7 @@ model:
 
 tools:
   max_read_bytes: 12000
+  max_parse_bytes: 1048576
   max_grep_results: 50
   max_observation_chars: 6000
   max_read_lines: 120

{flash_context-0.3.1 → flash_context-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "flash-context"
-version = "0.3.1"
+version = "0.4.0"
 description = "Read-only context exploration and retrieval for AI agents, starting with codebases and repositories."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -19,6 +19,8 @@ dependencies = [
   "httpx>=0.28.0",
   "PyYAML>=6.0.0",
   "regex>=2026.9.29",
+  "tree-sitter==0.25.2",
+  "tree-sitter-language-pack==0.13.0",
 ]
 
 [project.urls]
@@ -60,12 +62,14 @@ include = [
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["."]
 norecursedirs = ["tests/fixtures"]
 markers = [
   "e2e: endpoint-backed opt-in end-to-end tests",
 ]
 
 [tool.ruff]
+extend-exclude = ["tests/fixtures/httpx_0_28_1"]
 line-length = 88
 target-version = "py313"