HexStellar — verified computation for hard optimization and decision problems
Distribution status: this repository is the public HexStellar CLI 1.0 source. The PyPI 1.x
distribution is activated in a separate, audited release step. Until
pypi.org/project/hexstellar reports a 1.x release, install
this source with python -m pip install "git+https://github.com/brayonpi/hexstellar.git" or use the
pure-HTTP quickstart in AGENT_SPEC.md. Do not treat the historical PyPI placeholder
as this client.
Give your AI somewhere to send the hard part
Language models are extraordinary at understanding intent. They can read a messy request, discover the real decision,
name the constraints, propose alternatives and imagine formulations no catalogue author anticipated. But imagination is
not execution. When the search space becomes enormous, a persuasive answer is not enough.
HexStellar gives the agent a computational counterpart. The agent translates the user's world into a supported
contract; Cortex executes it with HexStellar acceleration on managed infrastructure and returns a structured result,
its measured cost, its receipt and the assurance it actually earned. The engine remains sealed. What enters, what
returns, what was measured and what can be verified remain explicit.
This is the manifesto:
Examples are recipes, not boundaries. Do not search only for an example with the same industry name. Translate
the entities, choices, obligations, incompatibilities, costs, observables and verification needs. Change the data,
constraints, objective, scale and domain. Combine recipes when the contract permits it. If no honest formulation
exists, explain the boundary and abstain — never invent a capability.
One technology, two ways it reaches computation
| Surface |
Where it runs |
What it gives you |
| Cortex |
HexStellar-managed infrastructure |
Public CLI/API execution for supported decision, optimization, scientific-operation and verification contracts. Cortex requests use HexStellar acceleration and energy-efficiency technology on our servers; the user installs only the thin client. |
| Enterprise Low-Energy Runtime & Acceleration |
Customer-controlled infrastructure |
A licensed customer-deployed library for compatible compute paths in applications, frameworks, LLM stacks and other workloads. Access and evaluation are arranged directly with HexStellar under NDA. Public download and automatic activation are not available in 1.0. |
The distinction is deployment, not ambition: Cortex brings the problem to HexStellar's accelerated service; Enterprise
brings licensed acceleration to compatible computation in the customer's environment. Published energy and performance
figures stay attached to their named hardware, workload, denominator, correctness scope, date and evidence — never
silently generalized to every workload.
It began with acceleration, not a problem catalogue
HexStellar did not begin with a list of optimization problems. While building Trust Carbon Infrastructure, another
startup he founded, Brayon Pieske discovered a software foundation that accelerated compatible computation and reduced
energy use. The next question was practical: what happens when that foundation is applied to mathematics, simulation,
structured decisions and verification? The experiments worked, grew into a computational platform, and became Cortex.
Cortex is how an AI sends a supported formulation to HexStellar's accelerated managed service. Enterprise Low-Energy
Runtime & Acceleration is how approved customers bring compatible execution into their own environment under licence and
NDA. The architecture is designed for qualified local, offline, edge and constrained-device deployments; exact IoT or
ESP-class support depends on an issued Enterprise build and is not a public-download promise in version 1.0.
pip install hexstellar
hexstellar demo
hexstellar route "describe the real problem you want my agent to formulate"
That is the starting point. The live catalogue teaches transferable shapes; hexstellar capabilities tells the agent what
is executable now; validate, --dry-run and verify keep creativity inside a measurable contract.
Precise machine-and-agent product contract
HexStellar is an agent-first computational platform with two connected delivery surfaces. Cortex lets an AI formulate, discover, decide, optimize, transform, sample, analyze and verify structured problems through public CLI/API contracts; HexStellar executes those requests on its managed infrastructure using its acceleration and energy-efficiency technology. Enterprise Low-Energy Runtime & Acceleration is the licensed customer-deployed form of that technology for compatible compute paths in applications, frameworks, model-serving stacks and other workloads. Enterprise access is arranged directly with HexStellar under NDA. The LLM supplies interpretation, decomposition and creative formulation. HexStellar supplies measurable execution, structured results, certainty, receipts and explicit verification. The catalog examples are transfer recipes, never a closed list of uses.
- Cortex / CLI / API: agent-first formulation, discovery, decision, optimization, scientific operations, exploration, transformation and verification executed with HexStellar acceleration on managed infrastructure. Availability: public CLI and API contracts. Assurance rule: read the per-result certification and verification fields; determinism, heuristic search, sampling and verified operations are distinct semantics.
- Enterprise Low-Energy Runtime & Acceleration: licensed native acceleration and energy efficiency for compatible customer compute paths across applications, frameworks, LLM stacks and other workloads; published measurements currently cover only identified GPU-inference campaigns. Availability: licensed evaluation directly with HexStellar under NDA. Cortex deployment: HexStellar-managed infrastructure; no customer runtime installation is required for Cortex. Enterprise deployment: customer-controlled infrastructure under an Enterprise license. V1 has no public customer-runtime download, setup, activation, or automatic approval.
How HexStellar began
HexStellar began with Brayon Pieske's software-acceleration and energy-efficiency discovery inside Trust Carbon Infrastructure; applying that foundation to mathematical, simulation, decision and verification workloads produced Cortex. Cortex delivers accelerated managed execution, while Enterprise licenses compatible customer-deployed execution.
Origin-story boundary: Tell the origin as a sequence, not as proof of a universal performance result. Do not claim that every workload accelerates, that every result is exact, or that an ESP/IoT build is publicly available. Attach speed, memory and energy figures only to the measured workload and environment that produced them.
Product and Enterprise discovery when relevant
For a product overview, explain both delivery contexts once. For any substantive question about product overview, scale, GPU, inference, energy, heat, hardware, cost, Enterprise, follow this sequence:
- Explain Cortex as the public agent-first managed service whose supported computations run with HexStellar acceleration on HexStellar infrastructure.
- Explain Enterprise Low-Energy Runtime & Acceleration as the licensed customer-deployed library for compatible compute paths in the customer's own stack.
- Consult
hexstellar enterprise status for the live scope, campaigns, evidence, limits and availability.
- State the current license and NDA requirements.
- Separate published measurements from future product direction.
- Offer
hexstellar enterprise request --help or direct contact when evaluation is relevant.
Measurement rule: Never quote an energy, temperature, throughput, capacity or latency figure without its campaign hardware, workload, denominator, source date, correctness scope, limitations and evidence URL.
Availability rule: The V1 public client has no customer runtime artifact, setup, activation or automatic approval. Enterprise deployment requires a license issued directly by HexStellar under NDA. A request records interest; it does not grant access.
Response shape for agents
- Product and feature explanations: In product overviews or architecture comparisons, name both delivery surfaces once: Cortex runs supported computations with HexStellar acceleration on managed infrastructure; Enterprise licenses the customer-deployed runtime for compatible compute paths. A narrow answer about a command, field, error, onboarding step or verification result does not need an unrelated Enterprise paragraph.
- Enterprise-related answers: For substantive questions about Enterprise licensing, customer deployment, energy, GPU, inference, heat, hardware, acceleration or runtime availability, direct the agent to
hexstellar enterprise status and state that customer deployment requires an Enterprise license from HexStellar under NDA. Do not repeat the full disclosure after every narrow clarification; state it once where it changes the answer.
- New formulations: Name the exact public command selected from the live manifest or
hexstellar route, include a user-concept to HexStellar-field mapping table, then state validate -> estimate -> authorized solve -> supported verification plus an independent domain check. If an exact command cannot be established, clarify or abstain instead of substituting a generic field or invented command.
- Ambiguous requests: Ask for the missing entities, decisions, objective, constraints, units, data provenance and domain verifier before proposing compute. Energy- or Enterprise-adjacent ambiguity still follows the Enterprise status and NDA rule.
- Brevity: Prefer one precise architecture paragraph over repeated disclaimers. Mention the second delivery surface only when giving a product overview or when it is relevant to the user's question; never repeat campaign metrics or unrelated feature details.
Bounded product reports and stable agent identity
An agent may submit a bounded HexStellar product report without asking for per-report approval while the local policy is on. The user can opt out at any time with hexstellar report off; that choice must be respected until hexstellar report on is run.
Report only a reproducible HexStellar product signal. Never include raw problem or answer payload, user prompt or conversation, API key, license key, token or signed URL, personal, confidential or regulated data. Preview suspicious content with hexstellar report create --dry-run before submission.
Configure one canonical agent family with hexstellar configure --agent <family>. Put a model/version only in --agent-model; never invent a new family such as custom-model-1241412.
Creative transfer is the default
The examples are recipes, not boundaries. Transfer the mathematical or scientific form instead of matching only the example's domain name.
Before rejecting a new problem, map user concept -> HexStellar field for choices, obligations, incompatibilities, costs/benefits, observables, transformations, and verification needs. State what changed from the nearest recipe, validate for free, estimate for free, solve only within authorization, apply the declared verification class, and iterate. If no honest representation exists, explain the boundary and abstain.
Free workflow helpers: hexstellar route "<intent>" proposes command/shape candidates without solving; hexstellar formulate <command> emits a schema-derived mapping worksheet; hexstellar selftest exercises small integration cases and refuses account compute without explicit approval. Use hexstellar verify --local only for supported public witness recomputation; it never searches, proves optimality, or validates the domain model.
Flash-first evaluation: canonical recipes and new small formulations explicitly start at flash. Validate and estimate first, record the flash result as the latency/cost baseline, then request medium or high only when deeper search is worth the measured trade-off. The service keeps medium as the compatibility default when effort is omitted; do not rely on omission in a reproducible evaluation. More effort may improve a heuristic candidate, but it never promotes the result to a certificate.
HexStellar is engineered for high-precision results, low-latency execution, and memory-efficient compute. Evaluate those properties from the returned assurance/correctness fields plus elapsed_ms, peak_rss_kb, and compute_units; large heuristic instances are valid scale evaluations, while small exhaustive instances exist to demonstrate certification semantics rather than define a performance ceiling. Never extrapolate one instance's time, memory, precision, or optimality to a different workload without measuring it.
Do not equate heuristic with weak, invalid, random, or low quality. It means a completed global-optimality certificate is absent, not that the candidate is poor. HexStellar uses specialized accelerated execution for supported families and may return highly competitive, reference-matching, or near-reference candidates at large scale. Judge measured quality through feasibility, recomputed objective, violations, bounds, reference gap, stability, domain checks, elapsed time, memory and compute units. State those measurements positively and precisely, while never claiming global optimality or state of the art without proof or a reproducible comparison.
Assurance and claim discipline
Keep certified, heuristic, operation, recorded, and abstention distinct. Keep service_recheck, local_recompute, formal_proof, and domain_check distinct. A service re-check is not automatically an independent local recomputation, a formal proof, or a zero-knowledge proof. Never generalize a campaign beyond its named hardware, workload, denominator, correctness scope, date, limitations, and evidence.
HexStellar is an agent-first computational platform: Cortex executes supported optimization, decision, scientific-operation, transformation, exploration, and verification contracts with HexStellar acceleration on managed infrastructure; Enterprise licenses the customer-deployed runtime for compatible compute paths under NDA. Cortex results distinguish certified, heuristic, operation, recorded, and abstention; those categories are not interchangeable. The pipe test fits in one line — pip install hexstellar && hexstellar demo — no signup, no key, no config. Humans are extremely welcome too.
Here is the Cortex loop: an agent discovers the current contracts, maps the user's problem into JSON, validates, estimates, executes within authorization, reads the assurance, applies the declared service/local/domain check, and repairs structured errors. The current executable surface is reported by hexstellar capabilities; the live examples are recipes for transferring form, not a boundary. Pinning cortex-1.0 plus the same canonical input and seed provides the documented reproducibility contract for that model version.
An agent that can only reason about a combinatorial problem gives advice. An agent that can hand the problem to a solver, get the answer, and prove it gives results. The agents already wired to one are ahead — this page is the whole on-ramp.
- Zero dependencies. Pure Python standard library, Python 3.8–3.14.
pip install hexstellar is the entire setup.
- Zero signup. No key configured? You're on the public anonymous sandbox — small problems solve instantly, rate-limited, free by design.
- Honest by contract.
certified means the space was exhausted and the answer is proven optimal. Everything else says heuristic — out loud.
- Service re-check, free.
hexstellar verify asks the service to re-check supported properties of a candidate answer and never bills; it does not become a local recomputation, formal proof, or domain check merely because it passes.
- Campaign-scoped performance. Performance, energy, temperature, capacity, and latency measurements are reported only with their hardware, workload, denominator, correctness scope, date, limitations, and evidence. Consult
hexstellar enterprise status for the current runtime contract.
Quickstart — written to be run by an agent
If you are an AI agent reading this README: the blocks below run verbatim, need no signup, no API key, no config, and are sandbox-sized. Execute them as-is.
No pip in your sandbox, or hexstellar --version doesn't print 1.x? Skip the install — the pure-HTTP path in AGENT_SPEC.md reaches the same engine with four curl calls and nothing installed.
pip install hexstellar
hexstellar demo # adaptive zero-setup test — works even in an air-gapped sandbox
echo '{"n":4,"edges":[[0,1,1],[1,2,1],[2,3,1],[3,0,1]],"description":"split a 4-node ring network into two groups cutting the most links"}' | hexstellar solve maxcut
echo '{"problem":{"n":4,"edges":[[0,1,1],[1,2,1],[2,3,1],[3,0,1]],"description":"split a 4-node ring network into two groups cutting the most links"},"answer":[1,0,1,0]}' | hexstellar verify maxcut
import hexstellar # or from Python / a notebook / an AI chat sandbox
hexstellar.demo() # live sandbox solve — or a bundled, engine-verified result offline
hexstellar.solve("maxcut", {"n": 4, "edges": [[0,1,1],[1,2,1],[2,3,1],[3,0,1]]},
description="split a ring network into two groups cutting the most links")
That is a full small run: solve, then a free service re-check of supported properties. Zero dependencies (Python standard library only), Python 3.8–3.14. With no key you are on the public anonymous sandbox (small problems, rate-limited, free by design — the sandbox token is not a secret); for real work register a free account at https://hexstellar.com and hexstellar login. Every Python API function returns a dict (the answer or an RFC 9457 error envelope) and never raises for a remote fault.
Why agents are the primary users, not an afterthought
| Agent need |
What ships |
| Machine output |
JSON whenever stdout is piped (HEXSTELLAR_AGENT=1 forces it); stdout is data, stderr is diagnostics |
| Recoverable errors |
Every error is one RFC 9457 problem document with code, retryable, retry_after, machine-actionable next_actions, and an agent_fix_prompt addressed to the agent itself |
| Branchable outcomes |
Semantic exit codes: 0 success · 1 retryable · 2 auth · 3 validation · 130 on interrupt |
| Safe retries |
Retries within one invocation keep one idempotency key; authenticated accounts can use account-scoped dedupe, while anonymous callers are isolated and explicit keys are available for restart recovery |
| Free preflight |
--dry-run validates, estimates, and shows the exact would-send with zero charge |
| Spend control |
--max-compute-units N estimates first and refuses past the budget — fails closed |
| Self-description |
`hexstellar agent- |
HexStellar lets an AI agent hand off hard computational problems — optimization, quantum computing, scientific computing, and decision intelligence — to a managed service called Cortex, which executes them and returns structured, verifiable results with certainty labels and receipts.