NAME
Langertha::Holmgang::Sim::Sehen - The answer world sehen — hand in what an image shows: graph, sequence, fields, table, values, finding
VERSION
version 0.001
SYNOPSIS
# suite.yaml: every tool names the world, the tool's name picks what it does
tools:
- { name: felder_abgeben, simulator: sehen, description: …, parameters: { … } }
# a case: the image goes with the user message, the world starts empty
state:
sehen: { type: sehen }
rules:
- title: Rechnungsdatum
state: sehen.felder.norm.datum
equals: "2024-04-03"
- title: Kante A nach B
state: sehen.graph.norm.kanten
contains: [ "a -> b" ]
my $sims = Langertha::Holmgang::Simulators->new;
my ( $output, $ok ) = $sims->tool_call( $state, sehen => bild_melden => { grund => 'unlesbar', notiz => '' } );
DESCRIPTION
A world without a device (contract: Langertha::Holmgang::Role::AnswerWorld; type sehen) for cases whose task is to read an image — a diagram, a receipt, a table, a chart, a screenshot of an error. The model hands in what it sees through one of the tools below; the world stores the answer, and the case's rules grade it at the end state. Nothing in the world knows the right answer, and no answer says whether the hand-in is right. Tool names, parameters and world keys are German, as the model sees them:
graph_abgeben { gerichtet, knoten[], kanten[{von, nach, text?}] } a graph or flow chart
ablauf_abgeben { teilnehmer[], nachrichten[{von, an, text}] } a sequence diagram
felder_abgeben { belegart, nummer, datum, lieferdatum, betrag_brutto,
betrag_netto, waehrung, iban, positionen[] } the fields of a receipt or invoice
tabelle_abgeben { kopf[], zeilen[[]] } a table
werte_abgeben { reihen[{name, punkte[{x, y}]}] } the data points of a chart
befund_abgeben { befehl, fehlercode, datei, zeile } what a screenshot of an error shows
bild_melden { grund, notiz } the image cannot be read as asked
grund (reason) of bild_melden is one of kein_diagramm (not a diagram), unlesbar (unreadable), teilweise_unlesbar (partly unreadable).
A repeated call replaces the earlier hand-in of the same tool entirely; hand-ins of different tools stand side by side. A call the world refuses (an error) changes nothing — an earlier hand-in stays.
Normalisation
Every hand-in is stored twice: as the model sent it (roh, raw) and normalised (norm), so rules compare values, not spellings. The rules (applied by the functions below, which case authors and generators may use to write expected values):
- Text ("norm_text")
-
Unicode NFC, full case folding,
ä ö ütranscribed asae oe ue(ßbecomesssby case folding), soStraße,STRASSEandstrasseare equal, andMüllerequalsMueller. Every dash and minus sign becomes-, typographic double quotes become", single quotes and apostrophes'; soft hyphens and zero-width characters are dropped; runs of white space become one space, trimmed at both ends. - Dates ("norm_date")
-
To ISO
YYYY-MM-DD. Read are ISO and year-first forms (2024-04-03,2024/04/03), the German dotted form (3.4.2024, day first), slash or hyphen forms with the year last (13/04/2024) when the day is evident, and month names in German or English (3. April 2024,April 3, 2024,3 Apr 2024,3. Jänner 2024). Ambiguous forms are refused neutrally and change nothing: a two-digit year (03.04.24), and a slash or hyphen form whose first two numbers both could be the month (03/04/2024). An impossible date (30.02.2024) is refused as well. - Amounts ("norm_amount")
-
To whole cents (an integer):
12.5,"12,50","1.234,56","1,234.56","1 234,56 €". A leading currency sign or code (€ $ £,EUR USD GBP CHF) or a trailing one is dropped — the currency is its own field. Ambiguous amounts are refused: one separator followed by exactly three digits (1.234,1,234— thousands or decimals?). More than two decimals are refused too (no cents). - IBAN
-
Compact and upper case: white space removed, letters upper case. The check digits are not verified — that would tell the model its reading is wrong.
- Currency
-
Trimmed and upper case;
€becomesEUR,£becomesGBP. Anything else stays as given (in upper case).
State
sehen:
type: sehen
graph:
roh: { gerichtet, knoten, kanten } # the arguments as sent
norm:
gerichtet: 1 | 0
knoten: [ text … ] # normalised, sorted, unique
kanten: [ "a -> b" … ] # directed; undirected "a -- b" with sorted ends; sorted, unique
beschriftungen: [ "a -> b: text" … ] # only edges with a text; sorted, unique
ablauf:
roh: { teilnehmer, nachrichten }
norm:
teilnehmer: [ text … ] # in the order given, unique
nachrichten: [ "von -> an: text" … ] # in the order given; "von -> an" without text
felder:
roh: { belegart, … }
norm:
belegart, nummer, waehrung, iban: text or null
datum, lieferdatum: "YYYY-MM-DD" or null
betrag_brutto, betrag_netto: cents (integer) or null
positionen: [ { text, menge?, betrag? } … ] # menge a number, betrag in cents
tabelle:
roh: { kopf, zeilen }
norm:
kopf: [ text … ]
zeilen: [ [ text … ] … ] # null cells as ""
zeilen_text: [ "a | b | c" … ] # each row joined, for contains
werte:
roh: { reihen }
norm:
reihen: { <name>: { <x>: y } } # x a number as text or normalised text, y a number
befund:
roh: { befehl, fehlercode, datei, zeile }
norm: { befehl, fehlercode, datei: text or null, zeile: integer or null }
meldung: # from bild_melden
roh: { grund, notiz }
norm: { grund, notiz }
The world starts as { type: sehen }; each key above appears with the first accepted call of its tool. In felder and befund every field may be null (the image does not show it); a missing key counts as null. A position may be given as a bare text. In graph and ablauf, an edge or message must name a node or participant from its own list.
Rules grade norm (sehen.felder.norm.betrag_brutto equals 11900, sehen.graph.norm.kanten contains [...], sehen.ablauf.norm.nachrichten before [...], sehen.werte.norm.reihen.umsatz.2023 equals 12), and roh when the exact spelling matters.
Only the state, deterministic, neutral.
device_type
sehen.
tools
my $tools = $world->tools; # { graph_abgeben => [qw( gerichtet knoten kanten )], … }
The tools of this world with their required parameters (for the loader).
tool
my ( $output, $ok ) = $world->tool( $sehen, $name, \%args, $ctx );
A tool call on the state of the world ($sehen is changed). A name not in "tools" is an error; an accepted call replaces the earlier hand-in of the same tool, a refused one changes nothing.
norm_text
norm_text(" Straße – „Süd“ "); # 'strasse - "sued"'
A text normalised (see "Normalisation"), or undef for undef or a reference.
norm_date
my ( $iso, $why ) = norm_date('3.4.2024'); # ( '2024-04-03' )
my ( $iso, $why ) = norm_date('03/04/2024'); # ( undef, 'mehrdeutig' )
A date as ISO YYYY-MM-DD, or undef and why: mehrdeutig (ambiguous), ungültig (no such day) or nicht lesbar (not readable).
norm_amount
my ( $cents, $why ) = norm_amount('1.234,56 €'); # ( 123456 )
my ( $cents, $why ) = norm_amount('1.234'); # ( undef, 'mehrdeutig' )
An amount in whole cents, or undef and why: mehrdeutig (ambiguous) or nicht lesbar (not readable). A JSON number and a text are read alike.
norm_number
norm_number('1,5'); # 1.5
A plain number (point or comma as decimal separator, no thousands separators), or undef.
norm_iban
norm_iban('de89 3704 0044 0532 0130 00'); # 'DE89370400440532013000'
norm_currency
norm_currency(' eur '); # 'EUR'
norm_currency('€'); # 'EUR'
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.