Skip to main content

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.

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

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, structured FDT-* 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)

Source distribution for focus-data-toolkit 0.14.0
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)

Table of built distributions (wheels) for focus-data-toolkit 0.14.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 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