docs/deployment.md

Free public deployment

Hosting endpoints:

• PrecedentAI website
• Backend Space and build logs

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.

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). Stop processes that write to the corpus or index, checkpoint SQLite, and then run:

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

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

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 and the discovery release commands. --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 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.

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

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, repository volumes, and Vercel Hobby documentation before creating another deployment.