Skip to main content

focus-data-toolkit

Generate realistic FOCUS 1.2 / 1.3 cost & usage data (AWS, Azure, GCP), convert it to FOCUS 1.4, and validate the result — from a single dependency-free Python core, usable three ways.

PyPI Python License: MIT AND CC-BY-4.0 CI

FOCUS is the open standard for cloud cost & usage data. FOCUS 1.4 defines four datasets: Cost and Usage, Contract Commitment, Billing Period and Invoice Detail. This toolkit migrates real data, synthesizes sample data, and checks structure — honestly: a structurally valid file is not automatically FOCUS-conformant, and any value it cannot derive from the source is either left empty (strict mode) or filled only as a clearly-labelled assumption (synthetic mode).

Three ways to use it

Interface Best for Get started
Studio FinOps users who prefer a UI pip install "focus-data-toolkit[studio]" → focus-toolkit ui
Runner Automation & large volumes docker run --rm ghcr.io/guymano/focus-data-toolkit:0.12.0 version
CLI & SDK Engineers & scripts pip install focus-data-toolkit → focus-toolkit --help

All three drive the same core, so their outputs are byte-for-byte identical — same datasets, manifest, diagnostics and SHA256SUMS. No FOCUS logic is duplicated across interfaces.

  • Studio — a local, single-user web app: pick or upload a file (or generate one), detect it, convert with live progress, preview a sampled page, and download the results. Binds 127.0.0.1, token-guarded; no data leaves your machine. → docs/studio.md
  • Runner — a non-root OCI image whose entrypoint is the CLI, for batch jobs and CI. → docs/runner.md
  • CLI & SDK — the focus-toolkit command and the importable Python API.

Install

pip install focus-data-toolkit

The core is standard-library only (Python ≥ 3.11). Optional features live behind extras:

Extra Adds
parquet Parquet I/O — columnar, decimal128, Hive partitioning (alias: scale)
studio the local web UI (focus-toolkit ui)
studio-all studio + parquet
validator the official FinOps validator (--official; needs Python ≥ 3.12)
all parquet + validator + studio
pipx install focus-data-toolkit                        # isolated CLI
uv tool install focus-data-toolkit                     # or with uv
docker pull ghcr.io/guymano/focus-data-toolkit:0.12.0  # container (Runner)

Quickstart

# 1. Generate provider-realistic sample data (aws|azure|gcp, FOCUS 1.2|1.3)
focus-toolkit generate --provider aws --focus-version 1.3 --rows 1000 --out ./out

# 2. Convert a 1.2/1.3 Cost & Usage file to FOCUS 1.4 (source version auto-detected)
focus-toolkit convert --cost-and-usage out/focus_1_3_cost_and_usage_aws.csv --out ./focus-1.4
#    strict conversion of this sample exits 3 (three datasets NOT_PRODUCED, by design) —
#    add --exit-policy pipeline in `set -e` / CI scripts. Use --mode synthetic to also emit
#    the other three datasets (clearly labelled), or --stream --output-format parquet for large files.

# 3. Open the Studio web app (needs the studio extra: pip install "focus-data-toolkit[studio]")
focus-toolkit ui

Use it as a library — the same engine the CLI, Studio and Runner run:

from focus_data_toolkit import convert_files

convert_files("cost_and_usage.csv", "focus-1.4", mode="strict")

What it does — and what it doesn't

  • Converts FOCUS 1.2 / 1.3 Cost & Usage → the four FOCUS 1.4 datasets. strict mode emits only what is genuinely derivable from the source; synthetic mode also fills the provider-billing datasets with clearly-labelled assumed data for demos and tests.
  • Honest by design. The source is Cost & Usage only, so Contract Commitment / Billing Period / Invoice Detail come only from client supplements or synthetic mode. There is no FOCUS 1.4 generator and no invalid-data generator. Generation is in-memory (use the CLI/Runner for very large synthetic sets), and the engine is single-node.
  • Built for real data. Bounded-memory streaming conversion, atomic/journaled writes, a deterministic manifest with per-column lineage, structured FDT-* diagnostics, and a cross-dataset validation gate.

See docs/compatibility.md for the Python / OS / FOCUS support matrix.

Exit codes

convert returns meaningful codes so pipelines can branch on the outcome:

Code Meaning
0 success, no assumptions
1 lint / validation / write failure
2 invalid input or arguments
3 strict result intentionally incomplete
4 synthetic result contains assumptions
5 disk space / budget exhausted (streaming / Runner)
130 cancelled (Ctrl-C / SIGTERM) — nothing partial is published

Code 5 is raised on the bounded-memory path (--stream, Parquet, partitioning, or the Runner); the eager default CSV conversion reports a disk-full as a write failure (1). Add --exit-policy pipeline to treat the functional-but-incomplete outcomes (3, 4) as 0.

Trust & provenance

  • Deterministic: the same input always produces the same output bytes (no clock, no RNG); the datasets and manifest are listed in SHA256SUMS (the non-deterministic _run.json run sidecar is intentionally excluded).
  • Verifiable model: the embedded FOCUS 1.4 model is extracted from the FinOps source workbook and its provenance is complete — hash-pinned and reproduced byte-for-byte. See docs/model-provenance.md.
  • Supply chain: releases are built reproducibly, signed (Sigstore/cosign), and ship an SBOM and build attestations. See docs/releasing.md.
  • Private: the core does no network I/O, has no telemetry, and needs no credentials. See docs/security-model.md.

Documentation

Studio · Runner · Supplements & gaps · Compatibility · Versioning · Security model · Model provenance · Releasing · Changelog · Contributing · Security policy

License & credits

Code is MIT (see LICENSE). The embedded FOCUS 1.4 data model is a derivative of the FinOps FOCUS data-model workbook, © the FinOps Foundation and licensed CC-BY-4.0, redistributed with attribution (see NOTICE). "FOCUS" and "FinOps" are trademarks of the FinOps Foundation; this is an independent community project, not endorsed by the FinOps Foundation. Related sample datasets were contributed upstream to FOCUS-Sample-Data.

Metadata

Release files for focus-data-toolkit 0.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for focus-data-toolkit 0.12.0
File Size Uploaded Provenance Actions
focus_data_toolkit-0.12.0.tar.gz 465.3 kB With provenance Details for focus_data_toolkit-0.12.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for focus-data-toolkit 0.12.0
File Interpreter ABI Platform Actions
focus_data_toolkit-0.12.0-py3-none-any.whl Python 3 none any Details for focus_data_toolkit-0.12.0-py3-none-any.whl

Total release size: 717.2 kB

Release files / focus_data_toolkit-0.12.0.tar.gz

Download URL focus_data_toolkit-0.12.0.tar.gz
Size 465.3 kB
Tags Source
SHA-256 checksum
How to use checksums
ccb4776039fe6d2340476ed977dd9bc610f05e8ca4455e89445992eee9f39a9a
BLAKE2b-256 checksum
How to use checksums
dbb94f9533f0d4c89445fb282ef665e8909b80aeecfa9a29ada83c45b321e46e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.

Transparency log

Release files / focus_data_toolkit-0.12.0-py3-none-any.whl

Download URL focus_data_toolkit-0.12.0-py3-none-any.whl
Size 251.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a9e6f420d822e502cb4dac120db5b2fd78c43631fd34f3af38f69169d9d5cf3b
BLAKE2b-256 checksum
How to use checksums
1b3a9ca9d2f0d1ab3e5b5c85616578d9da6dee8aab8aa5eefcd14c364be8167f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.

Transparency log

Security for focus-data-toolkit 0.12.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for focus_data_toolkit-0.12.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Aug 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page