db-agent-kit 0.2.0__py3-none-any.whl

db_agent/__init__.py

@@ -0,0 +1,3 @@
+"""db-agent CLI: read-only DBA toolkit. One verb set per database engine."""
+
+__version__ = "0.2.0"

db_agent/cli.py

@@ -0,0 +1,32 @@
+"""db-agent <engine> <verb>. Each available engine is a sub-command group; planned engines are only listed."""
+
+from __future__ import annotations
+
+import typer
+
+from . import __version__
+from .engines import ENGINES
+
+app = typer.Typer(add_completion=False, no_args_is_help=True,
+                  help="db-agent: read-only DBA toolkit. Run `db-agent engines` to see what is supported.")
+
+for _e in ENGINES:
+    if _e.status == "available":
+        app.add_typer(_e.load(), name=_e.name, help=_e.summary)
+
+
+@app.command()
+def engines() -> None:
+    """List database engines and whether they are implemented."""
+    for e in ENGINES:
+        typer.echo(f"{e.name:<12} {e.status:<10} {e.title}: {e.summary}")
+
+
+@app.command()
+def version() -> None:
+    """Print the db-agent version."""
+    typer.echo(__version__)
+
+
+if __name__ == "__main__":
+    app()

db_agent/engines/__init__.py

@@ -0,0 +1,36 @@
+"""Engine registry. One entry per database engine the CLI knows about.
+
+To add an engine, create `db_agent/engines/<name>/` with a `cli.py` that exposes a Typer `app`, then add
+an `Engine(...)` below with status "available". See docs/adding-an-engine.md.
+"""
+
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+
+import typer
+
+
+@dataclass(frozen=True)
+class Engine:
+    name: str            # the CLI verb: db-agent <name> ...
+    title: str
+    summary: str
+    status: str          # "available" or "planned"
+    module: str | None = None  # dotted path to a module exposing a Typer `app` (available engines only)
+
+    def load(self) -> typer.Typer:
+        if self.status != "available" or not self.module:
+            raise LookupError(f"engine {self.name!r} is {self.status}, not implemented")
+        return importlib.import_module(self.module).app
+
+
+ENGINES: tuple[Engine, ...] = (
+    Engine("sqlserver", "SQL Server and SSRS", "Inventory, migration risk, SSRS report triage and validation.",
+           "available", "db_agent.engines.sqlserver.cli"),
+    Engine("postgres", "PostgreSQL", "Not implemented yet.", "planned"),
+    Engine("mysql", "MySQL", "Not implemented yet.", "planned"),
+    Engine("databricks", "Databricks", "Workspace health: runtimes, legacy dependencies, DBU spend, spend waste.",
+           "available", "db_agent.engines.databricks.cli"),
+)

db_agent/engines/databricks/__init__.py

@@ -0,0 +1 @@
+"""db-agent Databricks engine: read-only workspace checks (system tables plus the REST API)."""

db_agent/engines/databricks/checks.py

