API reference

This section lists every public function and class with its signature and docstring, generated from the source code. Start from the task you have in mind below; each line names the symbols you need and the page that documents them. Everything listed in this table can be imported from grounded_decision directly unless a submodule is named. The check settings themselves are best learned from your history rather than set by hand; see Learn.

The supported surface is grounded_decision.__all__ plus grounded_decision.examples.catalog; the rules for what may change between versions are on Stability and versioning. The module pages also document internal helpers (for contributors); those can move without notice.

By task

To…	Use	Page
Write a policy as text	parse("test(suspicious) ; act(block)")	Grammar
Write a policy in Python	evt, act, seq, union, star	Grammar
Check a policy before deploying it	star_height, compile_expr; catch StarHeightError, ParseError, CompileError	Grammar
Draw a policy by hand (payoffs, priorities)	Statechart().state(...).on(...)	Statechart
Build the decision object	Module.from_expr(name, expr) or Module(name, chart)	Runtime
Make one decision	Module.decide(Event(...), EvidenceSnapshot(...)) → DecisionRecord	Runtime, Types
Save and restore an entity's position	record.extras["state"], Module.restore(state), Module.reset()	Runtime
Build evidence from your own graph	snapshot_from_graph(labels, edges, p_threshold=...)	Evidence
Build evidence from numbers you already have	EvidenceSnapshot(n=, p_hat=, p_threshold=, degree=, lambda_hat=, scores=, label_score=)	Types
Learn the check settings from labelled history	learn_parameters(cases, RiskTarget(max_risk=0.05)) → LearnedParameters; HistoricalCase, ParameterGrid (from grounded_decision.learn)	Learn
Use learned settings in a module	learned.limits(), learned.apply(evidence, proposed_action), learned.fingerprint, LearnedParameters.from_dict	Learn
Watch the live error rate after launch	RiskMonitor(target).record(acted=, action_was_correct=), .status()	Learn
Run one check on its own	reconstruction_report, threshold_report; conformal_report from evidence.conformal	Evidence
Read a decision	DecisionRecord.verdict, .action, .proposed_action, .reason, .channels, .to_dict()	Types
Put decide behind HTTP or a queue	handle_request(module, body)	Integrate
Replay a stream of events	DecisionSession(module).run(ticks)	Integrate
Simulate noisy evidence	EvidencePrior, Volatility, draw_snapshot	Integrate
Combine several policies	Pipeline([...]).decide(...), compose_parent(name, records)	Runtime
Change a cap or default	Limits(...), DEFAULT_LIMITS	Performance, Defaults
Ask a hard side question, or get a refusal	dispatch(Subgoal(name, envelope, payload))	Router
Compare outcome distributions	compare_outcome_laws(a, b, tau=...)	Compare
Test an A/B table against chance	sample_two_row(col_sums, row0)	Compare
Pick one feature, or accept from a stream	best_coordinate, single_item_max_of_samples, single_item_one_sample	Compare
Run the examples from Python	list_examples, run_example, interface_map (from examples.catalog)	Examples and CLI
See which result a check relies on	channels[].catalog on a record; constants in certificates	Certificates

By module

Page	Modules	What it is for
Types	types	Inputs and outputs of a decision
Runtime	runtime.module, runtime.pipeline	Building modules and deciding
Grammar	grammar.ast, height, parse, dfa	Policy text and its compilation
Statechart	machine, game, parity, mean_payoff	Hand-built charts and the progress check
Evidence	reconstruction, thresholds, conformal, support, graph	The four data checks and graph-to-evidence
Integrate	integrate.codec, session, priors	Services, replays and simulation
Router	dispatch, ugc, wl	Hard side questions: approximate or refuse
Compare	courtade_kumar, ot_stability, tables, prophet	Side analyses next to a decision
Performance	performance	Limits and two published constants
Learn	learn.calibrate, monitor, statistics	Settings learned from history, with a certificate
Certificates	certificates	References to the math results each check uses
Examples and CLI	examples.catalog, cli	The example registry and the command line
Service	service.config, limits, connection, app, server	Our own service: the protocol over HTTP and WebSocket

A minimal call

from grounded_decision import EvidenceSnapshot, Event, Module, parse

module = Module.from_expr("fraud", parse("test(suspicious) ; act(block)"))
record = module.decide(
    Event("suspicious"),
    EvidenceSnapshot(n=80, p_hat=0.35, p_threshold=0.08, degree=8.0, lambda_hat=0.55),
)
print(record.verdict, record.proposed_action)  # act block

What each argument means and how to choose it is explained in Your first decision.