Skip to main content

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/

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 8835218acf7b4f8e 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 replay runs 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. ship packs 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 finished. The agentic tier, the sweep executor for fidelity: stochastic, calibration with pyabc and an OpenLineage transport are absent, and the engine says so instead of degrading quietly. fluxsim describe --self says whether the libraries behind three of them (agentic, calibrate_abc, lineage_transport) are installed, and a bundle that asks for fidelity: stochastic is 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.

Where to go next

  • Tutorial: your first evidence pack in five minutes.
  • How-to guides: model customers, add a journey, use the FLUID seam, calibrate from aggregates, ship with evidence, load a simulation into a database.
  • Explanation: 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 sets up both. 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/.

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.6.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 flux-sim-engine 0.6.0
File Size Uploaded Provenance Actions
flux_sim_engine-0.6.0.tar.gz 687.4 kB With provenance Details for flux_sim_engine-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for flux-sim-engine 0.6.0
File Interpreter ABI Platform Actions
flux_sim_engine-0.6.0-py3-none-any.whl Python 3 none any Details for flux_sim_engine-0.6.0-py3-none-any.whl

Total release size: 1.5 MB

Release files / flux_sim_engine-0.6.0.tar.gz

Download URL flux_sim_engine-0.6.0.tar.gz
Size 687.4 kB
Tags Source
SHA-256 checksum
How to use checksums
86bf6a3dfbfae6bfe80b1fdfaa5875d43d0cd8810083b6892a217e88d834a57c
BLAKE2b-256 checksum
How to use checksums
438e427a70a48fd52624f7d21a99b33b206b20b5b456bf782869ba1f294d35ae
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 17, 2026.

Transparency log

Release files / flux_sim_engine-0.6.0-py3-none-any.whl

Download URL flux_sim_engine-0.6.0-py3-none-any.whl
Size 763.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b2e8424d051bda6f3b350305802f9cb0a6f51893fb4c48b9daf6ece7702a4792
BLAKE2b-256 checksum
How to use checksums
6cae671c15f9878538c7685a96d27847524b1f27d8f202a456022befd639c6fe
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 17, 2026.

Transparency log

Security for flux-sim-engine 0.6.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 flux_sim_engine-0.6.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 17, 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