Skip to content

PotatoHead

Agent

Source code in python/potato_head/_potato_head.pyi 
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
class Agent:
    def __init__(
        self,
        provider: Provider | str,
        system_instruction: Optional[str | List[str] | Message | List[Message]] = None,
    ) -> None:
        """Create an Agent object.

        Args:
            provider (Provider | str):
                The provider to use for the agent. This can be a Provider enum or a string
                representing the provider.
            system_instruction (Optional[str | List[str] | Message | List[Message]]):
                The system message to use for the agent. This can be a string, a list of strings,
                a Message object, or a list of Message objects. If None, no system message will be used.
                This is added to all tasks that the agent executes. If a given task contains it's own
                system message, the agent's system message will be prepended to the task's system message.

        Example:
        ```python
            agent = Agent(
                provider=Provider.OpenAI,
                system_instruction="You are a helpful assistant.",
            )
        ```
        """

    @property
    def system_instruction(self) -> List[Message]:
        """The system message to use for the agent. This is a list of Message objects."""

    def execute_task(
        self,
        task: Task,
        output_type: Optional[Any] = None,
        model: Optional[str] = None,
    ) -> AgentResponse:
        """Execute a task.

        Args:
            task (Task):
                The task to execute.
            output_type (Optional[Any]):
                The output type to use for the task. This can either be a Pydantic `BaseModel` class
                or a supported PotatoHead response type such as `Score`.
            model (Optional[str]):
                The model to use for the task. If not provided, defaults to the `model` provided within
                the Task's prompt. If the Task's prompt does not have a model, an error will be raised.

        Returns:
            AgentResponse:
                The response from the agent after executing the task.
        """

    def execute_prompt(
        self,
        prompt: Prompt,
        output_type: Optional[Any] = None,
        model: Optional[str] = None,
    ) -> AgentResponse:
        """Execute a prompt.

        Args:
            prompt (Prompt):`
                The prompt to execute.
            output_type (Optional[Any]):
                The output type to use for the task. This can either be a Pydantic `BaseModel` class
                or a supported potato_head response type such as `Score`.
            model (Optional[str]):
                The model to use for the task. If not provided, defaults to the `model` provided within
                the Prompt. If the Prompt does not have a model, an error will be raised.

        Returns:
            AgentResponse:
                The response from the agent after executing the task.
        """

    @property
    def id(self) -> str:
        """The ID of the agent. This is a random uuid7 that is generated when the agent is created."""

id property

The ID of the agent. This is a random uuid7 that is generated when the agent is created.

system_instruction property

The system message to use for the agent. This is a list of Message objects.

__init__(provider, system_instruction=None)

Create an Agent object.

Parameters:

Name Type Description Default
provider Provider | str

The provider to use for the agent. This can be a Provider enum or a string representing the provider.

 required
system_instruction Optional[str | List[str] | Message | List[Message]]

The system message to use for the agent. This can be a string, a list of strings, a Message object, or a list of Message objects. If None, no system message will be used. This is added to all tasks that the agent executes. If a given task contains it's own system message, the agent's system message will be prepended to the task's system message.

 None

Example: 

    agent = Agent(
        provider=Provider.OpenAI,
        system_instruction="You are a helpful assistant.",
    )

Source code in python/potato_head/_potato_head.pyi 
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
def __init__(
    self,
    provider: Provider | str,
    system_instruction: Optional[str | List[str] | Message | List[Message]] = None,
) -> None:
    """Create an Agent object.

    Args:
        provider (Provider | str):
            The provider to use for the agent. This can be a Provider enum or a string
            representing the provider.
        system_instruction (Optional[str | List[str] | Message | List[Message]]):
            The system message to use for the agent. This can be a string, a list of strings,
            a Message object, or a list of Message objects. If None, no system message will be used.
            This is added to all tasks that the agent executes. If a given task contains it's own
            system message, the agent's system message will be prepended to the task's system message.

    Example:
    ```python
        agent = Agent(
            provider=Provider.OpenAI,
            system_instruction="You are a helpful assistant.",
        )
    ```
    """

execute_prompt(prompt, output_type=None, model=None)

Execute a prompt.

Parameters:

Name Type Description Default
prompt Prompt

` The prompt to execute.

 required
output_type Optional[Any]

The output type to use for the task. This can either be a Pydantic BaseModel class or a supported potato_head response type such as Score.

 None
model Optional[str]

The model to use for the task. If not provided, defaults to the model provided within the Prompt. If the Prompt does not have a model, an error will be raised.

 None

Returns:

Name Type Description
AgentResponse AgentResponse

The response from the agent after executing the task.
Source code in python/potato_head/_potato_head.pyi 
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
def execute_prompt(
    self,
    prompt: Prompt,
    output_type: Optional[Any] = None,
    model: Optional[str] = None,
) -> AgentResponse:
    """Execute a prompt.

    Args:
        prompt (Prompt):`
            The prompt to execute.
        output_type (Optional[Any]):
            The output type to use for the task. This can either be a Pydantic `BaseModel` class
            or a supported potato_head response type such as `Score`.
        model (Optional[str]):
            The model to use for the task. If not provided, defaults to the `model` provided within
            the Prompt. If the Prompt does not have a model, an error will be raised.

    Returns:
        AgentResponse:
            The response from the agent after executing the task.
    """

execute_task(task, output_type=None, model=None)

Execute a task.

Parameters:

Name Type Description Default
task Task

The task to execute.

 required
output_type Optional[Any]

The output type to use for the task. This can either be a Pydantic BaseModel class or a supported PotatoHead response type such as Score.

 None
model Optional[str]

The model to use for the task. If not provided, defaults to the model provided within the Task's prompt. If the Task's prompt does not have a model, an error will be raised.

 None

Returns:

Name Type Description
AgentResponse AgentResponse

The response from the agent after executing the task.
Source code in python/potato_head/_potato_head.pyi 
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
def execute_task(
    self,
    task: Task,
    output_type: Optional[Any] = None,
    model: Optional[str] = None,
) -> AgentResponse:
    """Execute a task.

    Args:
        task (Task):
            The task to execute.
        output_type (Optional[Any]):
            The output type to use for the task. This can either be a Pydantic `BaseModel` class
            or a supported PotatoHead response type such as `Score`.
        model (Optional[str]):
            The model to use for the task. If not provided, defaults to the `model` provided within
            the Task's prompt. If the Task's prompt does not have a model, an error will be raised.

    Returns:
        AgentResponse:
            The response from the agent after executing the task.
    """

AgentResponse

Source code in python/potato_head/_potato_head.pyi 
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
class AgentResponse:
    @property
    def id(self) -> str:
        """The ID of the agent response."""

    @property
    def result(self) -> Any:
        """The result of the agent response. This can be a Pydantic BaseModel class or a supported potato_head response type such as `Score`.
        If neither is provided, the response json will be returned as a dictionary.
        """

    @property
    def token_usage(self) -> Usage:
        """Returns the token usage of the agent response if supported"""

    @property
    def log_probs(self) -> List["ResponseLogProbs"]:
        """Returns the log probabilities of the agent response if supported.
        This is primarily used for debugging and analysis purposes.
        """

id property

The ID of the agent response.

log_probs property

Returns the log probabilities of the agent response if supported. This is primarily used for debugging and analysis purposes.

result property

The result of the agent response. This can be a Pydantic BaseModel class or a supported potato_head response type such as Score. If neither is provided, the response json will be returned as a dictionary.

token_usage property

Returns the token usage of the agent response if supported

AudioUrl

Source code in python/potato_head/_potato_head.pyi 
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
class AudioUrl:
    def __init__(
        self,
        url: str,
        kind: Literal["audio-url"] = "audio-url",
    ) -> None:
        """Create an AudioUrl object.

        Args:
            url (str):
                The URL of the audio.
            kind (Literal["audio-url"]):
                The kind of the content.
        """

    @property
    def url(self) -> str:
        """The URL of the audio."""

    @property
    def kind(self) -> str:
        """The kind of the content."""

    @property
    def media_type(self) -> str:
        """The media type of the audio URL."""

    @property
    def format(self) -> str:
        """The format of the audio URL."""

format property

The format of the audio URL.

kind property

The kind of the content.

media_type property

The media type of the audio URL.

url property

The URL of the audio.

__init__(url, kind='audio-url')

Create an AudioUrl object.

Parameters:

Name Type Description Default
url str

The URL of the audio.

 required
kind Literal['audio-url']

The kind of the content.

 'audio-url'
Source code in python/potato_head/_potato_head.pyi 
105
106
107
108
109
110
111
112
113
114
115
116
117
def __init__(
    self,
    url: str,
    kind: Literal["audio-url"] = "audio-url",
) -> None:
    """Create an AudioUrl object.

    Args:
        url (str):
            The URL of the audio.
        kind (Literal["audio-url"]):
            The kind of the content.
    """

BinaryContent

Source code in python/potato_head/_potato_head.pyi 
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class BinaryContent:
    def __init__(
        self,
        data: bytes,
        media_type: str,
        kind: str = "binary",
    ) -> None:
        """Create a BinaryContent object.

        Args:
            data (bytes):
                The binary data.
            media_type (str):
                The media type of the binary data.
            kind (str):
                The kind of the content
        """

    @property
    def media_type(self) -> str:
        """The media type of the binary content."""

    @property
    def format(self) -> str:
        """The format of the binary content."""

    @property
    def data(self) -> bytes:
        """The binary data."""

    @property
    def kind(self) -> str:
        """The kind of the content."""

data property

The binary data.

format property

The format of the binary content.

kind property

The kind of the content.

media_type property

The media type of the binary content.

__init__(data, media_type, kind='binary')

Create a BinaryContent object.

Parameters:

Name Type Description Default
data bytes

The binary data.

 required
media_type str

The media type of the binary data.

 required
kind str

The kind of the content

 'binary'
Source code in python/potato_head/_potato_head.pyi 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
def __init__(
    self,
    data: bytes,
    media_type: str,
    kind: str = "binary",
) -> None:
    """Create a BinaryContent object.

    Args:
        data (bytes):
            The binary data.
        media_type (str):
            The media type of the binary data.
        kind (str):
            The kind of the content
    """

ChatResponse

Source code in python/potato_head/_potato_head.pyi 
860
861
862
863
864
865
class ChatResponse:
    def to_py(self) -> Any:
        """Convert the ChatResponse to it's Python representation."""

    def __str__(self) -> str:
        """Return a string representation of the ChatResponse."""

