Tour the demo repository
Inspect request classification and recorded policy examples with Python alone, or run the embedded-runtime examples for guarding data, explaining decisions and keeping an audit trail. Then design a support-ticket routing policy of your own.
The repository is public; the runtime is licensed
Anyone can clone https://github.com/HelixorAI/helixor-decision-demos. The runtime wheels come with a Developer license request. The repository's code is Apache-2.0; the runtime it calls is proprietary and is not in it.
Start with classic classification#
Classify an incoming business request shows English becoming fulfillment, expedite or unsupported. See actual recorded model scores, two confident mistakes, and the separate admission result before any runtime or business action.
python3 classification/review.py python3 classification/review.py --case ontology.test.00.02 --json
Python alone is enough to inspect these records. Fresh inference requires the model and source integration described in classification/README.md. The published snapshot admitted zero cases; inspecting a high score does not enable automatic routing.
Choose a policy example#
| Business question | What the example shows |
|---|---|
| Which team should review this support ticket? | Design a policy that recommends billing review for a reported duplicate charge, account support for a sign-in issue, and manual triage for unclear or multiple requests. Follow the authoring exercise. The runnable ticket demo is Planned. |
| Who needs to review this purchase? | Supplier status, amount and recorded approval select the next review route. Supplier review takes priority when both supplier and amount require attention. Follow the purchasing example. |
| What changes if finance lowers the approval threshold? | Compare the same $3,000 request under $5,000 and $2,500 thresholds before releasing a policy revision. |
For the recorded policy fixtures already in the repository, run these commands from its root after cloning with Python 3.11 or 3.12. They need no installed packages, runtime license or server.
python3 domain_packs/review.py python3 domain_packs/review.py --case purchase-unapproved-supplier python3 domain_packs/review.py --check
RECORDED EVIDENCE ONLY - no new policy execution or model inference Verified 5 artifact hashes; 11/11 recorded outcomes match the example expectations.
The output above is from --check. The walkthrough links inputs, recorded rules and cited policy. These are illustrative examples, not customer savings or language-model accuracy measurements. Editing a file invalidates its evidence hash; it does not run a new decision.
For fresh decisions, the domain-pack README explains how to import the bundled drafts, test cases, obtain separate review and approval, and run structured inputs in a provisioned Studio source integration. The public 0.3.1 wheel does not expose that runner. For the embedded-runtime examples below, follow the Quickstart.
Directories#
| Directory | What it is for |
|---|---|
classification/ | Classic English-to-category classification using actual recorded model predictions, scores and admission outcomes. The Python walkthrough and full evidence audit need no installed packages. |
domain_packs/ | Shipping and purchasing policy drafts, 11 cases, recorded runtime evidence, a policy-change comparison and Studio setup. Run python3 domain_packs/review.py separately from the runtime examples in run_all.sh. |
examples/ | The tutorial, 01 to 11, 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, receipts, outcome memory, and a pack you compile with your Developer license. |
use_cases/ | The runtime's other engines on business problems: loan recourse, demand forecasting, belief tracking, routing and rostering. |
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, and internal_ids.yaml and order_notes.yaml, the playbooks of Add custom rules and Write your own decision pack that example 11 compiles. Read them before you write your own; see Playbooks. |
policy-tests/ | The suite from Testing policies: a golden set, properties, a latency budget and streaming checks against the built-in pack. Run it with cd policy-tests && python -m pytest -q; run_all.sh runs it too when pytest is installed. |
docs/ | ARCHITECTURE.md: what the 0.3.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. |
scripts/check_docs.py | Re-runs the examples and the README's commands and compares them with the recorded outputs in tests/expected/ and the README, so neither can drift from what the runtime does. Exits 1 on any difference. |
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 shows which examples run with the runtime wheels and pytest, without a license file.
| Example | What it demonstrates | With the wheel alone |
|---|---|---|
examples/01_quickstart.py | Your first decisions: action, clean output and receipt for four payloads. | 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. | PASS |
examples/04_streaming_interceptor.py | Redact a token stream in flight and halt it on a fatal match; sync and async filters. | 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, which ships inside the runtime wheel: typed state, decide(), batch. | PASS |
examples/09_receipts.py | Recompute a receipt from what you log, never the payload; the same input gives the same receipt; and a hash-chained audit log that shows a deleted line. See Receipts. | PASS |
examples/10_outcome_memory.py | HelixorBeliefLedger: how belief moves, routing a rule per segment by confidence, and snapshot and restore. See Track outcomes and confidence. | PASS |
examples/11_compiled_pack.py | Compile internal_ids.yaml and order_notes.yaml with helixor-pack compile and your license, load them with HelixorEngine.load_pack(), and check every action against the two tutorials. The runtime finds the license by its own search order. | SKIP: needs your Developer license; without one it prints the runtime's LICENSE_NOT_FOUND guidance |
use_cases/loan_recourse.py | The smallest change that flips a denied loan, then a stress test. | 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, then a solve in the deployment model you choose (--mode embedded or --mode hosted). See Solving routes and rosters. | SKIP: needs the helixor-solvers package, not part of the wheel |
integrations/05_governed_query.py | Governed data access is Planned, so the script fails closed (UNAVAILABLE, exit 3). Its --simulate flag runs a local simulation of the planned contract, every line marked [SIMULATION]. | SKIP: fails closed; governed data access is Planned |
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#
pip install pytest ./run_all.sh
Helixor decision demos: helixor_runtime 0.3.1, Python 3.12.12 Examples (PII Guard tutorial) PASS examples/01_quickstart.py 0.1s PASS examples/02_batch_benchmark.py 0.3s ... PASS examples/10_outcome_memory.py 0.1s SKIP examples/11_compiled_pack.py needs your Developer license (HELIXOR_LICENSE_FILE or ~/.helixor/helixor.hxlic) 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) ... SKIP integrations/05_governed_query.py governed data access is Planned (fails closed) ... Policy tests (golden set, properties, latency budget, streaming) PASS policy-tests/ (33 passed) 0.5s Result: 16 passed, 0 failed, 8 skipped, 0 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. With runtime 0.3.1 no example is KNOWN. 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 |
|---|---|
| Review shipping or purchasing policy with a business owner | domain_packs/review.py, inspect a case with --case, read its cited policy, then follow domain_packs/README.md for new structured-input runs in Studio |
| 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 its DTI cap, re-run, 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 and run examples/11 |