a2ui-project / a2ui-project/a2ui
fix(sdk): auto-heal and normalize protocol version in DirectJsonParser
- 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
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