NAME

Langertha::Holmgang::Case - One case of a suite: its own format 2 values and what derives from them

VERSION

version 0.001

SYNOPSIS

my $case = $suite->cases->[0];

$case->id;                         # 'c1'
$case->rules;                      # as format 2 writes them
$case->effective('max_turns');     # own value, else the suite's default, else 12
$case->prompt_messages;            # [ { role, content } ] — generated text resolved, no untrusted mark
$case->has_images;                 # a user message carries images (k27)
$case->image_content('img/a.png'); # a Langertha::Content::Image, read when a request is built
$case->initial_state;              # the state the world starts from
$case->tier;                       # '48k' from the tag stufe-48k, or undef
$case->is_hard;                    # tag injection or verbot
$case->has_untrusted;              # a message or state hash marked untrusted
$case->no_tool;                    # solution: [] — the "no tool" family

DESCRIPTION

A case holds only its own values, exactly as format 2 writes them (ADR 0005): rules, handlers, expectations, tool calls and the state stay plain hashes and lists, generated content ({ generate => … } or a list of parts) stays the spec. A key the case does not have is undef. What derives from them — the effective settings, the resolved texts, the length tier, the hard and untrusted marks — comes from methods, never copied in, so an export writes back what was written.

Cases are built by Langertha::Holmgang::Structure, which checks the shape first; the loader and the DSL both go through it.

id

Required. [a-z0-9-], the file name without .yaml in format 2.

title

Required. The case's title, a non-empty text.

tags

A list of texts, or undef; "tier" and "is_hard" read them through "tag_list".

difficulty

leicht, mittel or schwer, as format 2 writes it.

system

The case's own system prompt; "effective" falls back to the suite's.

messages

[ { role, content, untrusted, images } ] as written; content may be a generate spec, images a list of { file, untrusted } on a user message (k27). What goes out is "prompt_messages".

state

The world as written (devices keyed by host name). The world starts from "initial_state".

observe

The observations as written: [ { match, when, output, error } ], answers to diagnostic commands that may depend on the state but never change it.

rules

The rules as written; the grader checks them on the end state, and a case passes when every required one is met.

solution

A list of { tool, args }; [] in the "no tool" family.

alternatives

Other correct paths, [ { title, calls } ]; lint replays each and it must pass like the reference solution.

wrong_solutions

[ { title, calls } ].

temperature

The case's own temperature (0..2) or undef; "effective" falls back to the suite's default, else 0.

max_tokens

The case's own token limit per turn (1..200000) or undef; "effective" falls back to the suite's default, else 2000.

max_turns

The case's own turn limit (1..50) or undef; "effective" falls back to the suite's default, else 12.

source

Where the case comes from, { title, authors, license, url, location }, or undef.

weight

Optional positive number (ADR 0005); "effective_weight" is 1 without it.

tools

The suite's tools, in the order they are offered to the model (by name, as in cai-platform). Context, not a value of the case.

defaults

The suite's defaults (system, temperature, max_tokens, max_turns). Context, not a value of the case.

simulators

The simulator registry that prepares the initial state.

haystack

The generator of long content (Langertha::Holmgang::Haystack).

initial_state

The state the world starts from: a copy of "state" with generated file contents resolved, prepared by each device's simulator (the running values a service read from its files at boot). Built when first needed; the structure check hands it in after checking it.

prompt_messages

The messages as they go to the model: role and content only, generated content resolved, the untrusted mark left out. A message with images (k27) has a list as content: the text as { type => 'text', text }, then one placeholder { image, sha256, bytes } per image -- the form a transcript and a report keep (ADR 0006). The runner turns each placeholder into a content part with "image_content" only when it builds a request.

image_files

What the structure check read of the images of the user messages (k27), keyed by the file as written: { file, path, media_type, width, height, bytes, sha256 }, path being the file on disk. Derived, never written back; empty for a case without images.

has_images

True when a user message of the case carries an image.

image_content

my $part = $case->image_content('img/chart.png');   # Langertha::Content::Image

The image as a Langertha::Content::Image for a request, read from disk on first use and kept for the case's later requests. Croaks when the bytes no longer have the SHA-256 the case was loaded with -- what was linted and digested is what goes out. Langertha turns it into each engine's own image part (OpenAI image_url, Anthropic image, Gemini inline_data ...).

effective

$case->effective('temperature');

The value of a setting (system, temperature, max_tokens, max_turns): the case's own, else the suite's defaults, else the built-in one ('', 0, 2000, 12).

effective_weight

The case's weight, 1 without one.

tag_list

The tags as a list.

tier

The length tier from the tag stufe-<tier> (16k, 48k, 96k, 160k), or undef — one value in list context too, so { tier => $case->tier } keeps its pairs. The tag ctx-<N>k names the context window a case is meant for, not its input length, and is no tier (ADR 0008, k56).

is_hard

True for a case tagged injection or verbot: one forbidden call fails the suite's verdict.

has_untrusted

True when a message, an image of a message or a hash in the state is marked untrusted: the case carries foreign content, and injection_held is defined for it.

no_tool

True in the "no tool" family: solution: [], where doing nothing is right.

report_meta

$report->add_run( ..., cases => [ map { $_->report_meta } @{ $suite->cases } ] );

The case meta "add_run" in Langertha::Holmgang::Report takes, as a new hash: case_id, title, tags, tier, difficulty, weight (the effective one), hard, untrusted.

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.