Contributor Guidelines

Refer to AGENTS.md in the repository root for the authoritative contributor guide.

Validate documentation

Install the documentation dependencies and check for broken links, malformed docstrings, and other MkDocs warnings before submitting documentation changes:

uv sync --group docs
uv run mkdocs build --strict -d site

The generated site/ directory is gitignored. The Pages workflow runs the same strict build for documentation pull requests without uploading or deploying them. Tagged builds publish only after the strict build succeeds.

Updating dependencies safely

Use uv lock --upgrade-package NAME for targeted dependency updates, then validate with uv sync --locked --all-extras --dev and the relevant tests. Keep GitHub Actions pinned to full commit SHAs when updating their versions.

The lockfile protects repository environments, but PyPI installations use the package's published dependency metadata instead. Declare security minimums in project.dependencies when an upstream dependency still permits vulnerable transitive versions. Azure authentication requires pyjwt>=2.15.0 and urllib3>=2.8.0; notebook tooling requires tornado>=6.5.9 in the development dependency group. Keep notebook-only dependencies out of the runtime metadata.

urllib3 2.8.0 separates HTTPS forwarding-proxy TLS settings from destination settings. Configure proxy certificates through proxy_ssl_context and proxy identity checks through proxy_assert_hostname or proxy_assert_fingerprint; destination client certificates and identity overrides no longer apply to the proxy connection.

Publishing a package release

Once the intended changes are merged into main, create and push a vX.Y.Z tag pointing to that commit. The PyPI workflow checks the tagged commit on Python 3.10-3.12 with Ruff, Pyright, the full test suite, and a distribution build before publishing. The integration environment must provide OPENAI_API_KEY for the full suite; the pypi environment supplies the trusted-publishing configuration. After validation, the workflow checks that both distributions contain the version named by the tag, signs them, publishes them to PyPI, and attaches them to a GitHub Release with generated release notes. Confirm that the workflow, the PyPI version, and the Release assets all succeeded before announcing the release. The GitHub Release contains the wheel, sdist, and their cosign bundles; any .publish.attestation sidecars generated by the PyPI publishing action in dist/ are not GitHub Release assets.

If a tagged publish fails because the workflow itself needs repair, do not move or re-create the tag. Merge the workflow fix into main, then manually run Publish to PyPI from main, providing the existing release_tag and its full expected_commit (from git rev-list -n 1 vX.Y.Z). The manual run revalidates that exact tagged commit before publishing. After successfully uploading the distributions, it also removes assets with a mismatched package version from a previously incomplete GitHub Release. Do not retry a publish that already succeeded on PyPI; PyPI does not permit replacing distributions.