Spaces:
Running on Zero
Running on Zero
| # Free public deployment | |
| Hosting endpoints: | |
| - [PrecedentAI website](https://precedent.lothnic.dev/chat) | |
| - [Backend Space and build logs](https://huggingface.co/spaces/lothnic/precedentai) | |
| The current deployment separates the web app from its large Python runtime: | |
| - Vercel hosts the TanStack Start frontend and its same-origin `/api/*` proxy. | |
| - Hugging Face hosts the Gradio Server wrapper on the free `zero-a10g` tier. The existing FastAPI application is mounted at `/backend`. | |
| - A private Hugging Face dataset holds the complete corpus and hybrid index. A read-only repository volume is pinned to the artifact commit. Public PDF archives are downloaded from their separately pinned upstream revisions. | |
| - Retrieval runs on CPU. The selected inference provider supplies answer generation through the OpenAI-compatible client. Ordinary chat does not allocate a GPU. This keeps LangGraph conversation and approval state in one process. | |
| The release contains 22,416 selected Supreme Court judgments/orders from 1950–2025 and 516 constitutional source units from the official 1 May 2026 edition. The four indexes contain 967,053 passages in total. Constitutional units include omitted provisions and reference Appendices; this is neither an in-force Article count nor comprehensive coverage of Indian courts and legislation. Runtime data occupies about 22.74 GiB including retained source PDFs. Startup verifies file sizes and SHA-256 hashes, preserves index freshness metadata, checks vector/registry counts, and warms the embedding model before serving research. It never replaces the corpus with the test fixture. | |
| ## Accounts and initial setup | |
| This path needs no credit card. A free Hugging Face account must qualify to create a ZeroGPU Space (verified email, account older than 30 days, available Space allowance). The platform accepted this account and created `lothnic/precedentai`. A Vercel personal account hosts `precedentai`. | |
| ```sh | |
| hf auth login | |
| vercel login | |
| hf repos create YOUR_NAME/precedentai --type space --space-sdk gradio --flavor zero-a10g --public --exist-ok | |
| ``` | |
| Install the Python project with its serving, ML and LLM dependencies. Configure the selected provider and its working key locally before uploading (see [LLM setup](setup.md#llm-stage-groq-openai-nvidia-agentrouter)). Stop processes that write to the corpus or index, checkpoint SQLite, and then run: | |
| ```sh | |
| uv run --extra serve --extra ml --extra llm python scripts/deploy_hf_space.py \ | |
| --space YOUR_NAME/precedentai --artifacts YOUR_NAME/precedentai-rag | |
| ``` | |
| The script uploads only allowlisted release artifacts to a private dataset, bundles their manifest with the Space code, mounts the dataset at the immutable commit, and sets the Space secrets and public configuration. Interrupted artifact uploads can resume. `--prepare-only` checks and stages the release without uploading. No raw training/data directory is published in the public Space repository. | |
| The deployed artifact release remains `35c80a7515dd216516b9ffc8fdba20671214c908`. | |
| The current 8 October approval-receipt release is backend code | |
| `8e0740261575a304290a8b6f6a28b2ec4c8284e5`, using the same immutable artifact. | |
| The private Supabase approval migration is applied. Loaded four-index/storage | |
| readiness and the metadata receipt route pass without a model call; see | |
| [approval receipts](v2-approvals.md) and `data/eval/v2_approval_backend_checks.json`. | |
| The preceding source-identity release was backend code | |
| `d637f7f6f0767138d38acc99dfc192de530186fb`. | |
| Its full registry audit and live document/readiness checks are recorded in | |
| `data/eval/v2_document_identity_audit.json` and | |
| `data/eval/v2_document_identity_backend_checks.json`. Source readers expose whether | |
| reported docket groupings have been checked against the retained PDF; distinct | |
| document IDs remain unchanged. See [source identity review](v2-source-audit.md). | |
| The preceding 8 October feedback release is backend code | |
| `df1329e77d60e290e4c656301e376591bfa521c8`, using the same immutable artifact. | |
| Loaded index/storage checks are recorded in `data/eval/v2_feedback_backend_checks.json`; | |
| feedback uses the dedicated private Supabase table migrated through the CLI. | |
| The preceding 8 October candidate-selection release is backend code | |
| `254f1494d46faa88ade061e76dfa517e16826cbd`, using the same immutable artifact. | |
| Its frozen-query comparison is recorded in `data/eval/v2_candidate_relevance_checks.json`; | |
| fresh hosted relevance acceptance is recorded in `data/eval/v2_candidate_relevance_hosted.json`. | |
| The anticipatory-bail probe returns relevant Chidambaram/Sushila Aggarwal passages; | |
| it does not verify a synthesized legal answer or the full v2 quality gates. The preceding trace/tie release | |
| is `007c4cdeee6f8ca707d53309799d5a181dd7b0a7`, and bounded admission was published | |
| at `85499f8cbad81e25f2fd113527917a73b20d7479`. The earlier source-readiness update is backend code | |
| `5a5a84f93cca14f3e9e6435dbb640a69a9cf8d5a`; actual public four-index and | |
| private-storage probes are recorded in `data/eval/v2_readiness_checks.json`. | |
| The preceding API-contract update is backend code | |
| `4f5dcf54e6b47a4dc8d1ce6a71e0ee4665b4a973`; its read-only release verification | |
| is recorded in `data/eval/v2_api_contract_checks.json`. The preceding answer update is | |
| backend code | |
| `96b4bf5f87d31eb8afd555fcd8c4085475b7fbf2`; its acceptance is recorded in | |
| `data/eval/v2_statutory_scope_checks.json`. The preceding date/context release | |
| `51528145bf7aef448a198564f5f6b60a6eedb1c5` remains documented in | |
| `data/eval/v2_named_decision_date_checks.json`. Vercel deployment | |
| `dpl_8wMp53Pd3nvTafZwqQ4WfPCbXk6Q` serves the custom domain with single-use | |
| review IDs and receipt privacy notices, alongside accessibility | |
| corrections, source-identity disclosures, feedback/support, the | |
| loaded-readiness badge and Google-only sign-in. Public Google handoff and | |
| desktop/mobile guest checks pass (`data/eval/v2_oauth_configuration_checks.json`). | |
| The preceding accessibility frontend was `dpl_GAVycfPnxxLosei6k4ceX8fsfypj`. | |
| Actual read-only approval proxy and served-bundle checks are in | |
| `data/eval/v2_approval_deployment.json`. | |
| The preceding source-identity frontend was `dpl_2F4XpkHRQ4BySRe6fLhUQAvgEKSV`. | |
| Accessibility evidence is recorded in `data/eval/v2_accessibility_checks.json` and | |
| `data/eval/v2_accessibility_deployment.json`; physical devices and real screen-reader | |
| sessions remain separate from local browser and hosted asset/API checks. | |
| The preceding feedback frontend was `dpl_79VVidW8ndwnyTCa8T7UCk99Qj4j`. | |
| The preceding source-log privacy frontend was `dpl_2oAQZ65mH6EV3j9qiWhYinVdmHvE`. | |
| The preceding candidate/readiness frontend was `dpl_3ncM5yN5JdDLrYCg4UFvtHMCtoCJ`; | |
| the earlier readiness frontend was `dpl_Ej4bSjr9mUUuG6e1zSDYQoUcvZsq`. | |
| The preceding Google-only frontend was `dpl_9KAawB9trzwPrsT4LoTPrCDB28oe`. | |
| The prior frontend was | |
| `dpl_Fz9qM7KJEM7Lr5DTCjaUAwEg5jLi`. Supabase activation used | |
| `dpl_3uJfAgGP3mdzFYBwJoCh1xHhxLK3` | |
| (`data/eval/v2_supabase_deployment.json`). The preceding 7 October | |
| Constitution release used backend `b5691561721db72b6b264cdb6c2f03d41823c349` | |
| and Vercel `dpl_HA5mPnctRtcpktp5sEue4cwjXywM`. | |
| The running Space landing page links to the custom domain. If the default transfer | |
| repeatedly stalls on a particular network, `HF_HUB_DISABLE_XET=1` selects Hugging | |
| Face's compatible LFS transfer path. This changes transfer behavior, not the | |
| verified artifact contents. | |
| The generated proxy key is stored locally in `deploy/.generated/hosting.env` with mode `0600`; that directory is ignored by Git. Keep it private. The runtime does not need a personal Hugging Face access token: the platform mounts the private dataset using the owner's identity. | |
| ### Routine code releases | |
| Frontend source is tracked in `web/` beside the Python backend. For an existing | |
| Space, first stage code against its current immutable artifact release: | |
| ```sh | |
| .venv/bin/python scripts/deploy_hf_space.py \ | |
| --space lothnic/precedentai --artifacts lothnic/precedentai-rag \ | |
| --code-only --prepare-only --output deploy/.generated/code-release | |
| ``` | |
| The command checks the live Space settings, bundled manifest and pinned dataset | |
| manifest, then prepares allowlisted code and writes `code-release.json` with file | |
| hashes. It does not build, upload or change the corpus. After local verification, | |
| run the same command without `--prepare-only` to publish code with a parent-commit | |
| guard against a concurrent code release. Existing secrets, artifact mounts and | |
| hardware are preserved. Wait for readiness and verify actual answers, storage and | |
| coverage before the frontend release: | |
| ```sh | |
| cd web | |
| bun run typecheck | |
| bun run test:auth | |
| bun run build:vercel | |
| vercel deploy --prod --yes | |
| ``` | |
| Use a regular remote Vercel build for production so deployment settings provide | |
| server credentials. A local build verifies packaging; its environment is not | |
| automatically suitable for production. Record returned web/backend revisions, | |
| retain the preceding release and run public acceptance. Code-only preparation | |
| was verified against the live pinned release on 8 October 2026. Broader release | |
| automation, generated API types and a hosted rollback drill remain open. | |
| ### V2 candidate releases | |
| The live public beta now uses a schema-2 catalog with the primary case corpus, | |
| the 1950 and 1973–1978 supplements, and the Constitution. This deployment does | |
| not complete every v2 milestone or establish practitioner-accepted legal quality. | |
| See [the Constitution guide](constitutional-corpus.md) and | |
| [the discovery release commands](v2-discovery.md#serving-additional-batches). | |
| `--prepare-only` validates and stages a candidate; `--artifacts-only` publishes | |
| its immutable private artifact revision without touching the live Space. Use a | |
| separate output directory under `deploy/.generated` to retain the baseline. | |
| The schema-2 manifest declares each corpus, registry identity, vector collection, | |
| document/passage count and combined coverage. Startup verifies all of them before | |
| serving research. Schema 1 remains accepted and explicitly clears supplement and | |
| v2-discovery settings when restored. The source archives are selected from the | |
| retained documents rather than a hardcoded year range, including historical PDFs. | |
| The current release was prepared with all three `--supplement NAME CORPUS INDEX` | |
| arguments. A no-flag deployment creates a primary-only release, so preserve those | |
| arguments when updating the expanded catalog. Parallel MCP recovery is enabled | |
| with `LEGAL_AI_ENABLE_WEB_FALLBACK=true` and a shared cap of 60 external HTTP | |
| attempts per rolling day. It uses anonymous access and no paid API fallback. | |
| Before promotion, retain the production identifiers and backend code recorded in | |
| `data/eval/v2_release_baseline.json`. Restore backend code, artifact variables and | |
| the read-only mount to that same baseline together if rollback is needed. The | |
| corresponding immutable Vercel deployment is recorded there too. Local restoration | |
| and rollback checks do not replace an actual hosted rollback/performance check. | |
| ## Frontend | |
| In `web`, link the Vercel project and configure **server-only** environment variables for both preview and production: | |
| - `BACKEND_URL=https://YOUR_NAME-precedentai.hf.space/backend` | |
| - `BACKEND_API_KEY` equal to the generated proxy key | |
| Use Vercel's environment settings or `vercel env add` with secure input. Do not use `VITE_*` variables for these secrets. Deploy with `vercel deploy`, verify the preview, and publish with `vercel deploy --prod`. The configured build command uses Nitro's Vercel preset. The frontend stays in its separately managed local checkout. | |
| The proxy creates an HMAC-signed, HttpOnly, SameSite cookie and supplies the secret and browser session to the backend. Each session's thread names are isolated, including draft approvals. Direct unauthenticated backend access is rejected; `/backend/health` is public liveness. The browser receives no API key. Successful API responses and conversation history are not cached. | |
| Optional [Google account login](authentication.md) uses encrypted Auth.js cookies. Verified sign-ins now resolve a stable UUID in the dedicated Supabase account database; guests continue using the signed browser session. Google is configured; its external audience and successful real login returning to signed-in chat are owner-confirmed on 8 October 2026. GitHub is deferred at the owner's request. Existing sessions need a fresh sign-in for the database identity. Browser history stays separate by account; signed-in users can explicitly enable and save private copies for another browser. Nothing uploads automatically. See [accounts and saved history](v2-accounts.md). | |
| Connection status retries after a cold start. An unsupported streaming endpoint can fall back to `/chat`; busy responses and interrupted streams are not automatically resubmitted, which prevents duplicate graph turns. The backend releases the research slot when the final response body is sent. | |
| ## Verification and limits | |
| Check the Space build and application logs with `hf spaces logs YOUR_NAME/precedentai` and its status with `hf spaces info YOUR_NAME/precedentai --expand runtime`. Wait for the full RAG readiness log before publishing the frontend. Confirm `/api/health` reports the fused backend and enabled LLM, and `/ready` confirms the configured indexes and private storage. Exercise a greeting, a source-linked research question, a PDF link, and a draft approval from the deployed website. | |
| The 9 October answer-checking release is backend | |
| `f8135ff6e5d714bd3ec21fd3913ff2eacbe84777`, using the existing immutable | |
| artifact `35c80a7515dd216516b9ffc8fdba20671214c908`. Frontend | |
| `dpl_Cn8QwcJRjuAstr7DyBWP6uETsYEd` is unchanged. Only the answer/support modules | |
| changed: strict checker response schema and a bounded provision-scope wording | |
| guard. The regular suite remains 176 passes/two skips; an actual one-call, | |
| 1,595-token provider checker diagnostic passes. That diagnostic checks one | |
| qualified claim against an exact retained source window, not a new hosted answer | |
| or automatic correction. See `data/eval/v2_answer_reliability_checks.json` and | |
| the separately scoped `data/eval/v2_answer_reliability_backend_checks.json`. | |
| The 7 October 2026 release verified 62 private artifact entries through remote | |
| LFS hashes or downloaded small-file hashes before promotion. The live runtime | |
| reported 22,932 source documents and all four catalog identities. The public | |
| website streamed a synthesized answer to the user's religion question, with | |
| citations to Articles 25–28 and a visible personal-law statute coverage gap. | |
| Canonical Article 25 metadata and the original PDF's exact SHA-256 matched the | |
| retained edition. Direct unauthenticated source requests returned 401. Three | |
| existing auth tests passed with stubbed OAuth; Google configuration was retained, | |
| but a new real-provider sign-in was not exercised. Startup emitted two ignored | |
| asyncio event-loop cleanup warnings after readiness; the catalog and live chat | |
| requests passed. These are deployment smoke checks, not legal-quality acceptance. | |
| Desktop/mobile browser checks on the public domain also passed for answer-first | |
| formatting, the edition-aware Constitution reader, exact quote highlights and | |
| the physical PDF page link. They replayed the actual public response and made no | |
| additional inference requests. The release report is | |
| `data/eval/constitution_deployment.json`. | |
| Initial release validation: 114 Python tests passed, with two optional model-integration tests skipped. The deployed API passed conversation-memory and session-isolation checks, SSE research with generated citations, byte-for-byte PDF hash verification, and the cross-session approval guard. The final research smoke request completed in about 5.5 seconds; this is one observation, not a latency guarantee. Frontend builds, type checks, desktop/mobile layout checks, and the busy/unsupported-stream retry scenarios also passed. A final browser check submitted a real research question on the public site and rendered the response on desktop and mobile without page errors or horizontal overflow. | |
| This is a public beta, with shared free-provider capacity rather than an uptime guarantee. The default safeguards serialize graph turns and allow ten turns per guest browser session or signed-in account per hour and thirty total turns per day. Busy or quota-limited requests return a readable message. These limits are configurable through `LEGAL_AI_PUBLIC_REQUESTS_PER_HOUR` and `LEGAL_AI_PUBLIC_REQUESTS_PER_DAY`. | |
| The Space's writable disk is ephemeral. Restarting it restores the verified release | |
| and clears default/guest RAM conversation state. Since 8 October 2026, protected | |
| requests, provider budgets, stable account identities and optional saved copies | |
| use private Supabase PostgreSQL storage. Approval receipts preserve consumed | |
| decisions separately. The 9 October recovery update adds default-off, bounded | |
| 24-hour checkpoints for signed-in users; see [temporary recovery](v2-recovery.md) | |
| for activation evidence and limits. Saved copies remain transcript-only. Prior | |
| RAM usage was not imported at cutover. Hosted scheduled/off-site backups, | |
| request-specific response replay and recovery drills remain unfinished. HF | |
| sleep/cold starts and free inference quotas can delay or limit service. Full v2 | |
| quality and operational gates remain open. | |
| The AgentRouter deployment uses `deepseek-v4-flash` for generation and answer checks. The preceding Groq configuration preferred `openai/gpt-oss-120b` and used `openai/gpt-oss-20b` when the preferred model returned HTTP 429. The fallback is optional in local configuration (`LEGAL_AI_LLM_FALLBACK_MODEL`) and stays on the same provider and account. Both models are listed in Groq's [free plan limits](https://console.groq.com/docs/rate-limits). Calls record the model actually used. SDK retries are disabled because the application already bounds retries; authentication errors never trigger a model switch. If generation remains unavailable, the app serves source excerpts instead. Citation checks establish provenance, not the correctness of every legal claim; drafts still require qualified review. Smoke tests exposed incorrect date attribution in generated privacy-law analysis despite valid source links. Treat claim/date verification as a remaining RAG quality gap, and do not describe this beta as providing legally verified answers. | |
| NVIDIA is also supported. To activate it on the existing Space, add a server-side | |
| `NVIDIA_API_KEY` secret and set `LEGAL_AI_LLM_PROVIDER=nvidia` plus | |
| `LEGAL_AI_LLM_MODEL=deepseek-ai/deepseek-v4.1-flash`. Clear | |
| `LEGAL_AI_LLM_FALLBACK_MODEL` and `LEGAL_AI_LLM_BASE_URL` when switching from | |
| Groq; NVIDIA supplies its own default endpoint. See [LLM setup](setup.md#llm-stage-groq-openai-nvidia-agentrouter). | |
| Full publication reads the selected local provider, publishes its matching key | |
| as a Space secret, and preserves any configured same-provider fallback and | |
| endpoint override. The automatic `openai/gpt-oss-20b` deployment fallback applies | |
| only to Groq. A code-only release preserves the active provider and secrets. | |
| AgentRouter can be selected on the existing Space after publishing its provider | |
| support. Add `AR_API_KEY` as a server-side Hugging Face Space secret, then set: | |
| ```dotenv | |
| LEGAL_AI_ENABLE_LLM=true | |
| LEGAL_AI_LLM_PROVIDER=agentrouter | |
| LEGAL_AI_LLM_MODEL=deepseek-v4-flash | |
| LEGAL_AI_LLM_FALLBACK_MODEL= | |
| LEGAL_AI_LLM_BASE_URL= | |
| ``` | |
| Use a model ID enabled for the AgentRouter account. The current integration | |
| defaults to `https://agentrouter.org/v1`; an explicit base URL overrides it. | |
| It retains the provider-specific User-Agent from `tools/llm_client.py`. | |
| `LEGAL_AI_AGENTROUTER_API_KEY` is an alternative scoped secret. Keep keys in | |
| Space secrets and never in public variables or frontend `VITE_*` settings. | |
| Code-only publication preserves the existing provider settings, so activating | |
| AgentRouter requires updating these Space variables separately. Verify a real | |
| hosted research turn and inspect provider usage after the restart. | |
| Answer prompts include passage text, source identity, and legal date/role caveats. File hashes, archive paths, and PDF links stay in server-side provenance and the response, reducing generation tokens without removing the evidence or source-reading capability. | |
| The repository's Dockerfile and systemd unit remain alternatives for users with an appropriate paid host or VM. They are not required for this no-card setup. Free-tier eligibility and allowances can change; check the [Hugging Face Spaces documentation](https://huggingface.co/docs/hub/spaces-overview), [repository volumes](https://huggingface.co/docs/hub/spaces-storage), and [Vercel Hobby documentation](https://vercel.com/docs/plans/hobby) before creating another deployment. | |