Skip to content

Stub compiler syntax

StubCompiler is the default offline compiler. It does line-based parsing with a tiny declarative syntax so you can drive the runtime without an LLM.

Each non-empty, non-comment line becomes one instruction. The compiler appends a final done instruction automatically.

Lines

? — ask the user

? <question> [-> <var>]
  • Stores the user's reply in <var> (default: answer).
  • The question is rendered with the current scope, so ? Hi {name}, ready? works.
? What's your name? -> name
? Ready, {name}? -> ready

: — say literal text

: <text>
  • Prints text to the IO adapter (ClickIO by default).
  • {var} placeholders are filled from scope.
: Hello {name}!

@agent — call an agent

@<agent> <prompt> [-> <var>]
  • Looks up <agent> in the runtime, calls it with the rendered prompt, and stores the result in <var> (omit to discard).
@writer draft a haiku about {topic} -> haiku

!tool — invoke a tool

!<tool> [key=value ...] [-> <var>]
  • Tools are plain Python callables registered with Runtime.register_tool.
  • Values are passed as strings; coerce inside the tool if needed.
!echo text=Hello -> greeting

Anything else — default agent

Any line that doesn't match a directive is forwarded to the default agent (main by default) and the result is immediately printed:

write a one-line poem about Hellig

is compiled to:

call(agent='main', prompt='write a one-line poem about Hellig', var='r0')
say(text='{r0}')

Comments and blank lines

Lines starting with # are ignored. Blank lines are skipped.

Variable substitution

?, :, @, and ! all support {var} placeholders that are resolved at execution time against the runtime's scope. Missing placeholders are left as-is rather than raising — so partial templates won't crash your session.

Custom default agent

from hellig.compiler import StubCompiler
compiler = StubCompiler(default_agent="planner")

Going beyond StubCompiler

StubCompiler is intentionally simple — it exists to keep the framework runnable offline and to give you a known target output. For richer natural language understanding, plug in your own LLM-backed compiler.