Data contracts next to LLM workflows

Contracts at seams—not afterthoughts.

Principle

LLM-heavy workflows stay governable when behavior, quality, and ownership stay visible at every handoff—not after a production surprise.

Pressure

Orchestration changes outpace boundary definition; models and providers churn; without named seams, teams default to “we’ll fix it in the prompt.”

Mechanism

1. Input contract: schema, required fields, validation before retrieval or tools run.
2. Evidence contract: what counts as admissible context for the reasoning step.
3. Output contract: publishable shape, safety checks, and downstream compatibility.

Version schemas, define retry and failure behavior, and wire violations to telemetry.

Application

Use full rigor when work spans teams, audit needs a trail, vendors change often, or latency and quality budgets are non-negotiable. Relax when the goal is a disposable learning spike only.

Related

• RAG retrieval maturity pattern
• Pattern catalog (RAG)
• Glossary — corpus and core terms
• Intent, structure, and system in practice
• When the stack is not the system

flowchart LR
    subgraph acq[Acquire]
        source[SourceData] --> contract1[InputContract]
    end
    subgraph ret[Retrieve]
        retrieve[RetrievalStep] --> contract2[EvidenceContract]
    end
    subgraph rea[Reason]
        reason[ReasoningStep] --> contract3[OutputContract]
    end
    subgraph pub[Publish]
        publish[DownstreamSystem]
    end
    contract1 --> retrieve
    contract2 --> reason
    contract3 --> publish
    classDef contract fill:#1e1b4b,stroke:#c4b5fd,color:#e9d5ff,stroke-width:4px;
    classDef step fill:#0f172a,stroke:#64748b,color:#e2e8f0;
    class contract1,contract2,contract3 contract;
    class source,retrieve,reason,publish step;