@@ -0,0 +1,221 @@
+"""Pure checks: plain dicts in, Findings out. No network, no SDK."""
+
+from __future__ import annotations
+
+from collections import Counter
+from datetime import date
+from typing import Iterable
+
+from . import runtimes
+from .model import Finding
+
+ALL_PURPOSE_SOURCES = {"UI", "API", None, ""}
+NO_ISOLATION = {"NONE", "LEGACY_TABLE_ACL", "LEGACY_PASSTHROUGH", "LEGACY_SINGLE_USER", "LEGACY_SINGLE_USER_STANDARD"}
+
+
+def _num(v) -> float:
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def is_all_purpose(c: dict) -> bool:
+    return c.get("cluster_source") in ALL_PURPOSE_SOURCES
+
+
+def _job_specs(jobs: Iterable[dict]) -> Iterable[dict]:
+    """Every cluster definition inside job settings: {'job_id','job','where','spec'}."""
+    for j in jobs:
+        s = j.get("settings") or {}
+        base = {"job_id": j.get("job_id"), "job": s.get("name")}
+        for jc in s.get("job_clusters") or []:
+            yield {**base, "where": f"job cluster {jc.get('job_cluster_key')}", "spec": jc.get("new_cluster") or {}}
+        for t in s.get("tasks") or []:
+            if t.get("new_cluster"):
+                yield {**base, "where": f"task {t.get('task_key')}", "spec": t["new_cluster"]}
+
+
+def _all_specs(clusters: list[dict], jobs: list[dict]) -> Iterable[dict]:
+    for c in clusters:
+        if is_all_purpose(c):
+            yield {"job_id": None, "job": None, "where": f"cluster {c.get('cluster_name')} ({c.get('cluster_id')})",
+                   "spec": c, "owner": c.get("creator_user_name")}
+    yield from _job_specs(jobs)
+
+
+# ---- runtimes -------------------------------------------------------------------------------------
+def runtime_findings(clusters, jobs, today: date, warn_days: int) -> list[Finding]:
+    rows, versions = [], Counter()
+    for s in _all_specs(clusters, jobs):
+        st = runtimes.classify(s["spec"].get("spark_version"), today, warn_days)
+        versions[st.label] += 1
+        if st.state in ("ended", "ending_soon"):
+            rows.append({"where": ("job " + str(s["job"]) + ": " if s["job"] else "") + s["where"],
+                         "runtime": st.label, "state": st.state,
+                         "end_of_support": st.eos.isoformat() if st.eos else "ended (before 10.5)",
+                         "days_left": st.days_left})
+    out = []
+    ended = [r for r in rows if r["state"] == "ended"]
+    soon = [r for r in rows if r["state"] == "ending_soon"]
+    if ended:
+        out.append(Finding("runtime.ended", "high", f"{len(ended)} cluster definitions on runtimes past end of support",
+                           "Databricks no longer supports these runtimes. Existing jobs may keep running, but they get no fixes.",
+                           ended, "Move to a supported LTS runtime (check the support table in the Databricks docs)."))
+    if soon:
+        out.append(Finding("runtime.ending_soon", "medium", f"{len(soon)} cluster definitions on runtimes that end support within {warn_days} days",
+                           "Plan the upgrade before the end-of-support date.", soon, "Test the workload on the next LTS runtime."))
+    unknown = sum(n for lbl, n in versions.items() if lbl.startswith("custom") or lbl == "unknown")
+    detail = ", ".join(f"{k}: {v}" for k, v in sorted(versions.items())) or "none found"
+    if unknown:
+        detail += f". {unknown} could not be classified (custom image or version newer than this tool's table)."
+    out.append(Finding("runtime.summary", "info", "Runtime versions in use", detail, [], ""))
+    return out
+
+
+# ---- legacy dependencies ----------------------------------------------------------------------------
+def init_script_findings(clusters, jobs) -> list[Finding]:
+    rows = []
+    for s in _all_specs(clusters, jobs):
+        for sc in s["spec"].get("init_scripts") or []:
+            dest = (sc.get("dbfs") or {}).get("destination")
+            if dest:
+                rows.append({"where": ("job " + str(s["job"]) + ": " if s["job"] else "") + s["where"], "script": dest})
+    if not rows:
+        return []
+    return [Finding("legacy.dbfs_init_scripts", "high", f"{len(rows)} init script references on DBFS",
+                    "DBFS root is local to one workspace, so these scripts do not exist in a new workspace.",
+                    rows, "Move the scripts to workspace files or a Unity Catalog volume and update the cluster definitions.")]
+
+
+def isolation_findings(clusters, jobs) -> list[Finding]:
+    rows, unset = [], 0
+    for s in _all_specs(clusters, jobs):
+        mode = s["spec"].get("data_security_mode")
+        if mode in NO_ISOLATION:
+            rows.append({"where": ("job " + str(s["job"]) + ": " if s["job"] else "") + s["where"], "data_security_mode": mode})
+        elif mode is None:
+            unset += 1
+    out = []
+    if rows:
+        out.append(Finding("legacy.no_isolation", "medium", f"{len(rows)} cluster definitions without Unity Catalog access mode",
+                           "No-isolation and legacy access modes cannot use Unity Catalog governance.", rows,
+                           "Switch to standard (shared) or dedicated (single user) access mode."))
+    if unset:
+        out.append(Finding("legacy.access_mode_unset", "info", f"{unset} cluster definitions do not set an access mode",
+                           "The effective mode then comes from workspace or policy defaults. Check them in the UI.", [], ""))
+    return out
+
+
+def hms_findings(schemas: dict[str, int] | None) -> list[Finding]:
+    if not schemas:
+        return []
+    total = sum(schemas.values())
+    if total == 0:
+        return []
+    rows = [{"schema": k, "tables": v} for k, v in sorted(schemas.items(), key=lambda kv: -kv[1]) if v][:25]
+    return [Finding("legacy.hive_metastore", "medium", f"{total} tables in the Hive metastore across {len(rows)} schemas",
+                    "Hive metastore tables belong to one workspace and are not governed by Unity Catalog. A new workspace will not see them.",
+                    rows, "Upgrade them to Unity Catalog (SYNC for external tables, DEEP CLONE or CTAS for managed ones).")]
+
+
+def mount_findings(events: list[dict] | None, lookback_days: int) -> list[Finding]:
+    if not events:
+        return []
+    return [Finding("legacy.dbfs_mounts", "medium", f"{len(events)} DBFS mount events in the last {lookback_days} days",
+                    "Audit logs show mount creation only. They do not list the mounts that exist today; run dbutils.fs.mounts() "
+                    "in a notebook for that. Mounts are workspace-local and deprecated in favour of Unity Catalog external locations.",
+                    [{"date": str(e.get("event_date")), "user": e.get("user_email"), "params": e.get("params")} for e in events[:25]],
+                    "Replace /mnt paths with external locations or volumes.")]
+
+
+# ---- waste -------------------------------------------------------------------------------------------
+def _scheduled(settings: dict) -> bool:
+    for key in ("schedule", "trigger", "continuous"):
+        v = settings.get(key)
+        if v and v.get("pause_status") != "PAUSED":
+            return True
+    return False
+
+
+def jobs_on_all_purpose(jobs, clusters, spend: dict[str, dict] | None, days: int) -> list[Finding]:
+    names = {c.get("cluster_id"): c for c in clusters}
+    rows = []
+    for j in jobs:
+        s = j.get("settings") or {}
+        if not _scheduled(s):
+            continue
+        ids = {t.get("existing_cluster_id") for t in s.get("tasks") or [] if t.get("existing_cluster_id")}
+        if s.get("existing_cluster_id"):
+            ids.add(s["existing_cluster_id"])
+        for cid in sorted(ids):
+            sp = (spend or {}).get(cid)
+            rows.append({"job": s.get("name"), "job_id": j.get("job_id"), "cluster": (names.get(cid) or {}).get("cluster_name", cid),
+                         "cluster_id": cid, f"cluster_spend_{days}d": round(_num(sp["cost"]), 2) if sp and sp.get("cost") is not None else None})
+    if not rows:
+        return []
+    rows.sort(key=lambda r: -(r[f"cluster_spend_{days}d"] or 0))
+    return [Finding("waste.jobs_on_all_purpose", "high", f"{len(rows)} scheduled jobs run on all-purpose clusters",
+                    "All-purpose compute costs more per DBU than job compute. Spend shown is the whole cluster's list-price spend, "
+                    "which includes anything else that ran on it (billing does not tag all-purpose usage with the job).",
+                    rows, "Give each job its own job cluster, or use serverless jobs.")]
+
+
+def no_autotermination(clusters, spend: dict[str, dict] | None, days: int) -> list[Finding]:
+    rows = []
+    for c in clusters:
+        if not is_all_purpose(c) or c.get("autotermination_minutes") != 0:   # only an explicit 0 means disabled
+            continue
+        sp = (spend or {}).get(c.get("cluster_id"))
+        rows.append({"cluster": c.get("cluster_name"), "cluster_id": c.get("cluster_id"), "state": c.get("state"),
+                     "owner": c.get("creator_user_name"), f"spend_{days}d": round(_num(sp["cost"]), 2) if sp and sp.get("cost") is not None else None})
+    if not rows:
+        return []
+    running = sum(1 for r in rows if r["state"] == "RUNNING")
+    rows.sort(key=lambda r: (r["state"] != "RUNNING", -(r[f"spend_{days}d"] or 0)))
+    return [Finding("waste.no_autotermination", "high" if running else "medium",
+                    f"{len(rows)} all-purpose clusters never auto-terminate ({running} running now)",
+                    "A cluster with auto-termination off bills until someone stops it.", rows,
+                    "Set auto-termination (for example 30 to 60 minutes) or enforce it with a cluster policy.")]
+
+
+def warehouse_findings(warehouses, spend: dict[str, dict] | None, queries: dict[str, dict] | None, days: int) -> list[Finding]:
+    billed_idle, never_stop = [], []
+    for w in warehouses:
+        wid = w.get("id")
+        sp = (spend or {}).get(wid)
+        q = (queries or {}).get(wid)
+        cost = _num(sp["cost"]) if sp and sp.get("cost") is not None else None
+        nq = int(q["queries"]) if q else (0 if queries is not None else None)
+        row = {"warehouse": w.get("name"), "id": wid, "state": w.get("state"), "size": w.get("cluster_size"),
+               "auto_stop_mins": w.get("auto_stop_mins"), f"spend_{days}d": round(cost, 2) if cost is not None else None,
+               f"queries_{days}d": nq, "last_query": q.get("last_query") if q else None}
+        if nq == 0 and sp and _num(sp.get("dbus")) > 0:
+            billed_idle.append(row)
+        if w.get("auto_stop_mins") == 0:
+            never_stop.append(row)
+    out = []
+    if billed_idle:
+        out.append(Finding("waste.idle_warehouses", "high", f"{len(billed_idle)} SQL warehouses billed DBUs but ran no queries in {days} days",
+                           "These warehouses were started and kept running without serving any query.", billed_idle,
+                           "Stop or delete them, and lower auto-stop."))
+    if never_stop:
+        out.append(Finding("waste.warehouse_no_autostop", "medium", f"{len(never_stop)} SQL warehouses with auto-stop disabled",
+                           "They run until someone stops them.", never_stop, "Set auto-stop to 10 minutes or less."))
+    return out
+
+
+def untagged_findings(rows: list[dict] | None, days: int) -> list[Finding]:
+    if not rows:
+        return []
+    total = sum(_num(r.get("cost")) for r in rows)
+    untagged = sum(_num(r.get("untagged_cost")) for r in rows)
+    if total <= 0:
+        return []
+    share = untagged / total * 100
+    items = [{"product": r["product"], "untagged_cost": round(_num(r.get("untagged_cost")), 2),
+              "total_cost": round(_num(r.get("cost")), 2)} for r in rows if _num(r.get("untagged_cost")) > 0][:15]
+    sev = "high" if share >= 50 else "medium" if share >= 20 else "low"
+    return [Finding("waste.untagged_spend", sev, f"{share:.0f}% of spend has no tags (${untagged:,.0f} of ${total:,.0f} in {days} days)",
+                    "Spend without tags cannot be charged back to a team or project. List price, before discounts.",
+                    items, "Add custom tags on clusters, jobs and warehouses, and enforce them with a cluster policy.")]

