CIRCLE
Community

Contributing

How to contribute to CIRCLE auth-ai (Python): setup, quality gates, the documentation site and where the rules live.

Contributions are welcome. Read CONTRIBUTING.md for the process (versioning, releases, Git workflow) and AGENTS.md for the technical standards (typing, architecture, error handling, testing, security): both are mandatory for any contribution.

Development workflow

Requires Python 3.12 or later and pip 25.1 or later (for --group, PEP 735).

git clone https://github.com/circle-rd/auth-ai-py.git
cd auth-ai-py
python -m venv .venv
. .venv/bin/activate
pip install -e ".[starlette]" --group dev
pytest

The unit tests run against a scripted mock identity provider: no auth-service instance is needed.

Quality gates

A pull request must pass all of them, on Python 3.12, 3.13 and 3.14:

CommandWhat it checks
ruff format --check .Formatting. Run ruff format . to fix it.
ruff check .Lint.
mypyStrict type-check of src/ and tests/.
pytest --covThe unit suite, with a coverage threshold of 90%.
python -m buildThe sdist and the wheel that are published.
pip-auditAdvisories of the runtime dependencies.

End-to-end check

When a change touches sign-in, tokens, the wallet or the gateway, run the example app against a real auth-service and use its Self-test.

Documentation

This site lives in docs-site/ (Nuxt 4 and Docus). Build it in Docker, without installing anything on your machine:

docker build -t auth-ai-py-docs ./docs-site
docker run --rm -p 3000:3000 auth-ai-py-docs

Then open http://localhost:3000/auth-ai-py/. Every statement in the documentation must be traceable to the source in src/auth_ai/: update the pages in the same pull request as the code. The workflow .github/workflows/docs.yml builds and pushes the image on every push to main.

Shared contract with the TypeScript SDK

The wire contract (the BFF routes, the cookie formats and the error codes) is shared with the TypeScript SDK @circle-rd/auth-ai: change it in both, or not at all.

Reporting a vulnerability

Do not open a public issue: use the private advisory form described in SECURITY.md.

Copyright © 2026