FLUX Simulation Engine
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.
Try it
You need uv.
uvx --from flux-sim-engine fluxsim init demo && cd demo && uvx --from flux-sim-engine fluxsim run . --verify --ship -o out
That 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 out
Open .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.
What it is
- 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".
What it is not
- 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.
How FLUX works
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.
Where to go next
- 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.
Develop
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.
License
Apache License 2.0. See LICENSE and NOTICE. Third-party components are listed in THIRD_PARTY_LICENSES.md.
Metadata
Release files for flux-sim-engine 0.7.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 |
|---|---|---|---|---|
| flux_sim_engine-0.7.0.tar.gz | 789.6 kB | With provenance | Details for flux_sim_engine-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| flux_sim_engine-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for flux_sim_engine-0.7.0-py3-none-any.whl |
Total release size: 1.7 MB
Release files / flux_sim_engine-0.7.0.tar.gz
| Download URL | flux_sim_engine-0.7.0.tar.gz |
|---|---|
| Size | 789.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a1e4363b70f9625775132394713cf8fbcbfa7c0f67b5300b3065a273f69a58ed
|
|
BLAKE2b-256 checksum How to use checksums |
2d940a7f2bb949dda8377616e25755e10f78b32396b71230106e4c27e7664acc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 19, 2026.
Transparency logRelease files / flux_sim_engine-0.7.0-py3-none-any.whl
| Download URL | flux_sim_engine-0.7.0-py3-none-any.whl |
|---|---|
| Size | 869.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
445bcfa6703872793ccea773450e8eb80daafbad1e525471833416fb651b9fec
|
|
BLAKE2b-256 checksum How to use checksums |
28edb91b4d11c9124b81e4388d9be4b18b942c2d73f9294e79385872a12c8d97
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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 Nov 19, 2026.
Transparency logSecurity for flux-sim-engine 0.7.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 flux_sim_engine-0.7.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 Nov 19, 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.