mini-format
Instalar

docs / Biblioteca Python

Biblioteca Python (minifmt 1.3.3)#

Implementación de referencia. Sin dependencias en tiempo de ejecución; tiktoken es opcional para contar tokens.

API pública#

from minifmt import (Contract, Field, MiniError, MiniValidationError, Document,
                     parse, dumps, detect_prefix, Registry, spec_block, parser_prompt,
                     canonical_equal, roundtrip_ok, __version__, SPEC_VERSION)
Función Qué hace
Registry.load(dir=…) Descubre forks/*/contract.json; reg.get("a") devuelve el Contract.
parse(text, contract, strict=True) Analiza y valida. Estricto: lanza MiniValidationError con todos los errores. Tolerante (strict=False): devuelve Document con records válidos y errors.
Document.to_canonical() JSON canónico: {"prefix", "header", "<records_key>": [...]}.
dumps(obj, contract) Canónico → .mini.
spec_block(contract, lang="en"|"es") Bloque de especificación para el prompt del modelo.
parser_prompt(contract, fixtures, lang) Prompt para que un modelo escriba un parser de la familia.
roundtrip_ok(obj, contract) parse(dumps(obj)) == obj y serialización estable.
detect_prefix(text) Prefijo declarado en la cabecera, sin validar.

MiniError#

Campos: code, line (1-based, 0 = documento), message, field. str(e) produce E10 line 3 [level]: …. Los códigos están en el índice de errores.

Modo tolerante#

doc = parse(texto, c, strict=False)
doc.records          # solo los válidos, con tipos del contrato
doc.errors           # lista de MiniError
doc.record_lines     # línea física de cada registro aceptado
doc.diagnostics()    # informe con las líneas a regenerar (mismo que `mini diagnose`)

Lectura en streaming#

from minifmt import read_records, create_reader
for item in read_records(fragmentos, c):   # str o bytes UTF-8, partidos en cualquier punto
    procesar(item.record, item.line)        # se emite al cerrarse la línea del registro

read_records produce los mismos registros y errores que parse y no retiene los registros, por lo que la memoria no crece con el tamaño del documento. create_reader(c) ofrece push(fragmento) y end() para integrarlo con la respuesta en streaming de un modelo.

Contratos desde JSON Schema y Pydantic#

from minifmt import from_json_schema, to_json_schema, from_pydantic
c = from_json_schema(esquema, "tk")         # registros de un nivel (SPEC §12)
esquema = to_json_schema(c)                 # ida y vuelta sin pérdida mediante anotaciones x-mini
c = from_pydantic(Modelo, "job")            # pydantic es opcional

Las propiedades requeridas pasan al núcleo y las opcionales a las extensiones; format: date produce el tipo date. Una estructura con más de un nivel de anidación se rechaza con E20, citando SPEC §12.

Reparación selectiva y proveedores#

from minifmt.ai import repair_request, merge_repair
from minifmt.ai.adapters import get_adapter
req = repair_request(respuesta, c, "es")    # solo las líneas inválidas, con sus códigos
if req.needed:
    modelo = get_adapter("openai", "gpt-5-mini")        # también "anthropic", "groq" o "simulado"
    reparada = modelo.generate(req.system, req.user, max_tokens=req.max_tokens_hint * 2, temperature=0)
    fusion = merge_repair(respuesta, reparada["text"], c, req)   # acepta cada corrección solo si es válida

Cambiar de proveedor no modifica el contrato ni el resto de la integración. Una demostración sin conexión del flujo completo se ejecuta con python demo/sin-conexion/demo.py.