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.

