Metadata-Version: 2.5
Name: caelum-ai
Version: 0.1.0
Summary: The control plane for AI inference: drop-in caching, routing, observability and fallback for LLM APIs.
Project-URL: Homepage, https://caelum-ai.com
Project-URL: Documentation, https://caelum-ai.com/docs
Project-URL: Repository, https://github.com/kanazoeissouf83-ops/caelum
Project-URL: Issues, https://github.com/kanazoeissouf83-ops/caelum/issues
Project-URL: Changelog, https://github.com/kanazoeissouf83-ops/caelum/blob/main/CHANGELOG.md
Author: Issouf KANAZOE
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: ai,anthropic,cache,gemini,inference,llm,llmops,mistral,observability,openai,routing,semantic-cache
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: fast
Requires-Dist: numpy>=1.26; extra == 'fast'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.30; extra == 'gemini'
Provides-Extra: mistral
Requires-Dist: mistralai>=3.0; extra == 'mistral'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: rich
Requires-Dist: rich>=13.0; extra == 'rich'
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0; extra == 'yaml'
Description-Content-Type: text/markdown

# 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

```bash
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`:

```python
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](https://github.com/kanazoeissouf83-ops/caelum/tree/main/docs).

Provider SDKs are optional extras: the core package stays lightweight.

## Development setup

Requires [uv](https://docs.astral.sh/uv/).

```bash
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:

```bash
uv run pytest -m integration
```

## License

Apache 2.0 — see [LICENSE](https://github.com/kanazoeissouf83-ops/caelum/blob/main/LICENSE).
