hello

A minimal pugmark handler that does no LLM work. It walks the session log, finds the most recent input event, and appends an echo event with the text uppercased. Useful as a smoke test for verifying your install before paying for an API key elsewhere. Full source on GitHub.

Run it

pugmark run --start -b file:///tmp/pug-hello -- python examples/hello/handler.py

One command. The handler self-bootstraps: it sees the empty log on the first invocation and seeds an {"kind":"input","text":"hello world"} event, then pugmark run loops back into it, the handler appends an {"kind":"echo","text":"HELLO WORLD"}, and on the third invocation it sees its own echo and calls pugmark.pause() to break the loop. Output:

hello: replayed 0 event(s) from the log
hello: empty log, seeding demo input 'hello world'
hello: replayed 1 event(s) from the log
hello: echoing 'hello world' → 'HELLO WORLD'
hello: replayed 2 event(s) from the log
hello: echo appended, pausing

The handler

import pugmark

DEMO_INPUT = "hello world"

def main() -> None:
    events = [
        obj.decode_json()
        for obj in pugmark.read()
        if obj.content_type() == "application/json"
    ]
    match events[-1] if events else None:
        case None:
            # Empty log, so seed a demo input to keep the example self-contained.
            # In a real handler this branch would just pause.
            pugmark.write({"kind": "input", "text": DEMO_INPUT})
        case {"kind": "input", "text": text}:
            pugmark.write({"kind": "echo", "text": text.upper()})
        case {"kind": "echo"}:
            pugmark.pause("done")

The canonical pugmark handler shape, in four moves: read the log, decode each entry as JSON, dispatch on the tail with structural pattern matching, append one new event. Every other example follows the same shape, with more cases.