Describe your customers and what they do in YAML, and this engine turns that into synthetic rows that follow a FLUID data contract: the same rows every time, with a report that says plainly what the run does not show.
Documentation: https://agenticstiger.github.io/flux/engine/
The pages in this repository describe the main branch, and the latest release on PyPI can lag behind it. The documentation site above holds a copy of them taken at a pinned engine version, so it can be older still. A feature that main has and the latest release lacks is marked where a page first mentions it, with the release it came after, for example (added after 0.6.0). To run exactly what the pages describe, install the engine from main:
uv tool install git+https://github.com/Agenticstiger/flux-engine
Which version these pages describe has the pip form.
You need uv.
uvx --from flux-sim-engine fluxsim init demo && cd demo && uvx --from flux-sim-engine fluxsim run . --verify --ship -o outThat writes a small project, runs a 500-customer simulation, checks the result and packs an evidence archive into out/, in a few seconds. With the command installed (uv tool install flux-sim-engine, or pip install flux-sim-engine in a virtual environment), the same two steps print this:
$ fluxsim init demo
created demo with a small FLUX bundle and its FLUID contract (10 files):
...
$ cd demo
$ fluxsim run . --verify --ship -o out
...
emitted payment_recovery_moment: 154 rows (scenario)
reproducible: not checked | validity: not asserted
...
shipped out/demo.flux.tgz
run ... complete; shipped to outOpen .flux/runs/<runId>/EVIDENCE.md first: its last section, "What Was Not Proven", lists what the run does not show. The tutorial goes through each step.
- Repeatable. The same bundle and the same seed give the same bytes on every system the project's CI checks (Linux and macOS, Python 3.11 to 3.13).
fluxsim replayruns a recorded plan again and refuses unless it reaches the digest you give it. - Declarative. A bundle is YAML documents for the world, the personas, the signals, the journeys and the treatments. It refers to a FLUID contract and never restates it, so the rows have the shape the contract expects.
- Six steps, one command each.
validate,plan,apply,run,verify,ship.shippacks the bundle, the run and a manifest into one archive, writes two unsigned in-toto statements beside it, and the report inside always ends in a section called "What Was Not Proven".
- Not evidence about the real world. The engine reproduces the scenario you describe. Whether the scenario matches reality is a separate question, and in this release the report answers it
validity: not asserted. - Not a privacy or fairness tool. The rows are made from the numbers you declare. The pack makes no claim about privacy, fairness or any model trained on the rows.
- Not a model of how related rows depend on each other. The tables a Simulation generates from statistics for one FLUID 0.7.7 contract are generated together: every key is unique, and every foreign key names a row its parent holds (KERNEL-SPEC.md section 8.2). A child row's other columns are still drawn on their own, so a return's amount does not follow from the sale it returns.
- Not finished. The agentic tier, the sweep executor for
fidelity: stochastic, calibration withpyabcand an OpenLineage transport are absent, and the engine says so instead of degrading quietly.fluxsim describe --selfsays whether the libraries behind three of them (agentic,calibrate_abc,lineage_transport) are installed, and a bundle that asks forfidelity: stochasticis refused with an error. Synthesis from real records, the way synthcity or SDV fit a model to rows, is not planned at all: see ADR 0003.
FLUX makes rows from the numbers a bundle declares, never by fitting a model to records. Those numbers can come from a profile: aggregate statistics that a data owner computes with fluid profile where the data lives. fluxsim init --contract --profile writes a bundle from a contract and a profile, and labels every number by what it rests on (write a bundle from a profile). A run can then be scored against a profile that carries the statistics its bundle declares. From data-product-forge 0.31.0, fluid profile writes one: an ungrouped mean/1 for each number column whose mean passes its output checks, so a mean property over such a column is scored. A property that reads any other statistic, such as a support, is refused with FLX-5037; score a run against a profile shows the check with a profile written by hand. Architecture and patterns draws the whole picture: what crosses over from the data, the parts you install, the packages inside the engine and the rules between them, the life of a run, and the design patterns behind it.
- Tutorial: your first evidence pack in five minutes.
- How-to guides: model your customers, add a journey, use the FLUID seam, calibrate from aggregates, draw a column given another, ship with evidence, score a run against a profile, seal and score a prediction, load a simulation into a database.
- Explanation: how the parts fit together, the six-step loop, determinism and the seed tree, the seam, and what an evidence pack does not claim.
- Reference: every command, every error code, the Python API and the schemas.
- The FLUX specification: Agenticstiger/flux.
See CONTRIBUTING.md. The short version:
uv sync --extra dev
make check
make check runs the static checks and the fast tests; make ci-local runs every check in .github/workflows/ci.yml. The repository also releases flux-stats, the statistics the fidelity check compares, as a distribution of its own that installs without the engine; uv sync --extra dev sets up both. flux-stats runs on Python 3.10 or newer, the engine on 3.11 or newer. make docs-test runs every page of the documentation as a test, and make docs-gen rewrites the generated reference pages. The decisions behind the design are in docs/adr/, and the specifications in docs/spec/.
The end-to-end harness under e2e/aws/ checks FLUX the way a data owner would use it, against a relational source on AWS. It is a project of its own that no CI job runs. Its privacy judge measures the method on a TPC-DS-shaped dataset that holds no real people, and is not a privacy guarantee.
Apache License 2.0. See LICENSE and NOTICE. Third-party components are listed in THIRD_PARTY_LICENSES.md.