Metadata-Version: 2.4
Name: flux-sim-engine
Version: 0.6.1
Summary: FLUX Simulation Engine: the runtime for FLUX bundles -- deterministic, governed simulation under a referenced FLUID contract.
Author: Agentics Transformation Ltd
License-Expression: Apache-2.0
Project-URL: Documentation, https://agenticstiger.github.io/flux/engine/
Project-URL: Repository, https://github.com/Agenticstiger/flux-engine
Project-URL: Issues, https://github.com/Agenticstiger/flux-engine/issues
Keywords: FLUX,FLUID,simulation,synthetic data,data contracts
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pyyaml>=6
Requires-Dist: jsonschema>=4.22
Requires-Dist: rfc8785>=0.1
Requires-Dist: cloudevents<3,>=1.10
Requires-Dist: cryptography>=42
Requires-Dist: flux-spec<0.6,>=0.5.2
Requires-Dist: flux-stats==0.6.1
Provides-Extra: lineage
Requires-Dist: openlineage-python>=1.20; extra == "lineage"
Provides-Extra: arrow
Requires-Dist: pyarrow>=18; extra == "arrow"
Provides-Extra: adbc
Requires-Dist: pyarrow>=18; extra == "adbc"
Requires-Dist: adbc-driver-manager>=1.0; extra == "adbc"
Provides-Extra: dev
Requires-Dist: pytest>=8.2; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: hypothesis>=6.100; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: black==26.10.1; extra == "dev"
Requires-Dist: import-linter>=2.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.6; extra == "dev"
Requires-Dist: pytest-timeout>=2.3; extra == "dev"
Requires-Dist: sybil==10.1.0; extra == "dev"
Requires-Dist: reuse[charset-normalizer]==6.3.0; extra == "dev"
Requires-Dist: pyarrow>=18; extra == "dev"
Requires-Dist: adbc-driver-manager>=1.0; extra == "dev"
Requires-Dist: adbc-driver-sqlite>=1.0; extra == "dev"
Requires-Dist: duckdb>=1.5; extra == "dev"
Dynamic: license-file

# FLUX Simulation Engine

Describe your customers and what they do in YAML, and this engine turns that into synthetic rows that follow a [FLUID](https://open-data-protocol.github.io/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`:

```text
uv tool install git+https://github.com/Agenticstiger/flux-engine
```

[Which version these pages describe](docs/README.md#which-version-these-pages-describe) has the `pip` form.

## Try it

You need [uv](https://docs.astral.sh/uv/).

<!-- skip: next "installs the published package, so it cannot test this checkout; the First run workflow runs these same commands from a built wheel" -->
```bash
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:

```console
$ 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](docs/tutorial/first-evidence-pack.md) 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 a generator of related tables yet.** The engine reads a FLUID 0.7.7 contract's primary and foreign keys, but it does not generate related tables together: a foreign key's values are not drawn from the rows of the table it names ([KERNEL-SPEC.md](docs/spec/KERNEL-SPEC.md) section 8.1).
- **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](docs/adr/0003-sdv-bsl-and-aggregate-only-rule.md).

## How FLUX works

FLUX makes rows from the numbers a bundle declares, never by fitting a model to records. Those numbers can be copied from a profile: aggregate statistics that a data owner computes with `fluid profile` where the data lives. A run can then be scored against a profile that carries the statistics its bundle declares. Today `fluid profile` writes column metrics only, so `verify --profile` refuses such a run with [FLX-5037](docs/reference/errors/FLX-5037.md) until the profiler writes them; [score a run against a profile](docs/how-to/score-a-run-against-a-profile.md) shows a profile written by hand. [Architecture and patterns](docs/explanation/architecture.md) 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](docs/tutorial/README.md): your first evidence pack in five minutes.
- [How-to guides](docs/how-to/README.md): [model your customers](docs/how-to/model-customers.md), [add a journey](docs/how-to/add-a-journey.md), [use the FLUID seam](docs/how-to/use-the-fluid-seam.md), [calibrate from aggregates](docs/how-to/calibrate-from-aggregates.md), [draw a column given another](docs/how-to/draw-a-column-given-another.md), [ship with evidence](docs/how-to/ship-with-evidence.md), [score a run against a profile](docs/how-to/score-a-run-against-a-profile.md), [seal and score a prediction](docs/how-to/seal-and-score-a-prediction.md), [load a simulation into a database](docs/how-to/load-a-simulation-into-a-database.md).
- [Explanation](docs/explanation/README.md): 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](docs/reference/README.md): every command, every error code, the Python API and the schemas.
- The FLUX specification: [Agenticstiger/flux](https://github.com/Agenticstiger/flux).

## Develop

See [CONTRIBUTING.md](CONTRIBUTING.md). The short version:

```text
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](packages/flux-stats/README.md), 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/](docs/adr/README.md), and the specifications in [docs/spec/](docs/spec/README.md).

[The end-to-end harness](e2e/aws/README.md) 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](LICENSE) and [NOTICE](NOTICE). Third-party components are listed in [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md).
