diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index b6c0c49..4f5fa5e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -42,7 +42,7 @@ jobs: - name: Install dependencies run: | python -m pip install --upgrade pip setuptools wheel build - pip install -e ".[dev]" + pip install -e ".[dev,api]" - name: Run test suite run: | diff --git a/docs/STATIC_PLAYGROUND_DEPLOYMENT.md b/docs/STATIC_PLAYGROUND_DEPLOYMENT.md new file mode 100644 index 0000000..f46d14a --- /dev/null +++ b/docs/STATIC_PLAYGROUND_DEPLOYMENT.md @@ -0,0 +1,69 @@ +# RepoNeedle V1.1.0 public demo deployment + +This document describes the public demo deployment. It does not change the installation path for the core Python package. + +## Components + +| Component | Location | Purpose | +|---|---|---| +| Core engine | `reponeedle/` | CPU-first retrieval library and CLI | +| Static frontend | `hf_artifacts/static_space/` | Browser UI hosted by Hugging Face Static Spaces | +| Demo API | `api.py` | FastAPI wrapper exposing retrieval for the embedded demo corpora | +| Demo snapshots and bundled UI engine | `hf_artifacts/space/` | Small Flask and Requests snapshots and synchronized RepoNeedle package used by the API | +| Dataset | `hf_artifacts/dataset/` | Lightweight synthetic demonstration benchmark | + +## Deploy the API on Render + +Create a Web Service connected to this repository and use: + +- Runtime: Python 3 +- Branch: `main` +- Root directory: repository root (blank) +- Build command: `pip install -r requirements-api.txt` +- Start command: `uvicorn api:app --host 0.0.0.0 --port $PORT` +- Health check path: `/health` +- Instance: Free (optional; subject to provider limits) + +The API imports the embedded corpora and engine from `hf_artifacts/space/`. Do not remove that directory while deploying this backend. + +Verify `https://YOUR-SERVICE.onrender.com/health`. A healthy response is: + +```json +{"status":"ok","service":"reponeedle-demo-api","version":"1.1.0"} +``` + +## Deploy the frontend on Hugging Face + +Create a public Static Space. Upload the contents of `hf_artifacts/static_space/` to the Space root. The `README.md` front matter must retain `sdk: static`. + +The UI defaults to `https://reponeedle.onrender.com`. Users can change the Backend API URL field and click **Connect API** to use another deployment. + +## API contract + +- `GET /` returns service metadata and a scope disclosure. +- `GET /health` is the health check. +- `POST /api/retrieve` accepts `repo_name`, `ranker`, `task_mode`, `budget_tokens`, `seed_files`, and `query`. +- Supported demo repositories: `pallets/flask`, `psf/requests`. +- Supported rankers: `legacy` (default), `change_impact`. +- The API validates query length, budget limits, repository choice, and seed count using Pydantic. + +## Limitations and security boundaries + +- This is a public, unauthenticated demonstration API. Do not send secrets, proprietary source code, or personal data. +- CORS is open so the public Hugging Face frontend can call the API. This is not an authentication or abuse-prevention control. +- The API only retrieves from the two embedded demonstration snapshots. It does not index arbitrary repositories or expose a general upload endpoint. +- The API does not persist visitor queries. Its in-memory caches reset when the service restarts. +- Free hosting may sleep after inactivity and has limited CPU/RAM. Cold starts and request latency can vary. +- The dataset is a small synthetic demo dataset, not the complete Agent Retrieval Bench v2 corpus. +- Selective abstention is experimental and should not be presented as reliable; see `KNOWN_LIMITATIONS.md`. + +## Local development and tests + +Install the package and development/API test extras: + +```bash +pip install -e ".[dev,api]" +pytest -q +``` + +The API tests use FastAPI's `TestClient` and the public-demo corpus shipped with the repository. diff --git a/hf_artifacts/space/reponeedle/engine.py b/hf_artifacts/space/reponeedle/engine.py index 2dc061f..f5743ee 100644 --- a/hf_artifacts/space/reponeedle/engine.py +++ b/hf_artifacts/space/reponeedle/engine.py @@ -394,7 +394,11 @@ def retrieve( workflow_boosts = np.zeros(num_docs, dtype=np.float32) elif effective_ranker == "change_impact": - inferred_task = query_obj.task_type or TaskType.COMMENT2CONTEXT + if query_obj.task_type == TaskType.AUTO: + inferred_task, _ = self.router.classify_intent(query_obj) + else: + inferred_task = query_obj.task_type + ci_cfg = change_impact_config or getattr(self, "change_impact_config", None) or ChangeImpactConfig() ranked_indices, fused_scores, impact_exps = self.change_impact_ranker.rank_with_scores( self.docs, lex_scores, sem_scores, query_obj, config_override=ci_cfg diff --git a/hf_artifacts/static_space/README.md b/hf_artifacts/static_space/README.md new file mode 100644 index 0000000..ba07b7c --- /dev/null +++ b/hf_artifacts/static_space/README.md @@ -0,0 +1,29 @@ +--- +title: RepoNeedle Playground +emoji: 🪡 +colorFrom: blue +colorTo: indigo +sdk: static +pinned: false +license: mit +--- + +# RepoNeedle Playground (V1.1.0) + +This is the static browser interface for the RepoNeedle V1.1.0 public demonstration. It calls a separately hosted FastAPI service; the static Space does not execute the Python retrieval engine itself. + +**Live backend:** `https://reponeedle.onrender.com` +**Source repository:** https://github.com/krishika08/RepoNeedle +**Dataset:** https://huggingface.co/datasets/RepoNeedle/RepoNeedle-Bench + +## Demonstration scope + +The public Playground uses small embedded demonstration snapshots for `pallets/flask` and `psf/requests`. It does not clone arbitrary GitHub repositories, accept repository uploads, or reproduce the complete ARB v2 evaluation. Benchmark results described in the source repository were obtained in separate documented evaluations; this web demo is not itself a benchmark reproduction. + +The browser sends retrieval requests to the public API. Queries are processed in memory and are not persisted by the demo API. The API is unauthenticated and intended for demonstration use, not production workloads. The free backend may sleep after inactivity, causing a cold-start delay. + +## Reproducing the Space + +Upload `README.md` and `index.html` from this directory to a Hugging Face Space with the **Static** SDK. The interface is preconfigured with the public demo API URL; users can change the URL to point to their own deployment. + +See [deployment guide](https://github.com/krishika08/RepoNeedle/blob/main/docs/STATIC_PLAYGROUND_DEPLOYMENT.md) in the GitHub repository for backend deployment and configuration instructions. diff --git a/hf_artifacts/static_space/index.html b/hf_artifacts/static_space/index.html new file mode 100644 index 0000000..9d181e6 --- /dev/null +++ b/hf_artifacts/static_space/index.html @@ -0,0 +1,366 @@ + + + + + + + + RepoNeedle Playground · V1.1.0 + + + +
+
+
+
🪡
+
RepoNeedle
Repository context retrieval
+
+
PLAYGROUND · V1.1.0
+
+ +
+
+
A context-selection engine for coding agents
+

