yvgude--lean-ctx/docs/integrations/finops.md

LeanCTX in the FinOps Stack — CloudZero, Vantage, FOCUS

lean-ctx finops export turns the tamper-evident savings ledger into daily cost rows your FinOps platform ingests for showback/chargeback. Unlike self-reported savings claims, every exported number is backed by a hash-chained event (lean-ctx ledger verify) with the model price pinned at recording time — an auditor can replay the chain.

savings ledger (hash-chained JSONL)
        │  aggregate: day × project × agent × model × tool
        ▼
DailyCostRow { date, project, agent_role, model, tool,
               tokens_actual, tokens_saved, cost_usd, savings_usd }
        │
        ├── FOCUS 1.2 CSV ──────────► any FOCUS consumer / data warehouse
        ├── CBF CSV / Stream JSON ──► CloudZero (AnyCost)
        └── Vantage CSV ────────────► Vantage (Custom Provider)
                                          │
                                          ▼
                                   CFO cost report

Quick reference

lean-ctx finops export --target=focus   --out=leanctx_focus.csv
lean-ctx finops export --target=cbf     --from=2026-06-01 --to=2026-06-30 --upload
lean-ctx finops export --target=vantage --out=leanctx_vantage.csv --upload

Data model decisions (read before importing)

• Costs are real reads: cost_usd = tokens actually sent through lean-ctx × the per-event pinned model price. No counterfactuals.
• Savings are separate rows, never mixed into spend: FOCUS/Vantage get ChargeCategory=Credit rows with negative BilledCost (FOCUS's category for granted reductions); CloudZero gets lineitem/type=Discount rows (CBF's documented mechanism, included in CloudZero "Real Cost"). Budgets built on Usage stay clean; savings stay drillable.
• No pricing table to maintain: each ledger event stores unit_price_per_m_usd at recording time. Provider price changes never rewrite history — the export is reproducible forever.
• Privacy: project is the truncated repo hash from the ledger (paths never leave the machine). For readable dashboards, add an opt-in showback mapping (see below) — applied at export time only, so the ledger and signed batch stay privacy-preserving.

Showback project names (--aliases, #668)

The ledger stores only a truncated repo hash, never a path. To show readable team/project names in chargeback dashboards, drop a mapping file and it is applied at export time only — the ledger, the signed batch and the hash chain are never touched.

# <config_dir>/finops-aliases.toml   (or point --aliases=FILE / $LEAN_CTX_FINOPS_ALIASES)
[projects]
# <repo_hash> = "<display name>"
a1b2c3d4e5 = "Payments"
deadbeef00 = "Platform / SRE"

lean-ctx finops export --target=focus --out=leanctx_focus.csv          # uses the default file
lean-ctx finops export --target=focus --aliases=team-map.toml          # explicit mapping

Unmapped hashes fall back to the hash, so an incomplete map never drops rows. Find the hashes to map in the project column of a plain (unmapped) export.

CloudZero (AnyCost)

Spec pinned: CBF — Common Bill Format, required columns time/usage_start + cost/cost.

1. In CloudZero, create an AnyCost Stream connection and note the connection ID + an API key.

2. Export and upload:

   export CLOUDZERO_API_KEY="..."
   export CLOUDZERO_CONNECTION_ID="..."
   lean-ctx finops export --target=cbf --from=2026-06-01 --to=2026-06-30 --upload
   

3. Idempotency: uploads carry "operation": "replace_drop" per month — re-running an export replaces that month's drop instead of duplicating (CloudZero-side guarantee). One drop is posted per calendar month in the range.

Dimensions arrive as resource/tag:project|agent_role|model|tool tags and are filterable in CloudZero Explorer.

Vantage (Custom Provider)

Spec pinned: Vantage Custom Providers ingest a FOCUS-aligned CSV — required columns BilledCost, ChargeCategory, ChargePeriodStart, ServiceName; negative costs documented as accepted.

1. Create the provider once: POST /v2/integrations/custom_provider (or console → Integrations → Custom Provider) and note the integration token.

2. Export and upload:

   export VANTAGE_API_TOKEN="..."
   export VANTAGE_INTEGRATION_TOKEN="accss_crdntl_..."
   lean-ctx finops export --target=vantage --from=2026-06-01 --to=2026-06-30 --upload
   

3. Idempotency warning: Vantage treats each CSV upload as an additive dataset — there is no replace operation. Before re-sending a period, delete the previous upload in Vantage (Settings → Integrations → your provider). The CLI prints the dataset window after every upload as a reminder.

Dimensions arrive in the Tags JSON column (project, agent_role, model, tool).

FOCUS CSV (generic)

Spec pinned: FOCUS v1.2 (June 2024 — first version with SaaS/token-denominated pricing columns). The file emits all 21 v1.2 Mandatory columns plus the FOCUS 1.0 required set (Provider, InvoiceIssuer, ResourceID, ChargeType, Tags, …) so both generations of consumers accept it; additive columns are explicitly allowed. lean-ctx dimensions ride in x_project, x_agent_role, x_model, x_tool, x_tokens_saved.

Validated against the FinOps Foundation's official validator (focus-validator 1.0.0):

pip install focus-validator 'multimethod<2.0'
lean-ctx finops export --target=focus --out=leanctx_focus.csv
# Run from the site-packages dir — the 1.0.0 validator resolves its
# currency-code list via a relative path (upstream packaging bug):
cd "$(python3 -c 'import focus_validator, os; print(os.path.dirname(os.path.dirname(focus_validator.__file__)))')"
focus-validator --data-file /path/to/leanctx_focus.csv --column-namespace x
# → Validation succeeded.

Showback queries that now work

• "What did agent context cost per project last month, and what did lean-ctx save us?" — group by project (tag/column), compare Usage vs. Credit/Discount.
• "Which agent role burns the most tokens?" — group by agent_role.
• "Is the savings rate degrading after the editor update?" — Credit ÷ Usage trend per day.

Verifying the numbers

Every row aggregates hash-chained ledger events recorded on the producing machine. To audit: lean-ctx ledger verify (chain integrity) and lean-ctx gain (the same totals the export uses). The ledger design is documented in docs/business/03-verified-savings-ledger.md.