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

{flash_context-0.1.0 → flash_context-0.3.0}/.env.example

@@ -4,10 +4,14 @@ FLASH_CONTEXT_API_KEY=
 FLASH_CONTEXT_MAX_TURNS=6
 FLASH_CONTEXT_MAX_READ_BYTES=12000
 FLASH_CONTEXT_MAX_GREP_RESULTS=50
-FLASH_CONTEXT_TRAJ_DIR=.flash-context
+FLASH_CONTEXT_TRAJ_DIR=
 FLASH_CONTEXT_TIMEOUT_SECONDS=120
 FLASH_CONTEXT_MAX_OBSERVATION_CHARS=6000
 FLASH_CONTEXT_MAX_READ_LINES=120
 FLASH_CONTEXT_MAX_COMPLETION_TOKENS=512
 FLASH_CONTEXT_TEMPERATURE=0
 FLASH_CONTEXT_MAX_PARALLEL_TOOLS=4
+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

flash_context-0.3.0/CHANGELOG.md

@@ -0,0 +1,65 @@
+# Changelog
+
+User-visible changes and migration instructions for each release.
+
+## [Unreleased]
+
+## [0.3.0] - 2026-11-01
+
+### Fixed
+
+- Resolve bare file-path queries locally with bounded previews and find unique
+  Python definitions even when many references precede them.
+- Keep literal and scoped searches from scanning unrelated directory trees while
+  preserving safety checks and existing resource limits.
+- Surface scan failures from the initial file sample and CLI result warnings.
+- Describe the MCP exploration tool during discovery and use tool-specific
+  trajectory counters instead of misleading empty read-content counts.
+
+### Migration
+
+- Citation objects no longer include the unused `reason` field. Consumers should
+  read `path`, `start_line`, and `end_line` without expecting `reason: null`.
+- The CLI now exits 6 for empty results after scan-budget exhaustion or a tool
+  processing timeout, retaining text/JSON on stdout and warnings on stderr.
+  Partial cited results and complete empty searches still exit 0.
+- Trajectory tool entries now include only their relevant counter:
+  `content_length` (read), `hit_count` (grep), or `match_count` (glob).
+
+### Changed
+
+- Prompt the explorer to prefer implementation source for coding questions and
+  the smallest supporting citation ranges. Validation checks safe line coverage;
+  precision and relevance remain model-dependent.
+- Publish GitHub releases automatically after PyPI installation verification,
+  using this changelog and the same distribution artifacts uploaded to PyPI.
+- Refresh package-index metadata during release installation retries.
+
+## [0.2.0] - 2026-11-01
+
+### Changed
+
+- Enforce deny/ignore rules on requested and resolved paths, including environment
+  files, private-key names, and runtime histories. Prune denied directories.
+- Bound scan bytes, directory entries, processing time, regex execution, tool
+  batches, and model observations; report incomplete coverage explicitly.
+- Improve exact-lookup routing, read ranges, truncation metadata, and structured
+  endpoint/filesystem failures across CLI and MCP.
+- Keep optional trajectory logs metadata-only and outside the inspected root.
+
+### Migration
+
+- Move any trajectory directory inside the inspected repository outside it, or
+  disable logging with `FLASH_CONTEXT_TRAJ_DIR=`. Empty/null settings disable
+  inherited logging. Existing logs remain untouched.
+
+## [0.1.0] - 2026-11-01
+
+### Added
+
+- Initial Python CLI and optional MCP adapter sharing a read-only explorer core.
+- OpenAI-compatible tool-call loop with bounded Read/Glob/Grep repository tools,
+  root-scoped path validation, validated citations, and raw source snippets.
+- Exact path/symbol lookup shortcuts, concurrent local tools, and configurable
+  endpoint settings and limits.
+- Wheel/source packaging and tag-driven TestPyPI/PyPI publication and smoke checks.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: flash-context
-Version: 0.1.0
+Version: 0.3.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
@@ -16,20 +16,37 @@ Classifier: Topic :: Software Development
 Requires-Python: >=3.13
 Requires-Dist: httpx>=0.28.0
 Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: regex>=2026.9.29
 Provides-Extra: mcp
 Requires-Dist: mcp<2,>=1.13.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # flash-context
 