__str__()

Return a string representation of the ChatResponse.

Source code in python/potato_head/_potato_head.pyi 
864
865
def __str__(self) -> str:
    """Return a string representation of the ChatResponse."""

to_py()

Convert the ChatResponse to it's Python representation.

Source code in python/potato_head/_potato_head.pyi 
861
862
def to_py(self) -> Any:
    """Convert the ChatResponse to it's Python representation."""

CompletionTokenDetails

Details about the completion tokens used in a model response.

Source code in python/potato_head/_potato_head.pyi 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
class CompletionTokenDetails:
    """Details about the completion tokens used in a model response."""

    @property
    def accepted_prediction_tokens(self) -> int:
        """The number of accepted prediction tokens used in the response."""

    @property
    def audio_tokens(self) -> int:
        """The number of audio tokens used in the response."""

    @property
    def reasoning_tokens(self) -> int:
        """The number of reasoning tokens used in the response."""

    @property
    def rejected_prediction_tokens(self) -> int:
        """The number of rejected prediction tokens used in the response."""

accepted_prediction_tokens property

The number of accepted prediction tokens used in the response.

audio_tokens property

The number of audio tokens used in the response.

reasoning_tokens property

The number of reasoning tokens used in the response.

rejected_prediction_tokens property

The number of rejected prediction tokens used in the response.

DocumentUrl

Source code in python/potato_head/_potato_head.pyi 
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class DocumentUrl:
    def __init__(
        self,
        url: str,
        kind: Literal["document-url"] = "document-url",
    ) -> None:
        """Create a DocumentUrl object.

        Args:
            url (str):
                The URL of the document.
            kind (Literal["document-url"]):
                The kind of the content.
        """

    @property
    def url(self) -> str:
        """The URL of the document."""

    @property
    def kind(self) -> str:
        """The kind of the content."""

    @property
    def media_type(self) -> str:
        """The media type of the document URL."""

    @property
    def format(self) -> str:
        """The format of the document URL."""

format property

The format of the document URL.

kind property

The kind of the content.

media_type property

The media type of the document URL.

url property

The URL of the document.

__init__(url, kind='document-url')

Create a DocumentUrl object.

Parameters:

Name Type Description Default
url str

The URL of the document.

 required
kind Literal['document-url']

The kind of the content.

 'document-url'
Source code in python/potato_head/_potato_head.pyi 
170
171
172
173
174
175
176
177
178
179
180
181
182
def __init__(
    self,
    url: str,
    kind: Literal["document-url"] = "document-url",
) -> None:
    """Create a DocumentUrl object.

    Args:
        url (str):
            The URL of the document.
        kind (Literal["document-url"]):
            The kind of the content.
    """

Embedder

Class for creating embeddings.

Source code in python/potato_head/_potato_head.pyi 
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
class Embedder:
    """Class for creating embeddings."""

    def __init__(  # type: ignore
        self,
        provider: Provider | str,
        config: Optional[OpenAIEmbeddingConfig | GeminiEmbeddingConfig] = None,
    ) -> None:
        """Create an Embedder object.

        Args:
            provider (Provider | str):
                The provider to use for the embedder. This can be a Provider enum or a string
                representing the provider.
            config (Optional[OpenAIEmbeddingConfig | GeminiEmbeddingConfig]):
                The configuration to use for the embedder. This can be a Pydantic BaseModel class
                representing the configuration for the provider. If no config is provided,
                defaults to OpenAI provider configuration.
        """

    def embed(
        self,
        input: str | List[str] | PredictRequest,
    ) -> OpenAIEmbeddingResponse | GeminiEmbeddingResponse | PredictResponse:
        """Create embeddings for input.

        Args:
            input: The input to embed. Type depends on provider:
                - OpenAI/Gemini: str | List[str]
                - Vertex: PredictRequest

        Returns:
            Provider-specific response type.
            OpenAIEmbeddingResponse for OpenAI,
            GeminiEmbeddingResponse for Gemini,
            PredictResponse for Vertex.

        Examples:
            ```python
            ## OpenAI
            embedder = Embedder(Provider.OpenAI)
            response = embedder.embed(input="Test input")

            ## Gemini
            embedder = Embedder(Provider.Gemini, config=GeminiEmbeddingConfig(model="gemini-embedding-001"))
            response = embedder.embed(input="Test input")

            ## Vertex
            from potato_head.google import PredictRequest
            embedder = Embedder(Provider.Vertex)
            response = embedder.embed(input=PredictRequest(text="Test input"))
            ```
        """

