Model validators fail during partial streaming with incomplete fields

[thomasnormal]

Description

When using @model_validator(mode="after") with partial streaming, validators can fail prematurely because they reference fields that haven't arrived yet in the stream.

Additionally, the Partial model makes all fields optional to allow incremental construction during streaming. However, this means required fields are never enforced, even after streaming completes.

Example: Model Validator Failure

from typing import Literal
from pydantic import BaseModel, model_validator
import instructor
from openai import OpenAI

class TaskResponse(BaseModel):
    status: Literal["pending", "completed"]
    priority: Literal["low", "high"]
    
    @model_validator(mode="after")
    def validate_consistency(self):
        # This fails during streaming when status is set but priority is None
        if self.status == "completed" and self.priority is None:
            raise ValueError("Completed tasks must have priority")
        return self

client = instructor.from_openai(OpenAI())

# This fails during streaming because the validator runs before all fields arrive
for partial in client.chat.completions.create_partial(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Create a completed high priority task"}],
    response_model=TaskResponse,
):
    print(partial)  # Fails when status arrives but priority is still None

Example: Missing Required Fields

class UserProfile(BaseModel):
    name: str  # Required
    email: str  # Required
    bio: Optional[str] = None

# If the LLM only returns {"name": "John"}, the Partial model accepts it
# because all fields are made optional during streaming.
# The missing 'email' field is never caught!

Expected Behavior

1. Model validators should be skipped during streaming and only run during final validation when all fields are complete.

2. Required fields should be enforced after streaming completes. The final object should be validated against the original model to catch missing required fields.

Additional Issue: Literal Types

A related issue occurs with Literal and Enum types during streaming. When using partial_mode="trailing-strings" (the default), incomplete strings like "act" fail validation for Literal["active", "inactive"].

Solution (PR #1994)

1. Skip model validators during streaming by passing context={"partial_streaming": True} and wrapping validators to check this context.

2. Final validation after streaming validates the final object against the original model to enforce required fields and run model validators.

3. PartialLiteralMixin switches to partial_mode="on" which drops incomplete strings instead of keeping them.

Environment

• Python 3.9+
• Pydantic 2.x
• instructor 1.x

[thomasnormal]

Fix Available in PR #1997

This issue is addressed by PR #1997 which introduces completeness-based validation for Partial streaming.

How It Works

Instead of trying to patch individual validator types (whack-a-mole approach), the fix takes a fundamental approach:

1. JSON Completeness Tracking: A new JsonCompleteness class tracks which parts of the streaming JSON are "complete" (closed with matching braces/brackets)

2. Validation-Free Partial Models: The partial model used during streaming has NO validators at all - it's a pure data container

3. Immediate Validation on Completion: When a JSON structure becomes complete, it's immediately validated against the original model with all validators

Result

• Model validators only run when the JSON is complete, so they see all fields
• Field constraints (min_length, etc.) only apply to complete data
• Field validators only run on complete values
• Required fields are enforced when validating against the original model

Example

class Task(BaseModel):
    status: Literal["pending", "completed"]
    priority: int

    @model_validator(mode="after")
    def check_priority(self):
        # This only runs when JSON is complete - all fields present
        if self.status == "completed" and self.priority < 5:
            raise ValueError("Completed tasks need high priority")
        return self

# Now works correctly during streaming
for partial in client.chat.completions.create_partial(...):
    print(partial)  # No errors on incomplete data

See PR #1997 for full details.

[jxnl]

Closing as this has been fixed by PR #1994 (merged Jan 13, 2026) which explicitly fixed model validators during partial streaming.