kavier 0.3.1__tar.gz

kavier-0.3.1/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AtLarge Research
+
+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.

kavier-0.3.1/PKG-INFO

@@ -0,0 +1,129 @@
+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).

kavier-0.3.1/README.md

@@ -0,0 +1,88 @@
+# 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).

kavier-0.3.1/pyproject.toml

@@ -0,0 +1,120 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "kavier"
+version = "0.3.1"
+description = "Kavier: Simulating the Performance, Sustainability, and Efficiency of LLM Ecosystems under Inference and Training"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Radu Nicolae" },
+    { name = "AtLarge Research", email = "info@atlarge-research.com" },
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.7",
+    "pandas>=2.2",
+    # pyarrow>=23.0.1: clears Arrow IPC use-after-free GHSA (high-sev); was >=16.0.
+    "pyarrow>=23.0.1",
+    "numpy>=2.2.6",
+    "tqdm>=4.67.1",
+    "cachetools>=6.1",
+    "rich>=13",
+    "pyyaml>=6",
+]
+keywords = [
+    "LLM",
+    "simulation",
+    "performance",
+    "sustainability",
+    "energy",
+    "carbon",
+    "GPU",
+    "training",
+    "inference",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Science/Research",
+    "Intended Audience :: Developers",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.urls]
+Homepage = "https://github.com/atlarge-research/kavier"
+Repository = "https://github.com/atlarge-research/kavier"
+Documentation = "https://github.com/atlarge-research/kavier"
+"Bug Tracker" = "https://github.com/atlarge-research/kavier/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.2",
+    "hypothesis>=6.102",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "pandas-stubs>=2.2",
+    "types-tqdm",
+    "types-cachetools",
+    "types-PyYAML",
+]
+
+[project.scripts]
+kavier        = "kavier_ui:main"
+kavier-perf   = "kavier_inference.cli:main"
+kavier-train  = "kavier_training.cli:main"
+kavier-energy = "kavier_energy.calculator:main"
+kavier-co2    = "kavier_co2.cli:main"
+kavier-eff    = "kavier_inference.cli:main_efficiency"
+
+# ------------------------------------------------------------------
+#  Tooling
+# ------------------------------------------------------------------
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = []
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["kavier*"]
+
+# Ship only small runtime/demo data (calibration table + tiny example trace); large trace stays out — see examples-local/.
+[tool.setuptools.package-data]
+# PEP 561: ship py.typed so installed consumers get inline type hints.
+kavier = ["py.typed"]
+kavier_training = ["py.typed", "data/calibration.json", "data/input/input_example.csv"]
+kavier_inference = ["py.typed", "data/input/input_example.csv"]
+kavier_io = ["py.typed"]
+kavier_energy = ["py.typed"]
+kavier_co2 = ["py.typed"]
+kavier_library = ["py.typed"]
+"kavier_io.opendc" = ["py.typed"]
+
+[tool.setuptools.exclude-package-data]
+kavier_inference = ["data/output/*", "data/output/**/*"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+mypy_path = "src"
+packages = [
+    "kavier_inference",
+    "kavier_training",
+    "kavier_library",
+    "kavier_io",
+    "kavier_energy",
+]
+exclude = ["tests/"]

kavier-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

kavier-0.3.1/src/kavier/__init__.py

@@ -0,0 +1,108 @@
+"""Umbrella facade: the public ``inference``/``training`` API plus ``kavier.<sub>`` legacy aliases."""
+
+from __future__ import annotations
+
+import importlib as _importlib
+import sys as _sys
+from importlib.abc import Loader as _Loader
+from importlib.abc import MetaPathFinder as _MetaPathFinder
+from importlib.machinery import ModuleSpec as _ModuleSpec
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+from types import ModuleType as _ModuleType
+from typing import Any as _Any
+from typing import Sequence as _Sequence
+
+# Pure aliases: ``kavier.<sub>`` (bare AND deep) resolves to the same object as ``kavier_<sub>``.
+_ALIAS_TO_LEGACY = {
+    "io": "kavier_io",
+    "energy": "kavier_energy",
+    "co2": "kavier_co2",
+    "library": "kavier_library",
+    "opendc": "kavier_io.opendc",
+}
+
+# ``inference`` and ``training`` are REAL packages here (the public predictor API). The bare module is
+# the new package, but DEEP imports (``kavier.training.core.calibration`` ...) still resolve to the
+# legacy package — preserving the live calibration ``_CAL`` swap contract (one module per spelling).
+_API_PACKAGES = {
+    "inference": "kavier_inference",
+    "training": "kavier_training",
+}
+
+
+class _LegacyAliasFinder(_MetaPathFinder):
+    _prefix = f"{__name__}."
+
+    def find_spec(
+        self,
+        fullname: str,
+        path: _Sequence[str] | None = None,
+        target: _ModuleType | None = None,
+    ) -> _ModuleSpec | None:
+        if not fullname.startswith(self._prefix):
+            return None
+        tail = fullname[len(self._prefix) :]
+        head, _, rest = tail.partition(".")
+        legacy_root = _ALIAS_TO_LEGACY.get(head)
+        if legacy_root is None:
+            # Deep imports under the real API packages alias to legacy; the bare package does not.
+            if rest and head in _API_PACKAGES:
+                legacy_root = _API_PACKAGES[head]
+            else:
+                return None
+        legacy_name = legacy_root if not rest else f"{legacy_root}.{rest}"
+        spec = _ModuleSpec(fullname, _LegacyAliasLoader(legacy_name))
+        return spec
+
+
+class _LegacyAliasLoader(_Loader):
+    def __init__(self, legacy_name: str) -> None:
+        self._legacy_name = legacy_name
+
+    def create_module(self, spec: _ModuleSpec) -> _ModuleType:
+        module = _importlib.import_module(self._legacy_name)
+        _sys.modules[spec.name] = module
+        return module
+
+    def exec_module(self, module: _ModuleType) -> None:  # already executed
+        return None
+
+
+_sys.meta_path.insert(0, _LegacyAliasFinder())
+
+
+def __getattr__(name: str) -> _Any:
+    legacy = _ALIAS_TO_LEGACY.get(name)
+    if legacy is not None:
+        return _importlib.import_module(f"{__name__}.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+from kavier import inference, training  # noqa: E402
+from kavier_library.gpu import GPU_SPEC_LIBRARY  # noqa: E402
+from kavier_library.llm import LLM_SPEC_LIBRARY  # noqa: E402
+from kavier_training.core.engine import (  # noqa: E402
+    simulate_full_training,
+    simulate_training_step,
+)
+
+__all__ = [
+    "simulate_training_step",
+    "simulate_full_training",
+    "GPU_SPEC_LIBRARY",
+    "LLM_SPEC_LIBRARY",
+    "training",
+    "inference",
+    "io",
+    "energy",
+    "co2",
+    "library",
+    "opendc",
+]
+
+# Version from installed dist metadata; pyproject's static ``version`` is the single source of truth.
+try:
+    __version__ = _pkg_version("kavier")
+except _PackageNotFoundError:  # editable/source tree without dist metadata
+    __version__ = "0.0.0+unknown"