__init__(provider, config=None)

Create an Embedder object.

Parameters:

Name Type Description Default
provider Provider | str

The provider to use for the embedder. This can be a Provider enum or a string representing the provider.

 required
config Optional[OpenAIEmbeddingConfig | GeminiEmbeddingConfig]

The configuration to use for the embedder. This can be a Pydantic BaseModel class representing the configuration for the provider. If no config is provided, defaults to OpenAI provider configuration.

 None
Source code in python/potato_head/_potato_head.pyi 
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
def __init__(  # type: ignore
    self,
    provider: Provider | str,
    config: Optional[OpenAIEmbeddingConfig | GeminiEmbeddingConfig] = None,
) -> None:
    """Create an Embedder object.

    Args:
        provider (Provider | str):
            The provider to use for the embedder. This can be a Provider enum or a string
            representing the provider.
        config (Optional[OpenAIEmbeddingConfig | GeminiEmbeddingConfig]):
            The configuration to use for the embedder. This can be a Pydantic BaseModel class
            representing the configuration for the provider. If no config is provided,
            defaults to OpenAI provider configuration.
    """

embed(input)

Create embeddings for input.

Parameters:

Name Type Description Default
input str | List[str] | PredictRequest

The input to embed. Type depends on provider: - OpenAI/Gemini: str | List[str] - Vertex: PredictRequest

 required

Returns:

Type Description
OpenAIEmbeddingResponse | GeminiEmbeddingResponse | PredictResponse

Provider-specific response type.
OpenAIEmbeddingResponse | GeminiEmbeddingResponse | PredictResponse

OpenAIEmbeddingResponse for OpenAI,
OpenAIEmbeddingResponse | GeminiEmbeddingResponse | PredictResponse

GeminiEmbeddingResponse for Gemini,
OpenAIEmbeddingResponse | GeminiEmbeddingResponse | PredictResponse

PredictResponse for Vertex.

Examples:

## OpenAI
embedder = Embedder(Provider.OpenAI)
response = embedder.embed(input="Test input")

## Gemini
embedder = Embedder(Provider.Gemini, config=GeminiEmbeddingConfig(model="gemini-embedding-001"))
response = embedder.embed(input="Test input")

## Vertex
from potato_head.google import PredictRequest
embedder = Embedder(Provider.Vertex)
response = embedder.embed(input=PredictRequest(text="Test input"))
Source code in python/potato_head/_potato_head.pyi 
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
def embed(
    self,
    input: str | List[str] | PredictRequest,
) -> OpenAIEmbeddingResponse | GeminiEmbeddingResponse | PredictResponse:
    """Create embeddings for input.

    Args:
        input: The input to embed. Type depends on provider:
            - OpenAI/Gemini: str | List[str]
            - Vertex: PredictRequest

    Returns:
        Provider-specific response type.
        OpenAIEmbeddingResponse for OpenAI,
        GeminiEmbeddingResponse for Gemini,
        PredictResponse for Vertex.

    Examples:
        ```python
        ## OpenAI
        embedder = Embedder(Provider.OpenAI)
        response = embedder.embed(input="Test input")

        ## Gemini
        embedder = Embedder(Provider.Gemini, config=GeminiEmbeddingConfig(model="gemini-embedding-001"))
        response = embedder.embed(input="Test input")

        ## Vertex
        from potato_head.google import PredictRequest
        embedder = Embedder(Provider.Vertex)
        response = embedder.embed(input=PredictRequest(text="Test input"))
        ```
    """

EventDetails

Source code in python/potato_head/_potato_head.pyi 
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
class EventDetails:
    @property
    def prompt(self) -> Optional[Prompt]:
        """The prompt used for the task."""

    @property
    def response(self) -> Optional[ChatResponse]:
        """The response from the agent after executing the task."""

    @property
    def duration(self) -> Optional[datetime.timedelta]:
        """The duration of the task execution."""

    @property
    def start_time(self) -> Optional[datetime.datetime]:
        """The start time of the task execution."""

    @property
    def end_time(self) -> Optional[datetime.datetime]:
        """The end time of the task execution."""

    @property
    def error(self) -> Optional[str]:
        """The error message if the task failed, otherwise None."""

duration property

The duration of the task execution.

end_time property

The end time of the task execution.

error property

The error message if the task failed, otherwise None.

prompt property

The prompt used for the task.

response property

The response from the agent after executing the task.

start_time property

The start time of the task execution.

ImageUrl

Source code in python/potato_head/_potato_head.pyi 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
class ImageUrl:
    def __init__(
        self,
        url: str,
        kind: Literal["image-url"] = "image-url",
    ) -> None:
        """Create an ImageUrl object.

        Args:
            url (str):
                The URL of the image.
            kind (Literal["image-url"]):
                The kind of the content.
        """

    @property
    def url(self) -> str:
        """The URL of the image."""

    @property
    def kind(self) -> str:
        """The kind of the content."""

    @property
    def media_type(self) -> str:
        """The media type of the image URL."""

    @property
    def format(self) -> str:
        """The format of the image URL."""

format property

The format of the image URL.

kind property

The kind of the content.

media_type property

The media type of the image URL.

url property

The URL of the image.

__init__(url, kind='image-url')

Create an ImageUrl object.

Parameters:

Name Type Description Default
url str

The URL of the image.

 required
kind Literal['image-url']

The kind of the content.

 'image-url'
Source code in python/potato_head/_potato_head.pyi 
74
75
76
77
78
79
80
81
82
83
84
85
86
def __init__(
    self,
    url: str,
    kind: Literal["image-url"] = "image-url",
) -> None:
    """Create an ImageUrl object.

    Args:
        url (str):
            The URL of the image.
        kind (Literal["image-url"]):
            The kind of the content.
    """

LogProbs

Source code in python/potato_head/_potato_head.pyi 
494
495
496
497
498
499
500
501
502
class LogProbs:
    @property
    def tokens(self) -> List[ResponseLogProbs]:
        """The log probabilities of the tokens in the response.
        This is primarily used for debugging and analysis purposes.
        """

    def __str__(self) -> str:
        """String representation of the log probabilities."""

tokens property

The log probabilities of the tokens in the response. This is primarily used for debugging and analysis purposes.

__str__()

String representation of the log probabilities.

Source code in python/potato_head/_potato_head.pyi 
501
502
def __str__(self) -> str:
    """String representation of the log probabilities."""

Message

