cost-intel 0.1.0__tar.gz

cost_intel-0.1.0/.env.example

@@ -0,0 +1,18 @@
+# Cost Intelligence — Environment Variables
+# Copy to .env and fill in values
+
+# OpenRouter — for pricing API + cost-per-model data
+OPENROUTER_API_KEY=
+
+
+# Linear — for task updates
+LINEAR_API_KEY=
+
+# Factory.ai — for Droid orchestration
+FACTORY_API_KEY=
+
+# GitHub — for issue/PR creation
+GITHUB_TOKEN=
+
+# Cost Intel home directory (default: ~/.cost-intel)
+# COST_INTEL_HOME=

cost_intel-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+          pip install pytest ruff pytest-cov
+
+      - name: Lint with ruff
+        run: |
+          ruff check src/ tests/
+          ruff format --check src/ tests/
+
+      - name: Test with pytest
+        run: |
+          pytest tests/ -v --cov=src --cov-report=term-missing
+        env:
+          COST_INTEL_HOME: /tmp/.cost-intel-test

cost_intel-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/cost-intel
+    permissions:
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

cost_intel-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Ruff
+.ruff_cache/
+
+# Environment
+.env
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Cost Intel data
+.cost-intel/

cost_intel-0.1.0/AGENTS.md

@@ -0,0 +1,153 @@
+# AGENTS.md — Cost Intelligence
+
+## Session Startup (MANDATORY)
+1. Read SOUL.md (in profile root)
+2. Read this file
+3. Read SESSION_HANDOFF.md (in workspace root) — **start here for current state**
+4. Read PHASE1_COMPLETE.md (in workspace root) — Phase 1 details
+5. Read mission-phase2.md (in workspace root) — Phase 2 task specs
+6. Check Linear for active tasks (project: Cost Intelligence, ONI-43..ONI-71)
+
+## Project Status (June 3 2026)
+**ALL 4 PHASES COMPLETE** — 26 tasks, 164 tests, pushed to GitHub.
+See PHASE4_COMPLETE.md for full details.
+
+**Project is DONE.** All phases implemented per the audit-approved plan.
+- Migration 002: quality_scores table + cost_run_cpqp view with PERCENT_RANK()
+- Quality score import adapters (Eval Harness, Braintrust, CSV)
+- CPQP report, waste detection, model comparison, optimization
+
+## Project
+`cost-intel` — a standalone Python CLI for AI cost tracking and quality correlation.
+
+## Mission
+Build a CLI tool that tracks AI spending at the task level, correlates with quality scores, and produces cost-efficiency metrics. No tool currently bridges cost tracking and quality evaluation in a CLI-native package.
+
+## Tech Stack
+- Python 3.11+
+- Typer + Rich (CLI + terminal output)
+- sqlite3 stdlib (WAL mode, busy_timeout=5000)
+- httpx (async HTTP for pricing API)
+- Pydantic v2 (data validation)
+- pyyaml (config loading)
+- tiktoken (token estimation)
+- hatchling (build backend)
+- ruff (lint + format), pytest (test)
+
+## Build Rules (NON-NEGOTIABLE)
+- **TDD**: write failing test → run → implement → run → commit
+- **Type hints everywhere** (mypy-compatible)
+- **Google-style docstrings** for all public functions
+- **ruff check + ruff format** before every commit
+- **Commit after every task** (git add -A && git commit -m "type: description")
+- **No API keys in source** — read from .env
+- **`from typing import Optional`** in all modules using Optional
+
+## Data Directory
+`~/.cost-intel/` (override: `COST_INTEL_HOME`)
+DB: `~/.cost-intel/cost-intel.db`
+Config: `~/.cost-intel/config.yaml`
+
+## File Organization
+```
+workspace/cost-intel/
+├── src/cost_intel/           # Source package
+│   ├── __init__.py           # __version__ = "0.1.0"
+│   ├── __main__.py           # Entry point
+│   ├── cli.py                # Typer app + sub-apps (ALL Phase 1 commands)
+│   ├── config.py             # Config loader (reads ~/.cost-intel/config.yaml)
+│   ├── db.py                 # Connection manager + migration runner
+│   ├── migration_runner.py   # Numbered SQL migration runner
+│   ├── migrations/           # Numbered SQL files
+│   │   └── 001_initial.sql   # Phase 1 schema (COMPLETE)
+│   ├── pricing.py            # OpenRouter fetch + historical store
+│   ├── record.py             # Cost run recording (cache tokens + raw_response)
+│   ├── report.py             # Aggregate views + time-window filtering
+│   ├── budget.py             # Budget set/status subcommands
+│   ├── estimate.py           # tiktoken pre-call estimation
+│   ├── ingest.py             # JSONL ingestion with provider cache extraction
+│   ├── duration.py           # parse_window("7d") → 7 (CANONICAL location)
+│   ├── utils.py              # Shared utilities (retry, now_iso)
+│   ├── quality.py            # [Phase 2] Score import + CPQP + waste detection
+│   ├── optimize.py           # [Phase 2] Model routing + target CPQP
+│   ├── compare.py            # [Phase 2] Model comparison with efficiency delta
+│   ├── trends.py             # [Phase 2] CPQP trend analysis
+│   ├── gate.py               # [Phase 3] CI/CD cost gates
+│   ├── alerts.py             # [Phase 3] Slack webhook + SMTP email alerts
+│   ├── otel.py               # [Phase 4] OpenTelemetry span ingestion + trace cost
+│   ├── enforce.py            # [Phase 4] Budget enforcement / hard-stop
+│   ├── prompt_opt.py         # [Phase 4] High-cost pattern analysis
+│   └── adapters/             # [Phase 2] Quality score import adapters
+│       ├── eval_harness.py   # [Phase 2] Eval Harness DB adapter
+│       └── braintrust.py     # [Phase 2] Braintrust API adapter
+├── tests/
+│   ├── conftest.py           # Shared fixtures (tmp_db, tmp_cost_intel_home)
+│   ├── test_*.py             # 10 test files, 77 tests (Phase 1 COMPLETE)
+│   └── integration/          # Integration tests (empty — Phase 2+)
+├── pyproject.toml            # hatchling build, dependencies, ruff config
+├── .env.example              # Required env vars (no real values)
+├── .github/workflows/ci.yml  # CI pipeline (ruff + pytest, Phase 1 COMPLETE)
+├── scripts/
+│   ├── bootstrap.sh          # One-command dev setup (executable)
+│   └── dogfood.sh            # Dogfood: ingest + report (executable)
+├── SESSION_HANDOFF.md        # **READ FIRST** — current state + next steps
+├── PHASE1_COMPLETE.md        # Phase 1 implementation details
+├── mission-phase2.md         # Factory Droid Phase 2 prompt
+└── plan.md                   # Full 4-phase plan (4297 lines, audit-approved)
+```
+
+## Database Conventions
+- Composite PK `(model_id, effective_date)` for historical pricing
+- `is_current` flag on pricing rows
+- Numbered SQL migrations: `001_initial.sql`, `002_add_quality.sql`, `003_add_traces.sql`
+- `schema_version` table for migration tracking
+- Views use `DROP VIEW IF EXISTS` + `CREATE VIEW` in migrations (not `IF NOT EXISTS`)
+- `PRAGMA busy_timeout=5000` on all connections
+- `PRAGMA journal_mode=WAL`
+- Use `with connect() as conn:` contextmanager pattern
+- **Standalone** — zero foreign keys to any other product
+
+## Testing
+- `pytest tests/ -v --cov=src --cov-report=term-missing`
+- Coverage target: >90%
+- Integration tests in `tests/integration/`
+- No real API calls in CI (mock HTTP with pytest-httpx)
+- Test file: `test_<module>.py` for each module
+- `conftest.py` — shared fixtures (tmp_db, tmp_cost_intel_home)
+- Each task: write failing test FIRST, then implement
+
+## CLI Conventions
+- Typer sub-apps for command groups (`budget`, `pricing`)
+- Rich tables for reports
+- Duration parser: `parse_window("7d")` → 7 (days). **Canonical location: `src/cost_intel/duration.py`**
+- Standard flags: `--last/-l`, `--days/-d`, `--window/-w`
+- `--version` flag via Typer `is_eager` callback
+
+## Phase Gates
+Each phase must pass validation before next phase starts:
+- **Phase 1**: `pip install cost-intel` works, record + report work end-to-end, costs match invoices
+- **Phase 2**: CPQP ordering matches intuition, division-by-zero guard works, percentile ratings displayed
+- **Phase 3**: Gate exits 0/1 correctly, alerts trigger at right threshold
+- **Phase 4**: OTel trace cost breakdown works, budget enforcement blocks when exceeded
+
+## Credentials (in ~/.hermes/profiles/cost-intel/.env)
+- `OPENROUTER_API_KEY`
+- `LINEAR_API_KEY`
+- `GITHUB_TOKEN`
+- `FACTORY_API_KEY`
+
+## Git
+- Repo: https://github.com/onicarps/cost-intel
+- Branch: main
+- Branch naming: `cost-intel/ONI-XX-description`
+- Commit style: `type: description` (feat:, fix:, test:, etc.)
+
+## Linear Project
+Cost Intelligence: ONI-43 through ONI-71 (29 issues, 4 phases)
+Project ID: 55e43d66-e6a2-4108-9abe-fd97600aa79a
+
+## Notion
+https://www.notion.so/Cost-Intelligence-373e2527f3178147957ad4e1705278db
+
+## Implementation Plan
+See `plan.md` in this directory for full 4-phase implementation plan (4297 lines, audit-approved, 0 open gaps).

