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.
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-toolkitcommand 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.
strictmode emits only what is genuinely derivable from the source;syntheticmode 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.jsonrun 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 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.