Tour the demo repository

The helixor-decision-demos repository holds runnable examples for the runtime. This page walks its structure: what each directory is for, which example shows what, and which ones run with nothing but the runtime wheel. Run the Quickstart first; it clones the repository and installs the runtime.

Tier 0Runtime 0.2.1Python 3.11+Verified 2026-09-29

The repository is private for now

You get read access with your Developer license request. Links on this page go to https://github.com/HelixorAI/helixor-decision-demos and work once your GitHub account has access. The repository's code is Apache-2.0; the runtime it calls is proprietary and is not in it.

Directories#

Directory	What it is for
`examples/`	The tutorial, 01 to 08, on the runtime's built-in example pack (data protection). Each adds one capability: evaluate, measure, guard a prompt, stream, serve, custom rules, generated SDK.
`use_cases/`	The runtime's other engines on business problems: loan recourse, demand forecasting, belief tracking, routing, rostering and sales dialogue.
`integrations/`	Patterns that connect the runtime to other systems: a batch CSV pipeline, a guardrail for an agent framework, and clients for a Helixor server.
`playbooks/`	`regulatory_pii_guard.yaml`, the playbook behind the built-in example pack. Read it before you write your own; see Playbooks.
`sdks/`	Typed Python and Java clients generated from the example pack's manifest. The native library they are written for is Planned; the Python client runs its generated evaluator when you ask for it explicitly.
`docs/`	`ARCHITECTURE.md`: what the 0.2.x runtime does and does not protect.
`tests/`	Checks that the examples compute what they print, plus repository hygiene. Run them with `pip install -e ".[dev]"` and `python -m pytest`.
`run_all.sh`	Runs every example and prints `PASS`, `FAIL`, `SKIP` or `KNOWN` for each, with the reason.

Which example shows what#

The last column is what run_all.sh reported on a clean checkout with only the runtime wheel installed.

Example	What it demonstrates	With the wheel alone
`examples/01_quickstart.py`	Your first decisions: action, clean output and receipt for four payloads. Quickstart step 4.	PASS
`examples/02_batch_benchmark.py`	Throughput and p50/p90/p99 engine latency over 5,000 evaluations on your machine. See Reproduce the benchmarks.	PASS
`examples/03_prompt_interceptor.py`	Decide on a prompt before it reaches a language model: send, send redacted, or stop. Quickstart step 5.	PASS
`examples/04_streaming_interceptor.py`	Redact a token stream in flight and halt it on a fatal match; sync and async filters. Quickstart step 5.	PASS
`examples/05_http_service.py`	The engine as an HTTP and SSE service. Starts and stops its own server on a free loopback port.	PASS
`examples/06_decision_protocols.py`	REST, SSE and WebSocket against one engine. Starts and stops its own server.	PASS
`examples/07_custom_rules.py`	Where custom rules go: in a playbook you compile with your Developer license, not into the built-in pack.	PASS
`examples/08_generated_sdk_client.py`	The generated typed Python client: typed state, `decide()`, batch.	PASS
`use_cases/loan_recourse.py`	The smallest change that flips a denied loan, then a stress test. Quickstart steps 5 and 6.	PASS
`use_cases/demand_forecasting.py`	A Bayesian forecaster switching regime. Its "95%" interval is not calibrated: 8 of the 13 demo actuals fall outside it.	PASS
`use_cases/belief_tracking.py`	Confidence in a hypothesis per context, with contradictions weighted more than confirmations.	PASS
`use_cases/fleet_routing.py`, `shift_rostering.py`	Feasibility checks, suggestions and ranked fallbacks before planning routes or rosters. Routing plans in 0.2.1 are checked against hard constraints, not optimized.	SKIP: needs the `helixor-solvers` package, not part of the wheel
`use_cases/sales_arbitration.py`	Sales dialogue arbitration.	KNOWN: 0.2.1 stops with `FileNotFoundError: sales binding not found`
`integrations/05_governed_query.py`	A local simulation of the governed-query contract: different fields for different roles, with an access receipt. It calls neither the runtime nor a data source. Governed data access is Planned.	PASS
`integrations/06` (guardrail)	A guardrail on model output, in the shape an agent framework expects. The model output is canned text.	PASS
`integrations/07_batch_csv_pipeline.py`	A CSV of records through the runtime field by field, with a clean file and a per-field report.	PASS
`integrations/01` to `04`	Clients for a Helixor server: evaluate, decide with streaming, the playbook lifecycle, ontology binding.	SKIP: need a server (`HELIXOR_API_URL`), which is not part of the license request

Run it all#

./run_all.sh

Helixor decision demos: helixor_runtime 0.2.1, Python 3.12.13

Examples (PII Guard tutorial)
  PASS   examples/01_quickstart.py                  0.1s
  PASS   examples/02_batch_benchmark.py             0.3s
  ...
Use cases
  PASS   use_cases/loan_recourse.py                 0.1s
  ...
  SKIP   use_cases/fleet_routing.py               needs the helixor-solvers package (not in the runtime wheel)
  SKIP   use_cases/shift_rostering.py             needs the helixor-solvers package (not in the runtime wheel)
  KNOWN  use_cases/sales_arbitration.py           runtime 0.2.1 does not package the sales playbook
...
Result: 14 passed, 0 failed, 6 skipped, 1 known issues

A SKIP names what the example needs; a KNOWN names a documented runtime defect and checks that the example still fails with that error, so a fix is noticed. Neither counts as a pass. The script exits non-zero on any FAIL; add -v to see the last lines of a failure.

A suggested order#

If you want to	Take, in order
Guard what goes into and out of a language model	`examples/01`, `03`, `04`, then `integrations/06`, then the Guard a model call tutorial
Serve decisions to services in other languages	`examples/01`, `05`, `06`, then Serve decisions to other languages
Process files and keep an audit trail	`examples/01`, `02`, `integrations/07`, then Run decisions over a batch
Explain and reverse adverse decisions	`use_cases/loan_recourse.py`: change a cap as in Quickstart step 6, then add a candidate change of your own
Decide on your own rules	`examples/07`, read `playbooks/regulatory_pii_guard.yaml`, then Add custom rules with your Developer license

How this page was verified#

The statuses and output above come from run_all.sh on a fresh clone of the repository (commit 1ed2315) in a new Python 3.12 virtual environment with only the runtime 0.2.1 wheel installed, on 2026-09-29. The tests (python -m pytest) reported 29 passed and 2 skipped (the routing and rostering tests, for the same reason as above).