Thanks for helping improve the tensic.ai Python SDK. This page covers the local workflow, the quality bar every change has to meet, and how pull requests are reviewed.
- Python 3.10 or newer (the test matrix runs 3.10 through 3.14).
- uv — the only tool you need; it manages the virtualenv, the interpreters for the matrix, and builds.
git clone https://github.com/tensicai/python-sdk
cd python-sdk
make install # = uv sync --extra dev (creates .venv with the SDK installed editable)uv.lock is committed: uv sync reproduces the exact development environment used in
CI, and CI installs with uv sync --locked, so a lock file that no longer matches
pyproject.toml fails the run instead of being silently re-resolved. The lock only pins the development environment — the published wheel keeps its loose
httpx>=0.25,<1 requirement. When you add or bump a dev dependency in pyproject.toml, run
uv lock and commit the updated lock file with the change.
| Command | What it runs |
|---|---|
make lint |
ruff check src tests examples + ruff format --check |
make format |
ruff format + ruff check --fix (auto-fixes imports etc.) |
make typecheck |
mypy src examples (strict) |
make test |
pytest -q on the current interpreter |
make test-all |
pytest -q on Python 3.10, 3.11, 3.12, 3.13 and 3.14 |
make check |
lint + typecheck + test — what CI runs |
make build |
uv build + twine check dist/* |
make clean |
removes build artefacts and caches |
Everything is a thin wrapper over uv run <tool>, so uv run pytest tests/test_chat.py -k send
works as you would expect.
- Unit tests live in
tests/and never touch the network:tests/conftest.pyprovidesMockAPI, an in-memory router behindhttpx.MockTransport, and theclient/aclientfixtures. Assert on the recorded requests (api.last,request_json(...),request_multipart(...)) as well as on the parsed result. - Cover both the sync and the async client.
tests/test_parity.pyfails if a sync resource gains a method or a parameter that its async twin lacks. tests/test_readme_snippets.pycompiles every ```python block inREADME.mdand `examples/*.py`, and executes the README snippets tagged `` against the mock server. If you change a documented signature, update the README in the same PR.- Live tests in
tests/integration/run only whenTENSIC_URLandTENSIC_API_KEYare set (optionallyTENSIC_PROJECT_IDfor chat).
from __future__ import annotationsin every module; full type hints;mypy --strictmust stay clean forsrc/, forexamples/and for every ```python block inREADME.md(`tests/test_readme_snippets.py` type-checks the documented code, so copy-pasting it into a strictly typed project never produces errors).- Optional request parameters are keyword-only and default to
NOT_GIVEN(omitted from the wire); an explicitNoneis sent as JSONnull. No mutable default arguments. - A resource method is a module-level builder returning a
RequestSpecplus a pure parser; the sync and async classes call the same pair. Seedocs/INTERNALS.mdfor the full guide andsrc/tensicai/resources/chat.pyfor the worked example. - Response models are lenient dataclasses (
TensicModel): unknown keys go to.extra, missing keys read asNone. Never raise on unexpected server output. - Every name a public signature mentions must be importable from
tensicai,tensicai.typesortensicai.resources, so aLiteralalias (Splitter,Privacy,Probe, ...) is defined once in its domaintypes/module and imported back by the resource —tests/test_packaging.pychecks this by introspection. - Every public class and method has a docstring naming the endpoint it calls.
- Never log or
repr()an API key.
The server source of truth for the HTTP contract is the tensic.ai OpenAPI document
(GET /openapi.json on any server, with the Swagger UI at /docs and ReDoc at /redoc —
all three require authentication). When in doubt, match the server, then update this SDK's
docs.
- Branch from
main; keep PRs focused (one feature or fix per PR). - Run
make checklocally — CI runs the same commands on all supported Python versions and also builds and installs the wheel. - Add tests for new behaviour and a line under Unreleased in
CHANGELOG.md(Keep a Changelog format). - Public API changes need README updates in the same PR; the snippet test will remind you.
- Do not bump
src/tensicai/_version.pyin feature PRs — maintainers do that in the release commit (see "Releasing" in the README). - Commit messages: imperative mood, short subject, body explaining why when it is not obvious.
By contributing you agree that your contributions are licensed under the Apache-2.0 license that covers this repository.