# 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

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

## Modulkonstanten

```python
# 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

```python
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

```python
from json_continuation import get_contexts

contexts = get_contexts(truncated_json)

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

### Konstanten anpassen

```python
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

```python
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

```python
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

```bash
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