`edit()`

Edit a target value using natural language instructions, along with type-specific, field/content selective, and planning capabilities.

API Reference

edit()

Synchronously edit a target value using a model or Pydantic AI agent.

Parameters:

Name	Type	Description	Default
`target`	`TargetParam[Output]`	The target value or type to edit.	required
`context`	`ContextType \| List[ContextType] \| None`	Optional context or conversation history for the operation. Defaults to None.	`None`
`selective`	`bool`	When True, perform selective edits. Defaults to True.	`True`
`iterative`	`bool`	When True, perform iterative edits. Requires plan=True. Defaults to False.	`False`
`plan`	`bool`	When True, create an edit plan first. Defaults to False.	`False`
`merge`	`bool`	When True, merge edits with existing values. Requires selective=True or plan=True. Defaults to False.	`False`
`confidence`	`bool`	When True, enables log-probability based confidence scoring. Defaults to False.	`False`
`model`	`ModelParam`	The model to use for editing. 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]: Edited result or stream of outputs, depending on `stream`.

aedit()

Asynchronously edit a target value using a model or Pydantic AI agent.

Parameters:

Name	Type	Description	Default
`target`	`TargetParam[Output]`	The target value or type to edit.	required
`context`	`ContextType \| List[ContextType] \| None`	Optional context or conversation history for the operation. Defaults to None.	`None`
`selective`	`bool`	When True, perform selective edits. Defaults to True.	`True`
`iterative`	`bool`	When True, perform iterative edits. Requires plan=True. Defaults to False.	`False`
`plan`	`bool`	When True, create an edit plan first. Defaults to False.	`False`
`merge`	`bool`	When True, merge edits with existing values. Requires selective=True or plan=True. Defaults to False.	`False`
`confidence`	`bool`	When True, enables log-probability based confidence scoring. Defaults to False.	`False`
`model`	`ModelParam`	The model to use for editing. 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]: Edited result or stream of outputs, depending on `stream`.

Overview

The edit() semantic operation is one of the most powerful and in-depth operations provided by ZYX. It allows you to pass some target data and have the model perform a single or series of edits on it, with the optional ability to plan the edits first as well as merge into the original data.

The biggest upsides of the edit() operation include 2 key points:

The ability to perform selective edits, where the model only generates the parts of the data that need to be edited. (Currently only supported for string and mapping-like (dict/basemodel/dataclass/etc) data types). Which allows the model to make more granular and cost-efficient edits.
The ability to plan edits and generate them iteratively (one edit at a time), allowing for greater control and accuracy over the edits.

Edit Strategies

When it is mentioned that a model can perform selective edits based on compatible targets; this is a reference to the various edit strategies that ZYX provides.

For example, in the case of strings, a model can generate string diffs or replacements based on specific anchors or selections within the text.

SyncAsync

Basic Edit

from zyx import edit


data = {
    "name": "John Doe",
    "age": 30,
    "email": "john.doe@example.com",
} # (1)!


result = edit(
    target=data,
    context="Change the name to 'Jane Doe'.",
    merge=False, # (2)!
)


print(result.output)
"""
{
    "name": "Jane Doe",
    "age": None,
    "email": None
}
"""

The target parameter when using edit can be a value of any standard target/data type.
The merge parameter allows to merge the edits into the original data, or just return the new content.

Basic Edit

from zyx import aedit


data = {
    "name": "John Doe",
    "age": 30,
    "email": "john.doe@example.com",
}


async def main():
    result = await aedit(
        target=data,
        context="Change the name to 'Jane Doe'.",
        merge=False,
    )

Selective Edits

By default, the edit() operation performs a selective edit (if a supported target is provided). Which means the model only generates the parts of the data that need to be edited.

We can best understand this by example:

SelectiveNon-Selective

Selective Edit

from zyx import edit
from pydantic import BaseModel


class Product(BaseModel):
    name : str = "Apple"
    description : str = "A delicious fruit that is red and sweet."
    price : float = 1.99
    quantity : int = 10


result = edit(
    target=Product(),
    context="We've got 15 of them right now.",
    selective=True,
    merge=False
)


print(result.output)
"""
Product(name=None, description=None, price=None, quantity=15)
"""

Non-Selective Edit

from zyx import edit
from pydantic import BaseModel


class Product(BaseModel):
    name : str = "Apple"
    description : str = "A delicious fruit that is red and sweet."
    price : float = 1.99
    quantity : int = 10


result = edit(
    target=Product(),
    context="We've got 15 of them right now.",
    selective=False, # (1)!
    merge=False
)


print(result.output) # (2)!
"""
Product(name="Apple", description="A delicious fruit that is red and sweet.", price=1.99, quantity=15)
"""

We set selective to False.
If its not immediately clear, as we have set merge to False, the model should only return the new content, and in this case all fields were returned, meaning the model performed a full re-generation of the data.