Structured outputs

Run in Colab

Step through this example interactively

Perceptron supports constrained decoding for structured replies. Provide a Pydantic class, JSON Schema, or regex pattern to constrain generation, then validate the completed response before using it. Token limits and stream errors can still leave an incomplete result.

Helpers overview

pydantic_format(MyModel, name=None, strict=None): Generate a response schema from a Pydantic v2 model; optionally override the schema name or set its strict flag.
json_schema_format(schema, name="response", strict=None): Wrap a JSON Schema dict describing the response keys, enums, and structure.
regex_format(pattern): Constrain short outputs (yes/no, IDs, emails) with a regex instead of a full schema.

All helpers feed into the same response_format argument available on perceive, async_perceive, Client.generate, and Client.stream.

Pydantic-backed responses

Use a Pydantic model to define the target shape, then pass pydantic_format. After a successful completion, validate the returned JSON with the same model.

from perceptron import image, perceive, pydantic_format, text
from pydantic import BaseModel, Field
from typing import Literal


class SceneAnalysis(BaseModel):
  scene_type: str = Field(description="outdoor, indoor, urban, nature")
  main_subjects: list[str]
  mood: Literal["calm", "energetic", "dramatic", "peaceful", "tense"]
  time_of_day: Literal["morning", "afternoon", "evening", "night", "unknown"]


@perceive(response_format=pydantic_format(SceneAnalysis))
def analyze_scene(path: str):
  return image(path) + text("Analyze this scene and return JSON.")


result = analyze_scene("scene.jpg")
analysis = SceneAnalysis.model_validate_json(result.text)
print(analysis.time_of_day)

Express required keys, allowed values, and extra-field handling in your schema; for example, use additionalProperties: false to disallow extra fields. Validate the response in your application even when requesting strict output.

Raw JSON Schema

If you already have a schema, pass it directly via json_schema_format.

from perceptron import image, json_schema_format, perceive, text

schema = {
  "type": "object",
  "properties": {
    "title": {"type": "string"},
    "keywords": {"type": "array", "items": {"type": "string"}},
    "confidence": {"type": "number"}
  },
  "required": ["title", "keywords", "confidence"],
  "additionalProperties": False
}

@perceive(response_format=json_schema_format(schema, name="summary", strict=True))
def summarize(path: str):
  return image(path) + text("Summarize the image and include keywords.")


resp = summarize("frame.png")
print(resp.text)

Regex constraints for short answers

Use regex_format when a compact pattern is enough (e.g., binary decisions, IDs, or numeric ranges).

from perceptron import image, perceive, regex_format, text

@perceive(response_format=regex_format(r"yes|no"))
def quick_check(path: str):
  return image(path) + text("Is there a stop sign in this photo? Respond yes or no.")


print(quick_check("frame.jpg").text)

Structured responses and function tools

These response constraints are separate from function.strict, which is accepted for function tools but does not enforce their argument schema. On models that support function calling, validate generated arguments before executing a tool. A request cannot declare non-empty tools together with a json_schema response format or regex. Complete the tool loop first, then request a constrained final response without declaring tools.

Streaming with structure

Client.stream and async_perceive(stream=True) support the same response_format. Buffer the text deltas and validate the complete result after successful generation. Individual deltas are not complete JSON. For raw API streams, check finish_reason and error events before parsing: length means the response may be truncated, and an error or interrupted connection may leave partial output. A terminal event alone does not guarantee a complete schema-valid response.

Schema compilation can add latency the first time you use a new shape. Reuse the same schema object or Pydantic model to benefit from provider-side caching.

Get Started

Capabilities

Developer Guides

Scaling & deployment

Best practices

Run in Colab

Helpers overview

Pydantic-backed responses

Raw JSON Schema

Regex constraints for short answers

Structured responses and function tools

Streaming with structure

Run in Colab

​Helpers overview

​Pydantic-backed responses

​Raw JSON Schema

​Regex constraints for short answers

​Structured responses and function tools

​Streaming with structure

Helpers overview

Pydantic-backed responses

Raw JSON Schema

Regex constraints for short answers

Structured responses and function tools

Streaming with structure