CAELUM Python SDK
The control plane for AI inference — drop-in caching, routing, observability and fallback for LLM APIs.
Status: pre-release. The API may still change before 1.0.
Change one import and get, all opt-in:
- exact and semantic cache (local SQLite file; rephrased questions are reused only after a small model confirms they ask the same thing);
- routing to the models you choose, from a dict, JSON or YAML file;
- retries with backoff and fallback to another provider or a local model (Ollama, llama.cpp, vLLM, LM Studio);
- metrics: calls, tokens, cache hits, latency, estimated cost;
caelum cache statsto see what your cache holds.
Works with the official OpenAI, Anthropic, Google Gen AI (Gemini) and Mistral SDKs, with their types unchanged. Python 3.10+, tested on Windows and Linux.
Installation
pip install "caelum-ai[openai]" # with the OpenAI SDK
pip install "caelum-ai[anthropic]" # with the Anthropic SDK
pip install "caelum-ai[gemini]" # with the Google Gen AI SDK (Gemini)
pip install "caelum-ai[mistral]" # with the Mistral SDK
pip install "caelum-ai[rich]" # prettier metrics output
pip install "caelum-ai[yaml]" # routing rules in YAML files
pip install "caelum-ai[fast]" # faster semantic cache on large caches (numpy)
The package is published as caelum-ai and imported as caelum:
from caelum import OpenAI # instead of: from openai import OpenAI
client = OpenAI(cache=True, retry=True)
response = client.chat.completions.create(
model="gpt-4o-mini",
messages=[{"role": "user", "content": "Hello"}],
)
client.metrics.print_summary()
Documentation: github.com/kanazoeissouf83-ops/caelum/tree/main/docs.
Provider SDKs are optional extras: the core package stays lightweight.
Development setup
Requires uv.
cd packages/python
uv sync --all-extras # create .venv and install everything (incl. dev tools)
uv run pytest # tests + coverage
uv run ruff format . # format
uv run ruff check . # lint
uv run pyright # type check (strict)
Integration tests calling real APIs are marked integration and excluded by default:
uv run pytest -m integration
License
Apache 2.0 — see LICENSE.
Metadata
Release files for caelum-ai 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| caelum_ai-0.1.0.tar.gz | 932.2 kB | With provenance | Details for caelum_ai-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| caelum_ai-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for caelum_ai-0.1.0-py3-none-any.whl |
Total release size: 1.1 MB
Release files / caelum_ai-0.1.0.tar.gz
| Download URL | caelum_ai-0.1.0.tar.gz |
|---|---|
| Size | 932.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4572b20fc627d6a984a79ac6432c53b3a004ebc38a6569b2c624a13fb509e533
|
|
BLAKE2b-256 checksum How to use checksums |
318f4e8acdda49ccb6e9b10ceb7e9f6c0f43caa1d673ad0f72447fc796207a28
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logRelease files / caelum_ai-0.1.0-py3-none-any.whl
| Download URL | caelum_ai-0.1.0-py3-none-any.whl |
|---|---|
| Size | 122.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b204e07d719d6aff8f107fde9437c921d168b95014ec9a2296f0d49ab89b761
|
|
BLAKE2b-256 checksum How to use checksums |
970026286d4ccc4d6f4d7c9ee88155e92fc3e7d6ad2712f008a5a791558aa951
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logSecurity for caelum-ai 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for caelum_ai-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.