docs / Inicio rápidoQuickstart
De tu JSON a un flujo con .mini#
Una empresa recibe quejas y consultas. Su aplicación pide a la IA que interprete cada mensaje y cree un ticket: un objeto con asunto, categoría y prioridad. Necesita recibir esos objetos en JSON para guardarlos y asignarlos.
.mini cambia cómo escribe la IA esos datos. Un contrato declara los campos, su orden y sus tipos. Un prompt es el texto de instrucciones que enseña ese formato a la IA. El workflow es el código que valida su respuesta, usa Repair y devuelve el mismo JSON para la aplicación.
Mira primero el caso de 20 tickets. Puedes repetirlo sin API key y ver qué se validó y reparó.
1. Instala y abre el asistente#
Descarga el paquete y extráelo. Desde esa carpeta:
python -m pip install --no-index mini_format-1.3.3-py3-none-any.whl
mini setup
El asistente pregunta primero español o inglés. Después puedes elegir un JSON que tu IA ya haya generado, definir tus campos o usar el ejemplo de tickets. Tu muestra debe incluir los campos y tipos que espera la aplicación; añade muestras si tienes campos opcionales o estructuras diferentes.
Elige un nombre y una carpeta nueva, por ejemplo .mini. El contrato define los campos y tipos; el prompt indica a la IA cómo devolverlos. No necesitas escribir ninguno a mano.
2. Prueba antes de integrar#
Abre .mini/try-prompt.md y copia su contenido a tu IA. Ya incluye el formato en el idioma elegido y pide 20 registros ficticios del mismo caso. Una ruta sola no enseña las instrucciones a la IA.
Guarda la respuesta como response.mini. Compruébala:
python .mini/validator.py response.mini
Puede salir bien a la primera. Si hay errores, Repair elimina envoltorios Markdown, BOM y saltos de línea de Windows. Para un tipo incorrecto o datos ausentes, hay que pedir una corrección a la IA.
python .mini/repair.py response.mini --out corrected.mini
Si Repair informa de errores pendientes, revisa sus diagnósticos: no ha producido una respuesta utilizable. El ejemplo completo muestra cómo el flujo pide a la IA sólo la línea incorrecta y comprueba otra vez el resultado.
3. Conecta el flujo de tu aplicación#
En mini setup tienes tres opciones: Todavía no tengo un flujo, Elegir mi archivo o Buscar en mi proyecto. Elige el archivo donde tu código llama a la IA. Setup prepara las instrucciones de integración y, para Python compatible, te ofrece revisar o aplicar el cambio con una copia del original.
Si todavía no tienes ese código, conserva el kit. El comando para retomarlo queda en README.md y GUIA.md. Cuando tengas el archivo, sustituye su ruta en:
mini integrate ruta/a/tu/app.py --bundle .mini --lang es
Localiza la llamada que pide JSON. Prepara integration/INTEGRATE.md con las rutas del contrato y del prompt y, si el código es compatible, un diff. Para aplicar uno de los patrones Python compatibles, añade --apply; conserva una copia del archivo original. Son compatibles el SDK de OpenAI (chat.completions.create seguido de json.loads) y una llamada requests.post o httpx.post a un endpoint de chat que pide response_format JSON, como la API de DeepSeek. En ese caso solo cambia la llamada: la aplicación conserva su URL, cabeceras, manejo de errores y lectura del JSON. Si la respuesta se corta por el límite de tokens, se conservan los registros completos y solo se piden los que faltan.
Para otros SDK, código asíncrono o lenguajes, entrega la guía a tu IA de código. Debe leer el prompt generado, cambiar el formato de salida de la llamada y conectar el callback a Workflow.run. Si tu API fuerza respuestas JSON, desactiva ese modo para recibir .mini.
El recorrido completo: tu tarea → IA → .mini → validar → Repair → corrección de IA si hace falta → volver a validar → JSON. La aplicación recibe datos sólo si la respuesta entera es válida. Puedes exigir el número de registros esperado para bloquear lotes incompletos.
4. Repite una ejecución completa#
Desde la carpeta del paquete:
python examples/flujo-soporte/run.py
Hay 20 mensajes, una respuesta .mini guardada y una corrección de una línea. El flujo real entrega output/soporte/result.json y guarda history.json. Las respuestas son ilustrativas, escritas por Muse; los fallos se introdujeron para enseñar Repair, no para medir la fiabilidad de una IA.
Para el formulario local con modo grabado y modo IA real:
python examples/flujo-soporte/run.py --serve
Abre la dirección que imprime. El formulario pide API key y modelo sólo al elegir una IA real. La clave se usa en memoria y no va al historial. Las llamadas reales y las correcciones tienen coste. Puedes conservar tu proveedor al integrar tu propia función.
¿Y el ahorro?#
Los tokens son fragmentos de texto que la API cuenta para cobrar. Con el mismo modelo y tarifa, menos tokens en la respuesta significa menos coste de salida. El coste total también suma las instrucciones que envías y las correcciones.
El resultado de estos 20 tickets usa 443 tokens JSON, 304 TOON y 278 .mini con o200k_base. El prompt .mini tiene 571 tokens; los reintentos se cuentan aparte. Menos salida no demuestra por sí sola menor coste total, sobre todo con lotes pequeños. Explorar costes.
Ya conozco .mini: alternativas por comando y referencias
`mini build muestra.json --prefix ticket --out .mini --lang es` crea el mismo toolkit sin asistente. Puedes pasar varias muestras. Si ya tienes un JSON Schema, consulta `mini from-schema --help` y el [perfil base](/docs/spec/). Las [14 familias de muestra](/docs/forks/) son opcionales. El [playground](/playground/) sirve para practicar el formato base. El toolkit generado usa Python; [Node/TypeScript](/docs/typescript/) implementa el perfil base SPEC 1.1.From your JSON to a .mini workflow#
A company receives complaints and questions. Its app asks AI to interpret each message and create a ticket: an object with a title, category and priority. It needs JSON to store and assign those objects.
.mini changes how AI writes the data. A contract declares fields, order and types. A prompt is instruction text teaching AI that format. The workflow is code that validates the response, uses Repair and delivers the same JSON to your app.
See the 20-ticket use case first. Replay it without an API key and inspect validation and repair.
1. Install and open the wizard#
Download the package and extract it. From that directory:
python -m pip install --no-index mini_format-1.3.3-py3-none-any.whl
mini setup
The wizard asks for Spanish or English first. Choose JSON your AI already generated, define fields or use the support example. Include representative fields and types; add samples for optional fields and different structures.
Choose a short name and a new directory such as .mini. The contract defines fields and types; the prompt explains the AI output format. Both are generated.
2. Test before integration#
Open .mini/try-prompt.md and paste its contents into your AI. It includes the format in your selected language and requests 20 fictional records for the same use case. A file path alone does not give AI those instructions.
Save the response as response.mini and check it:
python .mini/validator.py response.mini
The first response may already be valid. Repair removes Markdown wrappers, BOM and Windows line endings. Incorrect types or missing data require an AI correction.
python .mini/repair.py response.mini --out corrected.mini
Pending errors mean no usable repaired response was produced. The complete example shows the workflow requesting only the incorrect line, then checking the whole result again.
3. Connect your application workflow#
mini setup offers I do not have a workflow yet, Select my file or Search my project. Choose the file where your code calls AI. Setup prepares integration instructions and, for supported Python, offers to review or apply the change with an original backup.
No code yet? Keep the toolkit. The resume command is saved in README.md and GUIA.md. Once you have the file, replace its path in:
mini integrate path/to/app.py --bundle .mini --lang en
Locate the call requesting JSON. The command prepares integration/INTEGRATE.md with actual contract and prompt paths and a diff for compatible code. Add --apply for one of the supported Python patterns; it retains a backup. Supported: the OpenAI SDK (chat.completions.create followed by json.loads) and a requests.post or httpx.post call to a chat endpoint that requests a JSON response_format, such as the DeepSeek API. In that case only the call changes: the app keeps its URL, headers, error handling and JSON reader. A response cut by the output limit keeps its complete records and only the missing ones are requested.
For other SDKs, asynchronous code or languages, give the guide to your coding AI. Read the generated prompt, change the call's output format and connect its callback to Workflow.run. Disable API JSON-only mode to receive .mini.
The complete flow: task → AI → .mini → validate → Repair → optional AI correction → revalidate → JSON. The app gets data only when the entire response validates. Require an expected record count to block incomplete batches.
4. Replay a complete run#
From the package directory:
python examples/flujo-soporte/run.py
There are 20 messages, a saved .mini response and a one-line correction. The actual workflow delivers output/soporte/result.json and saves history.json. Responses were authored by Muse; errors were inserted for illustration, not to measure AI reliability.
For the local form with recorded and live AI modes:
python examples/flujo-soporte/run.py --serve
Open the printed address. The form asks for an API key and model only in live mode. The key stays in memory and is not stored in history. Real calls and corrections have provider costs. Integrate your own callback to keep your provider.
What about savings?#
Tokens are pieces of text counted for API billing. At the same model and rate, fewer response tokens mean lower output cost. Total cost also includes instructions and corrections.
The same 20-ticket output takes 443 JSON tokens, 304 TOON tokens and 278 .mini tokens with o200k_base. The .mini prompt has 571 tokens; retries are extra. Fewer output tokens alone do not prove lower total cost, especially for small batches. Explore costs.