Documentation

1. Install

The CLI is a thin client — no engine on your machine.

pip install hexstellar

2. Authenticate

Create a key in API keys, then store it once.

hexstellar login --key YOUR_KEY

3. Solve

echo '{"n":4,"edges":[[0,1,1],[1,2,1],[2,3,1],[3,0,1]]}' | hexstellar solve maxcut --format json

Or straight over HTTP:

curl -sS https://admin.hexstellar.com/api/v1/solve/maxcut \
  -H "Authorization: Bearer $HEXSTELLAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"n":4,"edges":[[0,1,1],[1,2,1],[2,3,1],[3,0,1]]}'

4. Every mode

One API, one JSON-in / JSON-out contract, across every mode below. Start with a core solver; reach for rules when a real problem has real constraints; the science and reliability modes are there when you need them. An answer is a certified optimum when the space was checked in full, and a strong hypothesis when it was too large — always labelled.

5. Read the answer

Every response carries a certainty label. Treat a certified answer as proven, and a heuristic one as a strong hypothesis to verify.

6. Errors & backpressure

7. Model versions — pin the math

Cortex ships frozen model versions, the way an LLM ships gpt-4o / claude side by side — a released model is never overwritten. Pin cortex-1.0 and the math is byte-stable forever (your automated tests never break under the hood); use cortex-latest to always ride the newest. The response echoes the resolved version; an unknown version is a clean error, never a silent switch.

hexstellar models                                          # the catalogue
echo '{...}' | hexstellar solve maxcut --model cortex-1.0   # frozen math, forever
# HTTP: "version":"cortex-1.0" in the body, or ?version=cortex-1.0 · GET /api/v1/models

8. Latency budget — never a hung request

Every solve runs under a wall-clock budget. If the search reaches it, the service returns the best answer found so far — marked stopped_at_deadline: true and certainty: "heuristic — verify" — never a dropped connection, never a fabricated “certified”. Set your own budget below your client's timeout so you always get a usable answer back in time. You can ask for less than the service ceiling, never more.

echo '{"n":2000,"edges":[...]}' | hexstellar solve maxcut --effort max --max-latency-ms 5000
# → answer + cut_value, stopped_at_deadline: true, latency_budget_ms: 5000

Over HTTP: ?max_latency_ms=5000 or {"contract":{"requirements":{"max_latency_ms":5000}}}. The response echoes latency_budget_ms and stopped_at_deadline.

9. For AI agents

The CLI carries a machine-readable spec, and hexstellar spec / hexstellar prompt fetch the latest live version from the docs site every run (so your agent is never out of date), falling back to the bundled copy offline — add --offline to force the bundled one.

hexstellar capabilities   # every command + input schema (bundled)
hexstellar spec           # the exhaustive agent specification (live — always current)
hexstellar prompt         # a drop-in system prompt for your agent (live)
hexstellar examples       # ready-to-run problem templates