class1 0.1.0__tar.gz

class1-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: class1
+Version: 0.1.0
+Summary: Monthly LLM cost-risk estimation and project controls for AI systems
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: PyJWT>=2.8.0
+Requires-Dist: cryptography>=42.0.0
+Provides-Extra: dev
+Requires-Dist: pytest~=8.3.0; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+
+# Class1 (Internal name: abc7d) — Project controls and cost-risk estimation for AI systems
+
+Class1 is a high-performance cost-engineering tool for LLM-based systems. Unlike typical observability tools that look backward at historical spend, Class1 focuses on **estimation**: providing a risk-adjusted forecast of a code change's monthly cost delta **in the pull request, before merge**, with a declared AACE estimate class and a calibration loop.
+
+Cost engineering, not dashboards.
+
+---
+
+## How it works
+
+When a developer submits a PR, the Class1 GitHub Action:
+1. **Scans the diff** to identify added, modified, or removed LLM callsites (Python AST + TS/JS tree-sitter).
+2. **Translates code changes** (model swaps, token changes, tool changes) into baseline vs. head scenarios.
+3. **Runs a Monte Carlo simulation** using Common Random Numbers (CRN) to estimate the monthly cost delta.
+4. **Applies a budget policy** to automatically warn or block the PR if the P90 tail risk exceeds your threshold.
+5. **Posts a detailed cost-risk report** directly to the PR comments.
+
+```
+ABC7D  ·  AI cost-risk report
+=========================================
+Expected Monthly Delta:  +$124.50
+P50 (Median) Delta:      +$112.00
+P90 (Tail Risk) Delta:   +$210.00
+P95 Delta:               +$245.00
+
+Estimate Class:          Class 4 (Study)
+Accuracy Range:          -30% / +50%
+
+Recommendation:
+Optimal model selected for the workload. Under-spec models (e.g. gpt-4o-mini)
+would result in lower unit cost but higher overall cost due to retries (+14%).
+
+Verdict: PASS
+```
+
+---
+
+## Getting Started: GitHub Action Setup
+
+Add the Class1 check to your repository in three simple steps:
+
+### 1. Create a budget policy
+Add a `.class1.json` file at the root of your repository:
+```json
+{
+  "fail_pr_if": {
+    "delta_p90_usd": 500.0,
+    "warn_at_fraction": 0.8
+  }
+}
+```
+*If a PR's estimated monthly P90 cost increase exceeds $500, the GitHub status check will fail, blocking the merge.*
+
+### 2. Configure the GitHub Actions workflow
+Create `.github/workflows/class1.yml`:
+```yaml
+name: Class1 Cost-Risk Guard
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  estimate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required to scan history and base ref diffs
+
+      - name: Run Class1 Guard
+        uses: class1-dev/class1@v1
+        with:
+          license_key: ${{ secrets.CLASS1_LICENSE_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 3. Add your License Key (Premium features)
+To unlock blocking budget gates, custom price overrides, and data persistence for post-merge calibration, get a license key from [https://class1.dev](https://class1.dev) and add it as a Repository Secret named `CLASS1_LICENSE_KEY`.
+
+*Class1 remains completely **free and advisory** (posting comments without blocking) for open-source repositories and individual developers.*
+
+---
+
+## Architecture & Subsystems (For Developers)
+
+If you are developing or hosting Class1 yourself, the project is structured as follows:
+
+1. **`cost_engine/`** — Pure cost-risk math (no GitHub/UI/DB).
+   - Monte Carlo simulation with systemic risk factors (`monte_carlo.py`, `distributions.py`).
+   - Forward escalation forecast decomposed into price, volume, and structure (`escalation.py`).
+   - Contingency and sensitivity tornado analysis (`contingency.py`).
+   - Estimate classification based on AACE standards (`classification.py`).
+   - Ecological footprint delta tracking (carbon, water, materials) (`footprint/`).
+2. **`blue_book/`** — The historical ledger database.
+   - Per-provider token usage normalization and deduplicated cost calculation.
+   - Spec sheet and historical capability indexing (`model_capability`).
+   - MEDALLION pipeline (`bronze -> silver -> gold`) for ingestion.
+3. **`takeoff/`** — The product integration surface.
+   - Python stdlib AST diff scanner and TS/JS tree-sitter scanner.
+   - Translation layers to transform code changes into Scenario models.
+   - CLI tool (`python -m takeoff.estimate_pr`) and GitHub Action harness.
+
+### Local Development Commands
+Run tests constantly using the project's Makefile wrapper:
+```bash
+make test          # Run full test suite (~870 tests, 2.5s)
+make demo          # Execute end-to-end local PR estimation demo
+make up            # Spin up local throwaway Postgres instance (docker-free)
+make down          # Tear down local Postgres instance
+```
+
+---
+
+## License
+
+Class1 is licensed under the Business Source License 1.1 (BSL) — see [LICENSE](file:///Users/owner/Desktop/abc7d/LICENSE) for details. The project relies on price and capability dataset snapshots under their respective open-source licenses.
+

class1-0.1.0/README.md

@@ -0,0 +1,119 @@
+# Class1 (Internal name: abc7d) — Project controls and cost-risk estimation for AI systems
+
+Class1 is a high-performance cost-engineering tool for LLM-based systems. Unlike typical observability tools that look backward at historical spend, Class1 focuses on **estimation**: providing a risk-adjusted forecast of a code change's monthly cost delta **in the pull request, before merge**, with a declared AACE estimate class and a calibration loop.
+
+Cost engineering, not dashboards.
+
+---
+
+## How it works
+
+When a developer submits a PR, the Class1 GitHub Action:
+1. **Scans the diff** to identify added, modified, or removed LLM callsites (Python AST + TS/JS tree-sitter).
+2. **Translates code changes** (model swaps, token changes, tool changes) into baseline vs. head scenarios.
+3. **Runs a Monte Carlo simulation** using Common Random Numbers (CRN) to estimate the monthly cost delta.
+4. **Applies a budget policy** to automatically warn or block the PR if the P90 tail risk exceeds your threshold.
+5. **Posts a detailed cost-risk report** directly to the PR comments.
+
+```
+ABC7D  ·  AI cost-risk report
+=========================================
+Expected Monthly Delta:  +$124.50
+P50 (Median) Delta:      +$112.00
+P90 (Tail Risk) Delta:   +$210.00
+P95 Delta:               +$245.00
+
+Estimate Class:          Class 4 (Study)
+Accuracy Range:          -30% / +50%
+
+Recommendation:
+Optimal model selected for the workload. Under-spec models (e.g. gpt-4o-mini)
+would result in lower unit cost but higher overall cost due to retries (+14%).
+
+Verdict: PASS
+```
+
+---
+
+## Getting Started: GitHub Action Setup
+
+Add the Class1 check to your repository in three simple steps:
+
+### 1. Create a budget policy
+Add a `.class1.json` file at the root of your repository:
+```json
+{
+  "fail_pr_if": {
+    "delta_p90_usd": 500.0,
+    "warn_at_fraction": 0.8
+  }
+}
+```
+*If a PR's estimated monthly P90 cost increase exceeds $500, the GitHub status check will fail, blocking the merge.*
+
+### 2. Configure the GitHub Actions workflow
+Create `.github/workflows/class1.yml`:
+```yaml
+name: Class1 Cost-Risk Guard
+
+on:
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  estimate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Required to scan history and base ref diffs
+
+      - name: Run Class1 Guard
+        uses: class1-dev/class1@v1
+        with:
+          license_key: ${{ secrets.CLASS1_LICENSE_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+```
+
+### 3. Add your License Key (Premium features)
+To unlock blocking budget gates, custom price overrides, and data persistence for post-merge calibration, get a license key from [https://class1.dev](https://class1.dev) and add it as a Repository Secret named `CLASS1_LICENSE_KEY`.
+
+*Class1 remains completely **free and advisory** (posting comments without blocking) for open-source repositories and individual developers.*
+
+---
+
+## Architecture & Subsystems (For Developers)
+
+If you are developing or hosting Class1 yourself, the project is structured as follows:
+
+1. **`cost_engine/`** — Pure cost-risk math (no GitHub/UI/DB).
+   - Monte Carlo simulation with systemic risk factors (`monte_carlo.py`, `distributions.py`).
+   - Forward escalation forecast decomposed into price, volume, and structure (`escalation.py`).
+   - Contingency and sensitivity tornado analysis (`contingency.py`).
+   - Estimate classification based on AACE standards (`classification.py`).
+   - Ecological footprint delta tracking (carbon, water, materials) (`footprint/`).
+2. **`blue_book/`** — The historical ledger database.
+   - Per-provider token usage normalization and deduplicated cost calculation.
+   - Spec sheet and historical capability indexing (`model_capability`).
+   - MEDALLION pipeline (`bronze -> silver -> gold`) for ingestion.
+3. **`takeoff/`** — The product integration surface.
+   - Python stdlib AST diff scanner and TS/JS tree-sitter scanner.
+   - Translation layers to transform code changes into Scenario models.
+   - CLI tool (`python -m takeoff.estimate_pr`) and GitHub Action harness.
+
+### Local Development Commands
+Run tests constantly using the project's Makefile wrapper:
+```bash
+make test          # Run full test suite (~870 tests, 2.5s)
+make demo          # Execute end-to-end local PR estimation demo
+make up            # Spin up local throwaway Postgres instance (docker-free)
+make down          # Tear down local Postgres instance
+```
+
+---
+
+## License
+
+Class1 is licensed under the Business Source License 1.1 (BSL) — see [LICENSE](file:///Users/owner/Desktop/abc7d/LICENSE) for details. The project relies on price and capability dataset snapshots under their respective open-source licenses.
+

class1-0.1.0/blue_book/actuals.py

@@ -0,0 +1,126 @@
+"""FinOps actuals — FOCUS-IN + close the calibration loop.
+
+The FinOps-canonical source of ACTUAL spend is a FOCUS dataset (FinOps Open Cost & Usage
+Specification): a cloud/billing export, a FinOps platform (Vantage / CloudZero / Finout) export,
+or the provider usage/costs API mapped to FOCUS. blue_book already EXPORTS FOCUS (focus.py); this is
+the inverse — read a FOCUS dataset, aggregate the FinOps `EffectiveCost` per workload/month into the
+monthly ACTUAL, and feed it (paired with the prior ESTIMATE) into the ActuarialTable so the estimate
+class rises from 5 (a guess) toward validated. Pure/offline: the REAL FOCUS rows are the user's data.
+"""
+from __future__ import annotations
+
+import csv
+from pathlib import Path
+
+from cost_engine.calibration import ActuarialTable  # NOTE: layer violation — blue_book imports cost_engine. Tracked as tech debt.
+
+
+def read_focus_csv(path: str | Path) -> list[dict]:
+    """Read a FOCUS-format CSV (as exported by focus.export_to_csv or any FinOps tool / cloud billing).
+    Uses utf-8-SIG: real exports (verified on Microsoft's Azure EA FOCUS sample) carry a UTF-8 BOM that
+    would otherwise corrupt the first column name (\\ufeffBilledCost)."""
+    with Path(path).open(newline="", encoding="utf-8-sig") as f:
+        return list(csv.DictReader(f))
+
+
+def monthly_actual(focus_rows: list[dict], workflow: str | None = None, month: str | None = None,
+                   cost_col: str = "EffectiveCost", tag_col: str = "x_workflow_name") -> float:
+    """The ACTUAL monthly spend = sum of FinOps EffectiveCost over FOCUS rows. Optionally scope to a
+    workload (the `tag_col` column == `workflow` — x_workflow_name for our LLM exports, or ServiceName/
+    ResourceId for cloud FOCUS) and/or a month (YYYY-MM prefix of ChargePeriodStart). EffectiveCost is
+    the post-discount FinOps cost — the right number to validate an estimate against."""
+    total = 0.0
+    for r in focus_rows:
+        if workflow is not None and (r.get(tag_col) or "") != workflow:
+            continue
+        if month is not None and not str(r.get("ChargePeriodStart", "")).startswith(month):
+            continue
+        try:
+            total += float(r.get(cost_col) or 0.0)
+        except (TypeError, ValueError):
+            continue
+    return total
+
+
+def record_actual(table: ActuarialTable, workflow: str, estimate: dict, focus_rows: list[dict], *,
+                  month: str | None = None, dominant_driver: str = "output length",
+                  tag_col: str = "x_workflow_name") -> float:
+    """Close the loop: pair the prior ESTIMATE for `workflow` with its ACTUAL spend (from the FOCUS
+    dataset) -> ActuarialTable. n_actuals rises -> estimate_class rises (the flywheel). Returns the
+    actual. This is the one step that turns a Class-5 guess into a validated estimate."""
+    actual = monthly_actual(focus_rows, workflow=workflow, month=month, tag_col=tag_col)
+    table.add(workflow, estimate, actual, dominant_driver)
+    return actual
+
+
+def variance_waterfall(estimate: dict, actual: float, driver_elasticities: dict[str, float] | None = None) -> dict[str, float]:
+    """Isolate the cost variance (Actual - Expected) into a waterfall of risk drivers.
+    
+    If actual exceeds expected, the variance is distributed proportionally 
+    across the drivers based on their simulated elasticities. This bridges
+    the gap between 'we missed the budget' and 'here is exactly why'.
+    """
+    driver_elasticities = driver_elasticities or {}
+    expected = float(estimate.get("expected", 0.0))
+    total_variance = actual - expected
+    
+    waterfall = {}
+    if total_variance == 0 or not driver_elasticities:
+        waterfall["unexplained"] = total_variance
+        return waterfall
+        
+    total_elasticity = sum(driver_elasticities.values())
+    if total_elasticity == 0:
+        waterfall["unexplained"] = total_variance
+        return waterfall
+        
+    explained = 0.0
+    for driver, elasticity in driver_elasticities.items():
+        # Using abs(elasticity) in case negative correlation exists but we allocate magnitude
+        weight = abs(elasticity) / sum(abs(v) for v in driver_elasticities.values())
+        impact = total_variance * weight
+        waterfall[driver] = impact
+        explained += impact
+        
+    remainder = total_variance - explained
+    if abs(remainder) > 0.01:
+        waterfall["remainder"] = remainder
+        
+    return waterfall
+
+def _main(argv=None) -> int:
+    """CLI: record a real ACTUAL (from a FOCUS export) against a stored ESTIMATE -> persist the loop.
+
+      python -m blue_book.actuals --focus bill.csv --workflow support_agent \\
+          --estimate '{"expected":18,"p50":16,"p90":30}' [--month 2026-06]
+    """
+    import argparse
+    import json
+
+    from cost_engine.calibration import ActuarialTable, load_table, save_table  # NOTE: layer violation — blue_book imports cost_engine. Tracked as tech debt.
+
+    ap = argparse.ArgumentParser(description="Close the calibration loop: a FOCUS actual vs a prior estimate.")
+    ap.add_argument("--focus", required=True, help="FOCUS CSV (FinOps export / cloud billing / provider-usage->FOCUS)")
+    ap.add_argument("--workflow", required=True, help="x_workflow_name to scope the actual to")
+    ap.add_argument("--estimate", required=True, help="JSON (file path or inline) with expected/p50/p90")
+    ap.add_argument("--month", default=None, help="YYYY-MM to scope the actual (default: all)")
+    ap.add_argument("--table", default="snapshots/actuarial_table.json", help="persisted ActuarialTable")
+    ap.add_argument("--driver", default="output length")
+    ap.add_argument("--scope-col", default="x_workflow_name",
+                    help="FOCUS column to scope by (x_workflow_name for LLM; ServiceName/ResourceId for cloud)")
+    a = ap.parse_args(argv)
+
+    est = json.loads(Path(a.estimate).read_text()) if Path(a.estimate).exists() else json.loads(a.estimate)
+    table = load_table(a.table) if Path(a.table).exists() else ActuarialTable()
+    actual = record_actual(table, a.workflow, est, read_focus_csv(a.focus),
+                           month=a.month, dominant_driver=a.driver, tag_col=a.scope_col)
+    save_table(table, a.table)
+    cls = table.estimate_class(a.workflow)
+    print(f"actual ${actual:,.2f} recorded for '{a.workflow}' (month={a.month or 'all'}) -> "
+          f"n_actuals={table.n_actuals(a.workflow)}, class={cls.label}, "
+          f"verdict={table._scoped(a.workflow)[-1].verdict}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(_main())