Crear tu toolkit#

mini build convierte muestras JSON en un contrato de dominio y herramientas Python ejecutables. El contrato viaja con la aplicación y el prompt explica al modelo cómo escribir las respuestas compactas.

mini build phones.json catalog.json --prefix phone --out .mini

Qué genera#

Archivo	Uso
`contract.json`	Orden de los campos, tipos, codificación y estructura del dominio.
`schema.json`	Esquema JSON de referencia inferido de las muestras.
`prompt.es.md`, `prompt.en.md`	Instrucción de formato para el modelo.
`parser.py`	Codifica JSON y reconstruye el JSON original desde `.mini`.
`validator.py`	Comprueba estructura, tipos y registros.
`repair.py`	Aplica correcciones seguras y entrega diagnósticos.
`example.json`, `example.mini`	Ejemplo verificable de ida y vuelta.
`manifest.json`, `README.md`	Perfil, inventario y guía de uso.

Muestras representativas#

La inferencia descubre lo observado; no puede adivinar las reglas de tu negocio. Incluye campos ausentes y presentes, nulos, listas vacías y completas, objetos anidados y los distintos tipos que aceptas. Revisa el contrato generado antes de integrarlo. Conserva una versión del toolkit por dominio para reproducir cada respuesta.

Un campo que aparece una sola vez puede ser opcional. Que todos los ejemplos tengan el mismo valor no convierte ese valor automáticamente en una regla de negocio. Los valores frecuentes pueden codificarse de forma reversible sin prohibir valores nuevos.

Dos perfiles explícitos#

El perfil base SPEC 1.0 mantiene las 14 familias y sus parsers Python, JavaScript y TypeScript. El perfil generado mini-domain/1 añade el mapa necesario para conservar estructuras JSON y adaptar la codificación al dominio. Se usa con su parser.py, no con un parser del perfil base que desconozca el contrato generado.

Ciclo de trabajo#

python .mini/parser.py encode input.json
python .mini/parser.py decode response.mini
python .mini/validator.py response.mini
python .mini/parser.py diagnose response.mini
python .mini/repair.py response.mini --out corrected.mini

La salida de decode es JSON listo para la aplicación. diagnose explica los fallos; repair conserva el contenido y aplica solamente cambios deterministas. Para aceptar explícitamente el número de registros recibidos: python .mini/repair.py response.mini --out corrected.mini --fix-count.

Un valor semánticamente incorrecto no tiene una reparación universal: utiliza el informe y el prompt de reintento para solicitar al modelo una corrección. No descartes silenciosamente datos ni completes información desconocida.

Para aplicar correcciones por línea, guarda un objeto como {"2": "línea .mini corregida"} en corrections.json y ejecuta:

python .mini/parser.py apply response.mini corrections.json --out corrected.mini

Solo acepta reemplazos de líneas diagnosticadas como inválidas y vuelve a validar el documento completo antes de escribirlo.

Medir el ahorro completo#

Compara el mismo JSON y el mismo tokenizador. Cuenta tanto el prompt de contrato como las salidas y los reintentos. El contrato se amortiza al reutilizarlo; los lotes pequeños o datos sin repetición pueden no compensarlo. Consulta la metodología y repite la medida con tus muestras.

Build your toolkit#

mini build turns JSON samples into a domain contract and executable Python tools. The contract ships with your application; the prompt tells the model how to write compact responses.

mini build phones.json catalog.json --prefix phone --out .mini

Generated files#

File	Purpose
`contract.json`	Field order, types, encoding and domain structure.
`schema.json`	Reference JSON schema inferred from samples.
`prompt.es.md`, `prompt.en.md`	Model format instruction.
`parser.py`	Encodes JSON and reconstructs original JSON from `.mini`.
`validator.py`	Checks structure, types and records.
`repair.py`	Applies safe corrections and returns diagnostics.
`example.json`, `example.mini`	Verifiable round-trip example.
`manifest.json`, `README.md`	Profile, inventory and usage guide.

Representative samples#

Inference discovers observed structure; it cannot guess business rules. Include missing and present fields, nulls, empty and populated lists, nested objects and every type you accept. Review the generated contract before integration. Keep a version of the toolkit per domain so every response remains reproducible.

A field appearing only once may be optional. A value shared by every example does not automatically become a business rule. Frequent values may receive a reversible encoding without banning new values.

Two explicit profiles#

The SPEC 1.0 base profile retains the 14 families and their Python, JavaScript and TypeScript parsers. The generated mini-domain/1 profile adds the mapping required to preserve JSON structures and adapt encoding to the domain. Use its parser.py, not a base-profile parser that does not know the generated contract.

Workflow#

python .mini/parser.py encode input.json
python .mini/parser.py decode response.mini
python .mini/validator.py response.mini
python .mini/parser.py diagnose response.mini
python .mini/repair.py response.mini --out corrected.mini

decode prints application-ready JSON. diagnose explains failures; repair preserves content and applies deterministic changes only. To explicitly accept the number of received records: python .mini/repair.py response.mini --out corrected.mini --fix-count.

A semantically incorrect value has no universal repair: use the report and retry prompt to ask the model for a correction. Never silently discard data or fill in unknown information.

To apply per-line corrections, save an object such as {"2": "corrected .mini line"} in corrections.json and run:

python .mini/parser.py apply response.mini corrections.json --out corrected.mini

Only lines diagnosed as invalid may be replaced. The complete document is validated again before it is written.

Measure complete savings#

Compare identical JSON with the same tokenizer. Count contract instructions, outputs and retries. Reuse amortizes the contract; small batches or non-repetitive data may not offset it. Read the methodology and repeat the measurement with your samples.