Source code in python/potato_head/_potato_head.pyi 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
class Message:
    def __init__(self, content: str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl) -> None:
        """Create a Message object.

        Args:
            content (str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl):
                The content of the message.
        """

    @property
    def content(self) -> str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl:
        """The content of the message"""

    def bind(self, name: str, value: str) -> "Message":
        """Bind context to a specific variable in the prompt. This is an immutable operation meaning that it
        will return a new Message object with the context bound.

            Example with Prompt that contains two messages

            ```python
                prompt = Prompt(
                    model="openai:gpt-4o",
                    message=[
                        "My prompt variable is ${variable}",
                        "This is another message",
                    ],
                    system_instruction="system_prompt",
                )
                bounded_prompt = prompt.message[0].bind("variable", "hello world").unwrap() # we bind "hello world" to "variable"
            ```

        Args:
            name (str):
                The name of the variable to bind.
            value (str):
                The value to bind the variable to.

        Returns:
            Message:
                The message with the context bound.
        """

    def bind_mut(self, name: str, value: str) -> "Message":
        """Bind context to a specific variable in the prompt. This is a mutable operation meaning that it
        will modify the current Message object.

            Example with Prompt that contains two messages

            ```python
                prompt = Prompt(
                    model="openai:gpt-4o",
                    message=[
                        "My prompt variable is ${variable}",
                        "This is another message",
                    ],
                    system_instruction="system_prompt",
                )
                prompt.message[0].bind_mut("variable", "hello world") # we bind "hello world" to "variable"
            ```

        Args:
            name (str):
                The name of the variable to bind.
            value (str):
                The value to bind the variable to.

        Returns:
            Message:
                The message with the context bound.
        """

    def unwrap(self) -> Any:
        """Unwrap the message content.

        Returns:
            A serializable representation of the message content, which can be a string, list, or dict.
        """

    def model_dump(self) -> Dict[str, Any]:
        """Unwrap the message content and serialize it to a dictionary.

        Returns:
            Dict[str, Any]:
                The message dictionary with keys "content" and "role".
        """

content property

The content of the message

__init__(content)

Create a Message object.

Parameters:

Name Type Description Default
content str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl

The content of the message.

 required
Source code in python/potato_head/_potato_head.pyi 
201
202
203
204
205
206
207
def __init__(self, content: str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl) -> None:
    """Create a Message object.

    Args:
        content (str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl):
            The content of the message.
    """

bind(name, value)

Bind context to a specific variable in the prompt. This is an immutable operation meaning that it will return a new Message object with the context bound.

Example with Prompt that contains two messages

```python
    prompt = Prompt(
        model="openai:gpt-4o",
        message=[
            "My prompt variable is ${variable}",
            "This is another message",
        ],
        system_instruction="system_prompt",
    )
    bounded_prompt = prompt.message[0].bind("variable", "hello world").unwrap() # we bind "hello world" to "variable"
```

Parameters:

Name Type Description Default
name str

The name of the variable to bind.

 required
value str

The value to bind the variable to.

 required

Returns:

Name Type Description
Message Message

The message with the context bound.
Source code in python/potato_head/_potato_head.pyi 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
def bind(self, name: str, value: str) -> "Message":
    """Bind context to a specific variable in the prompt. This is an immutable operation meaning that it
    will return a new Message object with the context bound.

        Example with Prompt that contains two messages

        ```python
            prompt = Prompt(
                model="openai:gpt-4o",
                message=[
                    "My prompt variable is ${variable}",
                    "This is another message",
                ],
                system_instruction="system_prompt",
            )
            bounded_prompt = prompt.message[0].bind("variable", "hello world").unwrap() # we bind "hello world" to "variable"
        ```

    Args:
        name (str):
            The name of the variable to bind.
        value (str):
            The value to bind the variable to.

    Returns:
        Message:
            The message with the context bound.
    """

bind_mut(name, value)

Bind context to a specific variable in the prompt. This is a mutable operation meaning that it will modify the current Message object.

Example with Prompt that contains two messages

```python
    prompt = Prompt(
        model="openai:gpt-4o",
        message=[
            "My prompt variable is ${variable}",
            "This is another message",
        ],
        system_instruction="system_prompt",
    )
    prompt.message[0].bind_mut("variable", "hello world") # we bind "hello world" to "variable"
```

Parameters:

Name Type Description Default
name str

The name of the variable to bind.

 required
value str

The value to bind the variable to.

 required

Returns:

Name Type Description
Message Message

The message with the context bound.
Source code in python/potato_head/_potato_head.pyi 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
def bind_mut(self, name: str, value: str) -> "Message":
    """Bind context to a specific variable in the prompt. This is a mutable operation meaning that it
    will modify the current Message object.

        Example with Prompt that contains two messages

        ```python
            prompt = Prompt(
                model="openai:gpt-4o",
                message=[
                    "My prompt variable is ${variable}",
                    "This is another message",
                ],
                system_instruction="system_prompt",
            )
            prompt.message[0].bind_mut("variable", "hello world") # we bind "hello world" to "variable"
        ```

    Args:
        name (str):
            The name of the variable to bind.
        value (str):
            The value to bind the variable to.

    Returns:
        Message:
            The message with the context bound.
    """

model_dump()

Unwrap the message content and serialize it to a dictionary.

Returns:

Type Description
Dict[str, Any]

Dict[str, Any]: The message dictionary with keys "content" and "role".
Source code in python/potato_head/_potato_head.pyi 
278
279
280
281
282
283
284
def model_dump(self) -> Dict[str, Any]:
    """Unwrap the message content and serialize it to a dictionary.

    Returns:
        Dict[str, Any]:
            The message dictionary with keys "content" and "role".
    """

unwrap()

Unwrap the message content.

Returns:

Type Description
Any

A serializable representation of the message content, which can be a string, list, or dict.
Source code in python/potato_head/_potato_head.pyi 
271
272
273
274
275
276
def unwrap(self) -> Any:
    """Unwrap the message content.

    Returns:
        A serializable representation of the message content, which can be a string, list, or dict.
    """

ModelSettings

Source code in python/potato_head/_potato_head.pyi 
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
class ModelSettings:
    def __init__(self, settings: OpenAIChatSettings | GeminiSettings) -> None:
        """ModelSettings for configuring the model.

        Args:
            settings (OpenAIChatSettings | GeminiSettings):
                The settings to use for the model. Currently supports OpenAI and Gemini settings.
        """

    @property
    def settings(self) -> OpenAIChatSettings | GeminiSettings:
        """The settings to use for the model."""

    def model_dump_json(self) -> str:
        """The JSON representation of the model settings."""

settings property

The settings to use for the model.

__init__(settings)

ModelSettings for configuring the model.

Parameters:

Name Type Description Default
settings OpenAIChatSettings | GeminiSettings

The settings to use for the model. Currently supports OpenAI and Gemini settings.

 required
Source code in python/potato_head/_potato_head.pyi 
287
288
289
290
291
292
293
def __init__(self, settings: OpenAIChatSettings | GeminiSettings) -> None:
    """ModelSettings for configuring the model.

    Args:
        settings (OpenAIChatSettings | GeminiSettings):
            The settings to use for the model. Currently supports OpenAI and Gemini settings.
    """

model_dump_json()

The JSON representation of the model settings.

Source code in python/potato_head/_potato_head.pyi 
299
300
def model_dump_json(self) -> str:
    """The JSON representation of the model settings."""

Prompt

