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.
Files changed (165) hide show
  1. flux_engine/__init__.py +22 -0
  2. flux_engine/_links.py +55 -0
  3. flux_engine/_vendor/__init__.py +5 -0
  4. flux_engine/_vendor/flux_spec/NOTICE +19 -0
  5. flux_engine/_vendor/flux_spec/VENDOR-NOTES.md +104 -0
  6. flux_engine/_vendor/flux_spec/__init__.py +9 -0
  7. flux_engine/_vendor/flux_spec/bundle.py +410 -0
  8. flux_engine/_vendor/flux_spec/enforce.py +316 -0
  9. flux_engine/_vendor/flux_spec/schema/flux-enforcement-0.5.0.json +121 -0
  10. flux_engine/_vendor/flux_spec/schema/flux-manifest-0.5.0.json +153 -0
  11. flux_engine/_vendor/flux_spec/schema/flux-schema-0.2.0.json +465 -0
  12. flux_engine/_vendor/flux_spec/schema/flux-schema-0.3.0.json +876 -0
  13. flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.0.json +1601 -0
  14. flux_engine/_vendor/flux_spec/schema/flux-schema-0.4.1.json +1668 -0
  15. flux_engine/_vendor/flux_spec/schema/flux-schema-0.5.0.json +1669 -0
  16. flux_engine/_vendor/flux_spec/schema/flux-schema-latest.json +1669 -0
  17. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.0.json +795 -0
  18. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.4.1.json +852 -0
  19. flux_engine/_vendor/flux_spec/schema/flux-ui-hints-0.5.0.json +852 -0
  20. flux_engine/_vendor/flux_spec/validate.py +537 -0
  21. flux_engine/_vendor/flux_spec/vectors/enforcement-vectors.json +935 -0
  22. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.3.json +5234 -0
  23. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.4.json +5437 -0
  24. flux_engine/_vendor/flux_spec/vendor/fluid/fluid-schema-0.7.5.json +5498 -0
  25. flux_engine/_vocabulary.py +141 -0
  26. flux_engine/accuracy/__init__.py +5 -0
  27. flux_engine/accuracy/_scoring/__init__.py +24 -0
  28. flux_engine/accuracy/accuracy_record.py +96 -0
  29. flux_engine/accuracy/policy.py +158 -0
  30. flux_engine/accuracy/records.py +264 -0
  31. flux_engine/accuracy/store.py +169 -0
  32. flux_engine/api/__init__.py +163 -0
  33. flux_engine/api/accuracy.py +209 -0
  34. flux_engine/api/agentic.py +134 -0
  35. flux_engine/api/calibration.py +125 -0
  36. flux_engine/api/claims.py +93 -0
  37. flux_engine/api/digests.py +73 -0
  38. flux_engine/api/emit.py +78 -0
  39. flux_engine/api/expressions.py +72 -0
  40. flux_engine/api/fidelity.py +110 -0
  41. flux_engine/api/lineage.py +78 -0
  42. flux_engine/api/stages.py +242 -0
  43. flux_engine/api/verdict.py +108 -0
  44. flux_engine/calibrate/__init__.py +5 -0
  45. flux_engine/calibrate/declared.py +253 -0
  46. flux_engine/calibrate/provenance.py +113 -0
  47. flux_engine/cli/__init__.py +2146 -0
  48. flux_engine/cli/__main__.py +17 -0
  49. flux_engine/cli/_documents.py +226 -0
  50. flux_engine/cli/_hints.py +118 -0
  51. flux_engine/cli/_init.py +152 -0
  52. flux_engine/cli/_progress.py +124 -0
  53. flux_engine/concordance/__init__.py +127 -0
  54. flux_engine/concordance/boundary/__init__.py +78 -0
  55. flux_engine/concordance/boundary/merkle.py +287 -0
  56. flux_engine/concordance/boundary/slice.py +429 -0
  57. flux_engine/concordance/boundary/statistic.py +561 -0
  58. flux_engine/concordance/boundary/store.py +334 -0
  59. flux_engine/concordance/boundary/vault.py +357 -0
  60. flux_engine/concordance/compiler.py +542 -0
  61. flux_engine/concordance/errors.py +189 -0
  62. flux_engine/concordance/gate.py +525 -0
  63. flux_engine/concordance/predicate.py +1217 -0
  64. flux_engine/concordance/record.py +554 -0
  65. flux_engine/concordance/verifier.py +583 -0
  66. flux_engine/core/__init__.py +5 -0
  67. flux_engine/core/artifact.py +99 -0
  68. flux_engine/core/canonical.py +369 -0
  69. flux_engine/core/clock.py +437 -0
  70. flux_engine/core/digest.py +288 -0
  71. flux_engine/core/errors.py +277 -0
  72. flux_engine/core/fixedpoint.py +929 -0
  73. flux_engine/core/lrm.py +158 -0
  74. flux_engine/core/rng.py +736 -0
  75. flux_engine/core/seedtree.py +891 -0
  76. flux_engine/core/trace.py +423 -0
  77. flux_engine/describe.py +207 -0
  78. flux_engine/engine.py +257 -0
  79. flux_engine/evidence/__init__.py +5 -0
  80. flux_engine/evidence/pack.py +411 -0
  81. flux_engine/evidence/report.py +243 -0
  82. flux_engine/expr/__init__.py +133 -0
  83. flux_engine/expr/ast.py +312 -0
  84. flux_engine/expr/attrs.py +386 -0
  85. flux_engine/expr/check.py +278 -0
  86. flux_engine/expr/compile.py +322 -0
  87. flux_engine/expr/errors.py +256 -0
  88. flux_engine/expr/lexer.py +297 -0
  89. flux_engine/expr/parser.py +313 -0
  90. flux_engine/expr/types.py +177 -0
  91. flux_engine/generator/__init__.py +97 -0
  92. flux_engine/generator/families.py +325 -0
  93. flux_engine/generator/paths.py +227 -0
  94. flux_engine/generator/rows.py +918 -0
  95. flux_engine/generator/statistics.py +524 -0
  96. flux_engine/governance/__init__.py +87 -0
  97. flux_engine/governance/audit.py +307 -0
  98. flux_engine/governance/gate.py +334 -0
  99. flux_engine/governance/skills.py +220 -0
  100. flux_engine/governance/sovereignty.py +251 -0
  101. flux_engine/lineage/__init__.py +5 -0
  102. flux_engine/lineage/emitter.py +398 -0
  103. flux_engine/py.typed +0 -0
  104. flux_engine/runtime/__init__.py +153 -0
  105. flux_engine/runtime/campaign.py +407 -0
  106. flux_engine/runtime/cast.py +283 -0
  107. flux_engine/runtime/detector.py +222 -0
  108. flux_engine/runtime/errors.py +58 -0
  109. flux_engine/runtime/experiment.py +311 -0
  110. flux_engine/runtime/journey.py +383 -0
  111. flux_engine/runtime/jurisdiction.py +72 -0
  112. flux_engine/runtime/payloads.py +124 -0
  113. flux_engine/runtime/signals.py +334 -0
  114. flux_engine/runtime/temperature.py +156 -0
  115. flux_engine/seam/__init__.py +5 -0
  116. flux_engine/seam/attest.py +290 -0
  117. flux_engine/seam/conform.py +448 -0
  118. flux_engine/seam/contract.py +605 -0
  119. flux_engine/seam/emit.py +488 -0
  120. flux_engine/seam/mapping.py +299 -0
  121. flux_engine/seam/resolve.py +1087 -0
  122. flux_engine/seam/sinks.py +157 -0
  123. flux_engine/spec/__init__.py +134 -0
  124. flux_engine/spec/bundle.py +25 -0
  125. flux_engine/spec/enforce.py +31 -0
  126. flux_engine/spec/validate.py +28 -0
  127. flux_engine/stages/__init__.py +30 -0
  128. flux_engine/stages/apply.py +447 -0
  129. flux_engine/stages/errors.py +315 -0
  130. flux_engine/stages/layout.py +292 -0
  131. flux_engine/stages/pipeline.py +600 -0
  132. flux_engine/stages/plan.py +241 -0
  133. flux_engine/stages/replay.py +83 -0
  134. flux_engine/stages/run.py +208 -0
  135. flux_engine/stages/ship.py +934 -0
  136. flux_engine/stages/validate.py +93 -0
  137. flux_engine/stages/verify.py +1129 -0
  138. flux_engine/starter/__init__.py +161 -0
  139. flux_engine/starter/bundle/detector.flux.yml +15 -0
  140. flux_engine/starter/bundle/journey.flux.yml +23 -0
  141. flux_engine/starter/bundle/module.flux.yml +16 -0
  142. flux_engine/starter/bundle/payment-recovery.fluid.yml +30 -0
  143. flux_engine/starter/bundle/persona.flux.yml +26 -0
  144. flux_engine/starter/bundle/signal.flux.yml +13 -0
  145. flux_engine/starter/bundle/simulation.flux.yml +29 -0
  146. flux_engine/starter/bundle/taxonomy.flux.yml +17 -0
  147. flux_engine/starter/bundle/treatment.flux.yml +13 -0
  148. flux_engine/starter/bundle/world.flux.yml +20 -0
  149. flux_engine/verticals/__init__.py +85 -0
  150. flux_engine/verticals/telco.py +89 -0
  151. flux_engine/world/__init__.py +89 -0
  152. flux_engine/world/derived.py +195 -0
  153. flux_engine/world/errors.py +41 -0
  154. flux_engine/world/families.py +260 -0
  155. flux_engine/world/population.py +602 -0
  156. flux_engine/world/tracing.py +66 -0
  157. flux_engine/world/values.py +121 -0
  158. flux_sim_engine-0.2.0.dist-info/METADATA +108 -0
  159. flux_sim_engine-0.2.0.dist-info/RECORD +165 -0
  160. flux_sim_engine-0.2.0.dist-info/WHEEL +5 -0
  161. flux_sim_engine-0.2.0.dist-info/entry_points.txt +2 -0
  162. flux_sim_engine-0.2.0.dist-info/licenses/LICENSE +202 -0
  163. flux_sim_engine-0.2.0.dist-info/licenses/NOTICE +10 -0
  164. flux_sim_engine-0.2.0.dist-info/licenses/flux_engine/_vendor/flux_spec/NOTICE +19 -0
  165. 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
+ ]