How requests become records¶
bharat-judgements has two data paths: live portal clients and a historical archive client. The Judgments facade chooses between them for supported judgment queries and returns a common model.
01 / Choose an entry point¶
Use Judgments.find for structured archive research or a default live High Court text query. Use a portal-specific client for CNR case details, orders, cause lists, SCR pagination or the SCI recent feed. Use ArchiveClient directly for streaming and cache operations.
The routing decision is determined by query shape. It is not a freshness detector and does not automatically fall back when a result is empty. See the routing table.
02 / Query the selected source¶
Live portals¶
Each client owns the session state required by its portal: cookies, CAPTCHA responses, rotating tokens and, for district courts, discovered anti-bot headers. Most live clients accept a solver; SCIClient reads the recent homepage feed without one.
RateLimitedClient provides request spacing, timeouts and retries for selected transport failures and server errors. Portal CAPTCHA retries have separate finite budgets. HTTP 4xx errors are not retried by the shared transport.
The live transport verifies TLS certificates by default. Set BHARAT_JUDGEMENTS_VERIFY_SSL=false only for a known portal certificate problem; verification is never silently disabled.
Historical archive¶
DuckDB queries metadata in the public S3 datasets. Court and year filters can reduce the partitions scanned. Bounded metadata queries can reuse locally cached parquet files; PDFs and SCI yearly language tars use a separate cache.
The archive uses its own HTTP client and does not use the live request-delay setting. Dataset update frequency and local metadata age both affect freshness.
03 / Parse a typed record¶
| Result | Meaning |
|---|---|
CaseInfo | Basic search metadata |
CaseDetail | Richer CNR case page, including published history and orders |
CaseOrder | An order with available date, type and PDF reference |
CauseListPDF | High Court list PDF link |
CauseListEntry | A structured listing entry |
JudgmentResult | Original live judgment/feed result |
Judgment | Common judgment metadata from the archive or facade |
SearchResult | Live judgment search page and pagination metadata |
These models preserve missing fields rather than inventing values. Dataclass serialisation converts dates to strings and binary PDF values to null; exclude_none=True omits null fields. See model reference.
04 / Retrieve the document¶
Live judgment PDFs require the original JudgmentResult and session continuity. Archive PDFs use a stored reference or CNR lookup. SCI archive retrieval may download a whole yearly tar, while High Court archive PDFs are fetched individually.
A common Judgment does not erase backend differences: a live facade result cannot be downloaded through Judgments.fetch_pdf. Use the direct judgment client.
Where an assistant fits¶
The skill bundle gives an assistant instructions for choosing SDK and CLI operations. The assistant still needs execution permissions, dependencies and source connectivity. Its interpretation of fetched records is separate from the SDK's retrieval.
The repository supplies a local stdio MCP server and Docker image. See Docker MCP for tools, limits, errors and provenance. No hosted assistant service is provided.
Next: source coverage, configuration, or API reference.