Source code in python/potato_head/_potato_head.pyi 
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
class Prompt:
    def __init__(
        self,
        message: (
            str
            | Sequence[str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl]
            | Message
            | List[Message]
            | List[Dict[str, Any]]
        ),
        model: str,
        provider: Provider | str,
        system_instruction: Optional[str | List[str]] = None,
        model_settings: Optional[ModelSettings | OpenAIChatSettings | GeminiSettings] = None,
        response_format: Optional[Any] = None,
    ) -> None:
        """Prompt for interacting with an LLM API.

        Args:
            message (str | Sequence[str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl] | Message | List[Message]):
                The prompt to use.
            model (str):
                The model to use for the prompt
            provider (Provider | str):
                The provider to use for the prompt.
            system_instruction (Optional[str | List[str]]):
                The system prompt to use in the prompt.
            model_settings (None):
                The model settings to use for the prompt.
                Defaults to None which means no model settings will be used
            response_format (Optional[BaseModel | Score]):
                The response format to use for the prompt. This is used for Structured Outputs
                (https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat).
                Currently, response_format only support Pydantic BaseModel classes and the PotatoHead Score class.
                The provided response_format will be parsed into a JSON schema.

        """

    @property
    def model(self) -> str:
        """The model to use for the prompt."""

    @property
    def provider(self) -> str:
        """The provider to use for the prompt."""

    @property
    def model_identifier(self) -> Any:
        """Concatenation of provider and model, used for identifying the model in the prompt. This
        is commonly used with pydantic_ai to identify the model to use for the agent.

        Example:
            ```python
                prompt = Prompt(
                    model="gpt-4o",
                    message="My prompt variable is ${variable}",
                    system_instruction="system_instruction",
                    provider="openai",
                )
                agent = Agent(
                    prompt.model_identifier, # "openai:gpt-4o"
                    system_instructions=prompt.system_instruction[0].unwrap(),
                )
            ```
        """

    @property
    def model_settings(self) -> ModelSettings:
        """The model settings to use for the prompt."""

    @property
    def message(
        self,
    ) -> List[Message]:
        """The user message to use in the prompt."""

    @property
    def system_instruction(self) -> List[Message]:
        """The system message to use in the prompt."""

    def save_prompt(self, path: Optional[Path] = None) -> None:
        """Save the prompt to a file.

        Args:
            path (Optional[Path]):
                The path to save the prompt to. If None, the prompt will be saved to
                the current working directory.
        """

    @staticmethod
    def from_path(path: Path) -> "Prompt":
        """Load a prompt from a file.

        Args:
            path (Path):
                The path to the prompt file.

        Returns:
            Prompt:
                The loaded prompt.
        """

    @staticmethod
    def model_validate_json(json_string: str) -> "Prompt":
        """Validate the model JSON.

        Args:
            json_string (str):
                The JSON string to validate.
        Returns:
            Prompt:
                The prompt object.
        """

    def model_dump_json(self) -> str:
        """Dump the model to a JSON string.

        Returns:
            str:
                The JSON string.
        """

    def bind(
        self,
        name: Optional[str] = None,
        value: Optional[str | int | float | bool | list] = None,
        **kwargs: Any,
    ) -> "Prompt":
        """Bind context to a specific variable in the prompt. This is an immutable operation meaning that it
        will return a new Prompt object with the context bound. This will iterate over all user messages.

        Args:
            name (str):
                The name of the variable to bind.
            value (str | int | float | bool | list):
                The value to bind the variable to. Must be a JSON serializable type.
            **kwargs (Any):
                Additional keyword arguments to bind to the prompt. This can be used to bind multiple variables at once.

        Returns:
            Prompt:
                The prompt with the context bound.
        """

    def bind_mut(
        self,
        name: Optional[str] = None,
        value: Optional[str | int | float | bool | list] = None,
        **kwargs: Any,
    ) -> "Prompt":
        """Bind context to a specific variable in the prompt. This is a mutable operation meaning that it
        will modify the current Prompt object. This will iterate over all user messages.

        Args:
            name (str):
                The name of the variable to bind.
            value (str | int | float | bool | list):
                The value to bind the variable to. Must be a JSON serializable type.
            **kwargs (Any):
                Additional keyword arguments to bind to the prompt. This can be used to bind multiple variables at once.

        Returns:
            Prompt:
                The prompt with the context bound.
        """

    @property
    def response_json_schema(self) -> Optional[str]:
        """The JSON schema for the response if provided."""

    def __str__(self): ...

message property

The user message to use in the prompt.

model property

The model to use for the prompt.

model_identifier property

Concatenation of provider and model, used for identifying the model in the prompt. This is commonly used with pydantic_ai to identify the model to use for the agent.

Example 
    prompt = Prompt(
        model="gpt-4o",
        message="My prompt variable is ${variable}",
        system_instruction="system_instruction",
        provider="openai",
    )
    agent = Agent(
        prompt.model_identifier, # "openai:gpt-4o"
        system_instructions=prompt.system_instruction[0].unwrap(),
    )

model_settings property

The model settings to use for the prompt.

provider property

The provider to use for the prompt.

response_json_schema property

The JSON schema for the response if provided.

system_instruction property

The system message to use in the prompt.

__init__(message, model, provider, system_instruction=None, model_settings=None, response_format=None)

Prompt for interacting with an LLM API.

Parameters:

Name Type Description Default
message str | Sequence[str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl] | Message | List[Message]

The prompt to use.

 required
model str

The model to use for the prompt

 required
provider Provider | str

The provider to use for the prompt.

 required
system_instruction Optional[str | List[str]]

The system prompt to use in the prompt.

 None
model_settings None

The model settings to use for the prompt. Defaults to None which means no model settings will be used

 None
response_format Optional[BaseModel | Score]

The response format to use for the prompt. This is used for Structured Outputs (https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat). Currently, response_format only support Pydantic BaseModel classes and the PotatoHead Score class. The provided response_format will be parsed into a JSON schema.

 None
Source code in python/potato_head/_potato_head.pyi 
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
def __init__(
    self,
    message: (
        str
        | Sequence[str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl]
        | Message
        | List[Message]
        | List[Dict[str, Any]]
    ),
    model: str,
    provider: Provider | str,
    system_instruction: Optional[str | List[str]] = None,
    model_settings: Optional[ModelSettings | OpenAIChatSettings | GeminiSettings] = None,
    response_format: Optional[Any] = None,
) -> None:
    """Prompt for interacting with an LLM API.

    Args:
        message (str | Sequence[str | ImageUrl | AudioUrl | BinaryContent | DocumentUrl] | Message | List[Message]):
            The prompt to use.
        model (str):
            The model to use for the prompt
        provider (Provider | str):
            The provider to use for the prompt.
        system_instruction (Optional[str | List[str]]):
            The system prompt to use in the prompt.
        model_settings (None):
            The model settings to use for the prompt.
            Defaults to None which means no model settings will be used
        response_format (Optional[BaseModel | Score]):
            The response format to use for the prompt. This is used for Structured Outputs
            (https://platform.openai.com/docs/guides/structured-outputs?api-mode=chat).
            Currently, response_format only support Pydantic BaseModel classes and the PotatoHead Score class.
            The provided response_format will be parsed into a JSON schema.

    """

bind(name=None, value=None, **kwargs)

Bind context to a specific variable in the prompt. This is an immutable operation meaning that it will return a new Prompt object with the context bound. This will iterate over all user messages.

Parameters:

Name Type Description Default
name str

The name of the variable to bind.

 None
value str | int | float | bool | list

The value to bind the variable to. Must be a JSON serializable type.

 None
**kwargs Any

Additional keyword arguments to bind to the prompt. This can be used to bind multiple variables at once.

 {}

Returns:

Name Type Description
Prompt Prompt