Find the code that
actually matters.

+

Explore token-budget-aware, workflow-adaptive repository retrieval. Compare RepoNeedle with classical BM25 and RepoMap-style PageRank, inspect selected files, and test the optional Change-Impact ranker.

+
+ +
+ +
+
BACKEND API URL
+ + +
Paste the public URL of the deployed Python API, then connect.
+
+ +
+
+

Configure retrieval

Choose a repository snapshot, ranking mode, workflow, and token budget.

+
+
+ + +
+
+
+ + +
+
+ + +
+
+
+ +
4,000 tokens
+
+
+ + +
Used by Change-Impact for seed-relative dependency scoring. Separate multiple paths with commas.
+
+
+ + +
+
+ + + +
+ +
Connect the API before running a query.
+
+
+ +
+
⌁
Your retrieval results will appear here.Connect the backend, enter a coding task, and run the query.
+
+
+
RETRIEVED CONTEXT
+
LEGACY
+
+
+
Files selected—
+
Tokens packed—
+
Confidence—
+
Latency—
+
+

ENGINE DIAGNOSTICS

+

SELECTED CONTEXT FILES

#File pathTierTokensScore
+

BASELINE COMPARISON

#RepoNeedleBM25RepoMap · PageRank
+

TOP FILE PREVIEW

