focus-data-toolkit
Generate realistic FOCUS 1.2 / 1.3 cost and usage data (AWS, Azure, GCP), convert it to FOCUS 1.4, and validate the result. One dependency-free Python core, usable three ways.
FOCUS is the open standard for cloud cost and usage data. FOCUS 1.4 defines four datasets: Cost and Usage, Contract Commitment, Billing Period, and Invoice Detail. The toolkit is honest by design: any value it cannot derive from your source is left empty (strict mode) or filled with clearly labelled assumptions (synthetic mode).
The source prepares 0.14.0, which converts FOCUS 1.2/1.3 sources toward 1.4 more faithfully:
- values are migrated to the 1.4 rules, and a stricter 1.4 lint checks the output;
- commitment terms can be supplied explicitly;
- Azure reservation and savings plan orders have adapters;
- a 1.2 source can declare who issued it, to name its Service Provider.
See the conversion rules and the changelog. The generator corrections and validation evidence describe the generated samples, unchanged since 0.13.0. The Docker examples below continue to pin the previously released 0.12.0 image.
Three ways to use it
| Interface | Best for | Get started |
|---|---|---|
| Studio | FinOps users who prefer a UI | pip install "focus-data-toolkit[studio]" then focus-toolkit ui |
| Runner | Automation and large volumes | docker run --rm ghcr.io/guymano/focus-data-toolkit:0.12.0 version |
| CLI & SDK | Engineers and scripts | pip install focus-data-toolkit then focus-toolkit --help |
All three run the same core, so their outputs are byte-for-byte identical. Studio is a local web app (binds 127.0.0.1, token-guarded, no data leaves your machine, see docs/studio.md). Runner is a non-root OCI image whose entrypoint is the CLI (see docs/runner.md).
Install
pip install focus-data-toolkit
The core needs only the standard library (Python 3.11+). Optional 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 |
everything above |
Also available via pipx install, uv tool install, or docker pull ghcr.io/guymano/focus-data-toolkit:0.12.0.
Quickstart
# 1. Generate 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 and 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
# 3. Open the Studio web app (needs the studio extra)
focus-toolkit ui
Or use it as a Python library, the same engine behind all three interfaces:
from focus_data_toolkit import convert_files
convert_files("cost_and_usage.csv", "focus-1.4", mode="strict")
Everything a library caller needs is importable from the package root, including supplements and the failures to handle:
from pathlib import Path
from focus_data_toolkit import (
AtomicWriteError, ConversionError, Mode, SupplementBundle, SupplementError,
SupplementFileSpec, convert_files,
)
try:
bundle = SupplementBundle.load([SupplementFileSpec(path=Path("invoices.json"))])
convert_files("cost_and_usage.csv", "focus-1.4", mode=Mode.STRICT, supplements=bundle)
except (ConversionError, SupplementError):
... # invalid source or unusable supplement: nothing was written
except AtomicWriteError:
... # the lint or cross-dataset gate refused publication: nothing was written
What it does, and what it doesn't
- Converts FOCUS 1.2/1.3 Cost and Usage into the four FOCUS 1.4 datasets. Values a 1.4 rule
fixes deterministically are migrated and reported (
FDT-MIG-*). Values it cannot fix without inventing a fact are refused. See docs/conversion-rules.md. - The three other datasets come only from supplements or synthetic mode. There is no FOCUS 1.4 generator and no invalid-data generator.
- Built for real data: bounded-memory streaming (
--stream), atomic writes, a deterministic manifest with per-column lineage, structuredFDT-*diagnostics, cross-dataset validation. - Single-node engine. See docs/compatibility.md for the support matrix.
Exit codes
| 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 or budget exhausted (streaming / Runner) |
130 |
cancelled (Ctrl-C / SIGTERM), nothing partial is published |
Add --exit-policy pipeline in set -e or CI scripts to treat codes 3 and 4 as 0.
Trust
- Deterministic: same input, same output bytes, all listed in
SHA256SUMS. - The embedded FOCUS 1.4 model is hash-pinned to the FinOps source workbook; see docs/model-provenance.md.
- Releases are reproducible, signed (Sigstore/cosign), with SBOM and attestations; see docs/releasing.md.
- Private: no network I/O, no telemetry, no credentials; see docs/security-model.md.
Documentation
Studio · Runner · Supplements · Compatibility · Versioning · Security model · Model provenance · Releasing · Changelog · Contributing · Security policy
License
Code is MIT (see LICENSE). The embedded FOCUS 1.4 data model derives from the FinOps FOCUS workbook, © the FinOps Foundation, CC-BY-4.0 (see NOTICE). "FOCUS" and "FinOps" are FinOps Foundation trademarks; this is an independent community project, not endorsed by the FinOps Foundation.
Metadata
Release files for focus-data-toolkit 0.14.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| focus_data_toolkit-0.14.0.tar.gz | 640.4 kB | With provenance | Details for focus_data_toolkit-0.14.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| focus_data_toolkit-0.14.0-py3-none-any.whl | Python 3 | none | any | Details for focus_data_toolkit-0.14.0-py3-none-any.whl |
Total release size: 916.3 kB
Release files / focus_data_toolkit-0.14.0.tar.gz
| Download URL | focus_data_toolkit-0.14.0.tar.gz |
|---|---|
| Size | 640.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
90c46c299494968bb94c4ed2b5ff97292f10ad908d40dbc01b41b9e611f16e65
|
|
BLAKE2b-256 checksum How to use checksums |
f4ff802a51ad814401c725c1e0a737d8aa66ca51e939b8cbf82ea61b6c034768
|
| 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 Oct 6, 2026.
Transparency logRelease files / focus_data_toolkit-0.14.0-py3-none-any.whl
| Download URL | focus_data_toolkit-0.14.0-py3-none-any.whl |
|---|---|
| Size | 276.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
339dc5b2509aec564b405c7cd9bbca0feaaf6914dcd659587c8d29ce2c890ad1
|
|
BLAKE2b-256 checksum How to use checksums |
bbb043bc6f8333aabcfbab7743e9473cc76cf9d7aad75ffded51a9682f79416c
|
| 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 Oct 6, 2026.
Transparency logSecurity for focus-data-toolkit 0.14.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.
Attestation for focus_data_toolkit-0.14.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 Oct 6, 2026.
Transparency logA 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.