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.3.1Python 3.11+

Versioning#

This reference describes helixor_runtime 0.3.1 (helixor_runtime.__version__ == "0.3.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.3.1", each with a workaround; behavior that changed from 0.2.1 is marked "Changed in 0.3.0", and from 0.3.0 "Changed in 0.3.1". The status of every issue is in Troubleshooting.

0.3.0 fixes most of the defects documented for 0.2.1: a WebSocket stream stays blocked after a fatal value, a compiled pack withholds the whole text of a blocked result, redaction covers the whole match, both engines use one receipt recipe over the input, evaluate() refuses an ambiguous dict, compiled packs enforce their actions, default_action and budget and the license's decision limits, compile_custom_rule() is removed, the outcome ledger has snapshot and restore, the bundled generated client is regenerated, the wheel requires Python 3.11 or later, and importing the runtime no longer loads the GPU solver's libraries. It also adds HelixorSolver with explicit embedded and hosted models (see Solver deployment models). Licenses signed by the revoked authority key that 0.2.0 and early 0.2.1 builds trusted are rejected.

0.3.1 changes how the runtime finds your license: the file is helixor.hxlic, and the CLI and every Python loader search the explicit path, HELIXOR_LICENSE_FILE, ./helixor.hxlic and ~/.helixor/helixor.hxlic, raising LicenseNotFoundError when there is none (see License file). It removes helixor-pack mint-license: licenses are issued by Helixor. HelixorSalesEngine is not part of the runtime and raises SalesEngineUnavailableError. GET /v1/health lists the rules the served engine evaluates, and running a solver engine in your process needs the solver.embedded feature.

Check the version you have installed:

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

What ships in 0.3.1

The 0.3.1 runtime is a Python package, installed with the helixor-constraint-network wheel it depends on. 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#

Capability matrix

SDK generation

OpenAPI clients in five languages and embedded decision SDKs in five languages, with C scoped explicitly.

Python

Python API

HelixorEngine, results, streaming sessions and the service helpers.

Java

Java clients

Generated OpenAPI client plus an embedded decision target.

JavaScript / TypeScript

TypeScript and Node

Generated typed OpenAPI client that compiles to JavaScript.

.NET client and binding

Generated .NET 8 OpenAPI client and embedded native-runtime binding.

Rust

Rust client and binding

Generated Cargo OpenAPI client and embedded native-runtime binding.

Embedded C11 SDK

Typed pack wrappers over the native runtime. C is not an OpenAPI target.

Formats#

YAML

Playbook schema

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

rules.dsl

Rule language

Grammar, every annotation and what a digital worker does with it, and the current limits.

.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
Choose a generated client or embedded SDK language	SDK generation
Serve decisions to other languages	HTTP API, CLI (`serve`)
Write your own rules	Playbook schema, CLI (`compile`)
Write business rules for a digital worker	Rule language
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.