gitm-labs 0.0.1__py3-none-any.whl

gitm/__init__.py

@@ -0,0 +1,9 @@
+"""gitm — behavioral compiler and intervention runtime."""
+
+from __future__ import annotations
+
+__version__ = "0.0.1"
+
+from gitm.api import optimize
+
+__all__ = ["__version__", "optimize"]

gitm/_paths.py

@@ -0,0 +1,109 @@
+"""Resolve data locations.
+
+GITM's canonical data store is **S3**. Datasets, plus the durable copy of run
+outputs, traces, and telemetry, all live under an ``s3://`` root. Datasets are
+far too large to hold on local disk wholesale (the AlphaFold2 DBs alone are
+~2.2 TB), so the local filesystem is treated only as *bounded scratch*: the
+active run's working set is staged in, used, and evicted. Nothing here ever
+assumes a dataset lives on local disk.
+
+Two roots:
+
+* ``$GITM_S3_ROOT`` — ``s3://bucket/prefix``, the canonical store. Datasets at
+  ``<s3_root>/datasets/<name>/``; durable run/trace/telemetry archives at
+  ``<s3_root>/{runs,traces,telemetry}/``.
+* ``$GITM_SCRATCH`` — a local *ephemeral* directory for the active run's
+  outputs and staged inputs (small: a run writes here, then the durable copy is
+  synced to S3). Defaults to ``~/.cache/gitm``. Never holds datasets at rest.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+DEFAULT_SCRATCH = "~/.cache/gitm"
+
+# Local scratch subdirectories. Note: no ``datasets`` — datasets are never
+# materialized wholesale on local disk; they are staged on demand into
+# ``staging/`` from S3 for the duration of a run, then evicted.
+_SCRATCH_SUBDIRS = ("runs", "traces", "telemetry", "staging")
+
+
+def s3_root(override: str | None = None) -> str | None:
+    """Return the canonical ``s3://`` root, or ``None`` if unconfigured.
+
+    Resolution order: explicit ``override``, then ``$GITM_S3_ROOT``. Returned
+    without a trailing slash. Returns ``None`` when neither is set so callers
+    can degrade gracefully (e.g. a local run with no archival). Callers that
+    *require* S3 — anything touching datasets — should use :func:`dataset_uri`
+    or :func:`require_s3_root`, which raise with a clear message instead.
+    """
+    raw = override or os.environ.get("GITM_S3_ROOT")
+    if not raw:
+        return None
+    return raw.rstrip("/")
+
+
+def require_s3_root(override: str | None = None) -> str:
+    """Like :func:`s3_root` but raise if no canonical store is configured."""
+    root = s3_root(override)
+    if root is None:
+        raise RuntimeError(
+            "No S3 root configured. GITM datasets live in S3 and are never "
+            "stored on local disk. Set $GITM_S3_ROOT, e.g.\n"
+            "    export GITM_S3_ROOT=s3://gitm-data/prod"
+        )
+    return root
+
+
+def dataset_uri(name: str, *, s3_root_override: str | None = None) -> str:
+    """Canonical ``s3://`` URI for a dataset.
+
+    ``dataset_uri("hft/hft_1b_seed42")`` -> ``s3://.../datasets/hft/hft_1b_seed42``.
+    """
+    return f"{require_s3_root(s3_root_override)}/datasets/{name.strip('/')}"
+
+
+def durable_uri(kind: str, run_id: str, *, s3_root_override: str | None = None) -> str:
+    """Canonical ``s3://`` archive URI for a run output.
+
+    ``kind`` is one of ``runs``, ``traces``, ``telemetry`` — the durable
+    destination a scratch artifact is synced to once the run completes.
+    """
+    if kind not in ("runs", "traces", "telemetry"):
+        raise ValueError(f"unknown durable artifact kind: {kind!r}")
+    return f"{require_s3_root(s3_root_override)}/{kind}/{run_id}"
+
+
+def scratch_root(override: str | None = None) -> Path:
+    """Return the local scratch directory as an absolute Path.
+
+    Resolution order: explicit ``override``, then ``$GITM_SCRATCH``, then
+    ``~/.cache/gitm``. Ephemeral — holds the active run's outputs and staged
+    working set only, never datasets at rest. Created if absent.
+    """
+    raw = override or os.environ.get("GITM_SCRATCH") or DEFAULT_SCRATCH
+    root = Path(raw).expanduser().resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    for sub in _SCRATCH_SUBDIRS:
+        (root / sub).mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def traces_dir(override: str | None = None) -> Path:
+    return scratch_root(override) / "traces"
+
+
+def runs_dir(override: str | None = None) -> Path:
+    return scratch_root(override) / "runs"
+
+
+def telemetry_dir(override: str | None = None) -> Path:
+    return scratch_root(override) / "telemetry"
+
+
+def staging_dir(override: str | None = None) -> Path:
+    """Local landing zone for datasets staged in from S3 for the active run."""
+    return scratch_root(override) / "staging"

gitm/agents/__init__.py

@@ -0,0 +1,12 @@
+"""Autonomous decision policy — selects interventions, drives rollback.
+
+The agent layer is intentionally thin: rank candidates by predicted delta
+returned from counterfactual replay, pre-filter by safety gate, apply with
+rollback, observe live delta, persist the chain into the provenance trail.
+"""
+
+from __future__ import annotations
+
+from gitm.agents.policy import Policy, RankedCandidate, select_interventions
+
+__all__ = ["Policy", "RankedCandidate", "select_interventions"]

gitm/agents/policy.py

@@ -0,0 +1,48 @@
+"""Selection policy: pre-filter by safety, rank by predicted delta, return top-N."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterable
+
+from gitm.kernels.spec import InterventionSpec
+from gitm.optimizer.replay import predict_delta
+from gitm.tracer.schema import Trace
+
+
+@dataclass
+class RankedCandidate:
+    spec: InterventionSpec
+    predicted_delta: float
+    rejected_reason: str | None = None
+
+
+@dataclass
+class Policy:
+    """Greedy by predicted delta with safety pre-filter."""
+
+    require_qualification_commit: bool = False
+    skip_high_risk: bool = False
+
+
+def select_interventions(
+    trace: Trace,
+    library: Iterable[InterventionSpec],
+    policy: Policy,
+    top_n: int = 5,
+) -> list[RankedCandidate]:
+    candidates: list[RankedCandidate] = []
+
+    for spec in library:
+        reason: str | None = None
+        if policy.skip_high_risk and spec.safety.tier == "high_risk":
+            reason = "policy.skip_high_risk"
+        elif spec.safety.requires_qualification_commit and not policy.require_qualification_commit:
+            reason = "safety.requires_qualification_commit"
+        delta = predict_delta(trace, spec) if reason is None else 0.0
+        candidates.append(RankedCandidate(spec=spec, predicted_delta=delta, rejected_reason=reason))
+
+    candidates.sort(
+        key=lambda c: (c.rejected_reason is not None, -c.predicted_delta, c.spec.name)
+    )
+    return candidates[:top_n]

