Experimental

Readable docs for building with uncertainty

BeliefLang helps you model intent and constraints as belief state, then run clear rules over that state. Use it when you want behavior that is inspectable, traceable, and not hidden inside prompt text.

Quick Start

Install, build, and run with trace output:

npm install -g belieflang
npm run build
bel run examples/intent.bel --trace

Mental Model

BeliefLang separates language understanding from execution logic. You keep uncertain state explicit and run deterministic policies on top. 

natural language -> observations -> inferred beliefs -> merge -> rules -> actions

Syntax

Beliefs

belief intent exclusive closed {
  book_flight: 0.82
  book_hotel: 0.12
  unknown: 0.06
}

Variables

let threshold = 0.7
let flights = call search_flights()

Rules

when confidence(intent.book_flight) > threshold:
  call rank_flights()

Belief Modes

Mode Meaning Runtime behavior
exclusive closed Exactly one listed label is true Values are normalized to sum to 1.0
exclusive open One listed or unlisted label is true Listed values must sum to <= 1.0, remainder is confidence(name.other)
multi closed Independent label confidences Each value is in [0, 1], no distribution normalization

Conditions

Use comparison and boolean operators with grouping:

when confidence(intent.book_flight) > 0.7 && (flights.count > 0 || !false):
  ask_user("I found flight options.")
  • Comparison: >, >=, <, <=, ==, !=
  • Boolean: &&, ||, !
  • Metrics: confidence(name.label), entropy(name)

Observe, Infer, Merge

Dynamic updates happen in a small pipeline: store observation, run inference adapter, merge returned beliefs. 

let message = "I need a cheap direct flight"

observe user_message(message)
infer beliefs from user_message

let extracted = call extract_patch()
merge beliefs from extracted

Merge accepts patch objects by belief name. Existing labels are preserved unless overwritten. For multi beliefs, merged values are clamped into [0, 1].

Trace and Provenance

Run with --trace to inspect evaluation and actions:

bel run examples/observe_infer_merge.bel --trace

Runtime also tracks provenance for belief updates from load, merge, and infer steps.

runtime.getProvenance()
runtime.explainBelief("intent.book_flight")

Runtime API

State Access

  • getState()
  • getVars()
  • confidence(path)
  • entropy(beliefName)

Dynamic Data

  • observe(eventName, value)
  • infer(source)
  • mergeBeliefsFromRuntimeValue(patch, source)

Auditability

  • getObservations()
  • getProvenance()
  • explainBelief(path)

Full Example

let message = "I need a cheap direct flight to Berlin"

belief intent exclusive closed {
  unknown: 1
}

observe user_message(message)
infer beliefs from user_message

let extracted = call extract_patch()
merge beliefs from extracted

when confidence(intent.book_flight) > 0.7 && confidence(user.budget_sensitive) > 0.5:
  call rank_flights()

when entropy(intent) > 0.5:
  ask_user("Can you clarify your travel intent?")