[krishika08]

Summary

Upgrades the repository-managed demo artifacts from RepoNeedle 1.1.0 to 1.2.0:

• the engine bundled in hf_artifacts/space/;
• the Gradio Space;
• the static Space;
• the Render demo API (api.py);
• the Hugging Face release script;
• the deployment documentation.

Nothing was uploaded or deployed. No Hugging Face repository or Render setting was changed. The live services still run 1.1.0.

Important

Merging this PR may deploy the API. Render builds the demo API from main. If auto-deploy is enabled for that service (I can't see Render settings from here), merging will redeploy https://reponeedle.onrender.com with 1.2.0. That API is backward compatible with the current static Space: the request field is optional, and the response field is additive. The two Spaces are never auto-deployed; they need manual uploads.

Bundled engine sync

	Before	After
hf_artifacts/space/reponeedle/__version__	1.1.0	1.2.0
Files differing from reponeedle/	5 (__init__.py, cli.py, core/abstention.py, engine.py, models.py)	0. Staged git blobs are identical for all 18 files.
reponeedle/mcp/	not bundled	not bundled (intentional; the demo doesn't need the MCP SDK)

The demo runs the bundled engine in a fresh process: api.py and app.py both put hf_artifacts/space first on sys.path. Results for all Space examples through the API, before and after the sync:

Example	1.1.0 bundle	1.2.0 bundle (default)	1.2.0 + explicit opt-in
5 non-selective examples (Flask and Requests, legacy and change_impact)	RETRIEVED CONTEXT	RETRIEVED CONTEXT, identical files and token counts	—
Selective "Cargo.toml" example (out of scope)	ABSTAINED (heuristic always on)	RETRIEVED CONTEXT (heuristic off by default)	ABSTAINED, same confidence (0.4099)

Changes

• Demo API (api.py)
  • /, /health and the OpenAPI version come from the imported engine's reponeedle.__version__; there are no hard-coded copies.
  • New optional request field enable_experimental_abstention (default false). New additive response object abstention = {enabled, status, experimental: true, calibrated: false}.
  • Unchanged: endpoint paths, the two demo repositories, query, budget and seed validation, and CORS.
  • HTTP 500 responses now return a generic message; exception details go to the server log only. Previously the exception text was returned, which could include paths.
• Gradio Space (hf_artifacts/space/)
  • V1.2.0 labels.
  • New Enable experimental abstention (opt-in) checkbox, value=False, with an experimental/uncalibrated disclosure (0 of 82 on the ARB v2 selective split).
  • Only the selective example opts in, and it does so explicitly. The status panel always states whether abstention is on.
  • README scope note: the demo ranks embedded documents in memory, so it doesn't exercise 1.2.0's filesystem link protections or indexing diagnostics, and it doesn't include the CLI JSON or MCP features.
  • requirements.txt gains fastapi<0.113 (see below). Gradio sdk_version 4.29.0 is unchanged.
• Static Space (hf_artifacts/static_space/)
  • V1.2.0 title, badge and footer.
  • Opt-in checkbox, unchecked by default, sent as enable_experimental_abstention. The abstention status appears in the engine diagnostics.
  • The default API URL (https://reponeedle.onrender.com) and the editable URL field are unchanged, and so is the layout.
• scripts/prepare_hf_release.py
  • The expected version comes from pyproject.toml. The bundle must be file-for-file identical to the root package (minus mcp/), and its version must match.
  • Only the selected targets are validated. --space-only never touches the dataset, and --dataset-only / --space-only are mutually exclusive.
  • New guard: it refuses to upload the Gradio app into an existing Space whose SDK isn't gradio. Previously --org Krishikax would have pushed the Gradio README and app over the live static Space.
  • After uploading, it verifies that the repository head is the uploaded commit.
  • The token is never printed and is redacted from error messages. Any validation failure stops before a Hub client is created.
• Docs
  • docs/STATIC_PLAYGROUND_DEPLOYMENT.md now covers 1.2.0: components, Hugging Face repository IDs, how the static frontend, Render API and bundled engine fit together, the /health response, deployment order, the unchanged dataset, and the abstention default and limitation. The existing security and scope disclosures are kept.
  • HF_RELEASE_CHECKLIST.md: its dated note now says the Space bundled 1.1.0 when the note was added. The historical checklist itself is unchanged.

Gradio Space dependency issue (found during smoke testing)

With the current requirements.txt, the Gradio Space fails to start. Gradio 4.x raises TypeError: unhashable type: 'dict' from Jinja when serving its page, because unpinned FastAPI pulls Starlette 1.x. I reproduced this with Gradio 4.29.0 (the Space's sdk_version) and with 4.44.1. It is independent of the engine, so a fresh deploy of the old 1.1.0 Space would fail the same way. fastapi<0.113 (Starlette 0.38.6) fixes it on both versions.

Hugging Face repository IDs

ID	Evidence	Public state (read-only check on 2026-11-12)
Krishikax/RepoNeedle-Playground	README badge (line 8); CORS test origin krishikax-reponeedle-playground.hf.space	Exists, SDK static, running. Its index.html differs from main in one respect: the live API URL field has no default value.
RepoNeedle/RepoNeedle-Playground	README badge (line 7); default target of prepare_hf_release.py	Not found. Authenticated as Krishikax (a member of the RepoNeedle org), the Hub returns repository-not-found. The README badge currently points to a missing Space.
RepoNeedle/RepoNeedle-Bench	README badge; script default	Exists. Unchanged by this PR.
Render API https://reponeedle.onrender.com	index.html default; deployment doc	/health currently returns "version":"1.1.0"

Testing

Check	Result
Full suite (Windows, Python 3.12)	532 passed, 7 skipped (file-symlink creation not permitted on this host). That is 26 new tests.
tests/test_public_api.py	15 passed. Covers: /health = {"status":"ok","service":"reponeedle-demo-api","version":"1.2.0"}; / and OpenAPI report 1.2.0; a fresh process imports hf_artifacts/space/reponeedle at 1.2.0; both repositories retrieve; abstention disabled by default and evaluated on opt-in; explicit false = default; non-boolean flag → 422; a 500 doesn't leak details.
tests/test_hf_space_bundle.py	18 passed. Covers: bundle = root package; no mcp; versions match; divergence detected; line endings ignored; Gradio app smoke test in a fresh process (both repositories, default off, single explicit opt-in, unchecked checkbox); release script (no upload in check-only, token never printed, --space-only skips the dataset, static-Space guard, missing Space created as Gradio, head-commit verification, diverged bundle and version mismatch stop publishing).
Documentation consistency tests	19 passed
Gradio startup: real gradio==4.29.0 from requirements.txt, launched and called through gradio_client	5/5. Default calls retrieve with abstention disabled; the opt-in call abstains; the checkbox defaults to False. With unpinned FastAPI: startup failure (see above).
Static Space: index.html in headless Chrome (Playwright); the default API URL is routed to a local uvicorn api:app, so no live service was contacted	21/21. V1.2.0 title, badge and footer; default URL kept and editable; Connected · RepoNeedle API 1.2.0; default request sends false and returns context; opt-in sends true and abstains with a disclosure; psf/requests example works; no horizontal scroll at 390 px; no page errors; no other hosts requested.
prepare_hf_release.py --check-only --space-only (authenticated, read-only)	Local validation passed (bundle identical, 1.2.0). --org RepoNeedle: preflight succeeded; the Space doesn't exist yet. --org Krishikax: blocked by the new static-Space guard. Nothing created or uploaded. The token didn't appear in the output.
Python 3.10 path of read_project_version (tomllib unavailable)	Returns 1.2.0

Deployment after merge (manual steps, not done here)

1. Render API. It auto-deploys on merge if Render auto-deploy is on; otherwise deploy manually. Check GET /health → "version":"1.2.0".
2. Static Space Krishikax/RepoNeedle-Playground. Upload hf_artifacts/static_space/README.md and index.html manually, then check the page shows V1.2.0 and connects to API 1.2.0. This also restores the default API URL, which the live copy lacks.
3. Gradio Space (optional; it doesn't exist yet): python scripts/prepare_hf_release.py --check-only --space-only, then --space-only.
4. Dataset: no upload needed.

Not changed

• Retrieval, ranking, routing and packing code, the root package and its version, and the v1.2.0 tag.
• The dataset, benchmarks, CI workflows and requirements-api.txt.
• No upload, no deploy and no PyPI release.

Remaining unverified

• Whether Render auto-deploys on merge.
• That the live services become 1.2.0. Each must be checked after its own deployment.
• A real Hugging Face build of the Gradio Space (tested locally with the same pinned requirements).
• Live coding-client behaviour is out of scope.

🤖 Generated with Claude Code