mini-format
Install

docs / Python library

Python library (minifmt 1.3.3)#

Reference implementation. No runtime dependencies; tiktoken is optional for token counting.

Public API#

from minifmt import (Contract, Field, MiniError, MiniValidationError, Document,
                     parse, dumps, detect_prefix, Registry, spec_block, parser_prompt,
                     canonical_equal, roundtrip_ok, __version__, SPEC_VERSION)
Function What it does
Registry.load(dir=…) Discovers forks/*/contract.json; reg.get("a") returns the Contract.
parse(text, contract, strict=True) Parses and validates. Strict: raises MiniValidationError with every error. Lenient (strict=False): returns a Document with valid records and errors.
Document.to_canonical() Canonical JSON: {"prefix", "header", "<records_key>": [...]}.
dumps(obj, contract) Canonical → .mini.
spec_block(contract, lang="en"|"es") Specification block for the model's prompt.
parser_prompt(contract, fixtures, lang) Prompt for a model to write a parser for the family.
roundtrip_ok(obj, contract) parse(dumps(obj)) == obj with stable serialization.
detect_prefix(text) Prefix declared in the header, without validating.

MiniError#

Fields: code, line (1-based, 0 = document), message, field. str(e) yields E10 line 3 [level]: …. Codes are in the error index.

Lenient mode#

doc = parse(texto, c, strict=False)
doc.records          # only the valid ones, with contract types
doc.errors           # list of MiniError
doc.record_lines     # physical line of each accepted record
doc.diagnostics()    # report with the lines to regenerate (same as `mini diagnose`)

Streaming read#

from minifmt import read_records, create_reader
for item in read_records(chunks, c):       # str or UTF-8 bytes, split anywhere
    handle(item.record, item.line)          # emitted when the record's line closes

read_records yields the same records and errors as parse and does not retain records, so memory does not grow with the document. create_reader(c) offers push(chunk) and end() for a model's streaming response.

Contracts from JSON Schema and Pydantic#

from minifmt import from_json_schema, to_json_schema, from_pydantic
c = from_json_schema(schema, "tk")          # one-level records (SPEC §12)
schema = to_json_schema(c)                  # lossless round trip through x-mini annotations
c = from_pydantic(Model, "job")             # pydantic is optional

Required properties become core fields and optional ones extensions; format: date yields the date type. Deeper nesting is rejected with E20, citing SPEC §12.

Selective repair and providers#

from minifmt.ai import repair_request, merge_repair
from minifmt.ai.adapters import get_adapter
req = repair_request(answer, c, "en")       # only the invalid lines, with their codes
if req.needed:
    model = get_adapter("openai", "gpt-5-mini")         # also "anthropic", "groq" or "simulated"
    repaired = model.generate(req.system, req.user, max_tokens=req.max_tokens_hint * 2, temperature=0)
    merged = merge_repair(answer, repaired["text"], c, req)     # accepts each correction only if valid

Switching providers changes neither the contract nor the rest of the integration. An offline demonstration of the whole flow runs with python demo/sin-conexion/demo.py.