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 as ae oe ue (ß becomes ss by case folding), so Straße, STRASSE and strasse are equal, and Müller equals Mueller. 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; € becomes EUR, £ becomes GBP. 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.