The prompt with the context bound.
Source code in python/potato_head/_potato_head.pyi 
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
def bind(
    self,
    name: Optional[str] = None,
    value: Optional[str | int | float | bool | list] = None,
    **kwargs: Any,
) -> "Prompt":
    """Bind context to a specific variable in the prompt. This is an immutable operation meaning that it
    will return a new Prompt object with the context bound. This will iterate over all user messages.

    Args:
        name (str):
            The name of the variable to bind.
        value (str | int | float | bool | list):
            The value to bind the variable to. Must be a JSON serializable type.
        **kwargs (Any):
            Additional keyword arguments to bind to the prompt. This can be used to bind multiple variables at once.

    Returns:
        Prompt:
            The prompt with the context bound.
    """

bind_mut(name=None, value=None, **kwargs)

Bind context to a specific variable in the prompt. This is a mutable operation meaning that it will modify the current Prompt object. This will iterate over all user messages.

Parameters:

Name Type Description Default
name str

The name of the variable to bind.

 None
value str | int | float | bool | list

The value to bind the variable to. Must be a JSON serializable type.

 None
**kwargs Any

Additional keyword arguments to bind to the prompt. This can be used to bind multiple variables at once.

 {}

Returns:

Name Type Description
Prompt Prompt

The prompt with the context bound.
Source code in python/potato_head/_potato_head.pyi 
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
def bind_mut(
    self,
    name: Optional[str] = None,
    value: Optional[str | int | float | bool | list] = None,
    **kwargs: Any,
) -> "Prompt":
    """Bind context to a specific variable in the prompt. This is a mutable operation meaning that it
    will modify the current Prompt object. This will iterate over all user messages.

    Args:
        name (str):
            The name of the variable to bind.
        value (str | int | float | bool | list):
            The value to bind the variable to. Must be a JSON serializable type.
        **kwargs (Any):
            Additional keyword arguments to bind to the prompt. This can be used to bind multiple variables at once.

    Returns:
        Prompt:
            The prompt with the context bound.
    """

from_path(path) staticmethod

Load a prompt from a file.

Parameters:

Name Type Description Default
path Path

The path to the prompt file.

 required

Returns:

Name Type Description
Prompt Prompt

The loaded prompt.
Source code in python/potato_head/_potato_head.pyi 
391
392
393
394
395
396
397
398
399
400
401
402
@staticmethod
def from_path(path: Path) -> "Prompt":
    """Load a prompt from a file.

    Args:
        path (Path):
            The path to the prompt file.

    Returns:
        Prompt:
            The loaded prompt.
    """

model_dump_json()

Dump the model to a JSON string.

Returns:

Name Type Description
str str

The JSON string.
Source code in python/potato_head/_potato_head.pyi 
416
417
418
419
420
421
422
def model_dump_json(self) -> str:
    """Dump the model to a JSON string.

    Returns:
        str:
            The JSON string.
    """

model_validate_json(json_string) staticmethod

Validate the model JSON.

Parameters:

Name Type Description Default
json_string str

The JSON string to validate.

 required

Returns: Prompt: The prompt object.

Source code in python/potato_head/_potato_head.pyi 
404
405
406
407
408
409
410
411
412
413
414
@staticmethod
def model_validate_json(json_string: str) -> "Prompt":
    """Validate the model JSON.

    Args:
        json_string (str):
            The JSON string to validate.
    Returns:
        Prompt:
            The prompt object.
    """

save_prompt(path=None)

Save the prompt to a file.

Parameters:

Name Type Description Default
path Optional[Path]

The path to save the prompt to. If None, the prompt will be saved to the current working directory.

 None
Source code in python/potato_head/_potato_head.pyi 
382
383
384
385
386
387
388
389
def save_prompt(self, path: Optional[Path] = None) -> None:
    """Save the prompt to a file.

    Args:
        path (Optional[Path]):
            The path to save the prompt to. If None, the prompt will be saved to
            the current working directory.
    """

PromptTokenDetails

Details about the prompt tokens used in a request.

Source code in python/potato_head/_potato_head.pyi 
16
17
18
19
20
21
22
23
24
25
class PromptTokenDetails:
    """Details about the prompt tokens used in a request."""

    @property
    def audio_tokens(self) -> int:
        """The number of audio tokens used in the request."""

    @property
    def cached_tokens(self) -> int:
        """The number of cached tokens used in the request."""

audio_tokens property

The number of audio tokens used in the request.

cached_tokens property

The number of cached tokens used in the request.

PyTask

Python-specific task interface for Task objects and results

Source code in python/potato_head/_potato_head.pyi 
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
class PyTask:
    """Python-specific task interface for Task objects and results"""

    @property
    def prompt(self) -> Prompt:
        """The prompt to use for the task."""

    @property
    def dependencies(self) -> List[str]:
        """The dependencies of the task."""

    @property
    def id(self) -> str:
        """The ID of the task."""

    @property
    def agent_id(self) -> str:
        """The ID of the agent that will execute the task."""

    @property
    def status(self) -> TaskStatus:
        """The status of the task."""

    @property
    def result(self) -> Optional[AgentResponse]:
        """The result of the task if it has been executed, otherwise None."""

    def __str__(self) -> str: ...

agent_id property

The ID of the agent that will execute the task.

dependencies property

The dependencies of the task.

id property

The ID of the task.

prompt property

The prompt to use for the task.

result property

The result of the task if it has been executed, otherwise None.

status property

The status of the task.

ResponseLogProbs

Source code in python/potato_head/_potato_head.pyi 
485
486
487
488
489
490
491
492
class ResponseLogProbs:
    @property
    def token(self) -> str:
        """The token for which the log probabilities are calculated."""

    @property
    def logprob(self) -> float:
        """The log probability of the token."""

logprob property

The log probability of the token.

token property

The token for which the log probabilities are calculated.

Score

A class representing a score with a score value and a reason. This is typically used as a response type for tasks/prompts that require scoring or evaluation of results.

Example: 

    Prompt(
        model="openai:gpt-4o",
        message="What is the score of this response?",
        system_instruction="system_prompt",
        response_format=Score,
    )

Source code in python/potato_head/_potato_head.pyi 
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
class Score:
    """A class representing a score with a score value and a reason. This is typically used
    as a response type for tasks/prompts that require scoring or evaluation of results.

    Example:
    ```python
        Prompt(
            model="openai:gpt-4o",
            message="What is the score of this response?",
            system_instruction="system_prompt",
            response_format=Score,
        )
    ```
    """

    @property
    def score(self) -> int:
        """The score value."""

    @property
    def reason(self) -> str:
        """The reason for the score."""

    @staticmethod
    def model_validate_json(json_string: str) -> "Score":
        """Validate the score JSON.

        Args:
            json_string (str):
                The JSON string to validate.

        Returns:
            Score:
                The score object.
        """

    def __str__(self): ...

reason property

The reason for the score.

score property

The score value.

model_validate_json(json_string) staticmethod

Validate the score JSON.

Parameters:

Name Type Description Default
json_string str

The JSON string to validate.

 required

Returns:

Name Type Description
Score Score

The score object.
Source code in python/potato_head/_potato_head.pyi 
955
956
957
958
959
960
961
962
963
964
965
966
@staticmethod
def model_validate_json(json_string: str) -> "Score":
    """Validate the score JSON.

    Args:
        json_string (str):
            The JSON string to validate.

    Returns:
        Score:
            The score object.
    """

Task

