`parse()`

Parse a source into a target type or schema. It treats the input as literal content to parse and returns only the structured output that matches the target.

API Reference

parse()

Synchronously parse a source into a target type using a model or Pydantic AI agent.

Parameters:

Name	Type	Description	Default
`source`	`SourceParam`	The source value to parse from.	required
`target`	`TargetParam[Output]`	The target type, schema, or agent to parse into. Defaults to str.	`str`
`context`	`ContextType \| List[ContextType] \| None`	Optional context or conversation history for the operation. Defaults to None.	`None`
`confidence`	`bool`	When True, enables log-probability based confidence scoring (if supported by the model). Defaults to False.	`False`
`model`	`ModelParam`	The model to use for parsing. Can be a string, Pydantic AI model, or agent. Defaults to "openai:gpt-4o-mini".	`'openai:gpt-4o-mini'`
`model_settings`	`PydanticAIModelSettings \| None`	Model settings to pass to the operation (e.g., temperature). Defaults to None.	`None`
`attachments`	`AttachmentType \| List[AttachmentType] \| None`	Attachments provided to the agent. Defaults to None.	`None`
`instructions`	`PydanticAIInstructions \| None`	Additional instructions/hints for the model. Defaults to None.	`None`
`tools`	`ToolType \| List[ToolType] \| None`	List of tools available to the model. Defaults to None.	`None`
`deps`	`Deps \| None`	Optional dependencies (e.g., `pydantic_ai.RunContext`) for this operation. Defaults to None.	`None`
`usage_limits`	`PydanticAIUsageLimits \| None`	Usage limits (token/request) configuration. Defaults to None.	`None`
`observe`	`bool \| Observer \| None`	If True or provided, enables CLI observation output.	`None`
`stream`	`bool`	Whether to stream the output of the operation. Defaults to False.	`False`

Returns:

Type	Description
`Result[Output] \| Stream[Output]`	Result[Output] \| Stream[Output]: Parsed result or stream of parsed outputs, depending on `stream`.

aparse()

Asynchronously parse a source into a target type using a model or Pydantic AI agent.

Parameters:

Name	Type	Description	Default
`source`	`SourceParam`	The source value to parse from.	required
`target`	`TargetParam[Output]`	The target type, schema, or agent to parse into. Defaults to str.	`str`
`context`	`ContextType \| List[ContextType] \| None`	Optional context or conversation history for the operation. Defaults to None.	`None`
`confidence`	`bool`	When True, enables log-probability based confidence scoring (if supported by the model). Defaults to False.	`False`
`model`	`ModelParam`	The model to use for parsing. Can be a string, Pydantic AI model, or agent. Defaults to "openai:gpt-4o-mini".	`'openai:gpt-4o-mini'`
`model_settings`	`PydanticAIModelSettings \| None`	Model settings to pass to the operation (e.g., temperature). Defaults to None.	`None`
`attachments`	`AttachmentType \| List[AttachmentType] \| None`	Attachments provided to the agent. Defaults to None.	`None`
`instructions`	`PydanticAIInstructions \| None`	Additional instructions/hints for the model. Defaults to None.	`None`
`tools`	`ToolType \| List[ToolType] \| None`	List of tools available to the model. Defaults to None.	`None`
`deps`	`Deps \| None`	Optional dependencies (e.g., `pydantic_ai.RunContext`) for this operation. Defaults to None.	`None`
`usage_limits`	`PydanticAIUsageLimits \| None`	Usage limits (token/request) configuration. Defaults to None.	`None`
`observe`	`bool \| Observer \| None`	If True or provided, enables CLI observation output.	`None`
`stream`	`bool`	Whether to stream the output of the operation. Defaults to False.	`False`

Returns:

Type	Description
`Result[Output] \| Stream[Output]`	Result[Output] \| Stream[Output]: Parsed result or stream of parsed outputs, depending on `stream`.

Overview

The parse() semantic operation is used to extract structured data from a source into a target type or schema. It treats the input as literal content to parse and returns only the structured output that matches the target.

SyncAsync

Parsing into a Model

from zyx import parse
from pydantic import BaseModel


class Invoice(BaseModel):
    id: str
    total: float


text = "Invoice #A-1045. Total due: $19.99"

result = parse(
    source=text,
    target=Invoice,
)


print(result.output)
"""
Invoice(id="A-1045", total=19.99)
"""

Parsing into a Model

from zyx import aparse
from pydantic import BaseModel


class Invoice(BaseModel):
    id: str
    total: float


async def main():
    result = await aparse(
        source="Invoice #A-1045. Total due: $19.99",
        target=Invoice,
    )

Default Target

If you do not provide a target, the operation defaults to str, which means it will parse and return the raw primary input as text.

Streaming

parse() can stream outputs as they are generated.

Streaming a Parsed Output

from zyx import parse


stream = parse(
    source="Invoice #A-1045. Total due: $19.99",
    target=str,
    stream=True,
)


for chunk in stream.text():
    print(chunk)