NAME
Langertha::Raider::CLI::Machine - Internal writer of the raider CLI's machine output (JSON, MessagePack, YAML)
VERSION
version 0.503
SYNOPSIS
# Internal to Langertha-Raider -- no API promise.
my $machine = Langertha::Raider::CLI::Machine->new(format => 'json', stream => 1);
$machine->event('run.started', engine => 'openai', model => 'gpt-4o-mini');
$machine->finish($machine->document(completed => response => 'hi', elapsed => 1));DESCRIPTION
Internal module. Its interface may change without notice.
The machine output of raider (ADR 0013): one format-independent model -- the run's document and, when streaming, the events leading up to it -- written in one of three encodings. The model is built as plain Perl data; "encode" turns it into octets for the chosen "format". The reference of the format itself is the POD of raider.
Before encoding, the data is normalized through JSON, so a value is a number, a string or a boolean exactly as the JSON encoding would write it -- the same fields and types in every encoding.
format
json, msgpack or yaml. Required.
stream
True for the --stream-* flags: "event" writes every event, and "finish" writes the document as the run.finished event. False writes only the document, once, at "finish".
version
The format version written into the document and every event. Only 1 exists; see "versions".
out
Filehandle the octets are written to. Defaults to STDOUT. It is switched to :raw before each write.
clock
Code reference returning the current time as epoch seconds, for the time of an event. Defaults to "time" in Time::HiRes.
max_content_length
How many characters of a tool.result's text an event carries in content; a longer text is cut and the event flagged truncated. Defaults to 1000.
versions
my @known = Langertha::Raider::CLI::Machine->versions; # (1)The format versions this raider can write.
document
my $doc = $machine->document(completed => response => $text, metrics => $m, elapsed => $s);
my $doc = $machine->document(failed => error => $message, elapsed => $s);The document of a finished run: version, status and the given fields.
event
$machine->event('tool.call', name => 'bash', arguments => { command => 'ls' });Writes one event -- the payload plus version, type, seq and time -- when "stream" is on; does nothing otherwise. The content of a tool.result is cut to "max_content_length" characters, with truncated telling whether it was.
finish
$machine->finish($doc);Writes the run's document: as the run.finished event when streaming (its payload is the document), otherwise as the one document of the run.
write
Encodes the data with "encode" and writes it to "out", flushed.
encode
my $octets = $machine->encode($data);The data normalized and encoded for "format": a pretty-printed canonical JSON document or one compact line per event, a MessagePack object with text as UTF-8 str, or a YAML document starting with ---.
normalize
The data after a round trip through JSON: numbers, strings and booleans (JSON::PP::Boolean) as JSON sees them, text as characters.
SEE ALSO
SUPPORT
Issues
Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-raider/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
AUTHOR
Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.