HEXIS

Why hexis

An agent skill (a SKILL.md document) tells an agent how to carry out a class of tasks. In the usual way of
executing a skill, the document sits in the model's context and the model chooses every next step, so
requirements that the document states clearly can still be skipped, reordered or applied in the wrong situation.

hexis compiles the skill into an extended finite state machine. The machine records progress in a current
state and a set of variables, executes the operation assigned to the current state and evaluates transition
guards over the recorded values to decide what comes next. Language models do the reasoning and generation inside
states, with the state's prompt and the variables it reads; the order of operations is enforced by the program.

Installation

pip install hexis-agent             # the package is imported as `hexis`; the command is `hexis-agent`
pip install .                       # from a checkout; Python >= 3.11
pip install -e ".[dev]"             # with pytest, build, twine and ruff for development

Running machines on real tasks also requires:

Requirement	Used for
An OpenAI-compatible chat endpoint	model calls (see Configuration)
OpenCode on PATH	native tool execution (--executor local runs bash without it)

Quick start

The package ships a small hermetic example skill, table_clean, with scripted tools and a scripted model, so a
machine runs without network access:

from hexis.execution import runtime
from hexis.examples import table_clean as tc

machine = tc.reference_machine()
task = tc.gen_tasks(1, seed=0)[0]
result = runtime.run_task(
    machine, task,
    model=tc.build_model(),
    tools=tc.build_registry(tc.MemFS(task["files"])),
    doc=tc.skill_doc(),
)
print(result.stopped, " -> ".join(result.path()), tc.verify(task, result.trace))
# terminal s1 -> s2 -> s4 -> end True

With a real skill and a model endpoint:

export API_KEY=...                         # or put MODEL / BASE_URL / API_KEY in a .env file
M="--model qwen3.6-flash --base-url https://your-endpoint/v1"

# 1. compile a machine from the skill document
hexis-agent compile --skill path/to/skill --out build/ $M

# 2. fold execution traces of the skill into the machine
hexis-agent update --build build/ --traces traces/ --show 3    # preview: no model calls, nothing written
hexis-agent update --build build/ --traces traces/ $M

# 3. use the machine
cat build/GUIDE.md                          # how the machine works; build/PROMPT.md is the agent prompt
hexis-agent run --machine build/ --input request="..." --workdir work/ --executor local $M