a2ui-project / a2ui-project/a2ui

fix(sdk): auto-heal and normalize protocol version in DirectJsonParser

Offen Anfängerfreundlich
#2,599 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
P2
Vorherrschende Sprache
TypeScript
Sterne
16.4k
Forks
1.3k
Ø Merge
3 T. 15 Std.
Gemergte PRs (30 T.)
134

Beschreibung

### Description

In the Direct JSON inference format (`DirectJsonFormat`), the LLM directly emits raw A2UI JSON message streams. The A2UI protocol schemas strictly require a top-level `"version"` property with a leading `'v'` (e.g., `"v0.9"`, `"v0.9.1"`, `"v1.0"`).

Because standard software version conventions use numeric strings (e.g. `"0.9"`, `"1.0"`), and system prompt workflow rules do not heavily emphasize envelope version string trivia, LLMs frequently omit the leading `'v'` (emitting `"version": "0.9"`) or omit the `"version"` property altogether. This causes non-deterministic schema validation failures (e.g., recent CI evals failure in #2594 where 5 samples failed solely due to `'0.9' is not one of ['v0.9', 'v0.9.1']`).

In contrast, other inference format compilers (`ExpressCompiler`, `ElementalCompiler`, `AtomCompiler`) deterministically inject the canonical target protocol version into compiled message payloads rather than burdening the LLM with envelope version formatting.

### Proposed Solution

1. **Auto-heal / Normalize Version in `DirectJsonParser`**:
- In `DirectJsonParser.compile()` (and `parse_and_fix`), check each compiled A2UI message dictionary.
- If `"version"` is missing the leading `'v'` (e.g. `"0.9"`, `"0.9.1"`, `"1.0"`), normalize it to `"v0.9"`, `"v0.9.1"`, or `"v1.0"`.
- If `"version"` is omitted entirely, deterministically inject the target protocol version associated with the catalog/format (e.g. `f"v{catalog.version}"`).
2. **Harmonize Evaluation & Specialist Parsing**:
- Ensure `subagent_tool` and evaluation scorers rely on `DirectJsonParser.compile()` so that syntax healing (smart quotes, trailing commas, and version normalization) is consistently applied.

### Related
- Relates to #2594

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

The issue is in the DirectJsonParser's compile and parse_and_fix methods. Look for the DirectJsonParser class in the codebase, likely in a file like `src/sdk/parser/direct_json_parser.ts`. Examine how it processes A2UI message dictionaries. The fix involves checking the 'version' property, adding a leading 'v' if missing, or injecting the catalog version. Run existing tests for the parser to ensure the normalization works.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Bereich
backend-api-design
Issue-Typ
Bug
Schwierigkeit
2/5
Geschätzter Aufwand
1-3 Stunden
Aktivitätsstatus
Aktiv
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
75/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.