cost_intel-0.1.0/AGENTS.md.project

@@ -0,0 +1,97 @@
+# AGENTS.md — Cost Intelligence
+
+## Session Startup (MANDATORY)
+1. Read SOUL.md
+2. Read workspace/cost-intel/plan.md (if exists)
+3. Check Linear for active tasks (project: Cost Intelligence)
+4. Check Notion for recent design decisions
+
+## Build Rules
+- **TDD**: write failing test → run → implement → run → commit
+- **Type hints everywhere** (mypy-compatible)
+- **Google-style docstrings** for all public functions
+- **ruff check + ruff format** before every commit
+- **Commit after every task** (git add -A && git commit -m "type: description")
+- **No API keys in source** — read from .env
+
+## Project Context
+Python CLI tool (`cost-intel`) that tracks AI spending at the task level and correlates with quality scores. Standalone — zero foreign keys to any other product.
+
+**Tech Stack:** Python 3.11+, Typer + Rich, sqlite3 (WAL), httpx, Pydantic v2, pyyaml, tiktoken, hatchling, ruff, pytest
+
+**Data directory:** `~/.cost-intel/` (env override: `COST_INTEL_HOME`)
+**DB:** `~/.cost-intel/cost-intel.db`
+**Config:** `~/.cost-intel/config.yaml`
+
+## File Organization
+- Source: `workspace/cost-intel/src/cost_intel/`
+- Tests: `workspace/cost-intel/tests/`
+- Migrations: `workspace/cost-intel/src/cost_intel/migrations/`
+- Docs: `workspace/cost-intel/docs/`
+
+## Database Conventions
+- Composite PK `(model_id, effective_date)` for historical pricing
+- `is_current` flag on pricing rows
+- Numbered SQL migrations: `001_initial.sql`, `002_add_quality.sql`, `003_add_traces.sql`
+- `schema_version` table for migration tracking
+- Views use `DROP VIEW IF EXISTS` + `CREATE VIEW` in migrations (not `IF NOT EXISTS`)
+- `PRAGMA busy_timeout=5000` on all connections
+- Use `with connect() as conn:` contextmanager pattern
+
+## Testing
+- `pytest tests/ -v --cov=src --cov-report=term-missing`
+- Integration tests in `tests/integration/`
+- No real API calls in CI (mock HTTP with pytest-httpx)
+- Coverage target: >90%
+
+## CLI Conventions
+- Typer sub-apps for command groups (`budget`, `pricing`)
+- Rich tables for reports
+- Duration parser: `parse_window("7d")` → 7 (days). Canonical location: `src/cost_intel/duration.py`
+- Standard flags: `--last/-l`, `--days/-d`, `--window/-w`
+
+## Code Conventions
+- `src/cost_intel/__init__.py` — `__version__ = "0.1.0"`
+- `src/cost_intel/db.py` — connection manager + migration runner
+- `src/cost_intel/migrations/` — numbered SQL files
+- `src/cost_intel/models.py` — Pydantic models
+- `src/cost_intel/pricing.py` — OpenRouter fetch + historical store
+- `src/cost_intel/record.py` — cost run recording (cache tokens + raw_response)
+- `src/cost_intel/report.py` — aggregate views + time-window filtering
+- `src/cost_intel/budget.py` — budget set/status subcommands
+- `src/cost_intel/estimate.py` — tiktoken pre-call estimation
+- `src/cost_intel/ingest.py` — JSONL ingestion with provider-specific cache extraction
+- `src/cost_intel/quality.py` — score import + CPQP + waste detection
+- `src/cost_intel/optimize.py` — model routing + target CPQP
+- `src/cost_intel/compare.py` — model comparison with efficiency delta
+- `src/cost_intel/gate.py` — CI/CD cost gates
+- `src/cost_intel/alerts.py` — Slack webhook + SMTP email alerts
+- `src/cost_intel/otel.py` — OpenTelemetry span ingestion + trace cost
+- `src/cost_intel/enforce.py` — budget enforcement / hard-stop
+- `src/cost_intel/prompt_optimize.py` — high-cost pattern analysis
+- `src/cost_intel/adapters/` — quality score import adapters
+- `None` imports: always `from typing import Optional`
+
+## Testing Conventions
+- Test file: `test_<module>.py` for each module
+- `conftest.py` — shared fixtures (tmp_db, tmp_cost_intel_home)
+- Each task: write failing test FIRST, then implement
+
+## Phase Gates
+Each phase must pass validation before next phase starts:
+- **Phase 1**: `pip install cost-intel` works, record + report work end-to-end, costs match invoices
+- **Phase 2**: CPQP ordering matches intuition, division-by-zero guard works, percentile ratings displayed
+- **Phase 3**: Gate exits 0/1 correctly, alerts trigger at right threshold
+- **Phase 4**: OTel trace cost breakdown works, budget enforcement blocks when exceeded
+
+## Credentials (in ~/.hermes/profiles/cost-intel/.env)
+- `OPENROUTER_API_KEY`
+- `LINEAR_API_KEY`
+- `GITHUB_TOKEN`
+- `FACTORY_API_KEY`
+
+## Git
+- Repo: (to be created)
+- Branch: main
+- Branch naming: `cost-intel/ONI-XX-description`
+- Commit style: `type: description` (feat:, fix:, test:, etc.)