db_agent/engines/databricks/cli.py

@@ -0,0 +1,61 @@
+"""db-agent databricks <verb>."""
+
+from __future__ import annotations
+
+from datetime import date
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from . import cost as cost_mod, health as health_mod, render
+
+app = typer.Typer(add_completion=False, no_args_is_help=True, help="Read-only checks of a Databricks workspace.")
+
+
+@app.callback()
+def _root() -> None:
+    """Databricks engine."""
+
+
+@app.command()
+def health(
+    profile: Annotated[Optional[str], typer.Option("--profile", help="Profile in ~/.databrickscfg. Without it, DATABRICKS_HOST/DATABRICKS_TOKEN or the default profile is used. Tokens are never taken on the command line.")] = None,
+    host: Annotated[Optional[str], typer.Option("--host", help="Workspace URL.")] = None,
+    warehouse_id: Annotated[Optional[str], typer.Option("--warehouse-id", help="SQL warehouse for system table queries. Default: a warehouse that is already running. A stopped warehouse starts (and bills) when it is used.")] = None,
+    no_sql: Annotated[bool, typer.Option("--no-sql", help="REST API checks only. Skips every system table query.")] = False,
+    lookback_days: Annotated[int, typer.Option("--lookback-days", min=1, max=365, help="Window for waste checks.")] = 30,
+    cost_from: Annotated[Optional[str], typer.Option("--cost-from", help="First month for the cost comparison, YYYY-MM. Default: two months before the current one.")] = None,
+    cost_to: Annotated[Optional[str], typer.Option("--cost-to", help="Last month, YYYY-MM. Default: the current month.")] = None,
+    eos_warning_days: Annotated[int, typer.Option("--eos-warning-days", help="Flag runtimes that end support within this many days.")] = 180,
+    all_workspaces: Annotated[bool, typer.Option("--all-workspaces", help="Include every workspace in the account in billing queries.")] = False,
+    out: Annotated[Path, typer.Option("--out", help="Output folder.")] = Path("db-agent-databricks-output"),
+    format: Annotated[str, typer.Option("--format", help="Comma list of: md, json.")] = "md,json",
+) -> None:
+    """Workspace health: runtimes, legacy dependencies, DBU spend over time, spend waste."""
+    formats = {f.strip().lower() for f in format.split(",") if f.strip()}
+    if formats - {"md", "json"}:
+        raise typer.BadParameter("--format accepts md and json")
+    if bool(cost_from) != bool(cost_to):
+        raise typer.BadParameter("give both --cost-from and --cost-to, or neither")
+    if cost_from:
+        try:
+            cost_mod.month_list(cost_from, cost_to)
+        except (ValueError, TypeError) as e:
+            raise typer.BadParameter(f"--cost-from/--cost-to: {e}")
+    from .client import DatabricksError, connect   # imports the SDK only when the command runs
+    try:
+        reader = connect(profile, host, warehouse_id, use_sql=not no_sql)
+    except Exception as e:   # noqa: BLE001
+        typer.echo(f"Could not connect to Databricks: {e}\nCheck `databricks auth login` or DATABRICKS_HOST/DATABRICKS_TOKEN.", err=True)
+        raise typer.Exit(2)
+    if not no_sql and not reader.has_sql:
+        typer.echo("No running SQL warehouse found. Pass --warehouse-id (it will start if stopped) or --no-sql.", err=True)
+    try:
+        rep = health_mod.run(reader, health_mod.Options(date.today(), lookback_days, cost_from, cost_to, eos_warning_days, all_workspaces))
+    except DatabricksError as e:
+        typer.echo(str(e), err=True)
+        raise typer.Exit(2)
+    typer.echo(render.console(rep))
+    for p in render.write(rep, out, formats):
+        typer.echo(f"wrote {p}")