Source code in python/potato_head/_potato_head.pyi 
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
class Task:
    def __init__(
        self,
        agent_id: str,
        prompt: Prompt,
        dependencies: List[str] = [],
        id: Optional[str] = None,
    ) -> None:
        """Create a Task object.

        Args:
            agent_id (str):
                The ID of the agent that will execute the task.
            prompt (Prompt):
                The prompt to use for the task.
            dependencies (List[str]):
                The dependencies of the task.
            id (Optional[str]):
                The ID of the task. If None, a random uuid7 will be generated.
        """

    @property
    def prompt(self) -> Prompt:
        """The prompt to use for the task."""

    @property
    def dependencies(self) -> List[str]:
        """The dependencies of the task."""

    @property
    def id(self) -> str:
        """The ID of the task."""

    @property
    def status(self) -> TaskStatus:
        """The status of the task."""

dependencies property

The dependencies of the task.

id property

The ID of the task.

prompt property

The prompt to use for the task.

status property

The status of the task.

__init__(agent_id, prompt, dependencies=[], id=None)

Create a Task object.

Parameters:

Name Type Description Default
agent_id str

The ID of the agent that will execute the task.

 required
prompt Prompt

The prompt to use for the task.

 required
dependencies List[str]

The dependencies of the task.

 []
id Optional[str]

The ID of the task. If None, a random uuid7 will be generated.

 None
Source code in python/potato_head/_potato_head.pyi 
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
def __init__(
    self,
    agent_id: str,
    prompt: Prompt,
    dependencies: List[str] = [],
    id: Optional[str] = None,
) -> None:
    """Create a Task object.

    Args:
        agent_id (str):
            The ID of the agent that will execute the task.
        prompt (Prompt):
            The prompt to use for the task.
        dependencies (List[str]):
            The dependencies of the task.
        id (Optional[str]):
            The ID of the task. If None, a random uuid7 will be generated.
    """

TaskEvent

Source code in python/potato_head/_potato_head.pyi 
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
class TaskEvent:
    @property
    def id(self) -> str:
        """The ID of the event"""

    @property
    def workflow_id(self) -> str:
        """The ID of the workflow that the task is part of."""

    @property
    def task_id(self) -> str:
        """The ID of the task that the event is associated with."""

    @property
    def status(self) -> TaskStatus:
        """The status of the task at the time of the event."""

    @property
    def timestamp(self) -> datetime.datetime:
        """The timestamp of the event. This is the time when the event occurred."""

    @property
    def updated_at(self) -> datetime.datetime:
        """The timestamp of when the event was last updated. This is useful for tracking changes to the event."""

    @property
    def details(self) -> EventDetails:
        """Additional details about the event. This can include information such as error messages or other relevant data."""

details property

Additional details about the event. This can include information such as error messages or other relevant data.

id property

The ID of the event

status property

The status of the task at the time of the event.

task_id property

The ID of the task that the event is associated with.

timestamp property

The timestamp of the event. This is the time when the event occurred.

updated_at property

The timestamp of when the event was last updated. This is useful for tracking changes to the event.

workflow_id property

The ID of the workflow that the task is part of.

TaskList

Source code in python/potato_head/_potato_head.pyi 
562
563
564
class TaskList:
    def __init__(self) -> None:
        """Create a TaskList object."""

__init__()

Create a TaskList object.

Source code in python/potato_head/_potato_head.pyi 
563
564
def __init__(self) -> None:
    """Create a TaskList object."""

Usage

Usage statistics for a model response.

Source code in python/potato_head/_potato_head.pyi 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
class Usage:
    """Usage statistics for a model response."""

    @property
    def completion_tokens(self) -> int:
        """The number of completion tokens used in the response."""

    @property
    def prompt_tokens(self) -> int:
        """The number of prompt tokens used in the request."""

    @property
    def total_tokens(self) -> int:
        """The total number of tokens used in the request and response."""

    @property
    def completion_tokens_details(self) -> CompletionTokenDetails:
        """Details about the completion tokens used in the response."""

    @property
    def prompt_tokens_details(self) -> "PromptTokenDetails":
        """Details about the prompt tokens used in the request."""

    @property
    def finish_reason(self) -> str:
        """The reason why the model stopped generating tokens"""

completion_tokens property

The number of completion tokens used in the response.

completion_tokens_details property

Details about the completion tokens used in the response.

finish_reason property

The reason why the model stopped generating tokens

prompt_tokens property

The number of prompt tokens used in the request.

prompt_tokens_details property

Details about the prompt tokens used in the request.

total_tokens property

The total number of tokens used in the request and response.

Workflow

Source code in python/potato_head/_potato_head.pyi 
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
class Workflow:
    def __init__(self, name: str) -> None:
        """Create a Workflow object.

        Args:
            name (str):
                The name of the workflow.
        """

    @property
    def name(self) -> str:
        """The name of the workflow."""

    @property
    def task_list(self) -> TaskList:
        """The tasks in the workflow."""

    @property
    def agents(self) -> Dict[str, Agent]:
        """The agents in the workflow."""

    @property
    def is_workflow(self) -> bool:
        """Returns True if the workflow is a valid workflow, otherwise False.
        This is used to determine if the workflow can be executed.
        """

    def __workflow__(self) -> str:
        """Returns a string representation of the workflow."""

    def add_task_output_types(self, task_output_types: Dict[str, Any]) -> None:
        """Add output types for tasks in the workflow. This is primarily used for
        when loading a workflow as python objects are not serializable.

        Args:
            task_output_types (Dict[str, Any]):
                A dictionary mapping task IDs to their output types.
                This can either be a Pydantic `BaseModel` class or a supported potato_head response type such as `Score`.
        """

    def add_task(self, task: Task, output_type: Optional[Any]) -> None:
        """Add a task to the workflow.

        Args:
            task (Task):
                The task to add to the workflow.
            output_type (Optional[Any]):
                The output type to use for the task. This can either be a Pydantic `BaseModel` class
                or a supported potato_head response type such as `Score`.
        """

    def add_tasks(self, tasks: List[Task]) -> None:
        """Add multiple tasks to the workflow.

        Args:
            tasks (List[Task]):
                The tasks to add to the workflow.
        """

    def add_agent(self, agent: Agent) -> None:
        """Add an agent to the workflow.

        Args:
            agent (Agent):
                The agent to add to the workflow.
        """

    def is_complete(self) -> bool:
        """Check if the workflow is complete.

        Returns:
            bool:
                True if the workflow is complete, False otherwise.
        """

    def pending_count(self) -> int:
        """Get the number of pending tasks in the workflow.

        Returns:
            int:
                The number of pending tasks in the workflow.
        """

    def execution_plan(self) -> Dict[str, List[str]]:
        """Get the execution plan for the workflow.

        Returns:
            Dict[str, List[str]]:
                A dictionary where the keys are task IDs and the values are lists of task IDs
                that the task depends on.
        """

    def run(
        self,
        global_context: Optional[Dict[str, Any]] = None,
    ) -> WorkflowResult:
        """Run the workflow. This will execute all tasks in the workflow and return when all tasks are complete.

        Args:
            global_context (Optional[Dict[str, Any]]):
                A dictionary of global context to bind to the workflow.
                All tasks in the workflow will have this context bound to them.
        """

    def model_dump_json(self) -> str:
        """Dump the workflow to a JSON string.

        Returns:
            str:
                The JSON string.
        """

    @staticmethod
    def model_validate_json(json_string: str, output_types: Optional[Dict[str, Any]]) -> "Workflow":
        """Load a workflow from a JSON string.

        Args:
            json_string (str):
                The JSON string to validate.
            output_types (Optional[Dict[str, Any]]):
                A dictionary mapping task IDs to their output types.
                This can either be a Pydantic `BaseModel` class or a supported potato_head response type such as `Score`.

        Returns:
            Workflow:
                The workflow object.
        """

