Skip to content

README.md

Latest commit

 

History

History
164 lines (125 loc) · 4.77 KB

README.md

File metadata and controls

164 lines (125 loc) · 4.77 KB

Sponsor

// SPDX-License-Identifier: MPL-2.0 // Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) j.d.a.jewell@open.ac.uk = Betlangiser Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk :toc: left :icons: font

== What Is This?

Betlangiser analyses deterministic code, identifies values that should be probabilistic, wraps them in Betlang distributions, and generates uncertainty-propagating code. Turn price = 100 into price = Normal(100, 5) with automatic propagation through arithmetic and control flow -- without rewriting your codebase.

Betlang is a ternary probabilistic programming language where every boolean becomes true / false / unknown, enabling reasoning under genuine uncertainty rather than forcing premature binary decisions.

== How It Works

  1. You write a betlangiser.toml manifest declaring which values are uncertain
  2. Betlangiser analyses your deterministic source to find numeric values, boolean conditions, and decision points
  3. The Idris2 ABI layer proves that distribution compositions are mathematically correct (Kolmogorov axioms, support bounds, parameter validity)
  4. The Zig FFI bridge provides zero-overhead C-ABI sampling and combination
  5. The codegen engine emits Betlang wrappers with ternary bet semantics
  6. You get probability distributions, not point estimates

== Key Value

  • Retrofit uncertainty -- add probabilistic modelling to existing code without a rewrite
  • Ternary logic -- every boolean becomes true/false/unknown, propagating uncertainty through conditionals and loops
  • Distribution types -- Normal, Uniform, Beta, Bernoulli, and custom distributions as first-class values
  • Proven correctness -- Idris2 dependent types prove distribution composition obeys Kolmogorov axioms at compile time
  • 14 number systems -- from exact rationals to fuzzy intervals, matched to precision requirements
  • Automatic propagation -- uncertainty flows through arithmetic, comparisons, and control flow without manual instrumentation

== Use Cases

  • Financial modelling -- model price uncertainty, risk distributions, portfolio Monte Carlo
  • Sensor fusion -- combine noisy readings with known error distributions
  • Risk assessment -- propagate uncertainty through decision trees
  • Monte Carlo pipelines -- generate full simulation harnesses from deterministic code
  • Scientific computing -- add measurement uncertainty to numerical models

== Architecture

Follows the hyperpolymath -iser pattern:

[source]

betlangiser.toml (manifest) -> Deterministic source analysis -> Idris2 ABI (proves distribution correctness) -> Zig FFI (C-ABI sampling bridge) -> Betlang codegen (uncertainty-propagating wrappers)

=== Idris2 ABI Layer

  • Types.idr -- Distribution, TernaryBool, ProbabilityValue, ConfidenceInterval, SamplingStrategy
  • Layout.idr -- Distribution struct memory layout, sample buffer layout
  • Foreign.idr -- Distribution creation, sampling, combination, ternary logic FFI declarations

=== Zig FFI Bridge

  • main.zig -- Distribution allocation, sampling engine, combination operators, ternary logic evaluation
  • build.zig -- Shared/static library build, cross-compilation
  • test/integration_test.zig -- ABI compliance tests

Part of the https://github.com/hyperpolymath/iseriser[-iser family].

== CLI Commands

[source,bash]

Initialise a new manifest

betlangiser init

Validate manifest

betlangiser validate -m betlangiser.toml

Generate Betlang wrappers and FFI bridge

betlangiser generate -m betlangiser.toml -o generated/betlangiser

Build generated artifacts

betlangiser build -m betlangiser.toml --release

Run the workload

betlangiser run -m betlangiser.toml

Show manifest info

betlangiser info -m betlangiser.toml

== Example Manifest

[source,toml]

[workload] name = "pricing-model" description = "Add uncertainty to deterministic pricing"

[sources] paths = ["src/pricing.rs"]

[distributions]

Wrap a deterministic value in a normal distribution

[[distributions.wrap]] target = "base_price" distribution = "Normal" params = { mean = 100.0, stddev = 5.0 }

[[distributions.wrap]] target = "demand_factor" distribution = "Uniform" params = { low = 0.8, high = 1.2 }

[[distributions.wrap]] target = "is_peak_season" distribution = "Bernoulli" params = { p = 0.3 }

[propagation] strategy = "monte-carlo" samples = 10000 confidence = 0.95

[output] format = "betlang" ternary-logic = true

== Building

[source,bash]

cargo build --release cargo test

== Status

Pre-alpha. Architecture defined, CLI scaffolded, ABI definitions in progress. Codegen engine pending.

== License

SPDX-License-Identifier: MPL-2.0