@@ -7,39 +7,155 @@ Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
77
88== What Is This?
99
10- Betlangiser adds **ternary probabilistic uncertainty modelling** to deterministic
11- code — expressing "maybe", "probably", and "unlikely" as first-class values.
10+ Betlangiser analyses deterministic code, identifies values that should be
11+ probabilistic, wraps them in **Betlang distributions**, and generates
12+ **uncertainty-propagating code**. Turn `price = 100` into
13+ `price = Normal(100, 5)` with automatic propagation through arithmetic
14+ and control flow -- without rewriting your codebase.
1215
13- Betlang is a probabilistic programming language built on Racket where the
14- core primitive is the ternary bet. Betlangiser wraps deterministic code
15- in probabilistic semantics .
16+ Betlang is a ternary probabilistic programming language where every boolean
17+ becomes **true / false / unknown**, enabling reasoning under genuine
18+ uncertainty rather than forcing premature binary decisions .
1619
1720== How It Works
1821
19- Annotate uncertain values in `betlangiser.toml`. Betlangiser:
20-
21- 1. Identifies deterministic decisions that should be probabilistic
22- 2. Generates Betlang probabilistic wrappers with ternary bet semantics
23- 3. Provides 14 number systems for different precision needs
24- 4. Runs Monte Carlo simulation or analytical inference
25- 5. Returns probability distributions, not point estimates
22+ 1. You write a `betlangiser.toml` manifest declaring which values are uncertain
23+ 2. Betlangiser **analyses your deterministic source** to find numeric values,
24+ boolean conditions, and decision points
25+ 3. The **Idris2 ABI layer** proves that distribution compositions are
26+ mathematically correct (Kolmogorov axioms, support bounds, parameter validity)
27+ 4. The **Zig FFI bridge** provides zero-overhead C-ABI sampling and combination
28+ 5. The **codegen engine** emits Betlang wrappers with ternary bet semantics
29+ 6. You get **probability distributions**, not point estimates
2630
2731== Key Value
2832
29- * **Uncertainty as a first-class citizen** — not bolted on, built in
30- * **Ternary bets** — richer than binary (true/false/uncertain)
31- * **14 number systems** — from exact rationals to fuzzy intervals
32- * **Decision under uncertainty** — Bayesian reasoning made accessible
33+ * **Retrofit uncertainty** -- add probabilistic modelling to existing code
34+ without a rewrite
35+ * **Ternary logic** -- every boolean becomes true/false/unknown, propagating
36+ uncertainty through conditionals and loops
37+ * **Distribution types** -- Normal, Uniform, Beta, Bernoulli, and custom
38+ distributions as first-class values
39+ * **Proven correctness** -- Idris2 dependent types prove distribution
40+ composition obeys Kolmogorov axioms at compile time
41+ * **14 number systems** -- from exact rationals to fuzzy intervals, matched
42+ to precision requirements
43+ * **Automatic propagation** -- uncertainty flows through arithmetic, comparisons,
44+ and control flow without manual instrumentation
45+
46+ == Use Cases
47+
48+ * **Financial modelling** -- model price uncertainty, risk distributions,
49+ portfolio Monte Carlo
50+ * **Sensor fusion** -- combine noisy readings with known error distributions
51+ * **Risk assessment** -- propagate uncertainty through decision trees
52+ * **Monte Carlo pipelines** -- generate full simulation harnesses from
53+ deterministic code
54+ * **Scientific computing** -- add measurement uncertainty to numerical models
3355
3456== Architecture
3557
36- Follows the hyperpolymath -iser pattern:
37- manifest -> Idris2 ABI proof -> Zig FFI bridge -> target language codegen.
58+ Follows the hyperpolymath **-iser pattern**:
59+
60+ [source]
61+ ----
62+ betlangiser.toml (manifest)
63+ -> Deterministic source analysis
64+ -> Idris2 ABI (proves distribution correctness)
65+ -> Zig FFI (C-ABI sampling bridge)
66+ -> Betlang codegen (uncertainty-propagating wrappers)
67+ ----
68+
69+ === Idris2 ABI Layer
70+
71+ * `Types.idr` -- Distribution, TernaryBool, ProbabilityValue,
72+ ConfidenceInterval, SamplingStrategy
73+ * `Layout.idr` -- Distribution struct memory layout, sample buffer layout
74+ * `Foreign.idr` -- Distribution creation, sampling, combination, ternary
75+ logic FFI declarations
76+
77+ === Zig FFI Bridge
78+
79+ * `main.zig` -- Distribution allocation, sampling engine, combination
80+ operators, ternary logic evaluation
81+ * `build.zig` -- Shared/static library build, cross-compilation
82+ * `test/integration_test.zig` -- ABI compliance tests
83+
3884Part of the https://github.com/hyperpolymath/iseriser[-iser family].
3985
86+ == CLI Commands
87+
88+ [source,bash]
89+ ----
90+ # Initialise a new manifest
91+ betlangiser init
92+
93+ # Validate manifest
94+ betlangiser validate -m betlangiser.toml
95+
96+ # Generate Betlang wrappers and FFI bridge
97+ betlangiser generate -m betlangiser.toml -o generated/betlangiser
98+
99+ # Build generated artifacts
100+ betlangiser build -m betlangiser.toml --release
101+
102+ # Run the workload
103+ betlangiser run -m betlangiser.toml
104+
105+ # Show manifest info
106+ betlangiser info -m betlangiser.toml
107+ ----
108+
109+ == Example Manifest
110+
111+ [source,toml]
112+ ----
113+ [workload]
114+ name = "pricing-model"
115+ description = "Add uncertainty to deterministic pricing"
116+
117+ [sources]
118+ paths = ["src/pricing.rs"]
119+
120+ [distributions]
121+ # Wrap a deterministic value in a normal distribution
122+ [[distributions.wrap]]
123+ target = "base_price"
124+ distribution = "Normal"
125+ params = { mean = 100.0, stddev = 5.0 }
126+
127+ [[distributions.wrap]]
128+ target = "demand_factor"
129+ distribution = "Uniform"
130+ params = { low = 0.8, high = 1.2 }
131+
132+ [[distributions.wrap]]
133+ target = "is_peak_season"
134+ distribution = "Bernoulli"
135+ params = { p = 0.3 }
136+
137+ [propagation]
138+ strategy = "monte-carlo"
139+ samples = 10000
140+ confidence = 0.95
141+
142+ [output]
143+ format = "betlang"
144+ ternary-logic = true
145+ ----
146+
147+ == Building
148+
149+ [source,bash]
150+ ----
151+ cargo build --release
152+ cargo test
153+ ----
154+
40155== Status
41156
42- **Pre-alpha.** Architecture defined, scaffolding in place, codegen pending.
157+ **Pre-alpha.** Architecture defined, CLI scaffolded, ABI definitions in progress.
158+ Codegen engine pending.
43159
44160== License
45161
0 commit comments