agents property

The agents in the workflow.

is_workflow property

Returns True if the workflow is a valid workflow, otherwise False. This is used to determine if the workflow can be executed.

name property

The name of the workflow.

task_list property

The tasks in the workflow.

__init__(name)

Create a Workflow object.

Parameters:

Name Type Description Default
name str

The name of the workflow.

 required
Source code in python/potato_head/_potato_head.pyi 
704
705
706
707
708
709
710
def __init__(self, name: str) -> None:
    """Create a Workflow object.

    Args:
        name (str):
            The name of the workflow.
    """

__workflow__()

Returns a string representation of the workflow.

Source code in python/potato_head/_potato_head.pyi 
730
731
def __workflow__(self) -> str:
    """Returns a string representation of the workflow."""

add_agent(agent)

Add an agent to the workflow.

Parameters:

Name Type Description Default
agent Agent

The agent to add to the workflow.

 required
Source code in python/potato_head/_potato_head.pyi 
762
763
764
765
766
767
768
def add_agent(self, agent: Agent) -> None:
    """Add an agent to the workflow.

    Args:
        agent (Agent):
            The agent to add to the workflow.
    """

add_task(task, output_type)

Add a task to the workflow.

Parameters:

Name Type Description Default
task Task

The task to add to the workflow.

 required
output_type Optional[Any]

The output type to use for the task. This can either be a Pydantic BaseModel class or a supported potato_head response type such as Score.

 required
Source code in python/potato_head/_potato_head.pyi 
743
744
745
746
747
748
749
750
751
752
def add_task(self, task: Task, output_type: Optional[Any]) -> None:
    """Add a task to the workflow.

    Args:
        task (Task):
            The task to add to the workflow.
        output_type (Optional[Any]):
            The output type to use for the task. This can either be a Pydantic `BaseModel` class
            or a supported potato_head response type such as `Score`.
    """

add_task_output_types(task_output_types)

Add output types for tasks in the workflow. This is primarily used for when loading a workflow as python objects are not serializable.

Parameters:

Name Type Description Default
task_output_types Dict[str, Any]

A dictionary mapping task IDs to their output types. This can either be a Pydantic BaseModel class or a supported potato_head response type such as Score.

 required
Source code in python/potato_head/_potato_head.pyi 
733
734
735
736
737
738
739
740
741
def add_task_output_types(self, task_output_types: Dict[str, Any]) -> None:
    """Add output types for tasks in the workflow. This is primarily used for
    when loading a workflow as python objects are not serializable.

    Args:
        task_output_types (Dict[str, Any]):
            A dictionary mapping task IDs to their output types.
            This can either be a Pydantic `BaseModel` class or a supported potato_head response type such as `Score`.
    """

add_tasks(tasks)

Add multiple tasks to the workflow.

Parameters:

Name Type Description Default
tasks List[Task]

The tasks to add to the workflow.

 required
Source code in python/potato_head/_potato_head.pyi 
754
755
756
757
758
759
760
def add_tasks(self, tasks: List[Task]) -> None:
    """Add multiple tasks to the workflow.

    Args:
        tasks (List[Task]):
            The tasks to add to the workflow.
    """

execution_plan()

Get the execution plan for the workflow.

Returns:

Type Description
Dict[str, List[str]]

Dict[str, List[str]]: A dictionary where the keys are task IDs and the values are lists of task IDs that the task depends on.
Source code in python/potato_head/_potato_head.pyi 
786
787
788
789
790
791
792
793
def execution_plan(self) -> Dict[str, List[str]]:
    """Get the execution plan for the workflow.

    Returns:
        Dict[str, List[str]]:
            A dictionary where the keys are task IDs and the values are lists of task IDs
            that the task depends on.
    """

is_complete()

Check if the workflow is complete.

Returns:

Name Type Description
bool bool

True if the workflow is complete, False otherwise.
Source code in python/potato_head/_potato_head.pyi 
770
771
772
773
774
775
776
def is_complete(self) -> bool:
    """Check if the workflow is complete.

    Returns:
        bool:
            True if the workflow is complete, False otherwise.
    """

model_dump_json()

Dump the workflow to a JSON string.

Returns:

Name Type Description
str str

The JSON string.
Source code in python/potato_head/_potato_head.pyi 
807
808
809
810
811
812
813
def model_dump_json(self) -> str:
    """Dump the workflow to a JSON string.

    Returns:
        str:
            The JSON string.
    """

model_validate_json(json_string, output_types) staticmethod

Load a workflow from a JSON string.

Parameters:

Name Type Description Default
json_string str

The JSON string to validate.

 required
output_types Optional[Dict[str, Any]]

A dictionary mapping task IDs to their output types. This can either be a Pydantic BaseModel class or a supported potato_head response type such as Score.

 required

Returns:

Name Type Description
Workflow Workflow

The workflow object.
Source code in python/potato_head/_potato_head.pyi 
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
@staticmethod
def model_validate_json(json_string: str, output_types: Optional[Dict[str, Any]]) -> "Workflow":
    """Load a workflow from a JSON string.

    Args:
        json_string (str):
            The JSON string to validate.
        output_types (Optional[Dict[str, Any]]):
            A dictionary mapping task IDs to their output types.
            This can either be a Pydantic `BaseModel` class or a supported potato_head response type such as `Score`.

    Returns:
        Workflow:
            The workflow object.
    """

pending_count()

Get the number of pending tasks in the workflow.

Returns:

Name Type Description
int int

The number of pending tasks in the workflow.
Source code in python/potato_head/_potato_head.pyi 
778
779
780
781
782
783
784
def pending_count(self) -> int:
    """Get the number of pending tasks in the workflow.

    Returns:
        int:
            The number of pending tasks in the workflow.
    """

run(global_context=None)

Run the workflow. This will execute all tasks in the workflow and return when all tasks are complete.

Parameters:

Name Type Description Default
global_context Optional[Dict[str, Any]]

A dictionary of global context to bind to the workflow. All tasks in the workflow will have this context bound to them.

 None
Source code in python/potato_head/_potato_head.pyi 
795
796
797
798
799
800
801
802
803
804
805
def run(
    self,
    global_context: Optional[Dict[str, Any]] = None,
) -> WorkflowResult:
    """Run the workflow. This will execute all tasks in the workflow and return when all tasks are complete.

    Args:
        global_context (Optional[Dict[str, Any]]):
            A dictionary of global context to bind to the workflow.
            All tasks in the workflow will have this context bound to them.
    """

WorkflowResult

Source code in python/potato_head/_potato_head.pyi 
921
922
923
924
925
926
927
928
929
930
class WorkflowResult:
    @property
    def tasks(self) -> Dict[str, PyTask]:
        """The tasks in the workflow result."""

    @property
    def events(self) -> List[TaskEvent]:
        """The events that occurred during the workflow execution. This is a list of dictionaries
        where each dictionary contains information about the event such as the task ID, status, and timestamp.
        """

events property

The events that occurred during the workflow execution. This is a list of dictionaries where each dictionary contains information about the event such as the task ID, status, and timestamp.

tasks property

The tasks in the workflow result.