Reference

Exact signatures, fields, formats, endpoints and flags for the Helixor Decision Runtime. Use it when you already know what you want to do and need the details. For explanations and walkthroughs, start with the User Guide.

Runtime 0.2.1Python 3.9+

Versioning#

This reference describes helixor_runtime 0.2.1 (helixor_runtime.__version__ == "0.2.1"). Everything documented here exists in that release. Items that are designed but not shipped carry Planned. Defects in the current release are called out in boxes titled "Known issue in 0.2.1", each with a workaround. When a defect is fixed in the runtime's source but not yet released, the box says "Fixed in the next release" and describes the new behavior. No new version has been released, and __version__ in the source still reads 0.2.1. The status of every issue is in Troubleshooting.

0.2.1 fixes most of the defects documented for 0.2.0: load_pack loads compiled packs, start_server serves the engine you pass, streaming no longer damages text split across short chunks, every matching rule is reported, compiled-pack results carry their license state, packs that declare rules the engine would ignore are rejected, redact rules redact, every runtime error is exported, and the service has bearer-token authentication and binds loopback by default. Licenses issued for 0.2.0 must be reissued: 0.2.1 trusts a new license authority key. Pages that describe 0.2.0 behavior say so explicitly.

Check the version you have installed:

python -c "import helixor_runtime; print(helixor_runtime.__version__)"

What ships in 0.2.1

The 0.2.1 runtime is a Python package. It runs in your process, spends no model tokens and makes no network calls when it evaluates. A compiled native library and a published package on the public index are Planned; see Installation for how to install today.

SDKs#

Python

Python API

HelixorEngine, results, streaming sessions and the service helpers.

Java

Generated Java client

The client generated from the pack manifest. Needs a runtime artifact that is Planned.

TypeScript

TypeScript and Node

No embedded SDK yet. Call the HTTP API from TypeScript today.

Formats#

YAML

Playbook schema

Every playbook key, and what the built-in engine and a compiled pack actually execute.

.hxpack

Packs and manifest

The encrypted pack container and the embedded-pack-manifest.json fields.

.hxlic

License file

Fields, signature and validity checks, tiers and features.

Interfaces#

HTTP

HTTP, SSE and WebSocket API

The local decision service: endpoints, request and response JSON.

CLI

Command line

helixor-pack: inspect licenses, compile, download, run and serve packs.

Errors

Errors and failure modes

Every exception, when it is raised, and which paths fail closed.

Config

Configuration

Environment variables, license search order, .env loading and ports.

Map of the reference#

You want to…	Page
Call `evaluate()` and read every result field	Python
Filter a token stream in flight	Python, streaming section
Serve decisions to other languages	HTTP API, CLI (`serve`)
Write your own rules	Playbook schema, CLI (`compile`)
Understand why a license or pack was rejected	Errors, License file
Set paths and endpoints for a deployment	Configuration

Out of scope for this release#

The runtime package also contains solver, forecasting, counterfactual, sales-dialogue and belief-tracking engines. They are not covered by this edition of the documentation, and their interfaces may change. The HTTP API's non-evaluate decision functions are listed for completeness only.