# Lizzy Distill agent integration contract Contract version: 2026.08 Last reviewed: 2026-08-27 Audience: tool-using AI runtimes integrating with Lizzy Distill Human documentation: https://lizzy.albinilabs.com/docs/start This file is the consolidated machine context for Lizzy Distill. It defines source authority, cross-surface invariants, resource flow, stop conditions, and recovery. It does not replace the OpenAPI schema for REST request shape, the MCP server for declared remote tool schemas, or the Pilot execution playbook for typed-tool policy. In this contract, agent means a tool-using AI runtime. It does not mean the customer-support agent resource exposed elsewhere in the Lizzy API. ## Canonical sources and precedence Use the narrowest controlling source for the decision: 1. OpenAPI 3.1: https://lizzy.albinilabs.com/v1/openapi.json Controls REST paths, methods, schemas, required fields, authentication, and operation metadata. 2. MCP server and guide: https://lizzy.albinilabs.com/v1/mcp and https://lizzy.albinilabs.com/docs/mcp `tools/list` controls remote tool names and input schemas. The guide controls connection, workflow phases, result envelopes, authority, and service limits. 3. Pilot execution playbook: https://lizzy.albinilabs.com/docs/agent-playbook.md Controls typed-tool selection, human handoffs, approval gates, stop rules, and response scope. 4. This file: https://lizzy.albinilabs.com/docs/llms-full.txt Controls cross-surface invariants, resource flow, state handling, and recovery. 5. Human guides: https://lizzy.albinilabs.com/docs/start Supply explanation, examples, and operator context. Tutorial prose must not be used to invent an endpoint, field, enum, identifier, tool argument, approval, or terminal state. When sources conflict, obey the source that controls the disputed fact. Do not merge contradictory sources into a plausible answer. If the controlling source is missing or ambiguous, stop and ask for the contract or a human decision. ## Choose one control surface ### Standalone REST client Use OpenAPI for the wire contract. The integrating application owns its human approval gate, credential handling, persistence, idempotency keys, retry policy, polling or webhook strategy, and budget checks. A direct authorized REST mutation executes according to the endpoint contract. Pilot-only proposals and handoffs do not change raw REST behavior. ### Remote MCP client Send stateless Streamable HTTP JSON-RPC requests to `POST https://lizzy.albinilabs.com/v1/mcp` with an `Authorization: Bearer ` header. The token must have `full_access`, and the workspace must have Pilot enabled. Start with a test token; all MCP reads and writes then stay in test mode. Responses are `application/json`, with no SSE stream or `Mcp-Session-Id`. The server exposes ten tools through `tools/list`. Distillation tools use one durable workflow with phases `scope -> data -> rewards -> plan -> training -> results -> deployment`; every MCP client and the dashboard see the same workspace workflows. Every tool result returns `{status, workflow_id, phase, summary, refs, blockers, next_actions}`. Use the declared next tool only in the recorded phase. A wrong-phase call returns an explicit mismatch result. The Pilot policy layer classifies underlying writes, but the MCP agent acts with the full authority of the supplied API token. Run spending is bounded only when the recipe sets `max_cost_usd`. ### Pilot typed tools Use only declared typed tools and the version-pinned Pilot execution playbook. A tool result that creates approval, handoff, input, block, or asynchronous watch state is durable workflow state. Chat wording cannot replace that state. Do not translate REST examples into guessed tool arguments or use generic tools to bypass a typed boundary. Never switch control surfaces inside an in-progress action merely because one path is waiting. A later operator may inspect the same underlying resource through another surface, but the current action keeps the authority and stop rules of the surface that created it. ## Global invariants - Keep Lizzy bearer tokens, BYOK provider credentials, connector credentials, webhook secrets, upload capabilities, and raw captured bodies out of model context. - Treat test and live mode as a data and authority boundary. Test artifacts do not authorize live training or deployment. - Use exact identifiers returned by Lizzy. Never infer, repair, normalize, or replace an ID. - Persist every workflow ID, resource ID, safe reference, request ID, status, and registered watch before taking another action. - Perform at most one side-effecting action per decision turn. - A timeout, lost response, local wait, or interrupted watch is not proof that remote work failed. - Reuse the same globally unique idempotency key and byte-identical JSON after an unknown REST write outcome. Do not rotate the key to force another resource. - Treat next_actions as permission to consider an action, not proof that prerequisites are ready. - Resolve readiness from the controlling resource state and contract. - Use exact reviewed reward IDs. Omission and an explicit empty list have different semantics. - A dry run validates a plan. It does not publish a serveable student. - Live training requires the exact validated dry run and plan hash in the same mode. - Serving starts in shadow with a resolvable teacher fallback. Change one rollout boundary at a time. - Branch on stable error.code values. Distinguish BYOK passthrough responses from managed teacher_unavailable errors. Preserve X-Request-Id and relevant resource IDs for diagnosis. - Never expose absent evidence as zero, false, clean, healthy, or complete. ## Resource flow The normal Distill dependency order is: distill loop -> source or connector or upload -> mutable dataset definition -> immutable dataset version -> explicit reward selection -> recipe and budget plan -> live-mode dry run and plan hash -> approved live training run -> evaluation report and optional published student -> shadow deployment -> percentage rollout -> full rollout or retirement Each arrow is a prerequisite boundary, not an instruction to continue automatically. Save the returned reference at every boundary. A later phase must consume the exact ready artifact created by the earlier phase. ## Bounded execution loop For each turn: 1. Read the durable workflow state and exact saved resource references. 2. Select one allowed next action from recorded state and the controlling contract. 3. Confirm mode, scope, prerequisites, budget, and required human authority. 4. Execute one bounded read or one idempotent mutation. 5. Persist returned IDs, safe references, status, request ID, watch, handoff, or approval state. 6. Stop on asynchronous work, approval, handoff, input, block, failure, or unknown state. 7. Advance only when a recorded platform event or fresh read proves the prerequisite state. Do not put a polling loop, retry loop, speculative fallback, or duplicate-resource path inside this decision loop. ## Stop conditions ### Asynchronous work Persist the resource reference and rely on its registered event watch or the integrating application's bounded observation strategy. Do not create another resource because the local watch ended. In Pilot, one bounded status read is allowed only when the user asks or an event wakes the workflow. ### approval_required Name the required role and decision, then stop. Do not approve, repeat, bypass, or replace the proposal. A verbal yes does not replace the recorded platform approval event. ### handoff_required Name the dashboard or human action, then stop. Credentials, connector repair, file bytes, upload parts, and other human-owned capabilities stay outside the model. Continue the same workflow after the platform records completion. Do not create a second handoff. ### input_required Ask for the single missing or corrected choice. Do not infer a default, broaden the task, or start a different data path. ### blocked Read the stable blocker. Correct only that blocker, then resume the same workflow once when the contract permits. If it remains blocked, stop. Do not call the phase action directly. ### failed Preserve error.code, X-Request-Id, workflow ID, resource ID, and the last action. Follow the documented recovery branch. Failure does not authorize a duplicate mutation. ### unknown or contradictory state Stop. Request the controlling contract, an exact reference, or a human decision. Never guess. ## Phase contract ### Capture Choose the source kind explicitly. A `kind: "managed"` source stores `teacher_model` from the current model catalog and needs no provider key. Read it with authenticated `GET /v1/distill/teachers` and `distill:read`; `stale: true` is a usable recent snapshot. The request body's required `model` is recorded as `model_requested`, while the source teacher is `model_served`. Live calls bill the workspace per token at the catalog rates; test calls record cost but are not charged. Empty balance returns 402 `insufficient_balance` before a model call. Failed calls are captured and never billed. A `kind: "byok"` source stores `base_url` and `upstream_key`, forwards the chat request verbatim, and records captured cost as zero because the workspace's provider bills it. Pilot never accepts or reveals the BYOK credential; it creates a human handoff and resumes from a safe source reference. The customer must generate traffic. A bounded traffic read that finds no traffic is input_required, not a retry cue. Captured bodies do not belong in model context. Managed source creation rejects BYOK fields, and `kind` is create-only. An unknown teacher ID is 400 `teacher_model_unknown`; an unreadable catalog is 503 `catalog_unavailable`. Managed model trouble keeps the original status, including 429, and returns `teacher_unavailable`. Retry according to that status or switch the source model; do not bill the failed call. ### Connector import Use an existing verified connector or create one human credential handoff. Start one reviewed pull with a bounded row limit and optional date bound. Persist the pull reference and stop while it runs. Authentication failure requires human connector repair. A successful zero-row pull is terminal and must not be retried automatically. ### File upload The human dashboard owns file bytes, multipart parts, completion, and short-lived storage capabilities. An agent may prepare the upload handoff and preserve the workflow. It must not request file contents or signed upload locations in chat. ### Dataset version Materialize the selected dataset once. The immutable ready version, not the mutable definition, is the input to planning and training. Preserve its split and review note. If empty or failed, inspect the same version and correct the source selection instead of creating materialization duplicates. ### Rewards Use exact reviewed ordered reward IDs. Deterministic criteria use verifiers. Subjective criteria need a concrete rubric. Webhook secrets remain human-owned. Explicit empty rewards means supervised-only training; omission is not equivalent. ### Plan and dry run Propose a recipe from one ready immutable version, explicit rewards, objective, budget guidance, and requested outcome. A serve-bound outcome requires publication. Save the reviewed plan, then start one live-mode dry run. The succeeded dry run and plan hash validate that exact version, recipe, budget, and compute. Any execution-affecting edit requires a new validation. ### Live training For Pilot, requesting live training creates approval_required and does not spend by itself. Stop until the recorded approval event creates the live run reference. For standalone REST, the integrating application owns approval before sending the authorized mutation. Persist the run and stop while queued or running. Cancel only on explicit human instruction. ### Results Resolve run state, metrics, report, and student as separate facts. A succeeded evaluation can produce a report without a deployable student. A dry run never publishes one. Report only evidence returned by the relevant read. State unavailable or truncated fields explicitly. A ready report is evidence for a human decision, not automatic rollout approval. ### Serving Require a ready published student and resolvable teacher fallback. Request shadow first. Each move to percentage, full, or retirement is one separately reviewed boundary. For Pilot, every boundary creates its own approval proposal. A provisioning result is asynchronous. A degraded deployment is a blocker. ## REST rules - API origin: https://lizzy.albinilabs.com - Versioned base path: /v1 - Send bearer credentials only from a trusted server. - Verify token workspace, environment, scopes, and API version before integration work. - Use Content-Type: application/json for JSON bodies. - Treat required headers, idempotency behavior, pagination, and async terminal states as declared by the current OpenAPI operation. - Distinguish managed Lizzy error envelopes from BYOK passthrough responses. - Preserve response X-Request-Id values. - Read the managed model catalog at `GET /v1/distill/teachers` with `distill:read`. Use its current IDs and USD-per-million-token prices for managed source selection and billing decisions. - Use the event type catalog at https://lizzy.albinilabs.com/v1/event_types for supported webhook subscription names. Do not invent wildcard or exact event names. ## MCP rules - Endpoint: `POST https://lizzy.albinilabs.com/v1/mcp`. - Protocol versions: `2025-03-26` and `2025-06-18`. - JSON-RPC methods: `initialize`, `notifications/initialized`, `ping`, `tools/list`, and `tools/call`. - Authentication: test or live API token with `full_access`; keep it in client configuration and out of model context. - Rate limit: 120 tool calls per minute per workspace in the `mcp_calls` bucket returned by `GET /v1/rate_limits`. - Tool calls are not billed. Live managed teacher calls bill at catalog rates; test-mode calls record cost without a charge. Runs and other triggered actions use their normal billing rules. - After about 30 minutes idle, allow about 10 seconds for the first call to cold-start. - API tokens work with Claude Code, Cursor, and the Anthropic API MCP connector. Claude.ai web connectors require OAuth and are not yet supported. ## Pilot response discipline - Answer with only fields the user explicitly requested. - Omit unrequested names, IDs, references, counts, configuration, and next-step interpretations. - Copy a requested ID exactly. - Do not infer readiness from next_actions or workflow checkpoint text. - Do not infer resource health from a successful read wrapper. - Use one report card at most for a multi-resource review, and attach exactly one report reference. - Stop after a handoff, approval, input request, block, failure, or asynchronous watch. ## Minimum resumable context Persist a packet with: - contract_version - control_surface: rest or pilot - mode: test or live - exact workflow_id when Pilot owns the flow - exact safe resource references - last recorded platform status - stable error code when present - request ID when present - one reviewed allowed next action - recorded human decision when the platform has accepted it Do not persist credentials, raw traffic bodies, upload bytes, signed capabilities, guessed values, or prose summaries in place of exact identifiers and state. ## Human guide index - Quickstart: https://lizzy.albinilabs.com/docs/start - Core concepts: https://lizzy.albinilabs.com/docs/concepts - Authentication: https://lizzy.albinilabs.com/docs/auth - Pilot typed-tool workflow: https://lizzy.albinilabs.com/docs/pilot - Remote MCP server: https://lizzy.albinilabs.com/docs/mcp - End-to-end example: https://lizzy.albinilabs.com/docs/example - Capture: https://lizzy.albinilabs.com/docs/capture - Datasets: https://lizzy.albinilabs.com/docs/datasets - Rewards: https://lizzy.albinilabs.com/docs/rewards - Training: https://lizzy.albinilabs.com/docs/training - Results: https://lizzy.albinilabs.com/docs/results - Serving: https://lizzy.albinilabs.com/docs/serving - Webhooks: https://lizzy.albinilabs.com/docs/webhooks - API conventions: https://lizzy.albinilabs.com/docs/api - Errors and recovery: https://lizzy.albinilabs.com/docs/errors - Changelog: https://lizzy.albinilabs.com/docs/changelog Final rule: if the controlling source cannot prove the next action is valid, stop. Ask for the contract, exact state, or human decision. Do not guess.