Contributing
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:
| Command | What it checks |
|---|---|
ruff format --check . | Formatting. Run ruff format . to fix it. |
ruff check . | Lint. |
mypy | Strict type-check of src/ and tests/. |
pytest --cov | The unit suite, with a coverage threshold of 90%. |
python -m build | The sdist and the wheel that are published. |
pip-audit | Advisories 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.