helixordevelopers
Architecture

Components

Seven components make up a Decision Runtime deployment. You run four of them yourself, one is optional and Helixor hosts two. This page lists each one and follows a pack from the playbook you write to the receipt you log.

Inventory#

ComponentWhat it isWhere it runs
Runtime libraryThe Python package helixor_runtime. HelixorEngine evaluates payloads and creates streaming sessions. A compiled native library behind the SDKs is Planned.Inside your application process.
Pack (.hxpack)A playbook compiled and encrypted with AES-256-GCM. It is bound to one pack_id and one license. The built-in Community PII pack ships inside the library.A file you mount read-only next to the runtime.
License (.hxlic)A signed JSON file. It names your organization, tier, validity window, licensed packs and solvers, and features. It also carries the key that decrypts your packs.A secret you mount read-only next to the runtime.
CLI (helixor-pack, helixor)Inspect licenses, compile playbooks, download catalog packs, run one evaluation, and serve a pack over HTTP.Build agents, operator workstations, and the decision service container.
Decision serviceThe runtime behind a small HTTP service. It offers REST, SSE and WebSocket endpoints for callers in other languages. Start it with helixor-pack serve.A sidecar on loopback, or a shared service inside your network.
License and compiler serviceHosted by Helixor. It issues licenses, compiles playbooks remotely, lists the pack catalog and delivers catalog packs sealed to your license. Optional: you can also compile locally.Helixor cloud. Used at build time, never on the decision path.
Hosted reasoning APIHosted by Helixor. It answers decisions that need evidence, multi-step reasoning or calibrated probabilities (POST /v1/decide).Helixor cloud. Optional escalation target.

Generated SDK models are also available for Python and Java; see the Reference. The Java client calls the native runtime library, which is Planned.

How the parts connect#

Your perimeter Application + runtime library HelixorEngine Decision service helixor-pack serve REST · SSE · WebSocket .hxpack .hxlic (secret) CLI on build agent HTTP Helixor cloud License and compiler service Hosted reasoning POST /v1/decide build optional escalation
The decision path stays inside your perimeter. Calls to Helixor cloud are made at build time for compilation, and optionally for escalation.

Pack lifecycle#

Build time Run time Authorplaybook.yaml Compile+ license Distribute.hxpack Loadverify, unseal Evaluatein memory Receiptreceipt_hash
A pack is compiled once per license and loaded at process start. Evaluation and receipts involve no network.
  1. Author

    Write a playbook in YAML. It needs a pack_id, a version, its actions and its rules. Keep it in source control. See Playbooks and the playbook schema.

  2. Compile

    helixor-pack compile --playbook playbook.yaml --license acme.hxlic --out guard.hxpack. The compiler checks that your license is entitled to the pack and to any solvers the playbook declares. It then encrypts the result for that license. Compile locally, or add --remote to use the Helixor compiler service; remote compilation sends the playbook and the license to Helixor. For a catalog pack, use helixor-pack download-pack --pack-id ... instead.

  3. Distribute

    Store the .hxpack in your artifact store and deploy it alongside the license it was compiled for. A pack opens only with that license, so the two travel as a pair.

  4. Load

    At start-up the runtime verifies the license signature and validity window. It then checks that the license covers the pack and its solvers, decrypts the pack in memory and checks its integrity. Any failure raises an error, and nothing is evaluated. The decrypted pack is never written to disk.

  5. Evaluate

    Each call extracts state from the payload, applies the rules, picks one declared action and computes the remedy. No network calls are made and no model tokens are used.

  6. Receipt

    Each result carries a receipt_hash, a SHA-256-derived fingerprint of the decision. Log it with your request ID. It is unkeyed and not chained; signed and chained receipts are Planned. See Receipts.

Decision service endpoints#

EndpointPurpose
GET /v1/healthService metadata, including the served pack_id and license tier. No token needed. See Reliability for liveness and readiness probes.
POST /v1/evaluateEvaluate one text payload and return the full result.
POST /v1/evaluate/streamSend a complete text; the service splits it into chunks and emits streaming results as server-sent events.
POST /v1/decisionOne dispatcher for evaluation and the in-process solvers.
WS /v1/ws/decisionEvaluate, and stream token by token, over one connection.

Request and response shapes are in the HTTP API reference.