focus-data-toolkit 0.12.0__tar.gz → 0.14.0__tar.gz

{focus_data_toolkit-0.12.0 → focus_data_toolkit-0.14.0}/CHANGELOG.md

@@ -9,6 +9,196 @@ policy.
 
 ## [Unreleased]
 
+## [0.14.0] — 2026-10-06
+
+FOCUS 1.2/1.3 to 1.4 conversion follows the specification more closely, and commitment
+terms and provider-native commitment inventories can complete the 1.4 datasets.
+
+- **Breaking:**
+  - the `aws-savings-plans` adapter (v2) is keyed by `savingsPlanArn`;
+  - a unit-price column the source does not carry is omitted from the 1.4 Cost and Usage
+    output instead of being written null.
+- **New byte baselines for converted output:**
+  - conversion manifests label migrated columns `DERIVED`;
+  - `ContractCommitmentDurationType` is written in whole years (`1 Year`, `3 Years`).
+
+  Generated samples are unchanged.
+- **Stricter lint:** output that passed with 0.13.0 can now be refused; see the upgrade
+  notes under Changed.
+
+### Added
+
+- The supplement API and the documented failures are now public, re-exported from the
+  package root: `SupplementBundle`, `SupplementFileSpec`, `load_bundle_dir`,
+  `compute_gaps`, `GapReport`, `Mode`, `ConversionError`, `SupplementError` and
+  `AtomicWriteError`. Library callers no longer import internal modules, which
+  docs/versioning.md leaves free to change. Existing import paths keep working.
+- `ContractCommitmentDurationType` is a `contract_commitment` supplement column. A
+  supplied term wins over the derived value. It must follow the format v1.4 recommends, a
+  positive whole number and a listed unit (`1 Year`, `3 Years`, `36 Months`); anything
+  else is refused (`FDT-SUPP-004`). That format is a SHOULD in the specification, so the
+  lint of a 1.4 file does not fail on it.
+- `fdt gaps` reports `ContractCommitmentDurationType` as a conditional advisory: it is
+  derived only for periods spanning whole calendar months, so the other terms must be
+  supplied. Without a commitment period in the source it is a blocking gap.
+- A supplement that almost matches a provider adapter now names what it lacks, e.g.
+  `aws-savings-plans@2 requires savingsPlanArn` for an export from the v1 adapter era.
+- Azure commitment adapters `azure-reservation-orders` and `azure-savings-plan-orders`
+  (REST shape, api-version 2022-11-01). One row per order, keyed by the lowercased order
+  ARM id. Each provides the term (`1 Year`, `3 Years`, `5 Years`, or `1 Month` for a
+  monthly savings plan), the payment model and interval, the lifecycle status where the
+  provisioning state determines one, the creation time where the response carries it,
+  and the benefit category. The commitment model is
+  not emitted: the order does not carry the commitment grain. A savings plan order is
+  recognised by its `sku.name`; a new `none_of` detection clause rules out the plan- and
+  reservation-level lists, which share it. A `lower` adapter transform supports
+  case-insensitive provider identifiers.
+- A FOCUS 1.2 source can declare who issued it (`provider_role="csp"` or `"msp"`, CLI
+  `--provider-role`), with the cloud provider's own publisher names
+  (`first_party_publishers`, CLI `--first-party-publisher`).
+  - With `csp`, a row whose `PublisherName` differs from `ProviderName` and is no declared
+    first-party name is a Marketplace charge. Its `ServiceProviderName` and
+    `HostProviderName` become the seller, as FOCUS 1.4 requires (`FDT-MIG-005`).
+  - With `msp`, they stay `ProviderName`, the MSP.
+  - Without a declaration, `ProviderName` is kept as before, and those rows are reported
+    (`FDT-CTX-005`). Nothing is refused.
+  - Only official FOCUS columns are read. See
+    [conversion rules](docs/conversion-rules.md#participating-entities-of-a-12-source),
+    including why `HostProviderName` = `ServiceProviderName` is an interpretation for a 1.2
+    source.
+
+### Changed
+
+- **Breaking:** the `aws-savings-plans` adapter (now v2) is keyed by `savingsPlanArn`,
+  the fully qualified identifier FOCUS recommends and the one Contract Commitment and
+  `CommitmentDiscountId` carry. v1 keyed by the bare `savingsPlanId`, so its rows could
+  never join. Exports without `savingsPlanArn` are no longer auto-detected; re-export
+  with the ARN (as `describe-savings-plans` returns it). The adapter also maps
+  `termDurationInSeconds` (1 and 3 years) to the duration.
+- **New byte baseline:** `ContractCommitmentDurationType` is written in whole years when
+  the term is a multiple of 12 months (`1 Year`, `3 Years`), as in the specification's
+  examples, instead of `12 Months` / `36 Months`. Other terms stay in months.
+- The FOCUS 1.4 linter now enforces more of the static Cost and Usage rules of the v1.4
+  requirements model. Output that passed before can now fail the lint, and strict
+  publication refuses it:
+  - Tax and Credit `EffectiveCost` equals `BilledCost` (CAU-EffectiveCost-C-017);
+  - `ListCost` and `ContractedCost` equal unit price × `PricingQuantity` when both are
+    present, Correction rows included (C-011). The relative tolerance is the official
+    focus-validator's (1e-9 × max(|cost|, 1)), and the arithmetic is exact whatever the
+    caller's Decimal context. An operand whose exponent lies beyond ±1000 is reported as
+    not computable instead of being computed;
+  - a unit is null exactly when its quantity is (`PricingUnit`, `ConsumedUnit`,
+    `CommitmentDiscountUnit`, C-005/C-006);
+  - `ListUnitPrice` and `ContractedUnitPrice` are present when `SkuPriceId` is set
+    (C-013/C-015). This applies in every profile, as these rules have no applicability
+    criteria, except for a column the source did not carry.
+    `lint_focus_1_4_structure(source_absent_columns=...)` lets a producer name such
+    columns that it writes all null, and a column missing from the rows counts as absent;
+  - under a declared `SupportsUnitPricing` condition, the pricing and quantity columns
+    are null when `SkuPriceId` is null (C-009 to C-016).
+
+  Other static rules of the model are not checked. These include the pricing-currency
+  unit prices' C-012, whose presence is not visible on a row and whose model condition
+  for `PricingCurrencyContractedUnitPrice` contradicts its text.
+  **Upgrade note:** expect refusals for:
+  - provider costs rounded to the cent (exact identity), and 1.2 Correction rows, which
+    1.2 exempted from the identity;
+  - Credit rows whose `EffectiveCost` differs from `BilledCost` (C-017), which the
+    converter copies as is (Tax rows are migrated, `FDT-MIG-001`);
+  - rows with a `SkuPriceId` but a null `ListUnitPrice` or `ContractedUnitPrice` in a
+    column the source carries (C-013/C-015).
+- **Breaking (output layout):** a unit-price column the source does not carry
+  (`ListUnitPrice`, `ContractedUnitPrice`, `PricingCurrencyListUnitPrice`,
+  `PricingCurrencyContractedUnitPrice`) is no longer written all null into the 1.4 Cost
+  and Usage output; it is omitted, as Invoice Detail already omits its unfilled
+  conditional columns. Its presence condition is not met, and written null it would break
+  the "MUST NOT be null when SkuPriceId is not null" rules in any validator, including
+  `focus-toolkit validate` on the published file. A column counts as carried when any
+  source row carries it. Sources that carry all four columns, such as the generated
+  samples, are unchanged.
+- The client-like test fixture violated the cost identity by a factor of 1000; its
+  quantities are corrected. Its Tax row no longer carries a pricing quantity, and its
+  pricing-currency effective cost now matches its effective cost.
+- **New byte baseline for conversion manifests.** On sources that can trigger those
+  migrations, `EffectiveCost` and the `SkuPriceId`-dependent columns are now labelled
+  `DERIVED` at column level. This follows the "weakest lineage the rule can produce"
+  convention, and `lineage_summary` records the per-value mix. Converted values of the
+  generated samples are unchanged.
+- `ConversionError` and `ConversionCancelled` are defined in `focus_data_toolkit.convert.exceptions`
+  and re-exported unchanged from `focus_data_toolkit.convert`.
+
+### Fixed
+
+- `focus-toolkit convert --stream` printed each diagnostic as `note None:`; it now prints
+  its code, as the eager path does.
+- `ContractCommitmentDurationType` is no longer rounded from `days / 30.44`, which turned
+  any span into a plausible-looking term. It is derived (`DERIVED`) only when the
+  commitment period spans a whole number of calendar months, the day clamped at month
+  end. Otherwise strict mode leaves it empty (`UNAVAILABLE`): Contract Commitment is not
+  produced until the term is supplied, and the other datasets are unaffected. Synthetic
+  mode assumes the nearest whole-month value (`ASSUMED`). `FDT-CC-001` lists the
+  commitments concerned, at the same point in the eager and streaming pipelines.
+- The duration's lineage is settled per row. A partial supplement no longer blanks, or
+  counts as supplied, the terms derived for the rows it does not cover.
+- A naive commitment timestamp is read as UTC, as FOCUS requires, instead of failing to
+  compare with an offset one; months are counted in the start's frame.
+- 1.2/1.3 Cost and Usage values that break a FOCUS 1.4 rule the converter can meet without
+  inventing a fact are migrated, instead of being copied into non-conformant output. Each
+  migration is counted and reported, and each migrated value counts as `DERIVED` in
+  `lineage_summary`:
+  - Tax `EffectiveCost` equals `BilledCost` (CAU-EffectiveCost-C-017), with the exact net
+    change per billing currency (`FDT-MIG-001`). Credit rows, also covered by C-017, are not
+    rewritten;
+  - pricing and quantity columns and their units are nulled where `SkuPriceId` is null, on
+    Tax, Credit, Adjustment and Correction rows (`FDT-MIG-002`). For a 1.2 source this
+    migrates values 1.2 allowed; a 1.3 source already broke its own version's rule;
+  - on Usage/Purchase rows that are not corrections, FOCUS 1.4 requires the same columns to
+    be non-null, so their values are kept and the conflict is reported (`FDT-MIG-004`); so
+    are rows whose `ChargeCategory` is missing or not an allowed value;
+  - null source pricing-currency values are backfilled with a warning (`FDT-MIG-003`).
+- A null `PricingCurrencyEffectiveCost` is no longer backfilled from `EffectiveCost` when
+  `PricingCurrency` differs from `BillingCurrency`, or when `BillingCurrency` is null. The
+  copy labelled a billing-currency amount with another, or an unknown, currency.
+  **Upgrade note:** a multi-currency source with such nulls used to convert; it now stops
+  with `FDT-MIG-011` (CLI exit 2). A Tax restatement across currencies stops with
+  `FDT-MIG-010`. See [conversion rules](docs/conversion-rules.md).
+
+### Security
+
+- The Runner image upgrades `perl-base` to 5.36.0-7+deb12u4 (bookworm-security). The
+  pinned base digest ships 5.36.0-7+deb12u3, which the container scan flags with three
+  CRITICAL (CVE-2026-13221, CVE-2026-42496, CVE-2026-8376) and four HIGH
+  (CVE-2026-42497, CVE-2026-48962, CVE-2026-57432, CVE-2026-57433) vulnerabilities.
+- The Runner image no longer ships the `libpcre2-8-0` 10.42-1 package flagged HIGH by
+  the container scan (CVE-2026-103111, CVE-2026-86145, CVE-2026-89157, CVE-2026-89161).
+  The base image digest (`python:3.12-slim-bookworm`) is refreshed, bringing
+  10.42-1+deb12u1. The runtime stage then installs the pinned bookworm-security fix
+  10.42-1+deb12u2, which no base digest ships yet.
+- Lock `urllib3` 2.8.0 (PYSEC-2026-4175, -4176, -4177). It reaches the lock only
+  transitively, through the optional `validator` extra (`focus-validator` -> `requests`)
+  and the release tooling (`twine`); the core toolkit has no runtime dependency.
+## [0.13.0] — 2026-09-05
+
+Prepared in source; publishing is a separate release step.
+
+- Correct period-subscription effective costs and derive illustrative 10% taxes
+  from earlier untaxed usage with exact amount and currency lineage.
+- Stabilize offer/SKU/price identities and public prices; correct recognized storage
+  properties, AWS namespaces and owning subaccounts, including allocations.
+- Model partially used fleets of 500 machines, exact annual capacity and complete
+  budget-aware groups. Add targeted 1.3 negotiated contracts, shared contract parents
+  and a common generation registry; Contract Commitment APIs accept `include_credits`.
+- Omit inapplicable ContractApplied metric properties while retaining legacy input
+  compatibility. Preserve exact invoice aggregates and widen affected Parquet cost
+  columns to `decimal128(38,17)` without silent rounding.
+- Replace FAIL-only official gating with complete inventories, violation counts,
+  resource/source/data fingerprints, archived reports and separately reviewed
+  candidate evidence. Public `validate --official` now rejects false-green exits.
+- **New byte baseline:** regenerated provider goldens, archived before examples,
+  independent corruption tests and reproducible statistics. See
+  [generator corrections](docs/generator-corrections.md) for assumptions, residual
+  official failures and the deliberate differences from upstream PRs 6 and 7.
+
 ## [0.12.0] — 2026-08-21
 
 Back-ports the reviewed FOCUS-Sample-Data conformance fixes into the generator engine.
@@ -694,7 +884,9 @@ conformance defects.
 
 <!-- Reference links. 0.2.0/0.3.0 were pre-release development milestones and were never tagged
      or published, so only the first public release (0.9.0) has a tag link. -->
-[Unreleased]: https://github.com/guymano/focus-data-toolkit/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/guymano/focus-data-toolkit/compare/v0.14.0...HEAD
+[0.14.0]: https://github.com/guymano/focus-data-toolkit/compare/v0.13.0...v0.14.0
+[0.13.0]: https://github.com/guymano/focus-data-toolkit/compare/v0.12.0...v0.13.0
 [0.12.0]: https://github.com/guymano/focus-data-toolkit/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/guymano/focus-data-toolkit/compare/v0.11.0rc1...v0.11.0
 [0.11.0rc1]: https://github.com/guymano/focus-data-toolkit/compare/v0.9.0...v0.11.0rc1

{focus_data_toolkit-0.12.0 → focus_data_toolkit-0.14.0}/CONTRIBUTING.md

@@ -49,6 +49,8 @@ pytest -m packaging                        # build + install a wheel/sdist (need
 
 python scripts/check_pinned_actions.py     # every GitHub Action is SHA/digest pinned
 python scripts/verify_model_provenance.py  # the embedded FOCUS model matches its provenance
+python scripts/describe_generated_samples.py # independently audited sample statistics
+python scripts/validate_official_samples.py --check-existing # archived reports + provenance
 ```
 
 A PR is expected to be green on lint, types, and the default test suite, and to
@@ -63,7 +65,8 @@ identical toolkit version and identical parameters (`provider`, `focus_version`,
 - Keep generator draws in a fixed order; do not introduce a clock, real RNG, or
   environment-dependent behaviour into generation/conversion.
 - Golden snapshots live in `tests/fixtures/golden/`:
-  - `compatibility_golden/` — outputs verified correct against the FOCUS spec.
+  - `compatibility_golden/` — reviewed synthetic outputs with executable semantic checks
+    and documented residual official-model/validator failures.
     These are a **byte-for-byte** intra-version contract.
   - `correctness_migration/` — cases with a *known* prior defect: the old output
     is archived for comparison, and the **new** output is the spec-correct one.
@@ -74,6 +77,11 @@ identical toolkit version and identical parameters (`provider`, `focus_version`,
 - If a diff changes a snapshot you did **not** intend to touch, treat it as a
   regression and investigate before updating the fixture.
 
+Generator changes also require a fresh official-validation **candidate**, review
+of every changed rule/state/count and explicit evidence promotion. See
+[generator corrections](docs/generator-corrections.md). A successful reference
+comparison does not certify complete FOCUS conformance.
+
 ## Changing the embedded FOCUS model
 
 The FOCUS 1.4 model JSON (`src/focus_data_toolkit/model/focus_1_4_model.json`) is

{focus_data_toolkit-0.12.0 → focus_data_toolkit-0.14.0}/MANIFEST.in

@@ -18,7 +18,9 @@ include tools/extract_focus_1_4_model.py
 recursive-include scripts *.py
 recursive-include schema *.json
 recursive-include docs *.md
+include docs/generator-statistics.json
 recursive-include tests *.py *.csv *.json *.md
+recursive-include tests/fixtures/official/generator_validation *.log
 
 global-exclude *.py[cod]
 global-exclude __pycache__

{focus_data_toolkit-0.12.0 → focus_data_toolkit-0.14.0}/NOTICE

@@ -46,6 +46,17 @@ documentation page it was authored against.
 
 3. Optional dependency: the official FinOps FOCUS validator
 -----------------------------------------------------------
+The source test evidence at tests/fixtures/official/generator_validation includes
+rule expressions from the FOCUS 1.2.0.1 and 1.3.0.1 models (FinOps Foundation,
+CC-BY-4.0, source and license links in section 2 above) and captured validator
+results. Model expressions are reproduced without modification; surrounding
+explanations and synthetic example records are authored by this project.
+
+Generator corrections adapt the behavior examined in FOCUS-Sample-Data PRs 6/7,
+at commits e14921a3ba8d5f75a7b899d878e372999482ba9a and
+99917010b27f7c0ca3586f8e0daab7e1c8103dac. See docs/generator-corrections.md for
+source links and the deliberate semantic adaptations.
+
 The optional `[validator]` extra installs `focus-validator` from PyPI, which is
 published by the FinOps Foundation under its own license. It is not vendored or
 redistributed by this project; it is resolved by your package manager on

focus_data_toolkit-0.14.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.4
+Name: focus-data-toolkit
+Version: 0.14.0
+Summary: Generate provider-realistic FOCUS 1.2/1.3 sample data (AWS, Azure, GCP) and convert it to the four FOCUS 1.4 datasets — strictly from source facts, completed by client supplements including native AWS/Azure/GCP exports — with schema detection, gap analysis, a cross-dataset validation gate and atomic writes.
+Author: Guy-Hermann Adiko
+License-Expression: MIT AND CC-BY-4.0
+Project-URL: Homepage, https://github.com/guymano/focus-data-toolkit
+Project-URL: Source, https://github.com/guymano/focus-data-toolkit
+Project-URL: Issues, https://github.com/guymano/focus-data-toolkit/issues
+Project-URL: Changelog, https://github.com/guymano/focus-data-toolkit/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://github.com/guymano/focus-data-toolkit#readme
+Keywords: finops,focus,billing,cost,sample-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+License-File: LICENSES/CC-BY-4.0.txt
+Provides-Extra: parquet
+Requires-Dist: pyarrow<26,>=15; extra == "parquet"
+Requires-Dist: tzdata>=2024.1; sys_platform == "win32" and extra == "parquet"
+Provides-Extra: scale
+Requires-Dist: focus-data-toolkit[parquet]; extra == "scale"
+Provides-Extra: validator
+Requires-Dist: focus-validator<3,>=2.1; python_version >= "3.12" and extra == "validator"
+Provides-Extra: studio
+Requires-Dist: fastapi<1,>=0.110; extra == "studio"
+Requires-Dist: uvicorn[standard]<1,>=0.29; extra == "studio"
+Requires-Dist: python-multipart<1,>=0.0.9; extra == "studio"
+Provides-Extra: studio-all
+Requires-Dist: focus-data-toolkit[parquet,studio]; extra == "studio-all"
+Provides-Extra: all
+Requires-Dist: focus-data-toolkit[parquet,studio,validator]; extra == "all"
+Provides-Extra: release
+Requires-Dist: build<2,>=1; extra == "release"
+Requires-Dist: twine<8,>=5; extra == "release"
+Provides-Extra: dev
+Requires-Dist: focus-data-toolkit[parquet,release,studio]; extra == "dev"
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov<8,>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy<2.5,>=1.11; extra == "dev"
+Requires-Dist: jsonschema<5,>=4.21; extra == "dev"
+Requires-Dist: httpx<1,>=0.27; extra == "dev"
+Dynamic: license-file
+
+# 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](https://img.shields.io/pypi/v/focus-data-toolkit)](https://pypi.org/project/focus-data-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/focus-data-toolkit)](https://pypi.org/project/focus-data-toolkit/)
+[![License: MIT AND CC-BY-4.0](https://img.shields.io/badge/license-MIT%20AND%20CC--BY--4.0-blue)](LICENSE)
+[![CI](https://github.com/guymano/focus-data-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/guymano/focus-data-toolkit/actions/workflows/ci.yml)
+
+[FOCUS](https://focus.finops.org) 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](docs/conversion-rules.md) and the [changelog](CHANGELOG.md).
+The [generator corrections and validation evidence](docs/generator-corrections.md)
+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](docs/studio.md)). Runner is a non-root OCI image whose entrypoint is the CLI (see [docs/runner.md](docs/runner.md)).
+
+## Install
+
+```bash
+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
+
+```bash
+# 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:
+
+```python
+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:
+
+```python
+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](docs/conversion-rules.md).
+- The three other datasets come only from [supplements](docs/supplements.md) 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](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](docs/model-provenance.md).
+- Releases are reproducible, signed (Sigstore/cosign), with SBOM and attestations; see [docs/releasing.md](docs/releasing.md).
+- Private: no network I/O, no telemetry, no credentials; see [docs/security-model.md](docs/security-model.md).
+
+## Documentation
+
+[Studio](docs/studio.md) · [Runner](docs/runner.md) · [Supplements](docs/supplements.md) · [Compatibility](docs/compatibility.md) · [Versioning](docs/versioning.md) · [Security model](docs/security-model.md) · [Model provenance](docs/model-provenance.md) · [Releasing](docs/releasing.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
+
+## License
+
+Code is MIT (see [LICENSE](LICENSE)). The embedded FOCUS 1.4 data model derives from the FinOps FOCUS workbook, © the FinOps Foundation, CC-BY-4.0 (see [NOTICE](NOTICE)). "FOCUS" and "FinOps" are FinOps Foundation trademarks; this is an independent community project, not endorsed by the FinOps Foundation.

focus_data_toolkit-0.14.0/README.md

@@ -0,0 +1,132 @@
+# 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](https://img.shields.io/pypi/v/focus-data-toolkit)](https://pypi.org/project/focus-data-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/focus-data-toolkit)](https://pypi.org/project/focus-data-toolkit/)
+[![License: MIT AND CC-BY-4.0](https://img.shields.io/badge/license-MIT%20AND%20CC--BY--4.0-blue)](LICENSE)
+[![CI](https://github.com/guymano/focus-data-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/guymano/focus-data-toolkit/actions/workflows/ci.yml)
+
+[FOCUS](https://focus.finops.org) 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](docs/conversion-rules.md) and the [changelog](CHANGELOG.md).
+The [generator corrections and validation evidence](docs/generator-corrections.md)
+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](docs/studio.md)). Runner is a non-root OCI image whose entrypoint is the CLI (see [docs/runner.md](docs/runner.md)).
+
+## Install
+
+```bash
+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
+
+```bash
+# 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:
+
+```python
+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:
+
+```python
+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](docs/conversion-rules.md).
+- The three other datasets come only from [supplements](docs/supplements.md) 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](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](docs/model-provenance.md).
+- Releases are reproducible, signed (Sigstore/cosign), with SBOM and attestations; see [docs/releasing.md](docs/releasing.md).
+- Private: no network I/O, no telemetry, no credentials; see [docs/security-model.md](docs/security-model.md).
+
+## Documentation
+
+[Studio](docs/studio.md) · [Runner](docs/runner.md) · [Supplements](docs/supplements.md) · [Compatibility](docs/compatibility.md) · [Versioning](docs/versioning.md) · [Security model](docs/security-model.md) · [Model provenance](docs/model-provenance.md) · [Releasing](docs/releasing.md) · [Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md) · [Security policy](SECURITY.md)
+
+## License
+
+Code is MIT (see [LICENSE](LICENSE)). The embedded FOCUS 1.4 data model derives from the FinOps FOCUS workbook, © the FinOps Foundation, CC-BY-4.0 (see [NOTICE](NOTICE)). "FOCUS" and "FinOps" are FinOps Foundation trademarks; this is an independent community project, not endorsed by the FinOps Foundation.