Skip to main content

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 stats to 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)

Source distribution for caelum-ai 0.1.0
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)

Table of built distributions (wheels) for caelum-ai 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page