kavier 0.3.1__py3-none-any.whl

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"

kavier/inference/__init__.py

@@ -0,0 +1,269 @@
+"""Inference predictors: ``performance / energy / efficiency / carbon`` over a batch of serving workloads.
+
+Each verb takes a *batch* — a pandas DataFrame, a list of dicts, or a single dict (one row per
+workload) — and returns a DataFrame: the input rows plus the predicted columns. The per-row engine
+logic is canonical here; ``kavier_ui.sims`` and the CLIs consume it, so the numbers match exactly.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import time
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from kavier_co2.engine import CarbonTrace, Fragment, compute_emissions
+from kavier_inference.core.cache import PrefixCache
+from kavier_inference.core.config import CacheCfg, SimConfig
+from kavier_inference.core.metrics import Metrics
+from kavier_inference.core.runner import simulate_one
+from kavier_library import get_gpu, get_llm
+
+# Defaults for workload keys a batch may omit (mirror the UI prompt defaults).
+DEFAULT_KV_CACHE = True
+DEFAULT_PREFIX_POLICY = "prefill"
+DEFAULT_PREFIX_MIN_TOKENS = 1024
+DEFAULT_INTENSITY_G_KWH = 400.0
+DEFAULT_GPU_HOUR_PRICE = 2.5
+
+Batch = "pd.DataFrame | list[dict[str, Any]] | dict[str, Any]"
+
+
+def _drop_missing(row: dict[str, Any]) -> dict[str, Any]:
+    """Drop NaN/None cells so ``.get(key)`` means 'absent' — a heterogeneous DataFrame fills gaps with NaN."""
+    out: dict[str, Any] = {}
+    for k, v in row.items():
+        if v is None:
+            continue
+        if isinstance(v, float) and pd.isna(v):
+            continue
+        out[k] = v
+    return out
+
+
+def _normalise(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> list[dict[str, Any]]:
+    """Coerce a DataFrame | list[dict] | single dict into a list of plain row dicts (NaN cells dropped)."""
+    if isinstance(batch, pd.DataFrame):
+        records: list[dict[str, Any]] = [{str(k): v for k, v in rec.items()} for rec in batch.to_dict(orient="records")]
+    elif isinstance(batch, dict):
+        records = [dict(batch)]
+    else:
+        records = [dict(row) for row in batch]
+    return [_drop_missing(row) for row in records]
+
+
+def _infer_params(row: dict[str, Any]) -> dict[str, Any]:
+    """Fill the inference-engine keys, defaulting cache settings the caller may omit."""
+    return {
+        **row,
+        "kv_cache": row.get("kv_cache", DEFAULT_KV_CACHE),
+        "prefix_policy": row.get("prefix_policy", DEFAULT_PREFIX_POLICY),
+        "prefix_min_tokens": row.get("prefix_min_tokens", DEFAULT_PREFIX_MIN_TOKENS),
+    }
+
+
+def run_inference(p: dict[str, Any]) -> dict[str, Any]:
+    """Loop ``simulate_one`` over a homogeneous workload (same engine as the CLI, no disk I/O)."""
+    llm = get_llm(p["model"])
+    gpu = get_gpu(p["gpu"])
+    cfg = SimConfig(
+        export_rate=0.1,
+        kv_cache=bool(p["kv_cache"]),
+        cache=CacheCfg(min_len=int(p["prefix_min_tokens"]), action=p["prefix_policy"], scope="session", max_entries=10),
+    )
+
+    n = int(p["num_requests"])
+    n_in, n_out = int(p["input_tokens"]), int(p["output_tokens"])
+    cache = PrefixCache(cfg.cache)
+    metrics = Metrics()
+    t0 = int(time.time_ns() / 1e6)
+    ttfts: list[float] = []
+    tasks: list[dict[str, Any]] = []
+    for i in range(n):
+        task, _frags, t_p, t_d = simulate_one(
+            idx=i,
+            session_id=None,
+            n_in_tokens=n_in,
+            n_out_tokens=n_out,
+            in_tokens=None,
+            llm=llm,
+            gpu=gpu,
+            cache=cache,
+            cfg=cfg,
+            export_rate_s=cfg.export_rate,
+            t0_ms=t0,
+        )
+        metrics.add(t_p, t_d, (t_p + t_d) * 1000.0)
+        ttfts.append(t_p * 1000.0)
+        tasks.append(task)
+
+    total_s = metrics.sum_prefill + metrics.sum_decode
+    total_tokens = n * (n_in + n_out)
+    lat = np.asarray(metrics.latencies)
+    return {
+        "model": llm.name,
+        "gpu": gpu.name,
+        "num_requests": n,
+        "input_tokens": n_in,
+        "output_tokens": n_out,
+        "kv_cache": cfg.kv_cache,
+        "prefix_policy": cfg.cache.action,
+        "prefix_min_tokens": cfg.cache.min_len,
+        "prefill_s": metrics.sum_prefill,
+        "decode_s": metrics.sum_decode,
+        "total_s": total_s,
+        "mean_ttft_ms": float(np.mean(ttfts)),
+        "p50_ms": float(np.percentile(lat, 50)),
+        "p95_ms": float(np.percentile(lat, 95)),
+        "p99_ms": float(np.percentile(lat, 99)),
+        "throughput_req_s": n / total_s if total_s else 0.0,
+        "throughput_tok_s": total_tokens / total_s if total_s else 0.0,
+        "total_tokens": total_tokens,
+        "cache_hits": cache.hits,
+        "cache_hit_ratio": cache.hits / n if n else 0.0,
+        "evictions": cache.evictions,
+        "_tasks": tasks,  # reused by the energy chain
+    }
+
+
+def _flat_trace(start: pd.Timestamp, hours: float, intensity_g_kwh: float) -> CarbonTrace:
+    """Constant-intensity trace so ``compute_emissions`` runs without an external grid trace."""
+    rows = max(2, int(hours) + 2)
+    df = pd.DataFrame(
+        {
+            "timestamp": [start + dt.timedelta(hours=h) for h in range(rows)],
+            "carbon_intensity": [float(intensity_g_kwh)] * rows,
+        }
+    )
+    return CarbonTrace.from_dataframe(df)
+
+
+def run_carbon_from_inference(infer: dict[str, Any], intensity_g_kwh: float) -> dict[str, Any]:
+    """Bill the GPU's max power over the summed busy time against a flat intensity."""
+    gpu = get_gpu(infer["gpu"])
+    runtime_s = float(infer["total_s"])
+    power_w = float(gpu.max_power_w)
+    start = pd.Timestamp("2026-01-01 00:00:00")
+    trace = _flat_trace(start, runtime_s / 3600.0, intensity_g_kwh)
+    frag = Fragment(start_time=start, duration_s=runtime_s, power_w=power_w)
+    res = compute_emissions([frag], trace)
+    return {
+        "source": "inference",
+        "model": infer["model"],
+        "gpu": infer["gpu"],
+        "intensity": float(intensity_g_kwh),
+        "runtime_s": runtime_s,
+        "power_w": power_w,
+        "total_energy_kwh": res.total_energy_kwh,
+        "total_co2_g": res.total_co2_g,
+        "total_co2_kg": res.total_co2_kg,
+        "total_tokens": infer["total_tokens"],
+    }
+
+
+def energy_from_inference(infer: dict[str, Any], gpu_hour_price: float | None) -> dict[str, Any]:
+    """$/Mtoken from GPU-hours, matching kavier_energy.metrics.financial_efficiency."""
+    carbon = run_carbon_from_inference(infer, intensity_g_kwh=DEFAULT_INTENSITY_G_KWH)
+    total_tokens = infer["total_tokens"]
+    energy_wh = carbon["total_energy_kwh"] * 1000.0
+    per_m = 1_000_000.0 / total_tokens if total_tokens else 0.0
+    gpu_hours = infer["total_s"] / 3600.0
+    return {
+        "model": infer["model"],
+        "gpu": infer["gpu"],
+        "total_tokens": total_tokens,
+        "energy_wh": energy_wh,
+        "energy_kwh": carbon["total_energy_kwh"],
+        "energy_per_mtoken_wh": energy_wh * per_m,
+        "carbon_per_mtoken_g": carbon["total_co2_g"] * per_m,
+        "gpu_hours": gpu_hours,
+        "financial_per_mtoken": (gpu_hours * gpu_hour_price * per_m) if gpu_hour_price else None,
+        "tokens_per_wh": total_tokens / energy_wh if energy_wh else 0.0,
+    }
+
+
+def export_opendc(infer: dict[str, Any], dst: Path) -> Path:
+    """Write the inference run's tasks/fragments as OpenDC input via the real adapter."""
+    from kavier_io.opendc.adapter import prepare_opendc_input
+
+    tasks = pd.DataFrame(infer["_tasks"])
+    # 1 fragment per task suffices for OpenDC's power model; adapter coerces the schema.
+    frags = pd.DataFrame(
+        [
+            {
+                "id": t["id"],
+                "duration": t["duration"],
+                "cpu_count": 1,
+                "cpu_usage": 0.0,
+                "gpu_count": 1,
+                "gpu_usage": t["gpu_capacity"],
+            }
+            for t in infer["_tasks"]
+        ]
+    )
+    dst.mkdir(parents=True, exist_ok=True)
+    prepare_opendc_input(tasks, frags, str(dst))
+    return dst
+
+
+def _with_columns(rows: list[dict[str, Any]], predicted: list[dict[str, Any]]) -> pd.DataFrame:
+    """Input rows + predicted columns, one output row per input row."""
+    merged = [{**row, **pred} for row, pred in zip(rows, predicted)]
+    return pd.DataFrame(merged)
+
+
+def performance(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-workload latency/throughput: + p50_ms, p95_ms, mean_ttft_ms, throughput_tok_s, total_s."""
+    rows = _normalise(batch)
+    cols = ("p50_ms", "p95_ms", "mean_ttft_ms", "throughput_tok_s", "throughput_req_s", "total_s", "total_tokens")
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        r = run_inference(_infer_params(row))
+        predicted.append({k: r[k] for k in cols})
+    return _with_columns(rows, predicted)
+
+
+def energy(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-workload energy (self-contained GPU-power estimate): + energy_wh, energy_per_mtoken_wh, tokens_per_wh."""
+    rows = _normalise(batch)
+    cols = ("energy_wh", "energy_kwh", "energy_per_mtoken_wh", "tokens_per_wh", "total_tokens")
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        e = energy_from_inference(run_inference(_infer_params(row)), gpu_hour_price=None)
+        predicted.append({k: e[k] for k in cols})
+    return _with_columns(rows, predicted)
+
+
+def efficiency(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-workload cost: + financial_per_mtoken ($/Mtoken). GPU $/hour from a ``gpu_hour_price`` column else 2.5."""
+    rows = _normalise(batch)
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        price = float(row.get("gpu_hour_price", DEFAULT_GPU_HOUR_PRICE))
+        e = energy_from_inference(run_inference(_infer_params(row)), gpu_hour_price=price)
+        predicted.append({"financial_per_mtoken": e["financial_per_mtoken"], "gpu_hours": e["gpu_hours"]})
+    return _with_columns(rows, predicted)
+
+
+def carbon(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-workload emissions: + total_co2_g, carbon_per_mtoken_g. Intensity from an ``intensity`` column else 400."""
+    rows = _normalise(batch)
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        intensity = float(row.get("intensity", DEFAULT_INTENSITY_G_KWH))
+        infer = run_inference(_infer_params(row))
+        c = run_carbon_from_inference(infer, intensity_g_kwh=intensity)
+        total_tokens = c["total_tokens"]
+        per_m = 1_000_000.0 / total_tokens if total_tokens else 0.0
+        predicted.append(
+            {
+                "total_co2_g": c["total_co2_g"],
+                "total_co2_kg": c["total_co2_kg"],
+                "carbon_per_mtoken_g": c["total_co2_g"] * per_m,
+                "total_energy_kwh": c["total_energy_kwh"],
+            }
+        )
+    return _with_columns(rows, predicted)

kavier/training/__init__.py

@@ -0,0 +1,164 @@
+"""Training predictors: ``performance / energy / efficiency / carbon`` over a batch of fine-tuning jobs.
+
+Each verb takes a *batch* — a pandas DataFrame, a list of dicts, or a single dict (one row per job)
+— and returns a DataFrame: the input rows plus the predicted columns. The per-row engine logic is
+canonical here; ``kavier_ui.sims`` and the CLIs consume it, so the numbers match exactly.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pandas as pd
+
+from kavier.inference import (
+    DEFAULT_GPU_HOUR_PRICE,
+    DEFAULT_INTENSITY_G_KWH,
+    _flat_trace,
+    _normalise,
+    _with_columns,
+)
+from kavier_co2.engine import Fragment, compute_emissions
+from kavier_training.core.engine import simulate_full_training, simulate_training_step
+
+DEFAULT_NUM_NODES = 1
+
+
+def _train_params(row: dict[str, Any]) -> dict[str, Any]:
+    """Default ``num_nodes`` (the only training key a batch commonly omits)."""
+    return {**row, "num_nodes": row.get("num_nodes", DEFAULT_NUM_NODES)}
+
+
+def run_training(p: dict[str, Any]) -> dict[str, Any]:
+    """Aggregate throughput/runtime (``simulate_full_training``) + per-step metrics (``simulate_training_step``)."""
+    full = simulate_full_training(
+        model_name=p["model"],
+        method=p["method"],
+        gpu_model=p["gpu"],
+        tokens_per_sample=int(p["seq_len"]),
+        batch_size=int(p["batch_size"]),
+        number_gpus=int(p["num_gpus"]),
+        number_nodes=int(p["num_nodes"]),
+        total_tokens=int(p["total_tokens"]) if p.get("total_tokens") else None,
+        epochs=float(p["epochs"]) if p.get("epochs") else None,
+        dataset_tokens=int(p["dataset_tokens"]) if p.get("dataset_tokens") else None,
+    )
+    total_gpus = int(p["num_gpus"]) * int(p["num_nodes"])
+    step = simulate_training_step(
+        model_name=p["model"],
+        gpu_model=p["gpu"],
+        tokens_per_sample=int(p["seq_len"]),
+        batch_size=int(p["batch_size"]),
+        method=p["method"],
+        num_gpus=total_gpus,
+        num_nodes=int(p["num_nodes"]),
+    )
+    out: dict[str, Any] = {**full, **step, "total_gpus": total_gpus}
+    out["aggregate_power_w"] = step["gpu_power_watts"] * total_gpus
+    return out
+
+
+def run_carbon_from_training(p: dict[str, Any]) -> dict[str, Any]:
+    """Bill one training-engine power fragment against a flat carbon intensity."""
+    tr = run_training(p)
+    runtime_s = float(tr["train_runtime"])
+    if runtime_s <= 0:
+        raise ValueError("training runtime is 0 — set a job size (total tokens or epochs) to bill carbon")
+    power_w = float(tr["aggregate_power_w"])
+    start = pd.Timestamp("2026-01-01 00:00:00")
+    trace = _flat_trace(start, runtime_s / 3600.0, p["intensity"])
+    frag = Fragment(start_time=start, duration_s=runtime_s, power_w=power_w)
+    res = compute_emissions([frag], trace)
+    return {
+        "source": "training",
+        "model": tr["model_name"],
+        "gpu": tr["gpu_name"],
+        "intensity": float(p["intensity"]),
+        "runtime_s": runtime_s,
+        "power_w": power_w,
+        "total_energy_kwh": res.total_energy_kwh,
+        "total_co2_g": res.total_co2_g,
+        "total_co2_kg": res.total_co2_kg,
+        "total_tokens": tr["total_tokens"],
+    }
+
+
+def performance(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-job throughput/util: + train_tokens_per_second, train_runtime, gpu_compute_utilization, gpu_power_watts."""
+    rows = _normalise(batch)
+    cols = (
+        "train_tokens_per_second",
+        "train_runtime",
+        "train_samples_per_second",
+        "gpu_compute_utilization",
+        "gpu_memory_utilization",
+        "gpu_power_watts",
+        "total_tokens",
+    )
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        r = run_training(_train_params(row))
+        predicted.append({k: r[k] for k in cols})
+    return _with_columns(rows, predicted)
+
+
+def energy(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-job energy (self-contained GPU-power estimate): + energy_wh, energy_per_mtoken_wh, aggregate_power_w."""
+    rows = _normalise(batch)
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        c = run_carbon_from_training({**_train_params(row), "intensity": DEFAULT_INTENSITY_G_KWH})
+        total_tokens = c["total_tokens"]
+        energy_wh = c["total_energy_kwh"] * 1000.0
+        per_m = 1_000_000.0 / total_tokens if total_tokens else 0.0
+        predicted.append(
+            {
+                "energy_wh": energy_wh,
+                "energy_kwh": c["total_energy_kwh"],
+                "energy_per_mtoken_wh": energy_wh * per_m,
+                "aggregate_power_w": c["power_w"],
+                "total_tokens": total_tokens,
+            }
+        )
+    return _with_columns(rows, predicted)
+
+
+def efficiency(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-job cost: + financial_per_mtoken ($/Mtoken). GPU $/hour from a ``gpu_hour_price`` column else 2.5."""
+    rows = _normalise(batch)
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        tr = run_training(_train_params(row))
+        total_tokens = tr["total_tokens"]
+        runtime_s = float(tr["train_runtime"])
+        price = float(row.get("gpu_hour_price", DEFAULT_GPU_HOUR_PRICE))
+        # GPU-hours = wall-clock runtime x total GPUs (matches the inference $/Mtoken basis).
+        gpu_hours = runtime_s / 3600.0 * int(tr["total_gpus"])
+        per_m = 1_000_000.0 / total_tokens if total_tokens else 0.0
+        predicted.append(
+            {
+                "financial_per_mtoken": (gpu_hours * price * per_m) if total_tokens else None,
+                "gpu_hours": gpu_hours,
+            }
+        )
+    return _with_columns(rows, predicted)
+
+
+def carbon(batch: pd.DataFrame | list[dict[str, Any]] | dict[str, Any]) -> pd.DataFrame:
+    """Per-job emissions: + total_co2_g, carbon_per_mtoken_g. Intensity from an ``intensity`` column else 400."""
+    rows = _normalise(batch)
+    predicted: list[dict[str, Any]] = []
+    for row in rows:
+        intensity = float(row.get("intensity", DEFAULT_INTENSITY_G_KWH))
+        c = run_carbon_from_training({**_train_params(row), "intensity": intensity})
+        total_tokens = c["total_tokens"]
+        per_m = 1_000_000.0 / total_tokens if total_tokens else 0.0
+        predicted.append(
+            {
+                "total_co2_g": c["total_co2_g"],
+                "total_co2_kg": c["total_co2_kg"],
+                "carbon_per_mtoken_g": c["total_co2_g"] * per_m,
+                "total_energy_kwh": c["total_energy_kwh"],
+            }
+        )
+    return _with_columns(rows, predicted)

kavier-0.3.1.dist-info/METADATA

@@ -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).