NAME
Langertha::Holmgang::Structure - The shape checks of suite format 2, shared by the loader and the DSL
VERSION
version 0.001
SYNOPSIS
my $structure = Langertha::Holmgang::Structure->new;
my %head = $structure->suite_head( $suite_yaml, dirname => 'example-lamp' );
my @texts = $structure->generated( $case_yaml, 'cases/c1.yaml' ); # for the digest
my $case = $structure->case( $case_yaml,
file => 'c1.yaml',
tools => $head{tools},
defaults => $head{defaults},
);
DESCRIPTION
The strict shape checks of suite format 2 (cai-platform docs/entwurf-evals.md §3): an unknown key, a wrong type, a bad id or regular expression, a call of a tool the suite does not offer — each is a Langertha::Holmgang::Error naming the field (cases/c1.yaml: rules[0].regex). Both front ends call this module, so the DSL cannot build what the loader would refuse (ADR 0005). Lint (Langertha::Holmgang::Lint) runs after it, on every load.
The checks leave the data as written: a Langertha::Holmgang::Case holds its own values, not a normalised copy. Generated content ({ generate => … }) is resolved here once to check it, and the initial state is prepared once by the simulators to check it; both results go into the case.
simulators
The simulator registry: device types, answer worlds and their tools, prepare.
haystack
Resolves generated content; shared with the cases, so a text is generated once.
excerpt
Sets the excerpts from the suite's quellen/ into message contents (Langertha::Holmgang::Excerpt, k52).
valid_id
$structure->valid_id('example-lamp'); # 1
True for a suite, case or topic id: lower-case letters, digits, dashes, at most 64 characters, not starting with a dash. Keeps paths like ../x out.
tool
$structure->tool( $tool, 'suite.yaml: tools[0]' );
Checks one tool of the suite: name, description, parameters (the subset of Langertha::Holmgang::ToolSchema, type: object), and exactly one of simulator (run_command, write_file with their required parameters, or an answer world that knows the tool's name) or handlers.
suite_head
my %args = $structure->suite_head( $suite_yaml, dirname => $dir, format => 1 );
Checks the head of a suite and returns the arguments for Langertha::Holmgang::Suite (without cases and digest). With dirname the id must equal it; with format (the loader) the file must say format: 2, and format 1 is refused with its own reason.
generated
my @texts = $structure->generated( $case_yaml, 'cases/c1.yaml', dir => $suite_dir );
# ( [ 'cases/c1.yaml: messages[0].content', $text ], … )
The generated contents of a case — message contents, then file contents of the state by device and path — each with its field and its text, in the order the digest takes them. A message content with an excerpt ({ auszug => … }, Langertha::Holmgang::Excerpt) counts as generated: the excerpts are set in from dir first, as cai-platform does. Refuses a broken generate spec or excerpt with its field.
case
my $case = $structure->case( $case_yaml,
file => 'c1.yaml', # the id must be the file name; fields start "cases/c1.yaml"
tools => \@suite_tools,
defaults => \%suite_defaults,
dir => $suite_dir, # images are files relative to it
);
Checks one case of format 2 and returns its Langertha::Holmgang::Case. Without file, field names the start of every field path. Lint is not part of it.
dir is the suite directory, which the file of an image on a user message ("IMAGES") and the datei of an excerpt (Langertha::Holmgang::Excerpt) are relative to; a case with images or excerpts and without dir is refused.
The state must be plain data, as format 2 writes it: texts, numbers, booleans, hashes and lists. A code reference, a regular expression object, a scalar or glob reference or any other object in it is refused with its path (suite.pl: case c1: state.web.handler) -- the DSL can put one there, YAML cannot (k59).
image_file
my $info = $structure->image_file( $suite_dir, 'img/chart.png', 'cases/c1.yaml: messages[0].images[0].file' );
# { file, path, media_type, width, height, bytes, sha256 }
Checks one image file of a suite ("IMAGES") and returns what the case keeps of it; refuses with the field otherwise.
image_measure
my ( $media_type, $width, $height ) = Langertha::Holmgang::Structure::image_measure($bytes);
The media type (image/png, image/jpeg) of image bytes by their first bytes, with the width and height from the PNG header or the JPEG frame header; only the media type when the size cannot be read, an empty list for anything else.
IMAGES
A user message may carry images (k27):
messages:
- role: user
content: "Copy the table in the picture with tabelle_abgeben."
images:
- file: img/table.png
- { file: img/scan.jpg, untrusted: true }
images is a list of one to four { file, untrusted }, only on a user message. file is relative to the suite directory and must stay inside it (no absolute path, no .., no link out of it); the file must be a PNG or a JPEG by its first bytes, at most 2 MiB, with a readable width and height. untrusted: true marks the image as foreign content for the report, like a message's mark; it never goes out.
The case keeps per file its media type, width, height, size and SHA-256 ("image_files" in Langertha::Holmgang::Case); the prompt message carries the text as the first part and each image as the placeholder { image, sha256, bytes } ("prompt_messages" in Langertha::Holmgang::Case). The image bytes are read again and turned into a content part only when a request is built (Langertha::Holmgang::Runner), so no base64 sits in a case, a transcript or a report.
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/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>
COPYRIGHT AND LICENSE
This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.