Metadata-Version: 2.4
Name: kavier
Version: 0.3.1
Summary: Kavier: Simulating the Performance, Sustainability, and Efficiency of LLM Ecosystems under Inference and Training
Author: Radu Nicolae
Author-email: AtLarge Research <info@atlarge-research.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/atlarge-research/kavier
Project-URL: Repository, https://github.com/atlarge-research/kavier
Project-URL: Documentation, https://github.com/atlarge-research/kavier
Project-URL: Bug Tracker, https://github.com/atlarge-research/kavier/issues
Keywords: LLM,simulation,performance,sustainability,energy,carbon,GPU,training,inference
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: pydantic>=2.7
Requires-Dist: pandas>=2.2
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: numpy>=2.2.6
Requires-Dist: tqdm>=4.67.1
Requires-Dist: cachetools>=6.1
Requires-Dist: rich>=13
Requires-Dist: pyyaml>=6
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: hypothesis>=6.102; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pandas-stubs>=2.2; extra == "dev"
Requires-Dist: types-tqdm; extra == "dev"
Requires-Dist: types-cachetools; extra == "dev"
Requires-Dist: types-PyYAML; extra == "dev"
Dynamic: license-file

# Kavier

Simulating performance, sustainability, and efficiency of LLM Ecosystems under inference and training.

[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-main-green.svg)](docs/index.html)
[![CI](https://github.com/atlarge-research/kavier/actions/workflows/ci.yml/badge.svg)](https://github.com/atlarge-research/kavier/actions/workflows/ci.yml)

---

This repository is the home of Kavier, the first scientific instrument for
predicting performance, sustainability, and efficiency of LLM ecosystems under
inference and training.

Kavier helps operators, researchers, and engineers predict:
* **Performance** — inference latencies, training throughput, GPU utilization
* **Sustainability** — energy consumption, carbon emissions (gCO2/Mtoken)
* **Efficiency** — financial and energy cost per token/sample given GPU-hour prices

## Quick start

```bash
git clone https://github.com/atlarge-research/kavier.git
cd kavier

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -U pip
pip install -e ".[dev]"
```

Run your first simulation against the tiny bundled synthetic example trace:

```bash
kavier-perf --trace src/kavier_inference/data/input/input_example.csv
```

Congrats! You have just run your first simulation with Kavier! 🎉

Or skip the flags — launch the **interactive UI** and pick a simulator, model and
GPU from guided menus, then chain into energy/carbon or export OpenDC:

```bash
kavier
```

If you installed Kavier from PyPI (`pip install kavier`) you have no `src/`
directory; the same synthetic example trace ships inside the package, so resolve
its path via `importlib.resources`:

```bash
TRACE=$(python -c "from importlib.resources import files; print(files('kavier_inference')/'data/input/input_example.csv')")
kavier-perf --trace "$TRACE"
```

## Structure

Kavier is organized into the following first-party packages:

```
src/
├── kavier/              # Umbrella facade (re-exports the sub-packages)
├── kavier_inference/    # Inference simulation (kavier-perf)
├── kavier_training/     # Training simulation (kavier-train)
├── kavier_energy/       # Energy calculator (kavier-energy)
├── kavier_co2/          # Carbon emissions (kavier-co2)
├── kavier_library/      # Shared GPU & LLM specifications
├── kavier_io/           # Shared I/O utilities
│   └── opendc/          # OpenDC workload export (tasks/fragments)
├── kavier_ui/           # Interactive REPL (the `kavier` command)
└── tests/               # Test suites
```

## Documentation

See [docs/index.html](docs/index.html) for the main documentation: getting started,
the Kavier CLIs (`kavier` interactive UI, `kavier-perf`, `kavier-train`,
`kavier-energy`, `kavier-co2`), the YAML `--config` input,
structure, and the contributing guide.

## Contributing

Questions, suggestions and contributions are welcome and appreciated!
Please refer to the [contributing guide](docs/contributing.md) for more details.

## License

Kavier is distributed under the MIT license. See [LICENSE.txt](/LICENSE.txt).
