From 5168a408bad4432f9a611898404bbc136446bdb6 Mon Sep 17 00:00:00 2001 From: Krishika <203898617+krishika08@users.noreply.github.com> Date: Thu, 12 Nov 2026 13:20:37 +0530 Subject: [PATCH] docs: finalize 1.2.0 release status 1.2.0 was published to PyPI on 2026-11-12. Replace the pre-release "upcoming / PyPI publication pending" wording and the "install from source until 1.2.0 is published" instructions with the released status. Historical benchmark provenance ("pre-release 1.2.0 development branch of 2026-11-09") and all limitations are unchanged. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 +--- CLAIMS_AND_EVIDENCE.md | 2 +- KNOWN_LIMITATIONS.md | 2 +- README.md | 14 +++++++------- REPONEEDLE_V1_FINAL_DELIVERY.md | 2 +- docs/ANNOUNCEMENT.md | 4 ++-- docs/BENCHMARK_CONFIGURATION.md | 2 +- docs/MCP_INTEGRATION.md | 18 ++++++++++-------- docs/ROADMAP.md | 4 ++-- 9 files changed, 26 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c63637d..2de5f41 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,9 +2,7 @@ All notable changes to RepoNeedle are documented here. Versions follow [Semantic Versioning](https://semver.org/). -## [1.2.0] — Unreleased (upcoming) - -> 1.2.0 has not yet been published to PyPI. Until it is, `pip install reponeedle` installs 1.1.0. +## [1.2.0] — 2026-11-12 ### Highlights diff --git a/CLAIMS_AND_EVIDENCE.md b/CLAIMS_AND_EVIDENCE.md index 279ece7..f2e35de 100644 --- a/CLAIMS_AND_EVIDENCE.md +++ b/CLAIMS_AND_EVIDENCE.md @@ -1,6 +1,6 @@ # CLAIMS AND EVIDENCE: SCIENTIFIC RECONCILIATION FOR REPONEEDLE -**Version**: Evidence originally compiled for the 0.1.0 Research Preview. Claims C11–C13 and corrections to C2, C4 and C6 were added on 2026-11-09 and cover released 1.1.0 and the pre-release development branch that became 1.2.0 (upcoming; PyPI publication pending). +**Version**: Evidence originally compiled for the 0.1.0 Research Preview. Claims C11–C13 and corrections to C2, C4 and C6 were added on 2026-11-09 and cover released 1.1.0 and the pre-release development branch that became 1.2.0 (published to PyPI on 2026-11-12). **Benchmark Suite**: Official Agent Retrieval Bench (ARB v2, $N=427$ total samples, $N=345$ positive retrieval samples across 25 repositories and 271 unique repository snapshots) **Evaluator**: `agent_retrieval_bench` v0.2.1, Commit `9e4d68937f29` **Evaluation Date**: 2026-10-28 diff --git a/KNOWN_LIMITATIONS.md b/KNOWN_LIMITATIONS.md index bc09846..0c7c5af 100644 --- a/KNOWN_LIMITATIONS.md +++ b/KNOWN_LIMITATIONS.md @@ -1,6 +1,6 @@ # KNOWN LIMITATIONS AND ARCHITECTURAL BOUNDARIES: REPONEEDLE -**Applies to**: Released 1.1.0 (PyPI) and 1.2.0 (upcoming; PyPI publication pending). Differences between the two are called out explicitly. +**Applies to**: Released 1.1.0 (PyPI, 2026-11-03) and 1.2.0 (PyPI, 2026-11-12). Differences between the two are called out explicitly. **Originally written for**: 0.1.0 Research Preview (October 2026); last reconciled with the source code on 2026-11-09. **Primary Benchmark**: Agent Retrieval Bench v2 ($N=427$ samples, 25 repositories, 271 unique snapshots) diff --git a/README.md b/README.md index 6534749..e36c3aa 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ RepoNeedle is a research-oriented project: its benchmark results, including wher ## 📌 Release Status -| Feature | 1.1.0 (released, PyPI) | 1.2.0 (**upcoming**; publication to PyPI pending) | +| Feature | 1.1.0 (PyPI, 2026-11-03) | 1.2.0 (PyPI, 2026-11-12) | | :--- | :---: | :---: | | CPU-first execution | ✅ | ✅ | | Python 3.10, 3.11, 3.12 | ✅ | ✅ | @@ -44,7 +44,7 @@ RepoNeedle is a research-oriented project: its benchmark results, including wher | HTTP / SSE MCP transport | Not implemented | Not implemented | | AST block slicing of large files | Not implemented | Not implemented | -Until 1.2.0 appears on [PyPI](https://pypi.org/project/reponeedle/), `pip install reponeedle` still installs 1.1.0; install from source (see below) to use the 1.2.0 features before then. +Both versions are published on [PyPI](https://pypi.org/project/reponeedle/), and `pip install reponeedle` installs the latest. Behaviour changes from 1.1.0 and migration steps are listed in [CHANGELOG.md](CHANGELOG.md#migrating-from-11x). --- @@ -57,7 +57,7 @@ Until 1.2.0 appears on [PyPI](https://pypi.org/project/reponeedle/), `pip instal pip install "reponeedle>=1.2.0" # core: Python API and CLI pip install "reponeedle[mcp]>=1.2.0" # core + MCP server -# Before 1.2.0 is published on PyPI: install from a clone +# For local development: install from a clone git clone https://github.com/krishika08/RepoNeedle.git cd RepoNeedle pip install -e ".[mcp]" @@ -129,11 +129,11 @@ RepoNeedle is self-contained and requires standard Python dependencies (`numpy`, | Core: Python API and CLI (incl. `--json`, `--anchors`, indexing diagnostics) | `pip install "reponeedle>=1.2.0"` | | Core + MCP server | `pip install "reponeedle[mcp]>=1.2.0"` | | Demo HTTP API dependencies (`fastapi`, `httpx`, `uvicorn`; only for the repository's `api.py`) | `pip install "reponeedle[api]"` | -| From a clone (before 1.2.0 is on PyPI, or for development) | `pip install -e ".[mcp]"` | +| From a clone, for development (core + MCP server) | `pip install -e ".[mcp]"` | | Test and development tools | `pip install -e ".[dev]"` | > [!NOTE] -> 1.2.0 is **upcoming**. Until it is published on PyPI, the PyPI commands above fail to resolve `>=1.2.0` (an unpinned `pip install reponeedle` installs 1.1.0, which has no MCP server, `--json` or `--anchors`). Install from a clone in the meantime. +> The `>=1.2.0` pin also upgrades an existing 1.1.0 installation. 1.1.0 has no MCP server, `--json` or `--anchors`. > [!TIP] > On Python 3.10, `tomli>=2.0.1` is automatically installed via conditional dependency. On Python 3.11 and 3.12, native standard library `tomllib` is used with zero extra dependencies. @@ -301,7 +301,7 @@ reponeedle "parser entry point" --repo ./my-project --json --max-file-size-bytes ### 4. Model Context Protocol (MCP) Server -*New in 1.2.0 (upcoming; install with `pip install "reponeedle[mcp]>=1.2.0"`, or `pip install -e ".[mcp]"` from a clone until 1.2.0 is on PyPI).* RepoNeedle includes a local **MCP server** that lets MCP-capable coding agents call it over STDIO. It is tested with the MCP Python SDK and a JSON-RPC STDIO handshake; it has not yet been validated in a live Claude Code, Cursor, Cline or Windsurf session. +*New in 1.2.0 (install with `pip install "reponeedle[mcp]>=1.2.0"`, or `pip install -e ".[mcp]"` from a clone for development).* RepoNeedle includes a local **MCP server** that lets MCP-capable coding agents call it over STDIO. It is tested with the MCP Python SDK and a JSON-RPC STDIO handshake; it has not yet been validated in a live Claude Code, Cursor, Cline or Windsurf session. ```bash # Launch the MCP server pointing to your project @@ -462,7 +462,7 @@ Empirically measured across the full Agent Retrieval Bench evaluation suite: ### Part E: System Architecture & Deployment Status - **CPU Native Architecture**: RepoNeedle runs entirely in Python/NumPy/SciPy/NetworkX without requiring CUDA GPUs or heavy deep learning runtime dependencies. -- **Release Status**: **1.1.0 is published on PyPI (2026-11-03)**, with the default `legacy` ranker and the opt-in `change_impact` ranker. 1.2.0 adds the features listed in [Release Status](#-release-status); it is **upcoming** (this repository's version; PyPI publication pending). +- **Release Status**: **1.2.0 is published on PyPI (2026-11-12)** and adds the features listed in [Release Status](#-release-status). 1.1.0 (PyPI, 2026-11-03) introduced the opt-in `change_impact` ranker; the default ranker is `legacy` in both. - **Abstention during these evaluations**: Parts A–C, the Part D latency table and Part F were measured with code in which the abstention heuristic was always on. A full re-run on ARB v2 (2026-11-09) verified that the heuristic would abstain on **0 of 345** positive queries and that selected files are identical with and without it, so the new opt-in default does not change any ARB v2 result. See [docs/BENCHMARK_CONFIGURATION.md](docs/BENCHMARK_CONFIGURATION.md). --- diff --git a/REPONEEDLE_V1_FINAL_DELIVERY.md b/REPONEEDLE_V1_FINAL_DELIVERY.md index e15e989..15aa91d 100644 --- a/REPONEEDLE_V1_FINAL_DELIVERY.md +++ b/REPONEEDLE_V1_FINAL_DELIVERY.md @@ -1,7 +1,7 @@ # REPONEEDLE V1.0.0 — FINAL DELIVERY REPORT > [!NOTE] -> **Historical record (2026-11-02), describing the 1.0.0 delivery only.** It has not been updated for later versions. The current release is **1.1.0** (PyPI, 2026-11-03); the development branch is planned for **1.2.0** (unreleased). Two statements below are qualified elsewhere: the description of RepoNeedle as "the first" engine of its kind is an unverified priority claim, and the zero-overflow guarantee holds for RepoNeedle's internal regex token model, not for every LLM tokenizer (see the README's tokenizer boundary disclosure). +> **Historical record (2026-11-02), describing the 1.0.0 delivery only.** It has not been updated for later versions. The current release is **1.2.0** (PyPI, 2026-11-12); 1.1.0 was published on 2026-11-03. Two statements below are qualified elsewhere: the description of RepoNeedle as "the first" engine of its kind is an unverified priority claim, and the zero-overflow guarantee holds for RepoNeedle's internal regex token model, not for every LLM tokenizer (see the README's tokenizer boundary disclosure). ## MASTER EXECUTION DIRECTIVE COMPLETION diff --git a/docs/ANNOUNCEMENT.md b/docs/ANNOUNCEMENT.md index 9145888..cb53d7c 100644 --- a/docs/ANNOUNCEMENT.md +++ b/docs/ANNOUNCEMENT.md @@ -2,7 +2,7 @@ > [!CAUTION] > **Historical document with corrections (corrected 2026-11-09).** This announcement was written for the **v0.1.0 research preview** (October 2026). It is kept for the record, but several of its original claims were not supported by later evaluation and have been corrected in place below: -> - **Selective abstention**: The original text described a "calibrated" abstention mechanism with perfect accuracy. That figure came from a synthetic benchmark containing only **3** selective samples. On the official Agent Retrieval Bench v2 selective split (**N = 82** no-gold queries) the heuristic correctly abstained on **0 of 82 (0.0%)**. The heuristic is uncalibrated and experimental, and from 1.2.0 (upcoming) it is **disabled by default**. +> - **Selective abstention**: The original text described a "calibrated" abstention mechanism with perfect accuracy. That figure came from a synthetic benchmark containing only **3** selective samples. On the official Agent Retrieval Bench v2 selective split (**N = 82** no-gold queries) the heuristic correctly abstained on **0 of 82 (0.0%)**. The heuristic is uncalibrated and experimental, and from 1.2.0 it is **disabled by default**. > - **Benchmark table**: The table below reports the v0.1.0 synthetic **RepoNeedle-Bench** run (15 samples). The stored result file (`benchmarks/results/benchmark_results.json`) is **not reproducible** by any later code version (1.1.0 or the pre-release 1.2.0 development branch); current re-run values are shown alongside. > - **Latency**: Sub-millisecond latency was measured on tiny synthetic corpora. On real repositories (ARB v2) mean query latency is ~318 ms (see README, Part D). > @@ -32,7 +32,7 @@ RepoNeedle solves these bottlenecks through four complementary innovations: 1. **Workflow-Adaptive Routing**: Automatically classifies task intent (`trace2code`, `code2test`, `edit2ripple`, `comment2context`, `selective`) and dynamically adjusts retrieval weights between AST symbols, inverted dependency graphs, dense subwords, and lexical matching. 2. **Inverted Test-to-Target Mapping**: Connects production code to its corresponding test suites via import reversal and naming conventions, achieving a **1.000 MRR on test discovery** on the synthetic benchmark (where RepoMap scores 0.122). *On real repositories (ARB v2 `code2test`, N=106) the measured MRR is 0.2660 vs RepoMap 0.1942; see README.* -3. **Selective Abstention (experimental heuristic, corrected)**: A heuristic combining repository vocabulary overlap, score peakiness ($Z$-score) and score margin was intended to abstain on out-of-scope queries. *Correction: it is not calibrated. It correctly abstained on 0 of 82 no-gold queries on ARB v2 and is disabled by default on the current development branch.* +3. **Selective Abstention (experimental heuristic, corrected)**: A heuristic combining repository vocabulary overlap, score peakiness ($Z$-score) and score margin was intended to abstain on out-of-scope queries. *Correction: it is not calibrated. It correctly abstained on 0 of 82 no-gold queries on ARB v2 and is disabled by default from 1.2.0.* 4. **Token-Budget Knapsack Optimization**: Uses marginal utility density packing with multi-tier structural skeletons (extracting signatures, docstrings, and query matches) to fit more relevant context into fixed token budgets (2k, 4k, 8k tokens). *The original "3-4x more files" figure was not backed by a recorded measurement and has been removed.* --- diff --git a/docs/BENCHMARK_CONFIGURATION.md b/docs/BENCHMARK_CONFIGURATION.md index 5035044..573d325 100644 --- a/docs/BENCHMARK_CONFIGURATION.md +++ b/docs/BENCHMARK_CONFIGURATION.md @@ -1,6 +1,6 @@ # Benchmark Configuration & Reproducibility -This document records **how each benchmark and research script configures RepoNeedle**, which historical results were measured under which defaults, and known reproducibility gaps. It exists because 1.2.0 (upcoming; PyPI publication pending) changed a default that some evaluations depend on. +This document records **how each benchmark and research script configures RepoNeedle**, which historical results were measured under which defaults, and known reproducibility gaps. It exists because 1.2.0 (PyPI, 2026-11-12) changed a default that some evaluations depend on. *Last audited: 2026-11-09. Machine-checked by `tests/test_documentation_consistency.py`.* diff --git a/docs/MCP_INTEGRATION.md b/docs/MCP_INTEGRATION.md index 3459247..ab073c1 100644 --- a/docs/MCP_INTEGRATION.md +++ b/docs/MCP_INTEGRATION.md @@ -1,6 +1,6 @@ # RepoNeedle Model Context Protocol (MCP) Integration Guide -**Status**: New in RepoNeedle 1.2.0 (**upcoming**; PyPI publication pending). The earlier PyPI release 1.1.0 does **not** include the MCP server. +**Status**: Released in RepoNeedle 1.2.0 (PyPI, 2026-11-12). The earlier release 1.1.0 does **not** include the MCP server. **Transport**: STDIO JSON-RPC 2.0 (HTTP/SSE transport is not implemented) **SDK Requirement**: `mcp>=1.28,<2` (Optional dependency group: `mcp`) **Validation**: Verified with the MCP Python SDK (in-process tool calls) and a raw JSON-RPC STDIO handshake (`initialize`, `tools/list`, `tools/call`) in the test suite. **Not yet validated in a live Claude Code, Cursor, Cline or Windsurf session**; the client configuration examples below follow each client's documented MCP configuration format. @@ -30,13 +30,15 @@ pip install "reponeedle[mcp]>=1.2.0" ``` > [!NOTE] -> 1.2.0 is **upcoming**. Until it is published on PyPI, the command above cannot be resolved (1.1.0, the latest version on PyPI until then, contains neither the MCP server nor the `mcp` extra). In the meantime, install from a clone: -> -> ```bash -> git clone https://github.com/krishika08/RepoNeedle.git -> cd RepoNeedle -> pip install -e ".[mcp]" -> ``` +> 1.1.0 contains neither the MCP server nor the `mcp` extra. The `>=1.2.0` pin also upgrades an existing 1.1.0 installation. + +For local development, install from a clone: + +```bash +git clone https://github.com/krishika08/RepoNeedle.git +cd RepoNeedle +pip install -e ".[mcp]" +``` To verify that the MCP server executable is available: diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 623eaea..17ba9b3 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -1,6 +1,6 @@ # RepoNeedle Research & Engineering Roadmap -This roadmap is grounded in empirical limitations observed during benchmark evaluations. Status labels distinguish what has been **released**, what is in the **upcoming 1.2.0** release (this repository's current version; PyPI publication pending), and what is **not implemented**. +This roadmap is grounded in empirical limitations observed during benchmark evaluations. Status labels distinguish what has been **released** (1.1.0 and 1.2.0) and what is **not implemented**. *Last reconciled with the source code: 2026-11-10.* @@ -17,7 +17,7 @@ This roadmap is grounded in empirical limitations observed during benchmark eval - [x] Selective abstention heuristic, **always on in 1.1.0**. It is **experimental and uncalibrated**: on the ARB v2 selective split it correctly abstained on **0 of 82** no-gold queries. - [x] Hugging Face release assets prepared in `hf_artifacts/` (dataset card, Gradio Playground Space bundling the 1.1.0 engine, where abstention is always on). -## Upcoming: RepoNeedle 1.2.0 (PyPI publication pending) +## Released: RepoNeedle 1.2.0 (PyPI, 2026-11-12) - [x] CLI machine-readable output (`--json`) and anchor files (`--anchors`). - [x] Native MCP server over STDIO (`reponeedle-mcp`, optional `mcp` extra) with `reponeedle_retrieve`, `reponeedle_change_impact` and `reponeedle_inspect`. Verified with the MCP Python SDK and a raw JSON-RPC STDIO handshake; **not yet validated in a live Claude Code or Cursor session**. - [x] Experimental abstention made **opt-in (disabled by default)**, with explicit diagnostics (`experimental: true`, `calibrated: false`) on every result.