gitm/api.py

@@ -0,0 +1,37 @@
+"""Public embedded API.
+
+    from gitm import optimize
+    optimize(engine, budget="24h", target=0.15)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from gitm.scheduler import LoopConfig, run_loop
+
+
+def optimize(
+    engine: Any | None = None,
+    *,
+    workload: str | None = None,
+    budget: str = "24h",
+    target: float = 0.15,
+    scratch: str | None = None,
+) -> dict[str, Any]:
+    """Run the autonomous 24-hour optimization loop and return a report.
+
+    Either pass an ``engine`` (e.g. a running vLLM engine handle) for the
+    embedded path, or pass ``workload`` (e.g. ``"vllm-decode"``) for the CLI
+    path. ``budget`` and ``target`` follow the SKU contract: a verified floor
+    of ``target`` fraction improvement within ``budget`` wall time, or a
+    qualification-gate diagnostic explaining why the floor was not committed.
+    """
+    cfg = LoopConfig(
+        engine=engine,
+        workload=workload,
+        budget=budget,
+        target=target,
+        scratch=scratch,
+    )
+    return run_loop(cfg)

gitm/bench/__init__.py

@@ -0,0 +1,30 @@
+"""Shared benchmark systems layer.
+
+The benchmark *layer* is deliberately dumb and identical across domains (HFT,
+biotech, edge/robotics) so the runtime layer — planner, deviation monitor,
+causal attribution — does the real work against a heterogeneous workload mix
+without per-benchmark plumbing. Everything domain-specific lives in a single
+``bench.toml`` per benchmark; everything mechanical lives here and is reused.
+
+What this package gives every benchmark pair:
+
+* :mod:`gitm.bench.schema` — the canonical data shapes: ``BenchConfig`` (parsed
+  ``bench.toml``), ``StallPhase`` (one row of the stall-breakdown table), and
+  ``BaselineRun`` (the ``<name>_baseline_N.json`` contract).
+* :mod:`gitm.bench.manifest` — streaming sha256 manifest build + verify, so any
+  holder of ``manifest.yaml`` can re-fetch byte-identical TB-scale datasets.
+* :mod:`gitm.bench.baseline` — the two sign-off gates: three seeds agree within
+  2 % (``spread``) and GPU active % stays under the ceiling (``saturation``).
+* :mod:`gitm.bench.profile` — the GITM profiling wrapper around nsys/rocprof +
+  py-spy/sar that produces the stall-breakdown table.
+* :mod:`gitm.bench.edge_manifest` — the nuScenes+KITTI ``manifest.jsonl`` builder.
+* :mod:`gitm.bench.results` — renders ``results.md``.
+
+Driven from each ``benchmarks/<name>/Makefile`` via ``python -m gitm.bench``.
+"""
+
+from __future__ import annotations
+
+from gitm.bench.schema import BaselineRun, BenchConfig, StallPhase
+
+__all__ = ["BaselineRun", "BenchConfig", "StallPhase"]

gitm/bench/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m gitm.bench`` entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from gitm.bench.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

gitm/bench/baseline.py

@@ -0,0 +1,169 @@
+"""Baseline aggregation and the two sign-off gates.
+
+A baseline is *locked* when three convergent runs (one per seed) agree on the
+top-line metric within 2 % — the recorded baseline is their mean. Two gates
+decide sign-off, both encoded here so every benchmark is judged identically:
+
+* **spread gate** — ``max-min`` over ``mean`` of the three metric values must
+  be under ``spread_tolerance`` (default 2 %). Convergence is what makes the
+  number trustworthy as an optimization reference.
+* **saturation gate** — wall-clock-weighted GPU active % must stay under
+  ``gpu_active_ceiling`` (default 85 %). A saturated benchmark has no residual
+  headroom for the runtime to find, so it trips the same-day swap rule.
+
+A third, optional check compares the recorded mean against ``baseline_target``
+(e.g. HFT ≥ 25 M events/s) in the configured direction.
+"""
+
+from __future__ import annotations
+
+import json
+import statistics
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from gitm.bench.schema import BaselineRun, BenchConfig
+
+
+def load_runs(paths: list[str | Path]) -> list[BaselineRun]:
+    runs = []
+    for p in paths:
+        runs.append(BaselineRun.model_validate_json(Path(p).read_text()))
+    return runs
+
+
+@dataclass
+class GateResult:
+    name: str
+    passed: bool
+    detail: str
+
+
+@dataclass
+class BaselineSummary:
+    benchmark: str
+    metric: str
+    n: int
+    mean: float
+    stddev: float
+    spread: float  # (max - min) / mean
+    gpu_active_overall: float  # worst (max) across runs
+    recorded: float  # the number we publish = mean
+    gates: list[GateResult] = field(default_factory=list)
+    seeds: list[int] = field(default_factory=list)
+
+    @property
+    def passed(self) -> bool:
+        return all(g.passed for g in self.gates)
+
+    def to_dict(self) -> dict:
+        return {
+            "benchmark": self.benchmark,
+            "metric": self.metric,
+            "n": self.n,
+            "seeds": self.seeds,
+            "recorded": self.recorded,
+            "mean": self.mean,
+            "stddev": self.stddev,
+            "spread": self.spread,
+            "gpu_active_overall": self.gpu_active_overall,
+            "passed": self.passed,
+            "gates": [
+                {"name": g.name, "passed": g.passed, "detail": g.detail}
+                for g in self.gates
+            ],
+        }
+
+
+def aggregate(runs: list[BaselineRun], config: BenchConfig) -> BaselineSummary:
+    """Aggregate baseline runs and evaluate the sign-off gates.
+
+    Does not assume exactly three runs — fewer is a gate failure, more is fine —
+    so a pair can iterate on two and still get a meaningful spread reading.
+    """
+    if not runs:
+        raise ValueError("no baseline runs to aggregate")
+
+    for r in runs:
+        if r.benchmark != config.name:
+            raise ValueError(
+                f"run benchmark {r.benchmark!r} != config {config.name!r}"
+            )
+        if r.metric != config.metric:
+            raise ValueError(f"run metric {r.metric!r} != config {config.metric!r}")
+
+    values = [r.metric_value for r in runs]
+    mean = statistics.fmean(values)
+    stddev = statistics.pstdev(values) if len(values) > 1 else 0.0
+    spread = (max(values) - min(values)) / mean if mean else float("inf")
+    gpu_overall = max(r.gpu_active_overall() for r in runs)
+
+    gates: list[GateResult] = []
+
+    # Gate 1: three convergent seeds.
+    n_ok = len(runs) >= 3
+    spread_ok = spread <= config.spread_tolerance
+    gates.append(
+        GateResult(
+            "count",
+            n_ok,
+            f"{len(runs)} run(s); need >= 3 convergent seeds",
+        )
+    )
+    gates.append(
+        GateResult(
+            "spread",
+            spread_ok,
+            f"spread {spread:.2%} vs tolerance {config.spread_tolerance:.2%}",
+        )
+    )
+
+    # Gate 2: saturation / swap rule.
+    sat_ok = gpu_overall < config.gpu_active_ceiling
+    gates.append(
+        GateResult(
+            "saturation",
+            sat_ok,
+            f"GPU active {gpu_overall:.1%} vs ceiling {config.gpu_active_ceiling:.0%}"
+            + ("" if sat_ok else " — trips swap rule, shard same day"),
+        )
+    )
+
+    # Gate 3 (optional): metric vs target.
+    if config.baseline_target is not None:
+        if config.target_direction == "ge":
+            tgt_ok = mean >= config.baseline_target
+            cmp = ">="
+        else:
+            tgt_ok = mean <= config.baseline_target
+            cmp = "<="
+        gates.append(
+            GateResult(
+                "target",
+                tgt_ok,
+                f"mean {mean:.4g} {cmp} target {config.baseline_target:.4g}",
+            )
+        )
+
+    return BaselineSummary(
+        benchmark=config.name,
+        metric=config.metric,
+        n=len(runs),
+        mean=mean,
+        stddev=stddev,
+        spread=spread,
+        gpu_active_overall=gpu_overall,
+        recorded=mean,
+        gates=gates,
+        seeds=sorted(r.seed for r in runs),
+    )
+
+
+def aggregate_files(paths: list[str | Path], config: BenchConfig) -> BaselineSummary:
+    return aggregate(load_runs(paths), config)
+
+
+def write_summary(summary: BaselineSummary, out: str | Path) -> Path:
+    out = Path(out)
+    out.write_text(json.dumps(summary.to_dict(), indent=2) + "\n")
+    return out