No selected file to preview.
+
+
+
+ + +
+ + + + diff --git a/pyproject.toml b/pyproject.toml index 1caa19d..ae9ae9e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,6 +37,11 @@ dev = [ "pytest>=7.0.0", "pytest-cov>=4.0.0", ] +api = [ + "fastapi>=0.115,<1.0", + "httpx>=0.24", + "uvicorn[standard]>=0.30,<1.0", +] hf = [ "huggingface_hub>=0.20.0", "gradio>=4.0.0", diff --git a/reponeedle/engine.py b/reponeedle/engine.py index 2dc061f..f5743ee 100644 --- a/reponeedle/engine.py +++ b/reponeedle/engine.py @@ -394,7 +394,11 @@ def retrieve( workflow_boosts = np.zeros(num_docs, dtype=np.float32) elif effective_ranker == "change_impact": - inferred_task = query_obj.task_type or TaskType.COMMENT2CONTEXT + if query_obj.task_type == TaskType.AUTO: + inferred_task, _ = self.router.classify_intent(query_obj) + else: + inferred_task = query_obj.task_type + ci_cfg = change_impact_config or getattr(self, "change_impact_config", None) or ChangeImpactConfig() ranked_indices, fused_scores, impact_exps = self.change_impact_ranker.rank_with_scores( self.docs, lex_scores, sem_scores, query_obj, config_override=ci_cfg diff --git a/tests/test_public_api.py b/tests/test_public_api.py new file mode 100644 index 0000000..9560a17 --- /dev/null +++ b/tests/test_public_api.py @@ -0,0 +1,105 @@ +"""Integration tests for the public RepoNeedle demonstration API.""" + +import pytest +from fastapi.testclient import TestClient + +from api import app + + +@pytest.fixture(scope="module") +def client(): + with TestClient(app) as test_client: + yield test_client + + +def test_root_discloses_demo_scope(client): + response = client.get("/") + assert response.status_code == 200 + payload = response.json() + assert payload["name"] == "RepoNeedle Demo API" + assert payload["version"] == "1.1.0" + assert "Embedded demonstration snapshots only" in payload["disclosure"] + + +def test_health_endpoint(client): + response = client.get("/health") + assert response.status_code == 200 + assert response.json() == { + "status": "ok", + "service": "reponeedle-demo-api", + "version": "1.1.0", + } + + +def test_legacy_retrieval_contract(client): + response = client.post( + "/api/retrieve", + json={ + "repo_name": "pallets/flask", + "ranker": "legacy", + "task_mode": "auto", + "budget_tokens": 4000, + "query": "Find the implementation of Flask request dispatching and related tests.", + }, + ) + assert response.status_code == 200, response.text + payload = response.json() + assert payload["ranker"] == "legacy" + assert payload["task_type"] in {"comment2context", "code2test", "edit2ripple", "trace2code"} + assert payload["tokens_used"] <= payload["token_budget"] + assert isinstance(payload["selected_files"], list) + assert isinstance(payload["comparison"], list) + assert payload["preview"] is None or "content" in payload["preview"] + + +def test_change_impact_auto_infers_task_from_seed(client): + response = client.post( + "/api/retrieve", + json={ + "repo_name": "pallets/flask", + "ranker": "change_impact", + "task_mode": "auto", + "budget_tokens": 4000, + "seed_files": ["src/flask/sessions.py"], + "query": "Fix cookie attribute handling during session modification in SecureCookieSessionInterface.", + }, + ) + assert response.status_code == 200, response.text + payload = response.json() + assert payload["ranker"] == "change_impact" + assert payload["task_type"] == "edit2ripple" + assert "seed-relative dependency boosts" in payload["ranker_note"].lower() + assert payload["tokens_used"] <= payload["token_budget"] + selected_paths = [item["path"] for item in payload["selected_files"]] + assert selected_paths + # Seed File Suppression should keep the seed from occupying the first result. + assert selected_paths[0] != "src/flask/sessions.py" + + +def test_invalid_repository_is_rejected(client): + response = client.post( + "/api/retrieve", + json={"repo_name": "unknown/repository", "query": "find request handling"}, + ) + assert response.status_code == 422 + + +def test_out_of_range_budget_is_rejected(client): + response = client.post( + "/api/retrieve", + json={"repo_name": "pallets/flask", "budget_tokens": 100, "query": "find request handling"}, + ) + assert response.status_code == 422 + + +def test_cors_preflight_is_available(client): + response = client.options( + "/api/retrieve", + headers={ + "Origin": "https://krishikax-reponeedle-playground.hf.space", + "Access-Control-Request-Method": "POST", + "Access-Control-Request-Headers": "content-type", + }, + ) + assert response.status_code == 200 + assert response.headers.get("access-control-allow-origin") == "*"