flux-sim-engine 0.2.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- flux_engine/__init__.py +22 -0
- flux_engine/_links.py +55 -0
- flux_engine/_vendor/__init__.py +5 -0
- flux_engine/_vendor/flux_spec/NOTICE +19 -0
- flux_engine/_vendor/flux_spec/VENDOR-NOTES.md +104 -0
- flux_engine/_vendor/flux_spec/__init__.py +9 -0
- flux_engine/_vendor/flux_spec/bundle.py +410 -0
- flux_engine/_vendor/flux_spec/enforce.py +316 -0
- flux_engine/_vendor/flux_spec/schema/flux-enforcement-0.5.0.json +121 -0
- flux_engine/_vendor/flux_spec/schema/flux-manifest-0.5.0.json +153 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.2.0.json +465 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.3.0.json +876 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.0.json +1601 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.1.json +1668 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-0.5.0.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-schema-latest.json +1669 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.0.json +795 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.1.json +852 -0
- flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.5.0.json +852 -0
- flux_engine/_vendor/flux_spec/validate.py +537 -0
- flux_engine/_vendor/flux_spec/vectors/enforcement-vectors.json +935 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
- flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.5.json +5498 -0
- flux_engine/_vocabulary.py +141 -0
- flux_engine/accuracy/__init__.py +5 -0
- flux_engine/accuracy/_scoring/__init__.py +24 -0
- flux_engine/accuracy/accuracy_record.py +96 -0
- flux_engine/accuracy/policy.py +158 -0
- flux_engine/accuracy/records.py +264 -0
- flux_engine/accuracy/store.py +169 -0
- flux_engine/api/__init__.py +163 -0
- flux_engine/api/accuracy.py +209 -0
- flux_engine/api/agentic.py +134 -0
- flux_engine/api/calibration.py +125 -0
- flux_engine/api/claims.py +93 -0
- flux_engine/api/digests.py +73 -0
- flux_engine/api/emit.py +78 -0
- flux_engine/api/expressions.py +72 -0
- flux_engine/api/fidelity.py +110 -0
- flux_engine/api/lineage.py +78 -0
- flux_engine/api/stages.py +242 -0
- flux_engine/api/verdict.py +108 -0
- flux_engine/calibrate/__init__.py +5 -0
- flux_engine/calibrate/declared.py +253 -0
- flux_engine/calibrate/provenance.py +113 -0
- flux_engine/cli/__init__.py +2146 -0
- flux_engine/cli/__main__.py +17 -0
- flux_engine/cli/_documents.py +226 -0
- flux_engine/cli/_hints.py +118 -0
- flux_engine/cli/_init.py +152 -0
- flux_engine/cli/_progress.py +124 -0
- flux_engine/concordance/__init__.py +127 -0
- flux_engine/concordance/boundary/__init__.py +78 -0
- flux_engine/concordance/boundary/merkle.py +287 -0
- flux_engine/concordance/boundary/slice.py +429 -0
- flux_engine/concordance/boundary/statistic.py +561 -0
- flux_engine/concordance/boundary/store.py +334 -0
- flux_engine/concordance/boundary/vault.py +357 -0
- flux_engine/concordance/compiler.py +542 -0
- flux_engine/concordance/errors.py +189 -0
- flux_engine/concordance/gate.py +525 -0
- flux_engine/concordance/predicate.py +1217 -0
- flux_engine/concordance/record.py +554 -0
- flux_engine/concordance/verifier.py +583 -0
- flux_engine/core/__init__.py +5 -0
- flux_engine/core/artifact.py +99 -0
- flux_engine/core/canonical.py +369 -0
- flux_engine/core/clock.py +437 -0
- flux_engine/core/digest.py +288 -0
- flux_engine/core/errors.py +277 -0
- flux_engine/core/fixedpoint.py +929 -0
- flux_engine/core/lrm.py +158 -0
- flux_engine/core/rng.py +736 -0
- flux_engine/core/seedtree.py +891 -0
- flux_engine/core/trace.py +423 -0
- flux_engine/describe.py +207 -0
- flux_engine/engine.py +257 -0
- flux_engine/evidence/__init__.py +5 -0
- flux_engine/evidence/pack.py +411 -0
- flux_engine/evidence/report.py +243 -0
- flux_engine/expr/__init__.py +133 -0
- flux_engine/expr/ast.py +312 -0
- flux_engine/expr/attrs.py +386 -0
- flux_engine/expr/check.py +278 -0
- flux_engine/expr/compile.py +322 -0
- flux_engine/expr/errors.py +256 -0
- flux_engine/expr/lexer.py +297 -0
- flux_engine/expr/parser.py +313 -0
- flux_engine/expr/types.py +177 -0
- flux_engine/generator/__init__.py +97 -0
- flux_engine/generator/families.py +325 -0
- flux_engine/generator/paths.py +227 -0
- flux_engine/generator/rows.py +918 -0
- flux_engine/generator/statistics.py +524 -0
- flux_engine/governance/__init__.py +87 -0
- flux_engine/governance/audit.py +307 -0
- flux_engine/governance/gate.py +334 -0
- flux_engine/governance/skills.py +220 -0
- flux_engine/governance/sovereignty.py +251 -0
- flux_engine/lineage/__init__.py +5 -0
- flux_engine/lineage/emitter.py +398 -0
- flux_engine/py.typed +0 -0
- flux_engine/runtime/__init__.py +153 -0
- flux_engine/runtime/campaign.py +407 -0
- flux_engine/runtime/cast.py +283 -0
- flux_engine/runtime/detector.py +222 -0
- flux_engine/runtime/errors.py +58 -0
- flux_engine/runtime/experiment.py +311 -0
- flux_engine/runtime/journey.py +383 -0
- flux_engine/runtime/jurisdiction.py +72 -0
- flux_engine/runtime/payloads.py +124 -0
- flux_engine/runtime/signals.py +334 -0
- flux_engine/runtime/temperature.py +156 -0
- flux_engine/seam/__init__.py +5 -0
- flux_engine/seam/attest.py +290 -0
- flux_engine/seam/conform.py +448 -0
- flux_engine/seam/contract.py +605 -0
- flux_engine/seam/emit.py +488 -0
- flux_engine/seam/mapping.py +299 -0
- flux_engine/seam/resolve.py +1087 -0
- flux_engine/seam/sinks.py +157 -0
- flux_engine/spec/__init__.py +134 -0
- flux_engine/spec/bundle.py +25 -0
- flux_engine/spec/enforce.py +31 -0
- flux_engine/spec/validate.py +28 -0
- flux_engine/stages/__init__.py +30 -0
- flux_engine/stages/apply.py +447 -0
- flux_engine/stages/errors.py +315 -0
- flux_engine/stages/layout.py +292 -0
- flux_engine/stages/pipeline.py +600 -0
- flux_engine/stages/plan.py +241 -0
- flux_engine/stages/replay.py +83 -0
- flux_engine/stages/run.py +208 -0
- flux_engine/stages/ship.py +934 -0
- flux_engine/stages/validate.py +93 -0
- flux_engine/stages/verify.py +1129 -0
- flux_engine/starter/__init__.py +161 -0
- flux_engine/starter/bundle/detector.flux.yml +15 -0
- flux_engine/starter/bundle/journey.flux.yml +23 -0
- flux_engine/starter/bundle/module.flux.yml +16 -0
- flux_engine/starter/bundle/payment-recovery.fluid.yml +30 -0
- flux_engine/starter/bundle/persona.flux.yml +26 -0
- flux_engine/starter/bundle/signal.flux.yml +13 -0
- flux_engine/starter/bundle/simulation.flux.yml +29 -0
- flux_engine/starter/bundle/taxonomy.flux.yml +17 -0
- flux_engine/starter/bundle/treatment.flux.yml +13 -0
- flux_engine/starter/bundle/world.flux.yml +20 -0
- flux_engine/verticals/__init__.py +85 -0
- flux_engine/verticals/telco.py +89 -0
- flux_engine/world/__init__.py +89 -0
- flux_engine/world/derived.py +195 -0
- flux_engine/world/errors.py +41 -0
- flux_engine/world/families.py +260 -0
- flux_engine/world/population.py +602 -0
- flux_engine/world/tracing.py +66 -0
- flux_engine/world/values.py +121 -0
- flux_sim_engine-0.2.0.dist-info/METADATA +108 -0
- flux_sim_engine-0.2.0.dist-info/RECORD +165 -0
- flux_sim_engine-0.2.0.dist-info/WHEEL +5 -0
- flux_sim_engine-0.2.0.dist-info/entry_points.txt +2 -0
- flux_sim_engine-0.2.0.dist-info/licenses/LICENSE +202 -0
- flux_sim_engine-0.2.0.dist-info/licenses/NOTICE +10 -0
- flux_sim_engine-0.2.0.dist-info/licenses/flux_engine/_vendor/flux_spec/NOTICE +19 -0
- flux_sim_engine-0.2.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""The starter project ``fluxsim init`` writes: a small FLUX bundle and its FLUID contract.
|
|
6
|
+
|
|
7
|
+
The bundle lives in ``flux_engine/starter/bundle/`` as package data. It is read
|
|
8
|
+
through :mod:`importlib.resources`, so it works from a wheel, an editable
|
|
9
|
+
install and a zip import alike, and it is copied byte for byte: a bundle's
|
|
10
|
+
digests are taken over its bytes, so a newline translated on the way out would
|
|
11
|
+
give every user a different ``inputDigest`` for the same project.
|
|
12
|
+
|
|
13
|
+
Only specification documents belong in that directory. A bundle directory
|
|
14
|
+
holds ``*.flux.yml``, ``*.fluid.yml``, ``flux.lock`` and the evidence
|
|
15
|
+
manifest, and nothing else (``FLX-3108``). That is why the starter carries no
|
|
16
|
+
README, no ``.gitignore`` and no Python file: the next steps are printed by
|
|
17
|
+
the command instead (:mod:`flux_engine.cli._init`).
|
|
18
|
+
|
|
19
|
+
The one rule when editing a starter file: a pinned test
|
|
20
|
+
(``tests/starter/test_starter_bundle.py``) holds the ``runDigest`` the bundle
|
|
21
|
+
produces, so a change here moves it on purpose, with the new value written
|
|
22
|
+
into that test in the same commit.
|
|
23
|
+
"""
|
|
24
|
+
|
|
25
|
+
from __future__ import annotations
|
|
26
|
+
|
|
27
|
+
from dataclasses import dataclass
|
|
28
|
+
from importlib import resources
|
|
29
|
+
from pathlib import Path
|
|
30
|
+
from typing import Dict, List, Tuple
|
|
31
|
+
|
|
32
|
+
__all__ = ["PURPOSES", "ScaffoldError", "StarterFile", "scaffold", "starter_files"]
|
|
33
|
+
|
|
34
|
+
_PACKAGE = "flux_engine.starter"
|
|
35
|
+
_BUNDLE_DIR = "bundle"
|
|
36
|
+
|
|
37
|
+
#: One line per starter file, said in the order a reader meets them. The test
|
|
38
|
+
#: suite holds this equal to the files actually shipped, so a file added to the
|
|
39
|
+
#: bundle without a line here (or the reverse) fails a test rather than printing
|
|
40
|
+
#: a blank description to the first person who runs ``fluxsim init``.
|
|
41
|
+
PURPOSES: Dict[str, str] = {
|
|
42
|
+
"simulation.flux.yml": "the run: seed, time window, and the contract it emits rows for",
|
|
43
|
+
"world.flux.yml": "the population: size, lifecycle mix, sovereignty",
|
|
44
|
+
"persona.flux.yml": "a kind of customer: traits and their distributions",
|
|
45
|
+
"signal.flux.yml": "an event the world produces: a payment is aborted",
|
|
46
|
+
"detector.flux.yml": "a pattern over signals; each firing is one row",
|
|
47
|
+
"journey.flux.yml": "what the business does about it, and how customers react",
|
|
48
|
+
"taxonomy.flux.yml": "the lifecycle states a journey may move a customer between",
|
|
49
|
+
"treatment.flux.yml": "the action a journey takes: a one-tap payment link",
|
|
50
|
+
"module.flux.yml": "bundles the signal, detector and journey into one swappable unit",
|
|
51
|
+
"payment-recovery.fluid.yml": "the FLUID contract the rows are emitted for",
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
#: How many of the names found in a refused directory the message lists.
|
|
55
|
+
_LISTED_ENTRIES = 3
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class ScaffoldError(Exception):
|
|
59
|
+
"""The directory cannot be scaffolded: it is not usable, or a write failed."""
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@dataclass(frozen=True)
|
|
63
|
+
class StarterFile:
|
|
64
|
+
"""One file of the starter bundle: its name, what it is for, its exact bytes."""
|
|
65
|
+
|
|
66
|
+
name: str
|
|
67
|
+
purpose: str
|
|
68
|
+
data: bytes
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
def starter_files() -> Tuple[StarterFile, ...]:
|
|
72
|
+
"""Every file of the starter bundle, in the order of :data:`PURPOSES`.
|
|
73
|
+
|
|
74
|
+
That is the order a reader meets them in. A file with no entry there sorts
|
|
75
|
+
after the rest, by name.
|
|
76
|
+
"""
|
|
77
|
+
root = resources.files(_PACKAGE).joinpath(_BUNDLE_DIR)
|
|
78
|
+
rank = {name: position for position, name in enumerate(PURPOSES)}
|
|
79
|
+
entries = sorted(
|
|
80
|
+
(entry for entry in root.iterdir() if entry.is_file()),
|
|
81
|
+
key=lambda e: (rank.get(e.name, len(rank)), e.name),
|
|
82
|
+
)
|
|
83
|
+
return tuple(
|
|
84
|
+
StarterFile(name=e.name, purpose=PURPOSES.get(e.name, ""), data=e.read_bytes())
|
|
85
|
+
for e in entries
|
|
86
|
+
)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _check_usable(target: Path) -> List[Path]:
|
|
90
|
+
"""Refuse an unusable *target*; return the directories that do not exist yet.
|
|
91
|
+
|
|
92
|
+
The returned list runs from *target* upward to the first existing parent, so
|
|
93
|
+
that a failed scaffold can remove exactly the directories it created.
|
|
94
|
+
"""
|
|
95
|
+
if target.is_symlink() and not target.exists():
|
|
96
|
+
raise ScaffoldError(f"{target} is a symbolic link to nothing")
|
|
97
|
+
if target.exists():
|
|
98
|
+
if not target.is_dir():
|
|
99
|
+
raise ScaffoldError(f"{target} exists and is not a directory")
|
|
100
|
+
held = sorted(entry.name for entry in target.iterdir())
|
|
101
|
+
if held:
|
|
102
|
+
shown = ", ".join(held[:_LISTED_ENTRIES]) + (
|
|
103
|
+
", ..." if len(held) > _LISTED_ENTRIES else ""
|
|
104
|
+
)
|
|
105
|
+
raise ScaffoldError(
|
|
106
|
+
f"{target} is not empty (it holds {shown}), and `fluxsim init` never overwrites "
|
|
107
|
+
"anything; give it a directory that does not exist yet, or an empty one"
|
|
108
|
+
)
|
|
109
|
+
return []
|
|
110
|
+
missing: List[Path] = []
|
|
111
|
+
here = target
|
|
112
|
+
while not here.exists() and here != here.parent:
|
|
113
|
+
missing.append(here)
|
|
114
|
+
here = here.parent
|
|
115
|
+
return missing
|
|
116
|
+
|
|
117
|
+
|
|
118
|
+
def scaffold(directory: Path) -> Tuple[str, ...]:
|
|
119
|
+
"""Write the starter bundle into *directory* and return the names written.
|
|
120
|
+
|
|
121
|
+
*directory* may be missing (it is created, parents included) or an empty
|
|
122
|
+
directory. A directory that holds anything, a path that is a file, and a
|
|
123
|
+
link to nothing are refused with a :class:`ScaffoldError` before a byte is
|
|
124
|
+
written. Every file is created exclusively (``O_EXCL``), so nothing that
|
|
125
|
+
appears in the directory between the check and the write can be overwritten
|
|
126
|
+
or written through, a symbolic link included. If a write fails part way,
|
|
127
|
+
every file this call created, the partly written one included, is removed,
|
|
128
|
+
and so is each directory it created.
|
|
129
|
+
"""
|
|
130
|
+
target = Path(directory)
|
|
131
|
+
try:
|
|
132
|
+
to_create = _check_usable(target)
|
|
133
|
+
except OSError as error:
|
|
134
|
+
raise ScaffoldError(f"cannot use {target}: {error.strerror or error}") from error
|
|
135
|
+
|
|
136
|
+
written: List[Path] = []
|
|
137
|
+
try:
|
|
138
|
+
if to_create:
|
|
139
|
+
target.mkdir(parents=True)
|
|
140
|
+
for entry in starter_files():
|
|
141
|
+
path = target / entry.name
|
|
142
|
+
handle = path.open("xb")
|
|
143
|
+
# From here the file is ours, even if the write below fails halfway.
|
|
144
|
+
written.append(path)
|
|
145
|
+
with handle:
|
|
146
|
+
handle.write(entry.data)
|
|
147
|
+
except OSError as error:
|
|
148
|
+
for path in written:
|
|
149
|
+
path.unlink(missing_ok=True)
|
|
150
|
+
for created in to_create:
|
|
151
|
+
try:
|
|
152
|
+
created.rmdir()
|
|
153
|
+
except OSError:
|
|
154
|
+
# Not there (mkdir failed before reaching it) or not empty (someone
|
|
155
|
+
# else wrote into it meanwhile): leave it, and try the next one up.
|
|
156
|
+
continue
|
|
157
|
+
raise ScaffoldError(
|
|
158
|
+
f"could not write into {target}: {error.strerror or error}; "
|
|
159
|
+
"what was written so far was removed"
|
|
160
|
+
) from error
|
|
161
|
+
return tuple(path.name for path in written)
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# A pattern over signals. This one fires when two payments are aborted within
|
|
2
|
+
# fifteen minutes (900000 ms) of each other. Each firing is one row of the
|
|
3
|
+
# emitted stream.
|
|
4
|
+
fluxVersion: "0.5.0"
|
|
5
|
+
kind: Detector
|
|
6
|
+
id: det-payment-aborted-burst
|
|
7
|
+
name: Aborted Payment Burst Detector
|
|
8
|
+
metadata:
|
|
9
|
+
owner:
|
|
10
|
+
team: growth-lab
|
|
11
|
+
spec:
|
|
12
|
+
timeWindowMs: 900000
|
|
13
|
+
pattern:
|
|
14
|
+
- { signalRef: sig-payment-aborted, predicate: "amount > 0" }
|
|
15
|
+
- { signalRef: sig-payment-aborted }
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# What the business does when the signal arrives, and how each persona reacts:
|
|
2
|
+
# the intervention, the chance it works, and the lifecycle state the customer
|
|
3
|
+
# moves to afterwards.
|
|
4
|
+
fluxVersion: "0.5.0"
|
|
5
|
+
kind: Journey
|
|
6
|
+
id: jr-payment-recovery
|
|
7
|
+
name: Payment Recovery Journey
|
|
8
|
+
metadata:
|
|
9
|
+
owner:
|
|
10
|
+
team: growth-lab
|
|
11
|
+
spec:
|
|
12
|
+
trigger:
|
|
13
|
+
signalRef: sig-payment-aborted
|
|
14
|
+
condition: "attempts >= 2"
|
|
15
|
+
intervention:
|
|
16
|
+
treatmentRef: tr-fast-recovery
|
|
17
|
+
action: offer_payment_link
|
|
18
|
+
taxonomyRef: jt-subscriber-lifecycle
|
|
19
|
+
personaReactions:
|
|
20
|
+
persona-pragmatic-family:
|
|
21
|
+
successProbability: 0.42
|
|
22
|
+
outcome: payment_completed
|
|
23
|
+
nextState: active
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# A module bundles related documents so they can be swapped as one unit, and
|
|
2
|
+
# declares which ports it binds. It is the only way a journey or a detector
|
|
3
|
+
# gets into a run.
|
|
4
|
+
fluxVersion: "0.5.0"
|
|
5
|
+
kind: Module
|
|
6
|
+
id: module-payment-recovery
|
|
7
|
+
name: Payment Recovery Module
|
|
8
|
+
version: 2.1.3
|
|
9
|
+
metadata:
|
|
10
|
+
owner:
|
|
11
|
+
team: growth-lab
|
|
12
|
+
spec:
|
|
13
|
+
resources: [sig-payment-aborted, det-payment-aborted-burst, jr-payment-recovery]
|
|
14
|
+
binds:
|
|
15
|
+
- { port: event-envelope, config: { spec: cloudevents/1.0 } }
|
|
16
|
+
- { port: fluid-contract }
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# The FLUID contract the simulation emits rows for. FLUX refers to it and never
|
|
2
|
+
# restates it, so the thing that ships is the thing that was checked.
|
|
3
|
+
fluidVersion: "0.7.5"
|
|
4
|
+
kind: DataProduct
|
|
5
|
+
id: telco.gold.payment_recovery_moment
|
|
6
|
+
name: Payment Recovery Moment
|
|
7
|
+
metadata:
|
|
8
|
+
owner:
|
|
9
|
+
team: growth-lab
|
|
10
|
+
exposes:
|
|
11
|
+
- exposeId: payment_recovery_moment
|
|
12
|
+
kind: stream
|
|
13
|
+
contract:
|
|
14
|
+
schema:
|
|
15
|
+
- name: subscriber_id
|
|
16
|
+
type: STRING
|
|
17
|
+
required: true
|
|
18
|
+
tags: [identifier]
|
|
19
|
+
- name: aborted_at
|
|
20
|
+
type: TIMESTAMP
|
|
21
|
+
required: true
|
|
22
|
+
- name: amount
|
|
23
|
+
type: "DECIMAL(18,4)"
|
|
24
|
+
- name: market
|
|
25
|
+
type: STRING
|
|
26
|
+
binding:
|
|
27
|
+
platform: kafka
|
|
28
|
+
format: kafka_topic
|
|
29
|
+
location:
|
|
30
|
+
topic: billing.payment-recovery.v1
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# A kind of customer. Traits are either a single number or a distribution the
|
|
2
|
+
# engine draws from, one value per simulated customer.
|
|
3
|
+
fluxVersion: "0.5.0"
|
|
4
|
+
kind: Persona
|
|
5
|
+
id: persona-pragmatic-family
|
|
6
|
+
name: Pragmatic Family Subscriber
|
|
7
|
+
metadata:
|
|
8
|
+
owner:
|
|
9
|
+
team: growth-lab
|
|
10
|
+
spec:
|
|
11
|
+
demographics: { ageBand: "35-44", household: family }
|
|
12
|
+
traits:
|
|
13
|
+
digitalFluency: 0.6
|
|
14
|
+
financialLiteracy: 0.4
|
|
15
|
+
priceSensitivity:
|
|
16
|
+
dist: categorical
|
|
17
|
+
levels: { low: 0.2, medium: 0.5, high: 0.3 }
|
|
18
|
+
monthlySpend:
|
|
19
|
+
dist: normal
|
|
20
|
+
mean: 42.0
|
|
21
|
+
stddev: 11.0
|
|
22
|
+
min: 0
|
|
23
|
+
worldview:
|
|
24
|
+
riskTolerance: low
|
|
25
|
+
trustInInstitutions: 0.55
|
|
26
|
+
trendFollowing: 0.3
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# An event the world produces, shaped as a CloudEvents 1.0 envelope.
|
|
2
|
+
fluxVersion: "0.5.0"
|
|
3
|
+
kind: Signal
|
|
4
|
+
id: sig-payment-aborted
|
|
5
|
+
name: Payment Aborted Signal
|
|
6
|
+
metadata:
|
|
7
|
+
owner:
|
|
8
|
+
team: growth-lab
|
|
9
|
+
spec:
|
|
10
|
+
envelope: cloudevents/1.0
|
|
11
|
+
source: "urn:flux:billing-gateway"
|
|
12
|
+
type: com.telco.payment.aborted
|
|
13
|
+
dataschema: https://example.com/schemas/payment-aborted.json
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
# The root document. One Simulation describes one run: which world, which
|
|
2
|
+
# people, which behaviour, and which FLUID contract the rows are emitted for.
|
|
3
|
+
fluxVersion: "0.5.0"
|
|
4
|
+
kind: Simulation
|
|
5
|
+
id: sim-payment-recovery
|
|
6
|
+
name: Payment Recovery Simulation
|
|
7
|
+
metadata:
|
|
8
|
+
owner:
|
|
9
|
+
team: growth-lab
|
|
10
|
+
spec:
|
|
11
|
+
worldRef: q3-retention-world
|
|
12
|
+
fidelity: deterministic # same bundle and seed, same bytes, on any machine
|
|
13
|
+
seed: 42
|
|
14
|
+
timeBounds:
|
|
15
|
+
start: "2026-07-01T00:00:00Z"
|
|
16
|
+
end: "2026-09-30T23:59:59Z"
|
|
17
|
+
personaRefs: [persona-pragmatic-family]
|
|
18
|
+
signalRefs: [sig-payment-aborted]
|
|
19
|
+
# Journeys and detectors reach a run only through a module's resources.
|
|
20
|
+
moduleRefs: [module-payment-recovery]
|
|
21
|
+
emits:
|
|
22
|
+
- productRef: telco.gold.payment_recovery_moment
|
|
23
|
+
exposeId: payment_recovery_moment
|
|
24
|
+
fluidVersion: "^0.7.3"
|
|
25
|
+
provenance:
|
|
26
|
+
# The digest of payment-recovery.fluid.yml. The engine refuses to run when the
|
|
27
|
+
# contract moves away from the one this simulation was written against, and
|
|
28
|
+
# prints the new digest so you can copy it in on purpose.
|
|
29
|
+
contractDigest: "sha256:b9b5ee575a8b313f6f72d039653d8be5d76e7ecc0012d7bd6ad2d37e0e60435d"
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# The lifecycle states a customer can be in, and the moves between them that a
|
|
2
|
+
# journey is allowed to make. A journey that moves a customer anywhere else is
|
|
3
|
+
# refused (FLX-2302).
|
|
4
|
+
fluxVersion: "0.5.0"
|
|
5
|
+
kind: JourneyTaxonomy
|
|
6
|
+
id: jt-subscriber-lifecycle
|
|
7
|
+
name: Subscriber Lifecycle Taxonomy
|
|
8
|
+
metadata:
|
|
9
|
+
owner:
|
|
10
|
+
team: growth-lab
|
|
11
|
+
spec:
|
|
12
|
+
states: [new, active, atrisk, churned]
|
|
13
|
+
transitions:
|
|
14
|
+
- { from: new, to: active }
|
|
15
|
+
- { from: active, to: atrisk }
|
|
16
|
+
- { from: atrisk, to: active }
|
|
17
|
+
- { from: atrisk, to: churned }
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# The action a journey takes: here, a one-tap payment link that expires in 48 hours.
|
|
2
|
+
fluxVersion: "0.5.0"
|
|
3
|
+
kind: Treatment
|
|
4
|
+
id: tr-fast-recovery
|
|
5
|
+
name: Fast Payment Recovery Link
|
|
6
|
+
metadata:
|
|
7
|
+
owner:
|
|
8
|
+
team: growth-lab
|
|
9
|
+
spec:
|
|
10
|
+
actionType: payment_recovery_link
|
|
11
|
+
payloadTemplate:
|
|
12
|
+
message: "Complete your payment in one tap"
|
|
13
|
+
ttlHours: 48
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# The population: how many customers, in which lifecycle state, under which
|
|
2
|
+
# sovereignty rules. Everything drawn from here is seeded, never random.
|
|
3
|
+
fluxVersion: "0.5.0"
|
|
4
|
+
kind: World
|
|
5
|
+
id: q3-retention-world
|
|
6
|
+
name: Q3 Retention World
|
|
7
|
+
metadata:
|
|
8
|
+
owner:
|
|
9
|
+
team: growth-lab
|
|
10
|
+
spec:
|
|
11
|
+
seed: 42
|
|
12
|
+
vertical: telco
|
|
13
|
+
sovereignty:
|
|
14
|
+
allowedZones: [eu-west, eu-central]
|
|
15
|
+
enforcement: block
|
|
16
|
+
population:
|
|
17
|
+
size: 500
|
|
18
|
+
lifecycleMix: { new: 0.15, active: 0.55, atrisk: 0.20, churned: 0.10 }
|
|
19
|
+
markets: [mkt-a, mkt-b, mkt-c]
|
|
20
|
+
temperature: { engagement: 0.5, campaignResponse: 0.5 }
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""Vertical attribute packs keyed by ``World.spec.vertical`` (v0.1 stopgap).
|
|
6
|
+
|
|
7
|
+
EXPR-SPEC §3 sources the vertical slice of the attribute model from
|
|
8
|
+
``World.spec.vertical`` -> ``verticals/<pack>.py``, and marks it explicitly as
|
|
9
|
+
a "v0.1 stopgap; FLUX 0.6 RFC moves the declaration into the spec". A pack
|
|
10
|
+
therefore declares **types only** -- no values, no rates, no sampling -- so
|
|
11
|
+
that moving the declaration into a FLUX document later changes where the
|
|
12
|
+
names come from and nothing about what they mean.
|
|
13
|
+
|
|
14
|
+
A pack is looked up by the string in ``World.spec.vertical``::
|
|
15
|
+
|
|
16
|
+
from flux_engine.verticals import get_pack
|
|
17
|
+
|
|
18
|
+
pack = get_pack(world["spec"]["vertical"])
|
|
19
|
+
|
|
20
|
+
The registry is closed at import time and keyed by NFC-normalised name, so the
|
|
21
|
+
lookup is deterministic and an unknown vertical fails by name.
|
|
22
|
+
"""
|
|
23
|
+
|
|
24
|
+
from __future__ import annotations
|
|
25
|
+
|
|
26
|
+
from typing import Mapping, Tuple
|
|
27
|
+
|
|
28
|
+
from flux_engine.expr.attrs import VerticalPack
|
|
29
|
+
from flux_engine.expr.types import nfc
|
|
30
|
+
from flux_engine.verticals.telco import TELCO, TELCO_EMIT_ALIASES
|
|
31
|
+
|
|
32
|
+
__all__ = [
|
|
33
|
+
"EMIT_ALIASES",
|
|
34
|
+
"PACKS",
|
|
35
|
+
"VerticalPack",
|
|
36
|
+
"emit_aliases",
|
|
37
|
+
"get_pack",
|
|
38
|
+
"pack_names",
|
|
39
|
+
]
|
|
40
|
+
|
|
41
|
+
#: Every pack this engine ships, keyed by the ``World.spec.vertical`` string.
|
|
42
|
+
PACKS: Mapping[str, VerticalPack] = {TELCO.name: TELCO}
|
|
43
|
+
|
|
44
|
+
#: Per-vertical expose-column aliases -- step 2 of
|
|
45
|
+
#: :func:`flux_engine.seam.mapping.resolve_column_mapping`. Kept beside the
|
|
46
|
+
#: packs rather than inside :class:`~flux_engine.expr.attrs.VerticalPack`
|
|
47
|
+
#: because a pack is EXPR-SPEC §3's attribute-model slice (what an
|
|
48
|
+
#: expression may name) and an alias is a seam concern (which declared
|
|
49
|
+
#: column a runtime attribute fills). Two questions, two tables, one
|
|
50
|
+
#: registry.
|
|
51
|
+
EMIT_ALIASES: Mapping[str, Mapping[str, str]] = {TELCO.name: TELCO_EMIT_ALIASES}
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def pack_names() -> Tuple[str, ...]:
|
|
55
|
+
"""Return the registered vertical names, sorted."""
|
|
56
|
+
return tuple(sorted(PACKS))
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def get_pack(name: str) -> VerticalPack:
|
|
60
|
+
"""Return the pack named by ``World.spec.vertical``.
|
|
61
|
+
|
|
62
|
+
Raises ``KeyError`` naming the known packs when *name* is not one of them:
|
|
63
|
+
a missing pack would silently strip the vertical attributes out of the
|
|
64
|
+
subject scope and turn every reference to one into ``FLX-6004``, which is
|
|
65
|
+
a confusing failure a long way from its cause.
|
|
66
|
+
"""
|
|
67
|
+
key = nfc(name)
|
|
68
|
+
if key not in PACKS:
|
|
69
|
+
raise KeyError(f"unknown vertical {name!r}; this engine ships {', '.join(pack_names())}")
|
|
70
|
+
return PACKS[key]
|
|
71
|
+
|
|
72
|
+
|
|
73
|
+
def emit_aliases(name: str) -> Mapping[str, str]:
|
|
74
|
+
"""Return the expose-column alias table for vertical *name*.
|
|
75
|
+
|
|
76
|
+
Empty for a registered vertical that declares none: an alias table is
|
|
77
|
+
a convenience, and a vertical whose contracts name their columns the
|
|
78
|
+
way the runtime names its attributes needs no entries. Raises
|
|
79
|
+
``KeyError`` for an unregistered vertical, the same way
|
|
80
|
+
:func:`get_pack` does -- one lookup rule for both tables.
|
|
81
|
+
"""
|
|
82
|
+
key = nfc(name)
|
|
83
|
+
if key not in PACKS:
|
|
84
|
+
raise KeyError(f"unknown vertical {name!r}; this engine ships {', '.join(pack_names())}")
|
|
85
|
+
return EMIT_ALIASES.get(key, {})
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""The ``telco`` vertical pack (EXPR-SPEC §3).
|
|
6
|
+
|
|
7
|
+
Every name here is quoted from EXPR-SPEC §3 and matches the shipped telco
|
|
8
|
+
example bundle (``examples/telco-payment-recovery`` in the FLUX spec repo),
|
|
9
|
+
whose ``World.spec.vertical`` is ``telco``:
|
|
10
|
+
|
|
11
|
+
* subject attributes -- "telco: ``products: set<string>``, ``tenureMonths:
|
|
12
|
+
number``, ``latePaymentCount: number``, ``arpu: number``". These are what
|
|
13
|
+
``seg-atrisk-tv``'s query (``lifecycle == 'atrisk' && products.has('tv')``)
|
|
14
|
+
resolves against.
|
|
15
|
+
* signal attributes -- "telco ``sig-payment-aborted``: ``amount: number``,
|
|
16
|
+
``attempts: number``, ``channel: string``". The Signal declares a
|
|
17
|
+
``dataschema`` URI that is not resolvable offline, so the pack is what types
|
|
18
|
+
``det-payment-aborted-burst``'s ``amount > 0`` and
|
|
19
|
+
``jr-payment-recovery``'s ``attempts >= 2``.
|
|
20
|
+
* observed features -- "telco: ``late_payment_count: number``,
|
|
21
|
+
``tenure_months: number``, ``arpu: number``". These type
|
|
22
|
+
``pb-billing-history``'s ``late_payment_count >= 2``.
|
|
23
|
+
|
|
24
|
+
Types only: a pack never carries a value, a rate or a distribution, so nothing
|
|
25
|
+
in this module can put a number into a hashed document.
|
|
26
|
+
"""
|
|
27
|
+
|
|
28
|
+
from __future__ import annotations
|
|
29
|
+
|
|
30
|
+
from typing import Mapping
|
|
31
|
+
|
|
32
|
+
from flux_engine.expr.attrs import VerticalPack
|
|
33
|
+
from flux_engine.expr.types import NUMBER, SET_STRING, STRING, Type
|
|
34
|
+
|
|
35
|
+
__all__ = ["TELCO", "TELCO_EMIT_ALIASES"]
|
|
36
|
+
|
|
37
|
+
#: EXPR-SPEC §3, ``subject`` scope, vertical-pack row.
|
|
38
|
+
_SUBJECT: Mapping[str, Type] = {
|
|
39
|
+
"products": SET_STRING,
|
|
40
|
+
"tenureMonths": NUMBER,
|
|
41
|
+
"latePaymentCount": NUMBER,
|
|
42
|
+
"arpu": NUMBER,
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
#: EXPR-SPEC §3, ``event`` scope: the payload fields of ``sig-payment-aborted``,
|
|
46
|
+
#: addressed as ``data.<field>`` with the bare spelling as sugar.
|
|
47
|
+
_SIGNALS: Mapping[str, Mapping[str, Type]] = {
|
|
48
|
+
"sig-payment-aborted": {
|
|
49
|
+
"amount": NUMBER,
|
|
50
|
+
"attempts": NUMBER,
|
|
51
|
+
"channel": STRING,
|
|
52
|
+
},
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
#: EXPR-SPEC §3, ``observed`` scope: "Aggregate features per observed subject
|
|
56
|
+
#: computed by the ingest step ... Never raw records."
|
|
57
|
+
_OBSERVED: Mapping[str, Type] = {
|
|
58
|
+
"late_payment_count": NUMBER,
|
|
59
|
+
"tenure_months": NUMBER,
|
|
60
|
+
"arpu": NUMBER,
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
#: Expose-column -> runtime-attribute aliases for this vertical, step 2 of
|
|
64
|
+
#: :func:`flux_engine.seam.mapping.resolve_column_mapping`.
|
|
65
|
+
#:
|
|
66
|
+
#: Every entry is a column whose contract name and whose runtime name
|
|
67
|
+
#: differ, so the by-name step (step 3) cannot reach it: a
|
|
68
|
+
#: ``payment_recovery_moment`` row calls the subject's identifier
|
|
69
|
+
#: ``subscriber_id`` and the moment's instant ``aborted_at``, and neither
|
|
70
|
+
#: name exists in any runtime scope. ``amount`` and ``market`` *would*
|
|
71
|
+
#: resolve by name -- they are listed anyway so the whole of the shipped
|
|
72
|
+
#: contract's row is declared in one place a reader can check against the
|
|
73
|
+
#: contract, rather than half declared here and half inferred.
|
|
74
|
+
#:
|
|
75
|
+
#: Types only, as everywhere else in a pack: an alias names a source, never
|
|
76
|
+
#: a value, a rate or a default.
|
|
77
|
+
TELCO_EMIT_ALIASES: Mapping[str, str] = {
|
|
78
|
+
"subscriber_id": "subject.id",
|
|
79
|
+
"aborted_at": "event.time",
|
|
80
|
+
"amount": "event.data.amount",
|
|
81
|
+
"market": "subject.market",
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
TELCO = VerticalPack(
|
|
85
|
+
name="telco",
|
|
86
|
+
subject_attributes=_SUBJECT,
|
|
87
|
+
signal_attributes=_SIGNALS,
|
|
88
|
+
observed_features=_OBSERVED,
|
|
89
|
+
)
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Copyright 2026 Agentics Transformation Limited
|
|
2
|
+
#
|
|
3
|
+
# SPDX-License-Identifier: Apache-2.0
|
|
4
|
+
|
|
5
|
+
"""Population materialisation: cohorts, markets, trait sampling, derived attributes.
|
|
6
|
+
|
|
7
|
+
The entry point is :func:`materialise_population`, which turns a schema-valid
|
|
8
|
+
``World`` plus the Simulation's ``Persona`` documents into a
|
|
9
|
+
:class:`SubjectStore` -- a columnar population iterated by ordinal -- while
|
|
10
|
+
appending the ``cohort`` / ``market`` / ``trait`` ops of KERNEL-SPEC §10 to a
|
|
11
|
+
:class:`~flux_engine.world.tracing.TraceLog`::
|
|
12
|
+
|
|
13
|
+
from flux_engine.core.seedtree import SeedTree, derive_root
|
|
14
|
+
from flux_engine.verticals import get_pack
|
|
15
|
+
from flux_engine.world import TraceLog, materialise_population
|
|
16
|
+
|
|
17
|
+
trace = TraceLog()
|
|
18
|
+
tree = SeedTree(root=derive_root(seam_bytes, effective_seed))
|
|
19
|
+
store = materialise_population(
|
|
20
|
+
world=world_doc, personas=[persona_doc], pack=get_pack("telco"),
|
|
21
|
+
seed_tree=tree, trace=trace,
|
|
22
|
+
)
|
|
23
|
+
store.cohort_counts() # LRM of World.spec.population.lifecycleMix
|
|
24
|
+
trace.component_digests()["population"]
|
|
25
|
+
|
|
26
|
+
The shapes the values are drawn from live in :mod:`flux_engine.world.derived`
|
|
27
|
+
(vertical-derived attributes) and :mod:`flux_engine.world.families` (the four
|
|
28
|
+
sampling families); the ``Decimal`` boundary is :mod:`flux_engine.world.values`.
|
|
29
|
+
"""
|
|
30
|
+
|
|
31
|
+
from __future__ import annotations
|
|
32
|
+
|
|
33
|
+
from flux_engine.world.derived import DERIVATIONS, Derivation, derivation_for
|
|
34
|
+
from flux_engine.world.errors import FLX_5040, FLX_5041
|
|
35
|
+
from flux_engine.world.families import (
|
|
36
|
+
Bernoulli,
|
|
37
|
+
BoundedNormal,
|
|
38
|
+
Categorical,
|
|
39
|
+
Constant,
|
|
40
|
+
Family,
|
|
41
|
+
RateCount,
|
|
42
|
+
SetOf,
|
|
43
|
+
StreamFactory,
|
|
44
|
+
)
|
|
45
|
+
from flux_engine.world.population import (
|
|
46
|
+
NORMAL_BOUND_SIGMAS,
|
|
47
|
+
SUBJECT_ID_LENGTH,
|
|
48
|
+
SUBJECT_ID_PREFIX,
|
|
49
|
+
TRAIT_SCALE,
|
|
50
|
+
PersonaSpec,
|
|
51
|
+
PopulationSpec,
|
|
52
|
+
Subject,
|
|
53
|
+
SubjectStore,
|
|
54
|
+
materialise_population,
|
|
55
|
+
subject_id,
|
|
56
|
+
)
|
|
57
|
+
from flux_engine.world.tracing import TraceLog
|
|
58
|
+
from flux_engine.world.values import decimal_of, int_of, probability_of, weight_map
|
|
59
|
+
|
|
60
|
+
__all__ = [
|
|
61
|
+
"DERIVATIONS",
|
|
62
|
+
"FLX_5040",
|
|
63
|
+
"FLX_5041",
|
|
64
|
+
"NORMAL_BOUND_SIGMAS",
|
|
65
|
+
"SUBJECT_ID_LENGTH",
|
|
66
|
+
"SUBJECT_ID_PREFIX",
|
|
67
|
+
"TRAIT_SCALE",
|
|
68
|
+
"Bernoulli",
|
|
69
|
+
"BoundedNormal",
|
|
70
|
+
"Categorical",
|
|
71
|
+
"Constant",
|
|
72
|
+
"Derivation",
|
|
73
|
+
"Family",
|
|
74
|
+
"PersonaSpec",
|
|
75
|
+
"PopulationSpec",
|
|
76
|
+
"RateCount",
|
|
77
|
+
"SetOf",
|
|
78
|
+
"StreamFactory",
|
|
79
|
+
"Subject",
|
|
80
|
+
"SubjectStore",
|
|
81
|
+
"TraceLog",
|
|
82
|
+
"decimal_of",
|
|
83
|
+
"derivation_for",
|
|
84
|
+
"int_of",
|
|
85
|
+
"materialise_population",
|
|
86
|
+
"probability_of",
|
|
87
|
+
"subject_id",
|
|
88
|
+
"weight_map",
|
|
89
|
+
]
|