# 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.