FLUX

Flow Language for Universe eXperimentation

The open, declarative standard for governed synthetic customer universes — the discovery-side sibling of FLUID.

📖 Documentation · 🚀 Quickstart · 🧭 The Nineteen Kinds · 🔗 The FLUID Seam · 🗺️ Roadmap · ✨ What's New

FLUX describes synthetic customer universes: a governed digital twin in which candidate rules and data products are discovered, stress-tested and proven before a single production system is touched. A FLUX universe is assembled from small declarative documents — nineteen kinds across six families — and a Simulation emits its results under a FLUID data-product contract: what is proven in the twin is byte-for-byte the contract that ships.

FLUX discovers.  FLUID delivers.  The seam is where the risk goes to die.

Status

v0.5.0 — working draft. All nine vNext RFCs are shipped additively on the 0.3.0 core — the spec now carries a runtime enforcement contract with conformance vectors and portable, signable evidence bundles alongside the declarative core. Pre-1.0: minor versions may break; every release ships with a schema diff and a regression suite. The design is documented in the position paper "FLUX and FLUID" (distributed separately under CC BY 4.0); where the paper and this schema disagreed, docs/reconciliation.md is the honest ledger.

The nineteen kinds

Every document shares one envelope, aligned with FLUID's:

fluxVersion: "0.5.0"
kind: World
id: q3-retention-world
name: Q3 Retention World
metadata:
  owner:
    team: growth-lab
spec:
  seed: 42
  population:
    size: 25000
    lifecycleMix: { new: 0.15, active: 0.55, atrisk: 0.20, churned: 0.10 }

Any kind may additionally declare agentPolicy (model allow-list, token budget, use-case limits) and skills — the uniform agentic extension point. A skill never changes the shape a kind must satisfy, only the content it emits within those bounds.

The FLUID seam

A Simulation emits streams by referencing the FLUID contract they are proven under — never by restating it:

spec:
  worldRef: q3-retention-world
  emits:
    - productRef: telco.gold.payment_recovery_moment   # a .fluid.yml in the bundle
      exposeId: payment_recovery_moment                # an expose of that product
      fluidVersion: "0.7.5"                            # validated against the vendored FLUID schema

The offline validator resolves the reference, validates the .fluid.yml against the vendored FLUID schema for the pinned version, and asserts the expose exists. Promotion to production is not a re-implementation: the same contract file is wrapped around the real estate.

Validate a bundle

pip install flux-spec
git clone https://github.com/Agenticstiger/flux.git && cd flux    # the worked example lives here
python3 -m flux_spec.validate examples/telco-payment-recovery     # schema + cross-document
python3 -m flux_spec.enforce                                      # RFC-04 conformance vectors
python3 -m flux_spec.bundle pack examples/telco-payment-recovery -o dist/   # RFC-09 evidence bundle

Point the same commands at your own bundle directory; the clone is only for the example.

Two layers, both offline (no cloud, no running engine):

1. Schema — every *.flux.yml against schema/flux-schema-0.5.0.json (JSON Schema 2020-12, closed specs, typed everything).
2. Cross-document — every reference resolves to the right kind (no dangling links), mixes and weights sum to 1, transitions stay inside their taxonomies, skills stay inside their agentPolicy, and the FLUID seam conforms.

Use the schema in your editor:

# yaml-language-server: $schema=https://agenticstiger.github.io/flux/schema/flux-schema-0.5.0.json

As a library

flux_spec is also an installable Python package — the exact code behind scripts/validate.py, scripts/enforce.py and scripts/bundle.py, not a reimplementation; the three scripts are thin shims onto it. It is on PyPI as flux-spec:

pip install flux-spec

from flux_spec.validate import Bundle
from flux_spec.enforce import decide, run_vectors
from flux_spec.bundle import pack, verify

python3 scripts/validate.py ... and python3 -m flux_spec.validate ... behave identically — same for enforce and bundle. The scripts need a clone of this repository; the modules (python3 -m flux_spec.validate, python3 -m flux_spec.enforce and python3 -m flux_spec.bundle) run from the installed package anywhere.

Engine

The FLUX Simulation Engine is the open-source runtime for FLUX bundles. It turns a bundle into synthetic rows that follow the FLUID contract, the same rows every time, with a report that says what the run does not show. It builds on flux-spec.

pip install flux-sim-engine
fluxsim init demo && cd demo && fluxsim run . --verify --ship -o out

The command is fluxsim, and the engine needs Python 3.11 or newer. Documentation: agenticstiger.github.io/flux/engine.

Example

examples/telco-payment-recovery/ is the paper's worked example, complete: all nineteen kinds plus the FLUID contract at the seam, green under CI.

Repository layout

schema/          flux-schema-<version>.json (+ -latest alias) — normative
schema-diffs/    one diff document per version pair
examples/        validated bundles (CI-enforced)
vendor/fluid/    vendored FLUID schemas the seam validates against
flux_spec/       the flux-spec package: validate.py · enforce.py (RFC-04) · bundle.py (RFC-09)
scripts/         validate.py / enforce.py / bundle.py — thin CLI shims onto flux_spec
tests/           regression suite + published enforcement conformance vectors
docs/            documentation site (VuePress): guide, concepts, schema, roadmap, releases,
                 the reconciliation ledger, and engine/ (the engine's own docs, copied
                 from its repository)

Relationship to FLUID

FLUID is the data-product contract standard (MIT, open-data-protocol). FLUX is the experimentation language that emits FLUID contracts. They are separate standards with separate schemas, designed to interlock at exactly one seam. This repo vendors FLUID schemas for offline seam validation; it does not fork or redefine them.

License

Apache License 2.0. The originating position paper is distributed separately under CC BY 4.0 by The FLUX Project.

Contributing

See CONTRIBUTING.md, GOVERNANCE.md and VERSIONING.md. Spec changes travel as one PR touching schema

• diff + examples + tests together.