llm-json-repair

Repara JSON roto devuelto por LLMs y devuélvelo como dict válido. Sin dependencias (solo stdlib).

Problema que resuelve: los modelos (GPT, Claude, Llama, etc.) suelen devolver JSON con comas sueltas, comillas sin cerrar, bloques ```json incompletos, texto explicativo alrededor, literales Python (True/None), comentarios o corchetes sin cerrar. Esta librería lo repara automáticamente.

v0.2: motor FSM

Nuevo núcleo sintáctico en v0.2.0 (ver CHANGELOG.md y docs/ARCHITECTURE.md):

• Tokenizer char-by-char sin regex en el núcleo: recorre la entrada carácter a carácter, respetando strings y escapes.
• Autoclose de truncados: cierra strings, objetos y arrays incompletos ({"a": [1, 2 → {"a": [1, 2]}).
• repair_stream / parse_stream / StreamingRepairer: reparación incremental para tokens en streaming.
• repair_and_validate con Pydantic (opcional): repara y valida contra un BaseModel.
• Benchmarks con 500 casos: comparativa vs json-repair y dirtyjson (ver docs/BENCHMARKS.md).

Benchmark (resumen)

Detalle completo y metodología en docs/BENCHMARKS.md.

Compatibilidad API v0.1: repair_json(text) -> str, loads(text) -> Any y RepairError mantienen la misma firma y semántica que en v0.1.0. Lo nuevo (streaming, validation) es solo aditivo, no rompe código existente.

Ejemplo rápido

from llm_json_repair import loads

broken = '''Here is your JSON:
```json
{"name": "Ana", "tags": ['ia', 'python',], "active": True,}
'''
print(loads(broken))
# {'name': 'Ana', 'tags': ['ia', 'python'], 'active': True}

Instalación

pip install llm-output-repair

PyPI: llm-output-repair · import: llm_json_repair (el nombre PyPI estaba ocupado).

Requiere Python >= 3.9. Sin dependencias de terceros.

Desde fuente:

git clone https://github.com/sergioo7r/llm-json-repair
pip install -e .

Uso

from llm_json_repair import repair_json, loads, RepairError

# 1. Reparar a string JSON válido
fixed_str = repair_json('{"a": 1,}')
# '{"a": 1}'

# 2. Reparar + parsear a objeto Python
data = loads('{"a": 1,}')
# {'a': 1}

# 3. Manejo de errores
try:
    data = loads("esto no es json")
except RepairError as e:
    print("irreparable:", e)

• repair_json(text) -> str: devuelve string JSON válido. Lanza TypeError si la entrada no es str, RepairError si no hay objeto/array reparable.
• loads(text) -> Any: repara y parsea con json.loads. Misma semántica de errores.
• RepairError(ValueError): indica entrada irreparable (vacía, sin {/[, o inválida tras el pipeline).

Tabla de reparaciones

Ver detalle por etapa en docs/PIPELINE.md y referencia completa en docs/API.md.

Integración con OpenAI

examples/openai_integration_test.py genera respuestas con la API de OpenAI y mide la tasa de reparación por modelo. Sirve como evidencia para solicitudes de créditos y como test de regresión.

export OPENAI_API_KEY=sk-...   # Windows: set OPENAI_API_KEY=sk-...
pip install openai
python examples/openai_integration_test.py --model gpt-4o-mini --n 50
# Reparadas: 48/50 (96.0%)

Quickstart sin claves:

python examples/quickstart.py

Ver docs/OPENAI_PROGRAM.md para justificación, coste estimado y evidencias.

Desarrollo

pip install -e ".[test]"  # o: pip install pytest
pytest -q

Estructura:

src/llm_json_repair/repair.py  # pipeline de 9 etapas (stdlib only)
tests/test_repair.py           # suite unitaria
examples/quickstart.py         # demo sin API keys
examples/openai_integration_test.py  # test suite masivo con OpenAI
docs/                          # documentación extendida

Convenciones y guía de contribución en CONTRIBUTING.md. Historial de cambios en CHANGELOG.md.

Roadmap

• v0.2: streaming (reparación incremental), CLI (llm-json-repair fix), validación opcional con pydantic.
• v0.3: benchmarks multilingües y matriz de modelos ampliada, corpus de fallos reales.
• v1.0: API estable, garantía de no-regresión, política de versionado semántico.

Detalle en ROADMAP.md.

Licencia

MIT. Ver LICENSE.

FAQ

1. ¿Sustituye a json.loads? No. Úsalo como fallback: intenta json.loads primero y loads de esta librería solo si falla. Así evitas transformaciones innecesarias en JSON válido.

2. ¿Puede corromper JSON válido? El pipeline conserva el input válido intacto (test test_valid_passthrough). Las transformaciones solo actúan fuera de strings con comillas dobles.

3. ¿Qué hace si la entrada es irreparable? Lanza RepairError (subclase de ValueError). Captúrala y aplica tu política: reintentar al modelo, pedir formato estricto o registrar el fallo.

4. ¿Funciona sin internet ni API keys? Sí. Es 100 % local y sin dependencias. Solo examples/openai_integration_test.py requiere OPENAI_API_KEY.

5. ¿Soporta JSONL, YAML o streaming? No en v0.1.0. Solo un objeto/array JSON por llamada. Streaming, CLI y validación pydantic están en el roadmap v0.2.