`query()`

Query a grounded source into a target type or schema. It only uses the provided source content and returns a structured output that matches the target type or schema.

API Reference

query()

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

Parameters:

Name	Type	Description	Default
`source`	`SourceParam`	The source value to query from.	required
`target`	`TargetParam[Output]`	The target type, schema, or agent to return. 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 querying. 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]: Queried result or stream of outputs, depending on `stream`.

aquery()

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

Parameters:

Name	Type	Description	Default
`source`	`SourceParam`	The source value to query from.	required
`target`	`TargetParam[Output]`	The target type, schema, or agent to return. 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 querying. 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]: Queried result or stream of outputs, depending on `stream`.

Overview

The query() semantic operation answers questions using a grounded source. It only uses the provided source content and returns a structured output that matches the target type or schema.

SyncAsync

Grounded Query

from zyx import query
from pydantic import BaseModel


class PolicyAnswer(BaseModel):
    max_refunds: int | None
    notes: str | None


policy_text = "Refunds are allowed up to 30 days after purchase."

result = query(
    source=policy_text,
    target=PolicyAnswer,
    context="How many days do customers have to request a refund?",
)


print(result.output)
"""
PolicyAnswer(max_refunds=30, notes=None)
"""

Grounded Query

from zyx import aquery
from pydantic import BaseModel


class PolicyAnswer(BaseModel):
    max_refunds: int | None
    notes: str | None


async def main():
    result = await aquery(
        source="Refunds are allowed up to 30 days after purchase.",
        target=PolicyAnswer,
        context="How many days do customers have to request a refund?",
    )

Unknowns

If the answer is not supported by the source, query will return None for the relevant fields when the schema allows it.

Streaming

query() can stream outputs as they are generated.

Streaming a Query

from zyx import query


stream = query(
    source="Refunds are allowed up to 30 days after purchase.",
    target=str,
    context="What does the policy say about refunds?",
    stream=True,
)


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