Contribute to bharat-judgements¶

Keep changes grounded in the portal behaviour and data models they affect. Reproduce a problem with a fixture or bounded query, then verify the smallest change that fixes it.

Set up a development environment¶

You need Git and Python 3.11 or newer. Repository access is required for this checkout.

git clone https://github.com/hhftechnology/bharat-judgements.git
cd bharat-judgements
python -m venv .venv

Activate the environment using the shell-specific installation instructions, then install development dependencies:

python -m pip install -e ".[cli,archive,dev]"

Add ocr or onnx when testing those optional solvers. .[all] installs every extra, including model runtime dependencies; it is not required just to build the docs.

Understand the source layout¶

Area	Responsibility
`facade.py`	Query routing and common judgment results
`hcservices/`, `districtcourts/`, `calcuttahc/`, `judgments/`, `sci/`	Portal-specific clients, endpoints and parsing
`archive/`	Metadata queries, caching, PDF storage and schema mapping
`models.py`, `courts.py`	Result models and court registry
`captcha/`	Solver interface and optional implementations
`cli.py`, `skill/`	Commands and assistant instructions

Use async context managers to close clients. Keep portal identifiers and session details in their source-specific layer. Preserve missing data rather than manufacturing values in a parser.

Run offline checks¶

pytest
ruff check .
ruff format --check .

Unit tests use fixtures and mocked HTTP. Optional-dependency tests may require their corresponding extras. The scripts under tests/integration/ make live requests and are not collected as ordinary unit tests. Run them deliberately, accounting for CAPTCHA input, source availability and download size.

For parser changes, add a minimal fixture that captures the response shape and the failing assertion. For routing or cache changes, test the source choice, empty-result behaviour and error path rather than relying on live services.

Build the Field Guide¶

python -m pip install -r requirements-docs.txt
mkdocs build --strict
mkdocs serve

Mkdocstrings reads the source statically; optional runtime dependencies are not needed for generated API pages. Review both themes, a narrow viewport, search, keyboard focus, code copying and API signatures after changing templates or styles.

The site uses shared Field Guide tokens in its extra stylesheet and the existing Material components. Keep route paths stable, retain native interactions and use accurate metadata. Set site_url only after verifying the actual publishing address; this repository has no configured public Pages address at the time of the rebrand.

Propose a change¶

Describe the concrete problem, the resulting behaviour and the checks you ran. Attach a fixture or clear reproduction without private matter data. Distinguish a successful empty response from a transport or CAPTCHA failure.

When adding a capability, update the relevant guide, API reference selection, CLI help if exposed, and bundled skill instructions. Ensure examples use the real argument names and required extras.

Next: architecture, sources, or the repository.