Choose a CAPTCHA solver¶

CAPTCHA-gated live clients accept a CaptchaSolver. The default tries bundled OCR support when installed, then falls back to manual input. Archive queries and the SCI recent feed do not require a CAPTCHA.

Default OCR workflow¶

python -m pip install "bharat-judgements[ocr]"

OCRCaptchaSolver uses ddddocr and its bundled model. No bharat-judgements API key is required. OCR can return a wrong or empty answer, so finite retries remain part of the live lookup. Installing an extra is not a guarantee that every portal CAPTCHA will be solved.

For explicit construction, import OCRCaptchaSolver from bharat_judgements.captcha.ocr and pass it as captcha_solver to a CAPTCHA-gated client. preprocess and threshold are optional OCR preprocessing controls; start with defaults.

Manual input¶

Without OCR, ManualCaptchaSolver saves the image to a temporary PNG, attempts to open it, and asks for input on standard input. A callback can supply the answer instead, for example in an application with its own image display.

import asyncio
from bharat_judgements import HCServicesClient, get_court
from bharat_judgements.captcha.manual import ManualCaptchaSolver


async def main():
    solver = ManualCaptchaSolver()
    async with HCServicesClient(captcha_solver=solver) as client:
        records = await client.case_status_by_party(
            get_court("delhi"), party_name="tata", year="2024"
        )
        print([record.to_dict(exclude_none=True) for record in records])


asyncio.run(main())

Manual input needs an interactive environment. An unattended assistant or CI job may block waiting for it. Provide automatic solving or a callback for that workflow.

ONNX alternative¶

python -m pip install "bharat-judgements[onnx]"

Construct ONNXCaptchaSolver(model_path=...) with a compatible local model, or omit model_path to use its model download. The default Hugging Face repository may require access approval and an HF_TOKEN environment value. Model access and optional dependencies are separate from the SDK's installation.

Pass this solver explicitly to the client: default discovery prefers OCR and does not select ONNX. Inspect the solver API before supplying a custom model.

Custom solvers¶

Implement the async CaptchaSolver.solve(image_bytes) method and return the recognised string. The callback or service you choose controls where the image is sent and any associated charges. Keep that data flow explicit in your application.

Understand retry budgets¶

HC Services and district clients use BHARAT_JUDGEMENTS_CAPTCHA_ATTEMPTS (default five, maximum ten). Judgment and Calcutta lookups expose a max_captcha_attempts argument. The CLI --captcha-attempts option sets the shared HC/district configuration and is passed to judgment and Calcutta lookups.

Retries re-establish session state where required. An exhausted budget raises a failure rather than a successful empty result. A malformed portal response or bad query is not automatically a CAPTCHA problem.

Next: solver reference, live clients, or configuration.