Instruction set

The runtime understands six opcodes. Every Instruction is a dataclass with an op name and an args dict; the runtime dispatches each op to a method on Runtime.

@dataclass
class Instruction:
    op: Literal["say", "ask", "call", "tool", "set", "done"]
    args: dict

All string arguments support {var} substitution against the current runtime scope.

say

Print text via the IO adapter.

Instruction.say("Hi {name}!")

Arg	Type	Notes
text	str	Required; rendered before printing

ask

Prompt the user, bind the reply into scope.

Instruction.ask(prompt="What's your name?", var="name")

Arg	Type	Notes
prompt	str	Rendered before being shown to the user
var	str	Name of the scope key receiving the reply

call

Dispatch a rendered prompt to a registered agent.

Instruction.call(agent="writer", prompt="haiku about {topic}", var="poem")

Arg	Type	Notes
agent	str	Must match a key in Runtime.agents; raises KeyError if not
prompt	str	Rendered before calling
var	str | None	If set, the agent's return value is stored under this key

The runtime calls agent.respond(prompt, **scope). Your agent's runtime callable receives the rendered prompt plus the entire scope as kwargs, so you can access prior variables if you want.

tool

Invoke a plain Python callable registered with Runtime.register_tool.

Instruction.tool("echo", var="greeting", text="hello")

Arg	Type	Notes
name	str	Must match a key in Runtime.tools
var	str | None	Where to bind the return value
kwargs	dict	Each value is rendered as a string before being passed to the tool

set

Bind a literal value (or rendered string) directly into scope.

Instruction.set(var="lang", value="zh-CN")

Arg	Type	Notes
var	str	Scope key
value	any	If a string, rendered against scope; otherwise stored as-is

done

Halt execution early. Anything after a done is skipped.

Instruction.done()

Internally raises HaltError, which the runtime catches to stop the program.

Constructing programs programmatically

from hellig import Program, Instruction

program = Program(
    source="(manual)",
    instructions=[
        Instruction.ask("Name?", "name"),
        Instruction.say("Hi {name}!"),
        Instruction.done(),
    ],
)

Programs returned by the stub compiler look exactly like this.