+[![CI](https://github.com/zyf0717/flash-context/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/zyf0717/flash-context/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/flash-context)](https://pypi.org/project/flash-context/)
+[![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.
 
-Ask natural-language questions across source code, documentation, configuration,
-and other local text files, and get validated file-line citations and snippets.
-The current focus is codebases and repositories. Both interfaces share one
-exploration core, backed by an OpenAI-compatible FastContext-style endpoint.
-Local tools enforce read-only access, path safety, and resource limits.
+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.
+
+Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
+on separating repository exploration from task solving, using specialized models
+to return focused file-line evidence while reducing the coding agent's context
+and token overhead.
 
 ## Quickstart
 
@@ -60,6 +77,14 @@ lookups can resolve locally without an endpoint. See the
 [CLI contract](specs/001-flash-context-explorer/contracts/cli.md) for options,
 output schemas, and exit codes.
 
+For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
+`--query 'BaseTransport'` returns its definition if unique within a complete
+Python source/stub scan. Local successes report `turns_used: 0` in JSON.
+
+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).
+
 ## MCP
 
 ```bash
@@ -74,6 +99,7 @@ See [MCP integration](docs/mcp.md) for editor configuration and source launches.
 - [Configuration](docs/configuration.md): endpoint settings, precedence, and limits.
 - [Architecture and scope](docs/architecture.md): design, status, specs, and references.
 - [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.
 
 ## License

flash_context-0.3.0/README.md

@@ -0,0 +1,84 @@
+# flash-context
+
+[![CI](https://github.com/zyf0717/flash-context/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/zyf0717/flash-context/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/flash-context)](https://pypi.org/project/flash-context/)
+[![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.
+
+Inspired by [FastContext](https://arxiv.org/abs/2606.14066), a now-withdrawn paper
+on separating repository exploration from task solving, using specialized models
+to return focused file-line evidence while reducing the coding agent's context
+and token overhead.
+
+## Quickstart
+
+Requires Python 3.13+, `uv`, and an OpenAI-compatible model endpoint with tool
+calling support.
+
+```bash
+uv tool install flash-context
+export FLASH_CONTEXT_BASE_URL=http://localhost:1234/v1
+export FLASH_CONTEXT_MODEL=your-model
+
+flash-context explore --repo . --query "Find the request validation logic"
+```
+
+Replace the endpoint and model with your settings. Set `FLASH_CONTEXT_API_KEY`
+if authentication is required. Installed commands use environment variables;
+source checkouts also support project-root `config.yaml` and `.env`.
+
+Default output is repository-relative citations:
+
+```text
+src/api/validation.py:42-88
+```
+
+Use `--format json` for structured results with source 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,
+output schemas, and exit codes.
+
+For example, `--query 'httpx/_client.py'` returns a bounded file preview, while
+`--query 'BaseTransport'` returns its definition if unique within a complete
+Python source/stub scan. Local successes report `turns_used: 0` in JSON.
+
+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).
+
+## MCP
+
+```bash
+uvx --from 'flash-context[mcp]' flash-context mcp --transport stdio
+```
+
+Exposes `explore_repository(query, repo_root?, max_turns?, citation?)`.
+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.
+- [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.
+
+## License
+
+[Apache License 2.0](LICENSE).

{flash_context-0.1.0 → flash_context-0.3.0}/config.yaml.example

@@ -8,7 +8,7 @@ explorer:
     - "dist"
     - "build"
   # Relative paths resolve from the flash-context project root.
-  traj_dir: ".flash-context"
+  traj_dir: null
 
 model:
   base_url: "http://100.105.153.85:1234/v1"
@@ -24,3 +24,7 @@ tools:
   max_observation_chars: 6000
   max_read_lines: 120
   max_parallel_tools: 4
+  max_scan_bytes: 16777216
+  max_scan_entries: 10000
+  tool_timeout_seconds: 5
+  max_tool_calls_per_turn: 16

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

@@ -1,6 +1,6 @@
 [project]
 name = "flash-context"
-version = "0.1.0"
+version = "0.3.0"
 description = "Read-only context exploration and retrieval for AI agents, starting with codebases and repositories."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -18,6 +18,7 @@ classifiers = [
 dependencies = [
   "httpx>=0.28.0",
   "PyYAML>=6.0.0",
+  "regex>=2026.9.29",
 ]
 
 [project.urls]
@@ -36,6 +37,7 @@ dev = [
   "pytest>=8.3.0",
   "ruff>=0.9.0",
   "types-PyYAML>=6.0.12",
+  "types-regex>=2026.9.29.20261030",
 ]
 
 [build-system]
@@ -50,6 +52,7 @@ include = [
   "/src/flash_context",
   "/pyproject.toml",
   "/README.md",
+  "/CHANGELOG.md",
   "/LICENSE",
   "/config.yaml.example",
   "/.env.example",
@@ -72,5 +75,5 @@ select = ["E", "F", "I", "UP", "B", "SIM"]
 [tool.mypy]
 python_version = "3.13"
 strict = true
-files = ["src/flash_context", "tests/unit", "tests/contract"]
+files = ["src/flash_context", "tests/unit", "tests/contract", "scripts"]
 exclude = ["tests/fixtures"]