gateway/modules/shared/jsonContinuation-logic.md

JSON Continuation Context Module

Ein Python-Modul zur Generierung von Kontextinformationen für abgeschnittene JSON-Strings, um AI-Modellen die Fortsetzung zu ermöglichen.

Problem

Wenn eine AI-Antwort als JSON abgeschnitten wird (z.B. Token-Limit erreicht), muss die nächste Iteration wissen:

• Wo der JSON abgeschnitten wurde
• Was bereits generiert wurde
• Was als nächstes geliefert werden soll

Lösung: Drei Kontexte

1. Overlap Context

• Zeigt das innerste Objekt/Array-Element, das den Cut-Punkt enthält
• Wird verwendet, um den abgeschnittenen Teil mit dem neuen Teil zu mergen
• Exakt so wie im Original-String (für String-Matching beim Merge)

2. Hierarchy Context

• Zeigt die hierarchische Struktur vom Root bis zum Cut-Punkt
• Mit Budget-Logik: Näher am Cut = vollständige Werte, weiter weg = "..." Platzhalter
• Gibt der AI den Kontext der gesamten JSON-Struktur

3. Complete Part (NEU)

• Der vollständige, valide JSON bis zum Cut-Punkt
• Alle offenen Strukturen werden geschlossen (}, ], ")
• Unvollständige Keys werden entfernt
• Kann direkt als valides JSON geparst werden

Installation

# Keine externen Abhängigkeiten erforderlich
cp json_continuation.py /your/project/

Modulkonstanten

# Diese Konstanten können vor dem Import angepasst werden
BUDGET_LIMIT: int = 500      # Zeichen-Budget für Datenwerte
OVERLAP_MAX_CHARS: int = 1000  # Max Zeichen für Overlap Context

Verwendung

Grundlegende Verwendung

from json_continuation import extract_continuation_contexts

truncated_json = '''{"customers": [
    {"id": 1, "name": "John"},
    {"id": 2, "name": "Jane", "email": "jane@exa'''

overlap, hierarchy, complete = extract_continuation_contexts(truncated_json)

print("Overlap Context:")
print(overlap)
# {"id": 2, "name": "Jane", "email": "jane@exa

print("Hierarchy Context:")
print(hierarchy)
# {"customers": [...structure with budget logic...]

print("Complete Part (valid JSON):")
print(complete)
# {"customers": [{"id": 1, "name": "John"}, {"id": 2, "name": "Jane", "email": "jane@exa"}]}

import json
parsed = json.loads(complete)  # ✓ Funktioniert!

Mit Dictionary-Interface

from json_continuation import get_contexts

contexts = get_contexts(truncated_json)

print(contexts['overlap'])
print(contexts['hierarchy'])
print(contexts['complete_part'])

Konstanten anpassen

import json_continuation

# Budget anpassen bevor Funktionen aufgerufen werden
json_continuation.BUDGET_LIMIT = 200
json_continuation.OVERLAP_MAX_CHARS = 500

overlap, hierarchy, complete = json_continuation.extract_continuation_contexts(truncated_json)

Rückgabewerte

Rückgabe	Typ	Beschreibung
overlap	str	Innerstes Element mit Cut-Punkt (für Merge)
hierarchy	str	Volle Struktur mit Budget-Logik
complete_part	str	Valides JSON mit geschlossenen Strukturen

Beispiele

Verschachtelte Objekte

json_str = '{"user": {"profile": {"bio": "Hello Wor'

overlap, hierarchy, complete = extract_continuation_contexts(json_str)

# Overlap: {"bio": "Hello Wor
# Hierarchy: {"user": {"profile": {"bio": "Hello Wor
# Complete: {"user": {"profile": {"bio": "Hello Wor"}}}  ← Valides JSON!

Array von Objekten mit unvollständigem Key

json_str = '''{
  "items": [
    {"id": 1, "name": "First"},
    {"id": 2, "name": "Second"},
    {"id": 3, "name": "Third", "add'''

overlap, hierarchy, complete = extract_continuation_contexts(json_str)

# Complete entfernt den unvollständigen Key "add":
# {"items": [{"id": 1, ...}, {"id": 2, ...}, {"id": 3, "name": "Third"}]}

Budget-Logik

Die Budget-Logik funktioniert wie folgt:

1. Sammeln: Alle String-Werte werden mit ihrer Position gesammelt
2. Sortieren: Nach Entfernung zum Cut-Punkt (näher = höhere Priorität)
3. Zuweisen: Budget wird von hinten nach vorne aufgebraucht
4. Ersetzen: Werte außerhalb des Budgets werden durch "..." ersetzt

Tests ausführen

python -m unittest test_json_continuation -v

API Referenz

extract_continuation_contexts(truncated_json: str) -> Tuple[str, str, str]

Hauptfunktion. Gibt (overlap, hierarchy, complete_part) zurück.

get_contexts(truncated_json: str) -> dict

Convenience-Funktion. Gibt Dictionary mit Keys 'overlap', 'hierarchy', 'complete_part' zurück.

Modulkonstanten

• BUDGET_LIMIT: int (default: 500) - Zeichen-Budget für Hierarchy-Context
• OVERLAP_MAX_CHARS: int (default: 1000) - Max Zeichen für Overlap-Context