Documentation

How to integrate HST into your systems.

HST is a licensed REST service and optional Python client for sparse incremental workloads. Compile the fixed operator once, keep state on your side, then send only the changed columns with each update.

1. Compile the operator

POST /v1/operators
Authorization: Bearer <api_key>

{
  "operator": {
    "n": 12000,
    "m": 12000,
    "rows": [0, 1],
    "cols": [0, 5],
    "values": [1.0, -0.5]
  },
  "compile_options": {
    "tile_size": 32,
    "gate": 0.75
  }
}

2. Apply a delta

Customer code owns x_prev and y_prev. Each call sends the sparse change and receives the next exact output plus telemetry.

POST /v1/operators/{operator_id}/apply_delta
Authorization: Bearer <api_key>

{
  "x_prev": [1.0, 0.0],
  "y_prev": [0.5, -0.2],
  "dx": {
    "columns": [0, 5],
    "values": [0.1, 0.2]
  },
  "run_options": {
    "mode": "hybrid",
    "allow_fallback": true,
    "report_level": "summary"
  }
}

Python SDK

The Python client wraps the same REST contract for evaluation notebooks and customer-side integration scripts.

from hst_client import HSTClient

client = HSTClient(
    "http://localhost:8080",
    api_key="hst_dev_key_001",
)

meta = client.compile_operator(operator)
result = client.apply_delta(
    meta["operator_id"],
    {
        "x_prev": x_prev,
        "y_prev": y_prev,
        "dx": {"columns": cols, "values": vals},
        "run_options": {"mode": "hybrid"},
    },
)

Telemetry and fallback

Responses include route, runtime, estimated error, work-saved ratio, and fallback status. Hybrid mode routes sparse local updates through HST and uses the exact CSC path when the workload shape stops fitting.

{
  "report": {
    "route": "hybrid_delta",
    "runtime_ms": 2.14,
    "estimated_error": 0.0,
    "tolerance_pass": true,
    "fallback": false,
    "work_saved_ratio": 0.81
  }
}

Common patterns

Video frame updates, sparse grids, rank recomputation.

HST is strongest when operator A is fixed or slow-moving, x changes incrementally, and update locality persists across calls. Frame-to-frame video, ranking systems with event streams, and simulation grids with local perturbations are the intended evaluation shapes.

For fully scattered updates, HST should route back to the exact path and report that decision. The right evaluation measures route, runtime, error, fallback rate, and visited work against representative customer data.

Deployment paths

HST is packaged three ways so teams can start with the lightest fit and move deeper only when the workload proves it out.

1. Plug-and-play web app + API
2. Customer-hosted Docker package
3. Custom-fit math integration

Canonical public host

hornesci.github.io remains the canonical public site while domain and mail changes stay deferred.

Public site: https://hornesci.github.io
Mirror + same-origin API: https://hornesci.pages.dev
Mirror health route: https://hornesci.pages.dev/api/v1/health

Plug-and-play web app + API

Use the hosted evaluation surface when you want the fastest way to show the workflow, telemetry, and customer-facing integration path.

Best for:
- discovery calls
- evaluation walkthroughs
- solution-engineering demos

Customer-hosted Docker package

Run the same API inside the customer environment when data residency, network control, or internal platform standards matter.

docker compose --env-file .env.customer \
  -f deploy/customer-compose.yml up -d

Custom-fit math integration

For teams that want HST embedded more directly into their own runtime, the same compile/apply contract can guide a custom integration engagement.

Compile once
Keep x_prev and y_prev in customer code
Send sparse updates
Receive y_next + route/runtime telemetry