cost_intel-0.1.0/DOGFOOD_RETROSPECTIVE.md

@@ -0,0 +1,165 @@
+# Cost Intelligence — Dogfood Retrospective & Pricing Research
+
+> **Date:** June 3, 2026
+> **Purpose:** Real-world testing with Hermes session data + pricing system analysis
+
+---
+
+## What We Found
+
+### 1. Hermes Real Usage (Last 30 Days)
+
+| Metric | Value |
+|--------|-------|
+| Sessions | 153 |
+| Total tokens | 6.5M in, 221K out |
+| **Total cost** | **$0.18** |
+| Free sessions | 138 (90%) |
+| Paid sessions | 15 (10%) |
+
+Cost breakdown by model:
+- `llama-4-scout`: 7 runs, $0.17 (94% of spend)
+- `granite4.1:3b`: 2 runs, $0.003
+- `qwen-3-235b`: 1 run, $0.002
+- `gpt-oss-120b`: 1 run, $0.001
+- All free models (owl-alpha, nemotron-free): $0.00
+
+### 2. Critical Bug: `* 1_000_000` in `refresh_all_pricing`
+
+**File:** `src/cost_intel/pricing.py`, lines 185-186
+
+```python
+# Comment says: "OpenRouter returns per-million-token pricing"
+# Reality: OpenRouter returns per-token pricing (e.g., 0.000000039)
+input_price = float(pricing.get("prompt", 0)) * 1_000_000
+output_price = float(pricing.get("completion", 0)) * 1_000_000
+```
+
+For `gpt-oss-120b`:
+- OpenRouter returns: `prompt = "0.000000039"` (per-token)
+- After `* 1_000_000`: `0.039` stored as "per-1K tokens"
+- But `0.039` is actually the **per-1M** price, not per-1K
+- `_compute_cost` then does `(tokens / 1000) * 0.039` = **1000x too high**
+
+The comment is wrong. OpenRouter returns per-token pricing. The multiplication by 1M converts it to per-1M pricing. But the column is named `per_1k_tokens`. The `_compute_cost` function divides by 1000, expecting per-1K pricing. So the final result is 1000x inflated.
+
+**Actual pricing for reference (per 1M tokens):**
+| Model | Input | Output |
+|-------|-------|--------|
+| gpt-oss-120b | $0.039 | $0.18 |
+| llama-4-scout | $0.08 | $0.30 |
+| qwen-3-235b | $0.071 | $0.099 |
+| granite-4.0-h-micro | $0.017 | $0.112 |
+| owl-alpha | FREE | FREE |
+
+### 3. Model Name Mismatch Problem
+
+Hermes state.db uses different names than OpenRouter API:
+- Hermes: `granite4.1:3b` → OpenRouter: `ibm-granite/granite-4.1-8b`
+- Hermes: `gpt-oss-120b` → OpenRouter: `openai/gpt-oss-120b`
+- Hermes: `openrouter/owl-alpha` → OpenRouter: `openrouter/owl-alpha` (matches)
+
+When `get_pricing()` can't find a match, it returns None and cost = $0.
+This silently zeros out costs for unmatched models.
+
+### 4. Cost Is Dynamic — Three Moving Parts
+
+```
+cost = tokens × price_per_token
+```
+
+**All three variables change:**
+
+1. **Tokens per session**: 2K to 1.5M input tokens (3 orders of magnitude)
+2. **Model used**: 8+ models, $0 to $150/1M tokens (5 orders of magnitude)
+3. **Pricing itself**: Models change price over time
+
+### 5. Model Pricing Evolution (OpenRouter data, June 2026)
+
+From the 343 models on OpenRouter:
+- 25 models are free (7.3%)
+- 318 models are paid (92.7%)
+- Price range: $0.01 to $150 per 1M input tokens
+- Median: $0.40 per 1M input tokens
+
+**Key observation:** Every major model family has BOTH free and paid variants:
+- `nvidia/nemotron-3-super-120b-a12b:free` → FREE
+- `nvidia/nemotron-3-super-120b-a12b` → $0.09/1M in, $0.45/1M out
+- `openai/gpt-oss-120b:free` → FREE  
+- `openai/gpt-oss-120b` → $0.039/1M in, $0.18/1M out
+
+This suggests OpenRouter (and providers) use a strategy of offering free tiers that can be upgraded. The `:free` suffix models are often rate-limited or lower-priority versions.
+
+### 6. Historical Pricing — The Real Challenge
+
+Model pricing changes over time. Examples from OpenRouter:
+- Models start as free during beta, then become paid
+- Prices decrease as models get more efficient (e.g., llama-3 vs llama-4)
+- Prices increase when demand spikes
+- Free tiers get discontinued
+
+**The current schema is designed for this:**
+- `model_pricing` has `(model_id, effective_date)` composite PK
+- `is_current` flag for quick lookups
+- Old pricing rows are preserved when prices change
+
+**But the cost computation bakes the price:**
+- `cost_run_calls.call_cost` is computed at record time using current pricing
+- If pricing changes later, historical costs don't update
+- This is a **design tension**: do we store the price at time of use, or recompute?
+
+For the Hermes dogfood, this doesn't matter much because:
+- Most sessions use free models (price = $0, won't change)
+- The paid sessions are tiny ($0.18 total)
+- Pricing for stable models changes slowly
+
+But at scale (thousands of $, enterprise usage), pricing history matters.
+
+---
+
+## Architectural Implications
+
+### Cost Tracking Needs a Reconciliation Layer
+
+The current flow:
+```
+Hermes session → model name → get_pricing(model_name) → cost
+```
+
+This breaks when:
+1. Model names don't match between systems (naming drift)
+2. Pricing is missing for a model (new model, API lag)
+3. Pricing changed retroactively (provider refunds, corrections)
+
+**Needed:**
+1. Model name mapping table (Hermes name ↔ OpenRouter ID)
+2. Pricing fallback chain: exact match → prefix match → fuzzy match → default
+3. Pricing freshness tracking with alerts
+4. Cost recomputation capability for historical data
+
+### Cost Is Effectively Free at Small Scale
+
+90% of sessions use free models. The 10% paid sessions average $0.012 each.
+At this scale, cost tracking is about:
+- **Anomaly detection**: alert when a paid model is used unexpectedly
+- **Trend tracking**: monitor the ratio of free vs paid over time
+- **Audit trail**: know which tasks required paid models
+
+### The Value Proposition Shifts with Scale
+
+- **Small scale (<$10/month)**: Cost tracking = anomaly detection
+- **Medium scale ($10-100/month)**: Cost tracking = optimization opportunities
+- **Large scale ($100+/month)**: Cost tracking = cost avoidance, budget enforcement
+
+Hermes is currently at the small scale. The OWL value prop ("unified cost-quality metric") is most valuable at medium-to-large scale.
+
+---
+
+## Action Items
+
+1. [ ] Fix `* 1_000_000` bug in `refresh_all_pricing` — the comment is wrong, OpenRouter returns per-token pricing
+2. [ ] Add model name mapping/normalization layer
+3. [ ] Add pricing freshness tracking and alerts
+4. [ ] Add cost recomputation for historical data
+5. [ ] Add cost anomaly detection (alert when cost > Nσ for model)
+6. [ ] Determine pricing unit convention and make it consistent (per-1K vs per-1M vs per-token)

cost_intel-0.1.0/PHASE1_COMPLETE.md

@@ -0,0 +1,103 @@
+# Cost Intelligence — Phase 1 Implementation Complete
+
+> **Date:** June 2-3, 2026
+> **Status:** Phase 1 (Cost-Only Foundation) — ALL 12 tasks complete
+> **Tests:** 77 passing, ruff clean, 0 lint errors
+> **GitHub:** https://github.com/onicarps/cost-intel (7 commits on main)
+
+---
+
+## What Was Built
+
+A standalone Python CLI (`cost-intel`) that tracks AI spending from the command line.
+No quality data needed — purely cost-only layer (Phase 1).
+
+### Source Modules Created
+
+| Module | Purpose |
+|--------|---------|
+| `src/cost_intel/__init__.py` | `__version__ = "0.1.0"` |
+| `src/cost_intel/__main__.py` | `python -m cost_intel` entry |
+| `src/cost_intel/cli.py` | Typer app with all CLI commands |
+| `src/cost_intel/config.py` | YAML config loader with caching |
+| `src/cost_intel/utils.py` | `now_iso()`, `retry()` with exponential backoff |
+| `src/cost_intel/duration.py` | `parse_window("7d")` → 7 (CANONICAL location) |
+| `src/cost_intel/db.py` | Connection manager + `connect()` contextmanager + `init_db()` |
+| `src/cost_intel/migration_runner.py` | Numbered SQL migration runner |
+| `src/cost_intel/migrations/001_initial.sql` | Full Phase 1 schema |
+| `src/cost_intel/pricing.py` | OpenRouter fetch, upsert (same-day update vs cross-date insert), get, manual |
+| `src/cost_intel/record.py` | `record_run()`, `get_run()`, `get_run_calls()` |
+| `src/cost_intel/report.py` | `report_summary()`, `report_by_model()`, `report_by_label()`, `report_by_day()` |
+| `src/cost_intel/budget.py` | `set_budget()`, `get_budget_status()` |
+| `src/cost_intel/estimate.py` | `estimate_tokens()`, `estimate_cost()` (tiktoken) |
+| `src/cost_intel/ingest.py` | `ingest_jsonl()` with provider token extraction |
+
+### CLI Commands Working
+
+```
+cost-intel --version                          → cost-intel 0.1.0
+cost-intel record --model M -i 100 -o 50      → record a cost run
+cost-intel report --last 7d --by-model        → cost report with tables
+cost-intel trends --last 30d                  → daily spending trends
+cost-intel export --format csv --last 7d      → CSV export
+cost-intel budget set --monthly 500           → set budget
+cost-intel budget status                      → show budget status
+cost-intel refresh-pricing                    → fetch from OpenRouter API
+cost-intel pricing set/show --model M         → manual pricing
+cost-intel estimate "hello" --model gpt-4     → token/cost estimation
+cost-intel ingest-api-responses file.jsonl    → ingest JSONL
+```
+
+---
+
+## Known Issues / Bugs Found During Implementation
+
+1. **OpenRouter pricing math**: API returns per-million-token pricing. Must multiply by `1_000_000` to get per-1K-token pricing (not `1_000`). Fixed in `refresh_all_pricing()`.
+
+2. **Same-day upsert DELETE+INSERT**: Using `INSERT OR REPLACE` with composite PK `(model_id, effective_date)` deleted the old row entirely, so `is_current=0` historical rows were lost. Fixed with conditional logic: same-day → UPDATE in place, different day → mark old `is_current=0` + INSERT new.
+
+3. **SQLite datetime comparison**: ISO timestamps with timezone offsets (`2025-01-01T00:00:00+00:00`) don't compare correctly with SQLite's `datetime('now', '-N days')` which returns `'YYYY-MM-DD HH:MM:SS'` format. Fixed test to use `'YYYY-MM-DD HH:MM:SS'` format for manually inserted timestamps.
+
+4. **`dict` params vs positional `?`**: Report `_days_filter()` passed a dict to `conn.execute()` but SQL used `?` positional placeholders. Fixed to return `list` instead of `dict`.
+
+---
+
+## Test Coverage (77 tests)
+
+| Test File | Tests | What's Covered |
+|-----------|-------|----------------|
+| `test_config.py` | 5 | Config loader (no file, reads YAML, caches, eval weights) |
+| `test_utils.py` | 3 | now_iso, retry (success, retries, raises) |
+| `test_duration.py` | 12 | parse_window (d/h/w/bare int/whitespace/case/invalid) |
+| `test_db.py` | 12 | Schema creation, migrations, composite PK, WAL, busy_timeout, foreign_keys, contextmanager commit/rollback |
+| `test_pricing.py` | 10 | Upsert, update preserves old row, same-day update, noop, cache pricing, historical pricing, manual pricing, refresh insert/skip |
+| `test_record.py` | 11 | Basic record, cost computation, unknown model, cache tokens, raw_response truncation, run_type, label, latency, get_run, get_run_calls |
+| `test_report.py` | 9 | Summary empty/with-runs/time-window, by-model, by-label, by-day, budget set/status/spending |
+| `test_estimate.py` | 5 | Token estimation (basic, empty, longer=text, cost with pricing/unknown) |
+| `test_ingest.py` | 9 | Token extraction (OpenRouter/Anthropic/OpenAI/unknown), JSONL ingest (basic, skip invalid, label, nonexistent file) |
+
+---
+
+## Remaining Phases
+
+### Phase 2: Quality Correlation (Weeks 4-6)
+Tasks 2.0-2.5 — Quality scores, CPQP metric, waste detection, model comparison
+
+Key migration needed: `002_add_quality.sql` — adds `quality_scores` table + `cost_run_cpqp` view with `PERCENT_RANK()` for A/B/C/D/F ratings.
+
+### Phase 3: CI/CD + Alerts (Weeks 7-9)
+Tasks 3.1-3.3 — Cost gate, GitHub Actions example, Slack/email alerts
+
+### Phase 4: Multi-Agent + Advanced (Weeks 10-12)
+Tasks 4.0-4.4 — OTel span ingestion, trace cost breakdown, prompt optimization, budget enforcement
+
+Migration needed: `003_add_traces.sql` — adds `trace_id`, `span_id`, `parent_span_id` to `cost_runs`.
+
+---
+
+## Key Files for Next Session
+
+- **Plan:** `research/cost-intelligence/plan.md` (4297 lines, audit-approved)
+- **AGENTS.md:** `workspace/cost-intel/AGENTS.md` (full project spec + file tree)
+- **Mission prompt:** `workspace/cost-intel/mission-phase1.md`
+- **This doc:** `workspace/cost-intel/PHASE1_COMPLETE.md`