Contributing¶
Thank you for helping with aiollm. The library is pre-alpha: the public API can still change, and every change is welcome, from a typo to a new provider. This repository is the core, published as aiollm-core; the providers are packages of their own, aiollm-openai and aiollm-anthropic, each with its own contributing guide. A change of a provider's endpoints, types or adapters goes to its repository. For anything larger than a fix, open an issue first and describe the change, so that we agree on the design before you spend time on code.
The guide below walks through one change from start to finish. The rules it refers to are written down in CLAUDE.md, the project's profile: commands, architecture invariants and conventions. It is written for AI assistants, and it is the most complete description of the code base for people too.
Setting up¶
You need Python 3.13 or newer and git. Fork the repository on GitHub, clone your fork and create a branch for your change:
Install the package with all its development dependencies (dev tools, tests and docs).
Using traditional approach (pip 25.1 or newer, which installs dependency groups):
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install -e . --group dev --group test --group docs
Or with uv, which the project uses and whose uv.lock pins every version:
Then install the git hooks once. They run the formatter, the linter and both type checkers on every commit:
Project layout¶
src/aiollm/
├── enums.py Provider, BodyFormat, ResponseFormat, Role,
│ IncompleteReason, GenerationEventType
├── exceptions.py AIAPIError (the root of all library errors),
│ RequestValidationError, SessionMismatchWarning
├── types/ BaseAPIType, files, matchers, BaseUnknown; requests/ and
│ responses/ hold the shared GenerationRequest/Response, events
├── serialization/ JSON codec, body value normalization, value formatters
├── http/ IAPI and BaseAPI, BearerAuth, APIKeyAuth, headers
│ └── exceptions/ status, transport and response errors, resolver
├── methods/ BaseAPIMethod, BaseStreamMethod, field checks, path templates
├── response/ BufferedResponse, Stream, transform_stream, map_stream;
│ parse/ parsers
├── session/ BaseSession, AiohttpSession, SessionFactory;
│ retry/ RetryPolicy, body/ builders
├── client/ BaseClient, BaseProviderClient
├── adapters/ adapters between shared types and provider methods
├── resources/ GenerationResource, use cases and AdapterUseCase orchestrators
└── testing/ the test kit: Recorder, fixtures, the shared scenarios,
the echo provider and the extension API
The packages are layers, listed from the bottom up; a module imports only from the layers below it. The core never imports a provider (aiollm_*), its infrastructure never imports the shared generation and files layer, and a provider takes from the core only the names of its extension API (aiollm/testing/extension_api.json, see Extending). Transport code lives only in */aiohttp.py modules, so import aiollm does not import aiohttp. The tests mirror this: tests/unit/, tests/session/, tests/integration/ (aiohttp against a local server), tests/testing/ (the test kit, and the shared scenarios of aiollm.testing.contract on its echo provider), tests/typing/ (static checks of the public API, on the echo provider), and the two folders that need the providers installed: tests/docs/ (the examples of these pages, with their own provider payloads) and tests/downstream/ (the providers against the extension API).
Making changes in code¶
At this point you can make any changes in the code that you want: fixes, new features or experiments. A few rules keep the code base consistent, and the checks below enforce most of them:
- Every module, class and function has a Google-style docstring. Ruff checks it. A docstring is user documentation: the reference is generated from it.
- Modern Python, the oldest supported version. Every module starts with
from __future__ import annotations; use PEP 695 generics (class Stream[T]) and nothing newer than Python 3.13 allows. - Public names are exported on purpose. A name users need goes into its package's
__init__.pywith a sorted__all__; everything else stays internal. - Fail early. A mistake in a method class raises
TypeErrorwhen the class is defined, a bad value raises before anything is sent, and nothing is dropped silently. - The providers stand on the core. A name a provider imports is in the extension API (
aiollm/testing/extension_api.json); a new one is added there in the same change, and a listed one is removed or changed only as a breaking change. CI runs both providers' suites on your branch (downstream). - Breaking changes are allowed before 1.0, but marked. Say so in the changelog fragment (see Describe changes); see Versioning for what counts as one.
For a new provider, read Extending: a provider is a package of its own, its methods follow the provider's own JSON schema field by field, and its wire-contract tests check that they do. A new endpoint of OpenAI or Anthropic goes to that provider's repository.
Format the code (code-style)¶
This project uses Ruff for formatting and linting (line length 79), so you should follow its code style. To be sure you are doing it correctly, reformat the code and fix what the linter can fix automatically.
Using traditional approach:
Or with uv:
The code is also type-checked in strict mode by two checkers, which must both pass.
Using traditional approach:
Or with uv:
Do not silence a checker to get green: a # type: ignore, # noqa or # pyright: ignore needs a reason in a comment next to it, and the reviewer will ask for it.
Run tests¶
All changes should be tested. A new behaviour gets a test of what a caller sees (the result, the error, what was sent); a bug fix starts with a test that fails without the fix.
Using traditional approach:
pytest
pytest --cov # with branch coverage
pytest --mypy -m mypy tests/typing # static checks of the public API
Or with uv:
tests/docs, tests/downstream and the docs site need both providers. They pin another core, so install them from their master without their dependencies (the next uv sync removes them):
uv pip install --no-deps "aiollm-openai @ git+https://github.com/aiollm-org/aiollm_openai@master" "aiollm-anthropic @ git+https://github.com/aiollm-org/aiollm_anthropic@master"
uv run --no-sync pytest tests/docs tests/downstream
What the tests expect from a change:
- Coverage stays at 100 % of lines and branches in practice (the configured floor is 98 %); a branch only a provider reaches is covered by the providers' suites in
downstream. - No real API. Network tests run against the local
Recorderserver ofaiollm.testing(its fixtures come from theaiollm.testing.pluginthattests/conftest.pyloads), which answers only what a test scripted and fails the test on any other request, so a hidden retry cannot pass. API keys from your environment are cleared for every test. - No sleeps. Wait for an event or a condition, not for time to pass.
- Every supported Python. CI runs the tests on CPython 3.13, 3.14 and 3.15, on Linux and Windows. To try another version locally with uv, run
UV_PYTHON=3.15 uv run --all-groups pytest(it rebuilds.venvfor that version; runuv sync --all-groupsto go back).
Docs¶
We are using MkDocs with the Material theme to render the docs; all sources are in the docs directory, and the reference pages are generated from the docstrings. You can change the sources, start the live-preview server and look at what you are doing at http://127.0.0.1:8000. The providers' pages need them installed (see Run tests).
Using traditional approach:
Or with uv:
Before you push, build the site in strict mode, where any warning (a broken link, a missing page) fails, and lint the Markdown:
Set NO_MKDOCS_2_WARNING=1 to hide Material's notice about its end of life.
Every ```python block of the README and of the docs is run by tests/docs/test_examples.py. A block is found by the title on its opening line, such as ```python title="query.py", so a new example needs a unique title and a test that runs it; a block without one fails test_every_example_is_tested. Output and shell snippets use ```text and ```bash, which are not run.
When the text and the code disagree, the code says what the library does: fix the text. If the code contradicts something the docs promise on purpose, that is a bug; open an issue.
Describe changes¶
Describe your changes in one or more sentences so that the developers who use the library know what changed. Create a changelog fragment in the CHANGES directory and write the description in it; towncrier turns the fragments into the changelog when a version is released.
Using traditional approach:
Or with uv:
- Name.
<PR number>.<type>.mdonce your pull request exists, or+<slug>.<type>.mdbefore it does. - Type. One of
added,changed,deprecated,removed,fixed,security. - Text. One Markdown paragraph about what a user sees, not about file names. A breaking change starts with
**Breaking:**and says how to migrate. - Do not bump the version or edit
CHANGELOG.md: a release is a separate pull request made by the maintainer, so pull requests made side by side never conflict in the changelog. - A change no user would notice (tests, CI, internal refactoring) needs no fragment; ask for the
no changeloglabel instead.
Preview what the next release holds with uv run towncrier build --draft. CHANGES/README.md has the details.
Complete¶
After you have made all your changes, commit them with a message that says what changed and why, push the branch to your fork and open a pull request against master. In its description, say what the change does and how you checked it.
CI runs on every pull request, and a pull request is merged only when all of these pass:
| Check | What it runs |
|---|---|
lint and types |
ruff, mypy, pyright, the typing tests, the Markdown lint and the strict docs build |
tests |
pytest with coverage on Linux and Windows, CPython 3.13, 3.14 and 3.15 |
package |
builds the wheel and imports it in a clean environment, without aiohttp or a provider |
downstream (openai), downstream (anthropic) |
each provider's suite on your branch, then the examples of the site and the extension API with both providers |
audit |
known vulnerabilities in the locked dependencies (uv audit) |
changelog |
a changelog fragment, unless the PR has the no changelog label |
| GitGuardian | no secrets in the diff |
downstream may fail on a breaking change, which the providers then follow in their own pull requests: say so in the description. Then wait for a review of these changes. Releases, version numbers and tags are made by the maintainer.
Contributing with Claude¶
Many changes to this library are written with Claude Code, and the repository is set up for it. If you use Claude (or another coding agent), these directives keep its work at the level of the rest of the code base. You are the author of the pull request and answer for every line of it, whoever typed it.
What the repository gives Claude¶
CLAUDE.mdis loaded into every session: the commands, the invariants that are easy to break and the conventions. If your change alters an invariant or a convention, updateCLAUDE.mdin the same pull request; a stale profile misleads the next session.- Project skills in
.claude/skills/carry the project's workflows, and Claude picks them up when a task matches; you can also call one by name, such as/ai-api-docs. They are listed in the table below. - Provider documentation. Point Claude at the providers' official sources: OpenAI's OpenAPI file (
openai/openai-openapi), Anthropic's SDK types and API reference. The schema snapshots, the code generation and the weekly upstream refresh live in the provider repositories.
| Skill | Use it for |
|---|---|
ai-api-provider |
a new provider package in its own repository |
ai-api-docs |
guide pages, docstrings and tested examples |
ai-api-release |
the changelog fragment of a change (and, for the maintainer, releases) |
Directives¶
- Discuss before code. For anything beyond a small fix, ask Claude for a proposal first (what changes, the options, the trade-offs, the tests) and read it before you let it write code. Open the issue with that proposal.
- Facts come from sources, not from memory. What a provider accepts or returns is checked against its schema or documentation, and the source is named. Claude must not guess a field, a status or a default.
- Test first for every bug. Ask Claude to write the failing test before the fix and to show that it fails on the unfixed code.
- Results are run, not predicted. Ask for the actual output of the full set of checks above. "It should pass" is not a result; neither is a check that was skipped without saying so.
- Nothing is weakened to get green. No new
skip,xfail,type: ignore,noqaor relaxed setting without a reason in the code and in the pull request; no lowered coverage. - Small, focused diffs. One concern per pull request, no drive-by refactoring or formatting of unrelated files, and no new abstraction without a second use for it.
- You decide what leaves your machine. Review every diff yourself. Claude does not push, open or merge pull requests, publish or delete anything unless you tell it to, one action at a time.
- No secrets in the conversation. Never paste a real API key into the session; the tests use fakes and a local server, and the library must never log a key, a header, a body, a query string or a file name.
- Your name on the commit. Commit messages and pull requests carry no model names or AI co-author trailers. If you want to say that a pull request was made with Claude, say it in its description.
- One task per session. Start a fresh session for a new task and give it the issue; a long session that drifted across topics makes worse decisions.
If you use a tool that condenses command output for the agent, exclude pytest from it, so that the coverage report stays visible.
License¶
By contributing, you agree that your contributions are licensed under the MIT License of the project.