Metadata-Version: 2.2
Name: continuum-ai
Version: 1.0.0
Summary: Unified runtime for token + tensor program execution across LLM and ML backends
Author: Continuum Authors
License: MIT License
         
         Copyright (c) 2026 Rithul Kamesh
         
         Permission is hereby granted, free of charge, to any person obtaining a copy
         of this software and associated documentation files (the "Software"), to deal
         in the Software without restriction, including without limitation the rights
         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
         copies of the Software, and to permit persons to whom the Software is
         furnished to do so, subject to the following conditions:
         
         The above copyright notice and this permission notice shall be included in all
         copies or substantial portions of the Software.
         
         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
         SOFTWARE.
         
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Interpreters
Requires-Python: >=3.10
Requires-Dist: torch>=2.2
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: hypothesis>=6; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.4; extra == "docs"
Requires-Dist: furo>=2024.7.18; extra == "docs"
Requires-Dist: breathe>=4.35.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: pytest-cov>=5.0; extra == "test"
Requires-Dist: hypothesis>=6; extra == "test"
Description-Content-Type: text/markdown

# Continuum

Continuum is a unified execution runtime for LLM and ML programs.
It is not just an API wrapper and not just orchestration glue.
Continuum executes a shared intermediate representation (IR) that spans token generation and tensor computation inside one runtime.

## Why Continuum

- **One IR, two worlds**: token ops and tensor ops in a single executable graph.
- **Backend-agnostic caching**: reusable backend state handles enable cross-call prefix reuse without backend-specific app code.
- **Capability-driven dispatch**: runtime routes ops by declared backend capability, not brittle string checks.
- **Explicit interoperability**: cross-backend tensors are tagged and converted explicitly, never silently mixed.
- **Native-ready architecture**: C++ core with ABI boundary prep for future dynamic backend loading.

## Core Idea

Continuum uses one IR to represent both token and tensor operations, then executes that graph through a single interpreter.
KV caching is treated as a program-level concern rather than a backend-specific add-on.
Backends receive reusable state handles through a common contract, so cache-aware execution can remain backend-agnostic.
This allows the same execution model to drive cloud LLM calls, local LLM backends, and tensor workloads.

## What Works Today

- C++ execution engine with IR + interpreter
- KV cache index with canonical prefix normalization
- Azure backend (real network execution)
- libtorch backend (tensor/training execution)
- MLX backend (native tensor op path for Apple workflows)

## Example

See `examples/01_research_agent.py` for a paired benchmark workflow that exercises cache-aware token generation across backends.

## Benchmarking Approach

Benchmarks are run as paired trials (uncached vs cached on identical input), with warmup discarded and robust statistics reported (median/p50/p95).
Primary signal is token reduction (`tokens_saved / (tokens_sent + tokens_saved)`), with latency ratio tracked as secondary due to provider/network noise.

## Status

- v1 release hardening in progress
- Capability-driven backend dispatch implemented (tensor/token/cache)
- MLX + libtorch tensor interoperability implemented with explicit conversion rules
- CIR schema lock added (`schema/cir.fbs`) with serialization conformance tests
- Python + C++ API docs pipelines wired (Sphinx + Doxygen + GitHub Pages workflow)
- Packaging migrated to `continuum-ai` (import path `continuum`) with PyPI publish workflow
- CI matrix active on Linux + macOS with coverage gates and fuzz workflow

[![Star History Chart](https://api.star-history.com/chart?repos=rithulkamesh/continuum&type=date&legend=top-left)](https://www.star-history.com/?repos=rithulkamesh%2Fcontinuum&type=date&legend=top-left)


## Install

```bash
python -m pip install continuum-ai
```

Import remains:

```python
import continuum
```

## Reproducible Example Validation

```bash
PYTHONPATH=python python scripts/benchmarks/run_examples.py | python scripts/benchmarks/validate_outputs.py
```

## Pre-commit Hooks

Set up local quality gates (`ruff`, formatting, YAML/whitespace checks):

```bash
pip install pre-commit
pre-commit install
pre-commit run --all-files
```

Note: generated docs/build outputs are excluded by default in `.pre-commit-config.yaml`.

## API Docs

Build Python docs locally:

```bash
python -m venv .venv-docs
. .venv-docs/bin/activate
pip install sphinx furo breathe
PYTHONPATH=python sphinx-build -b html docs/api/python docs/api/python/_build
```

Then open:

- `docs/api/python/_build/index.html`
- GitHub Pages: `https://rithulkamesh.github.io/continuum/python/`

Build C++ docs locally:

```bash
doxygen Doxyfile
```

Then open:

- `docs/api/cpp/html/index.html`
- GitHub Pages: `https://rithulkamesh.github.io/continuum/cpp/`

## Citation

If Continuum helps your work, cite it as:

```bibtex
@software{continuum2026,
  title        = {Continuum: Unified Runtime for Token and Tensor Programs},
  author       = {Kamesh, Rithul and Contributors},
  year         = {2026},
  url          = {https://github.com/rithulkamesh/continuum},
  version      = {1.0.0}
}
```
