structured-output — adaptive JSON/TOON presentation

Package scope and prerequisites

This catalog ships instructions, not the executable runtime. Python modules, scripts, local services and optional tools named below must be installed separately from the upstream project. Check their availability before running commands; if they are missing, explain the prerequisite instead of claiming execution or results. The host agent may use model tokens while following these instructions.

Use this module at the boundary between programmatic JSON data and LLM-facing text. JSON remains canonical for storage, APIs, schemas, JSON-RPC, caches, and model artifacts.

Contract

• Default output is strict compact JSON.
• auto considers only the implemented TOON v3.3 tabular subset.
• TOON requires a successful encode/decode round-trip.
• TOON requires at least 10% estimated savings and 32 estimated source tokens.
• Unsupported, small, or non-beneficial data falls back to compact JSON.
• Non-JSON text is preserved byte-for-byte.
• The dependency-free estimate is ceil(characters / 4) and is never activation-eligible.
• MCP TOON requires an active per-model profile by default. The profile requires an exact counter, zero fidelity failures, at least 10% aggregate incremental savings, and paired JSON/TOON comprehension evidence with no TOON regression.
• Formatting/tokenization p95 must fit both a 50 ms absolute ceiling and 10% of the measured JSON TTFT p95 for that model.
• Runtime loading revalidates the current quality report, model fingerprint, eligibility, and digest. Replaced or stale evidence disables the profile.

Supported TOON shapes:

• JSON primitives;
• primitive arrays;
• flat objects containing primitives or supported arrays;
• uniform non-empty object arrays with identical keys and primitive values.

Deep objects, mixed arrays, and nested cell values remain JSON.

Commands

python -m skills.structured_output.test_structured_output
python -m skills.structured_output.benchmark
python -m skills.structured_output.benchmark --json --repeat 50
python -m skills.structured_output.comprehension MODEL --json
python -m skills.structured_output.candidate_latency MODEL --trials 3 --json
python -m skills.structured_output.candidate_latency MODEL --trials 3 \
  --response-mode structured --json
python -m skills.structured_output.profile MODEL --counter heuristic --json
python -m skills.structured_output.profile MODEL --counter lmstudio_sdk \
  --endpoint localhost:1234 --activate --json

Exact counter adapters are available for llama.cpp /tokenize, vLLM /tokenize, an explicit tiktoken encoding, a locally cached Hugging Face tokenizer, and an already-loaded model through the optional LM Studio Python SDK. HTTP adapters refuse public hosts and redirects.

MCP opt-in

BOTTE_MCP_OUTPUT_FORMAT=json|toon|auto
BOTTE_MCP_OUTPUT_MODEL=exact-consumer-model-id
BOTTE_MCP_TOON_MIN_SAVINGS=0.10
BOTTE_MCP_TOON_MIN_TOKENS=32
BOTTE_MCP_TOON_REQUIRE_PROFILE=1
BOTTE_MCP_TOON_PROFILE_PATH=.botte-cache/structured-output-profiles.json
BOTTE_MCP_FORMAT_TELEMETRY=0|1

json is the default. These settings affect only JSON-shaped tool text inside MCP results. Missing, inactive, stale, inexact, slow, quality-unverified, or failed profiles select compact JSON. BOTTE_MCP_TOON_REQUIRE_PROFILE=0 is a diagnostic override, not a production activation path. The JSON-RPC transport and tool schemas always remain JSON.

When enabled, telemetry is a machine-local aggregate under .botte-cache/. It stores format/reason counts, total token counts, exact-call count, and latency totals/maxima. It never stores source text, output text, or raw model paths.

The paired comprehension report is also machine-local under .botte-cache/. It stores case IDs, correctness, token counts, and latency only; prompts, payloads, expected answers, and model answers are excluded.

candidate_latency measures formatting plus generation only for values that clear the exact adaptive gates. Its report has activation_authority=false; it diagnoses typical and tail latency but cannot activate a model profile. --response-mode final measures the unwrapped FINAL: contract, while --response-mode structured uses the LM Studio schema constraint to isolate bounded answer generation. The modes write separate machine-local reports.

Safety

• Do not persist auto-selected output as canonical state.
• Do not name a fallback JSON file .toon.
• Do not decode arbitrary full TOON with this subset decoder.
• Do not mark tiktoken or Hugging Face tokenization exact unless the selected encoding/reference is proven to match the served model.
• Do not activate from the character heuristic.