db_agent/engines/databricks/client.py

@@ -0,0 +1,86 @@
+"""The only module that imports the Databricks SDK. Read-only by construction:
+
+* REST: list/get calls only (clusters, jobs, warehouses, workspace id).
+* SQL: statements go through sqlguard.check() and are SELECT/WITH or SHOW ... IN hive_metastore only.
+tests/databricks/test_architecture.py enforces both rules.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from . import sqlguard
+
+
+class DatabricksError(Exception):
+    pass
+
+
+class Reader:
+    def __init__(self, ws: Any, warehouse_id: str | None, sql_timeout_s: int = 300, sql_skipped: bool = False):
+        self._ws = ws
+        self.sql_skipped = sql_skipped
+        self.warehouse_id = warehouse_id
+        self._timeout = sql_timeout_s
+
+    @property
+    def has_sql(self) -> bool:
+        return bool(self.warehouse_id)
+
+    # ---- REST -------------------------------------------------------------------------------------
+    def workspace_id(self) -> str:
+        return str(self._ws.get_workspace_id())
+
+    def host(self) -> str:
+        return str(self._ws.config.host)
+
+    def clusters(self) -> list[dict]:
+        return [c.as_dict() for c in self._ws.clusters.list()]
+
+    def jobs(self) -> list[dict]:
+        return [j.as_dict() for j in self._ws.jobs.list(expand_tasks=True)]
+
+    def warehouses(self) -> list[dict]:
+        return [w.as_dict() for w in self._ws.warehouses.list()]
+
+    # ---- SQL --------------------------------------------------------------------------------------
+    def sql(self, statement: str) -> list[dict]:
+        if not self.warehouse_id:
+            raise DatabricksError("no SQL warehouse selected")
+        sqlguard.check(statement)
+        r = self._ws.statement_execution.execute_statement(
+            statement=statement, warehouse_id=self.warehouse_id, wait_timeout="30s", row_limit=10000)
+        deadline = time.monotonic() + self._timeout
+        while r.status and r.status.state.value in ("PENDING", "RUNNING"):
+            if time.monotonic() > deadline:
+                self._ws.statement_execution.cancel_execution(r.statement_id)
+                raise DatabricksError(f"query still running after {self._timeout}s, cancelled")
+            time.sleep(2)
+            r = self._ws.statement_execution.get_statement(r.statement_id)
+        state = r.status.state.value if r.status and r.status.state else "UNKNOWN"
+        if state != "SUCCEEDED":
+            err = r.status.error.message if r.status and r.status.error else state
+            raise DatabricksError(str(err)[:400])
+        cols = [c.name for c in (r.manifest.schema.columns if r.manifest and r.manifest.schema else [])]
+        rows = (r.result.data_array if r.result and r.result.data_array else [])
+        return [dict(zip(cols, row)) for row in rows]
+
+
+def connect(profile: str | None, host: str | None, warehouse_id: str | None, use_sql: bool = True) -> Reader:
+    """Unified auth: --profile, DATABRICKS_HOST/DATABRICKS_TOKEN, OAuth from `databricks auth login`.
+    A token is never accepted on the command line."""
+    from databricks.sdk import WorkspaceClient   # lazy: keeps `db-agent --help` fast
+
+    kw: dict[str, Any] = {}
+    if profile:
+        kw["profile"] = profile
+    if host:
+        kw["host"] = host
+    ws = WorkspaceClient(**kw)
+    chosen = warehouse_id
+    if use_sql and not chosen:
+        running = [w for w in ws.warehouses.list() if w.state and w.state.value == "RUNNING"]
+        if running:
+            chosen = running[0].id
+    return Reader(ws, chosen if use_sql else None, sql_skipped=not use_sql)

db_agent/engines/databricks/cost.py

@@ -0,0 +1,96 @@
+"""Month-over-month DBU spend and a split of the change into volume and price."""
+
+from __future__ import annotations
+
+from calendar import monthrange
+from datetime import date
+
+TIERS = ("STANDARD", "PREMIUM", "ENTERPRISE")
+
+
+def month_list(start: str, end: str) -> list[date]:
+    """'2026-09' .. '2026-11' -> first days of each month."""
+    def p(s: str) -> date:
+        y, m = s.split("-")
+        return date(int(y), int(m), 1)
+    a, b = p(start), p(end)
+    if b < a:
+        raise ValueError("--cost-to is before --cost-from")
+    out, cur = [], a
+    while cur <= b:
+        out.append(cur)
+        cur = date(cur.year + (cur.month == 12), cur.month % 12 + 1, 1)
+    if len(out) > 24:
+        raise ValueError("at most 24 months")
+    return out
+
+
+def default_range(today: date, n: int = 3) -> tuple[str, str]:
+    y, m = today.year, today.month - (n - 1)
+    while m < 1:
+        m += 12
+        y -= 1
+    return f"{y:04d}-{m:02d}", f"{today.year:04d}-{today.month:02d}"
+
+
+def tier_of(sku: str) -> str:
+    head = sku.split("_", 1)[0]
+    return head if head in TIERS else "OTHER"
+
+
+def normalized(sku: str) -> str:
+    return sku.split("_", 1)[1] if tier_of(sku) != "OTHER" else sku
+
+
+def _f(v) -> float | None:
+    return None if v is None else float(v)
+
+
+def analyze(rows: list[dict], today: date) -> dict:
+    """rows: month, sku_name, dbus, cost, days. Returns per-month figures and a volume/price split per day,
+    measured against the first month that has data."""
+    by_month: dict[str, dict] = {}
+    for r in rows:
+        key = str(r["month"])[:7]
+        m = by_month.setdefault(key, {"month": key, "dbus": 0.0, "cost": 0.0, "unpriced_dbus": 0.0, "days": 0,
+                                      "tiers": {}, "skus": {}})
+        dbus, cost = float(r["dbus"] or 0), _f(r.get("cost"))
+        m["dbus"] += dbus
+        m["days"] = max(m["days"], int(r.get("days") or 0))
+        if cost is None:
+            m["unpriced_dbus"] += dbus
+        else:
+            m["cost"] += cost
+        t = tier_of(r["sku_name"])
+        m["tiers"][t] = m["tiers"].get(t, 0.0) + dbus
+        n = normalized(r["sku_name"])
+        s = m["skus"].setdefault(n, {"dbus": 0.0, "cost": 0.0})
+        s["dbus"] += dbus
+        s["cost"] += cost or 0.0
+    months = [by_month[k] for k in sorted(by_month)]
+    for m in months:
+        y, mo = map(int, m["month"].split("-"))
+        m["partial"] = (y, mo) == (today.year, today.month)
+        d = max(m["days"], 1)
+        m["dbus_per_day"] = m["dbus"] / d
+        m["cost_per_day"] = m["cost"] / d
+        m["rate"] = (m["cost"] / (m["dbus"] - m["unpriced_dbus"])) if m["dbus"] - m["unpriced_dbus"] > 0 else None
+        m["dominant_tier"] = max(m["tiers"], key=m["tiers"].get) if m["tiers"] else None
+    if months:
+        base = months[0]
+        base_rate = {k: v["cost"] / v["dbus"] for k, v in base["skus"].items() if v["dbus"] > 0 and v["cost"] > 0}
+        for m in months[1:]:
+            d, bd = max(m["days"], 1), max(base["days"], 1)
+            at_base = 0.0
+            for k, v in m["skus"].items():
+                rate = base_rate.get(k) or (v["cost"] / v["dbus"] if v["dbus"] else 0.0)
+                at_base += v["dbus"] / d * rate
+            base_pd = base["cost"] / bd
+            m["vs_first"] = {"cost_per_day_change": m["cost_per_day"] - base_pd,
+                             "pct": ((m["cost_per_day"] / base_pd - 1) * 100) if base_pd else None,
+                             "volume_effect_per_day": at_base - base_pd,
+                             "price_effect_per_day": m["cost_per_day"] - at_base}
+    tiers = [m["dominant_tier"] for m in months if m["dominant_tier"]]
+    changed = len(set(tiers)) > 1
+    return {"months": months, "tier_changed": changed,
+            "tier_sequence": [(m["month"], m["dominant_tier"]) for m in months]}