API Reference

This page documents the PDL members that likely to be used to run PDL programs from Python.

Program

PDL programs are represented by the Pydantic data structure defined in this file.

Classes:

Name	Description
PdlLocationType	Internal data structure to keep track of the source location information.
LocalizedExpression	Internal data structure for expressions with location information.
Pattern	Patterns allowed to match values in a case clause.
OrPattern
ArrayPattern
ObjectPattern
AnyPattern
Parser	Common fields for all parsers (parser field).
PdlParser
RegexParser	A regular expression parser
PdlTiming	Internal data structure to record timing information in the trace.
PdlUsage	Internal data structure to record token consumption usage information.
Block	Common fields for all PDL blocks.
FunctionBlock	Function declaration.
CallBlock	Calling a function.
LitellmParameters	Parameters passed to LiteLLM. More details at https://docs.litellm.ai/docs/completion/input.
ModelBlock	Common fields for the model blocks.
LitellmModelBlock	Call an LLM through the LiteLLM API.
GraniteioModelBlock	Call an LLM through the granite-io API.
CodeBlock	Execute a piece of code.
ArgsBlock	Execute a command line, which will spawn a subprocess with the given argument vector. Note: if you need a shell script execution, you must wrap your command line in /bin/sh or somne shell of your choosing.
GetBlock	Get the value of a variable.
DataBlock	Arbitrary value, equivalent to JSON.
TextBlock	Create the concatenation of the stringify version of the result of each block of the list of blocks.
LastOfBlock	Return the value of the last block if the list of blocks.
ArrayBlock	Return the array of values computed by each block of the list of blocks.
ObjectBlock	Return the object where the value of each field is defined by a block. If the body of the object is an array, the resulting object is the union of the objects computed by each element of the array.
MessageBlock	Create a message.
IfBlock	Conditional control structure.
MatchCase	Case of a match.
MatchBlock	Match control structure.
JoinConfig	Configure how loop iterations should be combined.
JoinText
JoinArray
JoinObject
JoinLastOf
RepeatBlock	Repeat the execution of a block.
ReadBlock	Read from a file or standard input.
IncludeBlock	Include a PDL file.
ImportBlock	Import a PDL file.
ErrorBlock	Block representing an error generated at runtime.
EmptyBlock	Block without an action. It can contain definitions.
Program	Prompt Declaration Language program (PDL)

Functions:

Name	Description
get_default_model_parameters	Model-specific defaults to apply
get_sampling_defaults	Model-specific defaults to apply if we are sampling.

Attributes:

Name	Type	Description
AdvancedBlockType	TypeAlias	Different types of structured blocks.
BlockType	TypeAlias	All kinds of blocks.
BlockOrBlocksType	TypeAlias	Block or list of blocks.

AdvancedBlockType: TypeAlias = FunctionBlock | CallBlock | LitellmModelBlock | GraniteioModelBlock | CodeBlock | ArgsBlock | GetBlock | DataBlock | IfBlock | MatchBlock | RepeatBlock | TextBlock | LastOfBlock | ArrayBlock | ObjectBlock | MessageBlock | ReadBlock | IncludeBlock | ImportBlock | ErrorBlock | EmptyBlock module-attribute

Different types of structured blocks.

BlockType: TypeAlias = None | bool | int | float | str | AdvancedBlockType module-attribute

All kinds of blocks.

BlockOrBlocksType: TypeAlias = BlockType | list[BlockType] module-attribute

Block or list of blocks.

PdlLocationType

Bases: BaseModel

Internal data structure to keep track of the source location information.

Source code in src/pdl/pdl_ast.py

class PdlLocationType(BaseModel):
    """Internal data structure to keep track of the source location information."""

    model_config = ConfigDict(extra="forbid")
    path: list[str]
    file: str
    table: dict[str, int]

LocalizedExpression

Bases: BaseModel, Generic[LocalizedExpressionT]

Internal data structure for expressions with location information.

Source code in src/pdl/pdl_ast.py

class LocalizedExpression(BaseModel, Generic[LocalizedExpressionT]):
    """Internal data structure for expressions with location information."""

    model_config = ConfigDict(
        extra="forbid",
        use_attribute_docstrings=True,
        arbitrary_types_allowed=True,
        model_title_generator=(lambda _: "LocalizedExpression"),
    )
    expr: Any
    pdl__result: Optional[LocalizedExpressionT] = None
    pdl__location: Optional[PdlLocationType] = None

Pattern

Bases: BaseModel

Patterns allowed to match values in a case clause.

Attributes:

Name	Type	Description
def_	Optional[str]	Name of the variable used to store the value matched by the pattern.

Source code in src/pdl/pdl_ast.py

class Pattern(BaseModel):
    """Patterns allowed to match values in a `case` clause."""

    model_config = ConfigDict(extra="forbid")
    def_: Optional[str] = Field(default=None, alias="def")
    """Name of the variable used to store the value matched by the pattern.
    """

def_: Optional[str] = Field(default=None, alias='def') class-attribute instance-attribute

Name of the variable used to store the value matched by the pattern.

OrPattern

Bases: Pattern

Attributes:

Name	Type	Description
anyOf	list[PatternType]	Match any of the patterns.

Source code in src/pdl/pdl_ast.py

class OrPattern(Pattern):
    anyOf: list["PatternType"]
    """Match any of the patterns."""

anyOf: list[PatternType] instance-attribute

Match any of the patterns.

ArrayPattern

Bases: Pattern

Attributes:

Name	Type	Description
array	list[PatternType]	Match an array.

Source code in src/pdl/pdl_ast.py

class ArrayPattern(Pattern):
    array: list["PatternType"]
    """Match an array."""

array: list[PatternType] instance-attribute

Match an array.

ObjectPattern

Bases: Pattern

Attributes:

Name	Type	Description
object	dict[str, PatternType]	Match an object.

Source code in src/pdl/pdl_ast.py

class ObjectPattern(Pattern):
    object: dict[str, "PatternType"]
    """Match an object."""

object: dict[str, PatternType] instance-attribute

Match an object.

AnyPattern

Bases: Pattern

Attributes:

Name	Type	Description
any	Literal[None]	Match any value.

Source code in src/pdl/pdl_ast.py

class AnyPattern(Pattern):
    any: Literal[None]
    """Match any value."""

any: Literal[None] instance-attribute

Match any value.

Parser

Bases: BaseModel

Common fields for all parsers (parser field).

Attributes:

Name	Type	Description
description	Optional[str]	Documentation associated to the parser.
spec	Optional[dict[str, Any]]	Expected type of the parsed value.

Source code in src/pdl/pdl_ast.py

class Parser(BaseModel):
    """Common fields for all parsers (`parser` field)."""

    model_config = ConfigDict(extra="forbid")
    description: Optional[str] = None
    """Documentation associated to the parser.
    """
    spec: Optional[dict[str, Any]] = None
    """Expected type of the parsed value.
    """

description: Optional[str] = None class-attribute instance-attribute

Documentation associated to the parser.

spec: Optional[dict[str, Any]] = None class-attribute instance-attribute

Expected type of the parsed value.

PdlParser

Bases: Parser

Attributes:

Name	Type	Description
pdl	BlockType	Use a PDL program as a parser specification.

Source code in src/pdl/pdl_ast.py

class PdlParser(Parser):
    pdl: "BlockType"
    """Use a PDL program as a parser specification."""

pdl: BlockType instance-attribute

Use a PDL program as a parser specification.

RegexParser

Bases: Parser

A regular expression parser

Attributes:

Name	Type	Description
regex	str	Regular expression to parse the value.
mode	Annotated[Literal['search', 'match', 'fullmatch', 'split', 'findall'], BeforeValidator(_ensure_lower)]	Function used to parse to value (https://docs.python.org/3/library/re.html).

Source code in src/pdl/pdl_ast.py

class RegexParser(Parser):
    """A regular expression parser"""

    regex: str
    """Regular expression to parse the value."""
    mode: Annotated[
        Literal["search", "match", "fullmatch", "split", "findall"],
        BeforeValidator(_ensure_lower),
    ] = "fullmatch"
    """Function used to parse to value (https://docs.python.org/3/library/re.html)."""

regex: str instance-attribute

Regular expression to parse the value.

mode: Annotated[Literal['search', 'match', 'fullmatch', 'split', 'findall'], BeforeValidator(_ensure_lower)] = 'fullmatch' class-attribute instance-attribute

Function used to parse to value (https://docs.python.org/3/library/re.html).

PdlTiming

Bases: BaseModel

Internal data structure to record timing information in the trace.

Attributes:

Name	Type	Description
start_nanos	Optional[int]	Time at which block execution began.
end_nanos	Optional[int]	Time at which block execution ended.
first_use_nanos	Optional[int]	Time at which the value of the block was needed for the first time.
timezone	Optional[str]	Timezone of start_nanos and end_nanos.

Source code in src/pdl/pdl_ast.py

class PdlTiming(BaseModel):
    """Internal data structure to record timing information in the trace."""

    model_config = ConfigDict(extra="forbid")
    start_nanos: Optional[int] = 0
    """Time at which block execution began.
    """
    end_nanos: Optional[int] = 0
    """Time at which block execution ended.
    """
    first_use_nanos: Optional[int] = 0
    """Time at which the value of the block was needed for the first time.
    """
    timezone: Optional[str] = ""
    """Timezone of start_nanos and end_nanos.
    """

start_nanos: Optional[int] = 0 class-attribute instance-attribute

Time at which block execution began.

end_nanos: Optional[int] = 0 class-attribute instance-attribute

Time at which block execution ended.

first_use_nanos: Optional[int] = 0 class-attribute instance-attribute

Time at which the value of the block was needed for the first time.

timezone: Optional[str] = '' class-attribute instance-attribute

Timezone of start_nanos and end_nanos.

PdlUsage

Bases: BaseModel

Internal data structure to record token consumption usage information.

Attributes:

Name	Type	Description
completion_tokens	Optional[int]	Completion tokens consumed
prompt_tokens	Optional[int]	Prompt tokens consumed

Source code in src/pdl/pdl_ast.py

class PdlUsage(BaseModel):
    """Internal data structure to record token consumption usage information."""

    completion_tokens: Optional[int] = 0
    """Completion tokens consumed
    """
    prompt_tokens: Optional[int] = 0
    """Prompt tokens consumed
    """

completion_tokens: Optional[int] = 0 class-attribute instance-attribute

Completion tokens consumed

prompt_tokens: Optional[int] = 0 class-attribute instance-attribute

Prompt tokens consumed

Block

Bases: BaseModel

Common fields for all PDL blocks.

Attributes:

Name	Type	Description
description	Optional[str]	Documentation associated to the block.
spec	Any	Type specification of the result of the block.
defs	dict[str, BlockType]	Set of definitions executed before the execution of the block.
def_	Optional[str]	Name of the variable used to store the result of the execution of the block.
contribute	Sequence[ContributeTarget | dict[str, ContributeValue]]	Indicate if the block contributes to the result and background context.
parser	Annotated[Optional[ParserType], BeforeValidator(_ensure_lower)]	Parser to use to construct a value out of a string result.
fallback	Optional[BlockType]	Block to execute in case of error.
role	RoleType	Role associated to the block and sub-blocks.
context	Optional[ModelInput]	Current context
pdl__id	Optional[str]	Unique identifier for this block
pdl__result	Optional[Any]	Result of the execution of the block

Source code in src/pdl/pdl_ast.py

class Block(BaseModel):
    """Common fields for all PDL blocks."""

    model_config = ConfigDict(
        extra="forbid",
        use_attribute_docstrings=True,
        arbitrary_types_allowed=True,
    )

    description: Optional[str] = None
    """Documentation associated to the block.
    """
    spec: Any = None
    """Type specification of the result of the block.
    """
    defs: dict[str, "BlockType"] = {}
    """Set of definitions executed before the execution of the block.
    """
    def_: Optional[str] = Field(default=None, alias="def")
    """Name of the variable used to store the result of the execution of the block.
    """
    contribute: Sequence[ContributeTarget | dict[str, ContributeValue]] = [
        ContributeTarget.RESULT,
        ContributeTarget.CONTEXT,
    ]
    """Indicate if the block contributes to the result and background context.
    """
    parser: Annotated[Optional[ParserType], BeforeValidator(_ensure_lower)] = None
    """Parser to use to construct a value out of a string result."""
    fallback: Optional["BlockType"] = None
    """Block to execute in case of error.
    """
    role: RoleType = None
    """Role associated to the block and sub-blocks.
    Typical roles are `system`, `user`, and `assistant`,
    but there may be other roles such as `available_tools`.
    """
    context: Optional[ModelInput] = []
    """Current context
    """
    # Fields for internal use
    pdl__id: Optional[str] = ""
    """Unique identifier for this block
    """
    pdl__result: Optional[Any] = None
    """Result of the execution of the block"""
    pdl__location: Optional[PdlLocationType] = None
    pdl__timing: Optional[PdlTiming] = None

description: Optional[str] = None class-attribute instance-attribute

Documentation associated to the block.

spec: Any = None class-attribute instance-attribute

Type specification of the result of the block.

defs: dict[str, BlockType] = {} class-attribute instance-attribute

Set of definitions executed before the execution of the block.

def_: Optional[str] = Field(default=None, alias='def') class-attribute instance-attribute

Name of the variable used to store the result of the execution of the block.

contribute: Sequence[ContributeTarget | dict[str, ContributeValue]] = [ContributeTarget.RESULT, ContributeTarget.CONTEXT] class-attribute instance-attribute

Indicate if the block contributes to the result and background context.

parser: Annotated[Optional[ParserType], BeforeValidator(_ensure_lower)] = None class-attribute instance-attribute

Parser to use to construct a value out of a string result.

fallback: Optional[BlockType] = None class-attribute instance-attribute

Block to execute in case of error.

role: RoleType = None class-attribute instance-attribute

Role associated to the block and sub-blocks. Typical roles are system, user, and assistant, but there may be other roles such as available_tools.

context: Optional[ModelInput] = [] class-attribute instance-attribute

Current context

pdl__id: Optional[str] = '' class-attribute instance-attribute

Unique identifier for this block

pdl__result: Optional[Any] = None class-attribute instance-attribute

Result of the execution of the block

FunctionBlock

Bases: LeafBlock

Function declaration.

Attributes:

Name	Type	Description
function	Optional[dict[str, Any]]	Functions parameters with their types.
returns	BlockType	Body of the function

Source code in src/pdl/pdl_ast.py

class FunctionBlock(LeafBlock):
    """Function declaration."""

    kind: Literal[BlockKind.FUNCTION] = BlockKind.FUNCTION
    function: Optional[dict[str, Any]]
    """Functions parameters with their types.
    """
    returns: "BlockType" = Field(..., alias="return")
    """Body of the function
    """
    # Field for internal use
    pdl__scope: SkipJsonSchema[Optional[ScopeType]] = Field(default=None, repr=False)

function: Optional[dict[str, Any]] instance-attribute

Functions parameters with their types.

returns: BlockType = Field(..., alias='return') class-attribute instance-attribute

Body of the function

CallBlock

Bases: LeafBlock

Calling a function.

Attributes:

Name	Type	Description
call	ExpressionType	Function to call.
args	ExpressionType	Arguments of the function with their values.

Source code in src/pdl/pdl_ast.py

class CallBlock(LeafBlock):
    """Calling a function."""

    kind: Literal[BlockKind.CALL] = BlockKind.CALL
    call: ExpressionType
    """Function to call.
    """
    args: ExpressionType = {}
    """Arguments of the function with their values.
    """
    # Field for internal use
    pdl__trace: Optional["BlockType"] = None

call: ExpressionType instance-attribute

Function to call.

args: ExpressionType = {} class-attribute instance-attribute

Arguments of the function with their values.

LitellmParameters

Bases: BaseModel

Parameters passed to LiteLLM. More details at https://docs.litellm.ai/docs/completion/input.

Note that not all models and platforms accept all parameters.

Attributes:

Name	Type	Description
timeout	Optional[Union[float, str]] | str	Timeout in seconds for completion requests (Defaults to 600 seconds).
temperature	Optional[float] | str	The temperature parameter for controlling the randomness of the output (default is 1.0).
top_p	Optional[float] | str	The top-p parameter for nucleus sampling (default is 1.0).
n	Optional[int] | str	The number of completions to generate (default is 1).
stop	Optional[str | list[str]] | str	Up to 4 sequences where the LLM API will stop generating further tokens.
max_tokens	Optional[int] | str	The maximum number of tokens in the generated completion (default is infinity).
presence_penalty	Optional[float] | str	It is used to penalize new tokens based on their existence in the text so far.
frequency_penalty	Optional[float] | str	It is used to penalize new tokens based on their frequency in the text so far.
logit_bias	Optional[dict] | str	Used to modify the probability of specific tokens appearing in the completion.
user	Optional[str] | str	A unique identifier representing your end-user. This can help the LLM provider to monitor and detect abuse.
logprobs	Optional[bool] | str	Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message
top_logprobs	Optional[int] | str	top_logprobs (int, optional): An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.
extra_headers	Optional[dict] | str	Additional headers to include in the request.
functions	Optional[list] | str	A list of functions to apply to the conversation messages (default is an empty list)
function_call	Optional[str] | str	The name of the function to call within the conversation (default is an empty string)
base_url	Optional[str] | str	Base URL for the API (default is None).
api_version	Optional[str] | str	API version (default is None).
api_key	Optional[str] | str	API key (default is None).
model_list	Optional[list] | str	List of api base, version, keys.
mock_response	Optional[str] | str	If provided, return a mock completion response for testing or debugging purposes (default is None).
custom_llm_provider	Optional[str] | str	Used for Non-OpenAI LLMs, Example usage for bedrock, set model="amazon.titan-tg1-large" and custom_llm_provider="bedrock"
max_retries	Optional[int] | str	The number of retries to attempt (default is 0).

Source code in src/pdl/pdl_ast.py

class LitellmParameters(BaseModel):
    """Parameters passed to LiteLLM. More details at [https://docs.litellm.ai/docs/completion/input](https://docs.litellm.ai/docs/completion/input).

    Note that not all models and platforms accept all parameters.
    """

    model_config = ConfigDict(extra="allow", protected_namespaces=())
    timeout: Optional[Union[float, str]] | str = None
    """Timeout in seconds for completion requests (Defaults to 600 seconds).
    """
    temperature: Optional[float] | str = None
    """The temperature parameter for controlling the randomness of the output (default is 1.0).
    """
    top_p: Optional[float] | str = None
    """The top-p parameter for nucleus sampling (default is 1.0).
    """
    n: Optional[int] | str = None
    """The number of completions to generate (default is 1).
    """
    # stream: Optional[bool] = None
    # """If True, return a streaming response (default is False).
    # """
    # stream_options: Optional[dict] = None
    # """A dictionary containing options for the streaming response. Only set this when you set stream: true.
    # """
    stop: Optional[str | list[str]] | str = None
    """Up to 4 sequences where the LLM API will stop generating further tokens.
    """
    max_tokens: Optional[int] | str = None
    """The maximum number of tokens in the generated completion (default is infinity).
    """
    presence_penalty: Optional[float] | str = None
    """It is used to penalize new tokens based on their existence in the text so far.
    """
    frequency_penalty: Optional[float] | str = None
    """It is used to penalize new tokens based on their frequency in the text so far.
    """
    logit_bias: Optional[dict] | str = None
    """Used to modify the probability of specific tokens appearing in the completion.
    """
    user: Optional[str] | str = None
    """A unique identifier representing your end-user. This can help the LLM provider to monitor and detect abuse.
    """
    # openai v1.0+ new params
    response_format: Optional[dict] | str = None
    seed: Optional[int] | str = None
    tools: Optional[list] | str = None
    tool_choice: Optional[Union[str, dict]] | str = None
    logprobs: Optional[bool] | str = None
    """Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message
    """
    top_logprobs: Optional[int] | str = None
    """top_logprobs (int, optional): An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.
    """
    parallel_tool_calls: Optional[bool] | str = None
    # deployment_id = None
    extra_headers: Optional[dict] | str = None
    """Additional headers to include in the request.
    """
    # soon to be deprecated params by OpenAI
    functions: Optional[list] | str = None
    """A list of functions to apply to the conversation messages (default is an empty list)
    """
    function_call: Optional[str] | str = None
    """The name of the function to call within the conversation (default is an empty string)
    """
    # set api_base, api_version, api_key
    base_url: Optional[str] | str = None
    """Base URL for the API (default is None).
    """
    api_version: Optional[str] | str = None
    """API version (default is None).
    """
    api_key: Optional[str] | str = None
    """API key (default is None).
    """
    model_list: Optional[list] | str = None  # pass in a list of api_base,keys, etc.
    """List of api base, version, keys.
    """
    # Optional liteLLM function params
    mock_response: Optional[str] | str = None
    """If provided, return a mock completion response for testing or debugging purposes (default is None).
    """
    custom_llm_provider: Optional[str] | str = None
    """Used for Non-OpenAI LLMs, Example usage for bedrock, set model="amazon.titan-tg1-large" and custom_llm_provider="bedrock"
    """
    max_retries: Optional[int] | str = None
    """The number of retries to attempt (default is 0).
    """

timeout: Optional[Union[float, str]] | str = None class-attribute instance-attribute

Timeout in seconds for completion requests (Defaults to 600 seconds).

temperature: Optional[float] | str = None class-attribute instance-attribute

The temperature parameter for controlling the randomness of the output (default is 1.0).

top_p: Optional[float] | str = None class-attribute instance-attribute

The top-p parameter for nucleus sampling (default is 1.0).

n: Optional[int] | str = None class-attribute instance-attribute

The number of completions to generate (default is 1).

stop: Optional[str | list[str]] | str = None class-attribute instance-attribute

Up to 4 sequences where the LLM API will stop generating further tokens.

max_tokens: Optional[int] | str = None class-attribute instance-attribute

The maximum number of tokens in the generated completion (default is infinity).

presence_penalty: Optional[float] | str = None class-attribute instance-attribute

It is used to penalize new tokens based on their existence in the text so far.

frequency_penalty: Optional[float] | str = None class-attribute instance-attribute

It is used to penalize new tokens based on their frequency in the text so far.

logit_bias: Optional[dict] | str = None class-attribute instance-attribute

Used to modify the probability of specific tokens appearing in the completion.

user: Optional[str] | str = None class-attribute instance-attribute

A unique identifier representing your end-user. This can help the LLM provider to monitor and detect abuse.

logprobs: Optional[bool] | str = None class-attribute instance-attribute

Whether to return log probabilities of the output tokens or not. If true, returns the log probabilities of each output token returned in the content of message

top_logprobs: Optional[int] | str = None class-attribute instance-attribute

top_logprobs (int, optional): An integer between 0 and 5 specifying the number of most likely tokens to return at each token position, each with an associated log probability. logprobs must be set to true if this parameter is used.

extra_headers: Optional[dict] | str = None class-attribute instance-attribute

Additional headers to include in the request.

functions: Optional[list] | str = None class-attribute instance-attribute

A list of functions to apply to the conversation messages (default is an empty list)

function_call: Optional[str] | str = None class-attribute instance-attribute

The name of the function to call within the conversation (default is an empty string)

base_url: Optional[str] | str = None class-attribute instance-attribute

Base URL for the API (default is None).

api_version: Optional[str] | str = None class-attribute instance-attribute

API version (default is None).

api_key: Optional[str] | str = None class-attribute instance-attribute

API key (default is None).

model_list: Optional[list] | str = None class-attribute instance-attribute

List of api base, version, keys.

mock_response: Optional[str] | str = None class-attribute instance-attribute

If provided, return a mock completion response for testing or debugging purposes (default is None).

custom_llm_provider: Optional[str] | str = None class-attribute instance-attribute

Used for Non-OpenAI LLMs, Example usage for bedrock, set model="amazon.titan-tg1-large" and custom_llm_provider="bedrock"

max_retries: Optional[int] | str = None class-attribute instance-attribute

The number of retries to attempt (default is 0).

ModelBlock

Bases: LeafBlock

Common fields for the model blocks.

Attributes:

Name	Type	Description
model	ExpressionType	Model to use.
input	BlockType	Messages to send to the model.
modelResponse	Optional[str]	Variable where to store the raw response of the model.
pdl__usage	Optional[PdlUsage]	Tokens consumed during model call

Source code in src/pdl/pdl_ast.py

class ModelBlock(LeafBlock):
    """Common fields for the `model` blocks."""

    kind: Literal[BlockKind.MODEL] = BlockKind.MODEL
    model: ExpressionType
    """Model to use.
    """
    input: "BlockType" = "${ pdl_context }"
    """Messages to send to the model.
    """
    modelResponse: Optional[str] = None
    """Variable where to store the raw response of the model.
    """
    # Field for internal use
    pdl__usage: Optional[PdlUsage] = None
    """Tokens consumed during model call
    """
    pdl__model_input: Optional[ModelInput] = None

model: ExpressionType instance-attribute

Model to use.

input: BlockType = '${ pdl_context }' class-attribute instance-attribute

Messages to send to the model.

modelResponse: Optional[str] = None class-attribute instance-attribute

Variable where to store the raw response of the model.

pdl__usage: Optional[PdlUsage] = None class-attribute instance-attribute

Tokens consumed during model call

LitellmModelBlock

Bases: ModelBlock

Call an LLM through the LiteLLM API.

Example:

- model: ollama/granite-code:8b
  parameters:
    stop: ['!']

Attributes:

Name	Type	Description
platform	Literal[LITELLM]	Optional field to ensure that the block is using LiteLLM.
model	ExpressionType[str]	Name of the model following the LiteLLM convention.
parameters	Optional[LitellmParameters | ExpressionType[dict]]	Parameters to send to the model.

Source code in src/pdl/pdl_ast.py

class LitellmModelBlock(ModelBlock):
    """
    Call an LLM through [the LiteLLM API](https://docs.litellm.ai/).

    Example:
    ```PDL
    - model: ollama/granite-code:8b
      parameters:
        stop: ['!']
    ```
    """

    platform: Literal[ModelPlatform.LITELLM] = ModelPlatform.LITELLM
    """Optional field to ensure that the block is using LiteLLM.
    """
    model: ExpressionType[str]
    """Name of the model following the LiteLLM convention.
    """
    parameters: Optional[LitellmParameters | ExpressionType[dict]] = None
    """Parameters to send to the model.
    """

platform: Literal[ModelPlatform.LITELLM] = ModelPlatform.LITELLM class-attribute instance-attribute

Optional field to ensure that the block is using LiteLLM.

model: ExpressionType[str] instance-attribute

Name of the model following the LiteLLM convention.

parameters: Optional[LitellmParameters | ExpressionType[dict]] = None class-attribute instance-attribute

Parameters to send to the model.

GraniteioModelBlock

Bases: ModelBlock

Call an LLM through the granite-io API.

Attributes:

Name	Type	Description
platform	Literal[GRANITEIO]	Optional field to ensure that the block is using granite-io.
model	ExpressionType[object]	Model name used by the backend.
backend	ExpressionType[str | dict[str, Any]]	Backend name and configuration.
processor	Optional[ExpressionType[str]]	IO Processor name.
parameters	Optional[ExpressionType[dict[str, Any]]]	Parameters sent to the model.

Source code in src/pdl/pdl_ast.py

class GraniteioModelBlock(ModelBlock):
    """Call an LLM through the granite-io API."""

    platform: Literal[ModelPlatform.GRANITEIO] = ModelPlatform.GRANITEIO
    """Optional field to ensure that the block is using granite-io.
    """
    model: ExpressionType[object]
    """Model name used by the backend.
    """
    backend: ExpressionType[str | dict[str, Any]]
    """Backend name and configuration.
    """
    processor: Optional[ExpressionType[str]] = None
    """IO Processor name.
    """
    parameters: Optional[ExpressionType[dict[str, Any]]] = None
    """Parameters sent to the model.
    """

platform: Literal[ModelPlatform.GRANITEIO] = ModelPlatform.GRANITEIO class-attribute instance-attribute

Optional field to ensure that the block is using granite-io.

model: ExpressionType[object] instance-attribute

Model name used by the backend.

backend: ExpressionType[str | dict[str, Any]] instance-attribute

Backend name and configuration.

processor: Optional[ExpressionType[str]] = None class-attribute instance-attribute

IO Processor name.

parameters: Optional[ExpressionType[dict[str, Any]]] = None class-attribute instance-attribute

Parameters sent to the model.

CodeBlock

Bases: BaseCodeBlock

Execute a piece of code.

Example:

lang: python
code: |
    import random
    # (In PDL, set `result` to the output you wish for your code block.)
    result = random.randint(1, 20)

Attributes:

Name	Type	Description
lang	Annotated[Literal['python', 'command', 'jinja', 'pdl'], BeforeValidator(_ensure_lower)]	Programming language of the code.
code	BlockType	Code to execute.

Source code in src/pdl/pdl_ast.py

class CodeBlock(BaseCodeBlock):
    """
    Execute a piece of code.

    Example:
    ```PDL
    lang: python
    code: |
        import random
        # (In PDL, set `result` to the output you wish for your code block.)
        result = random.randint(1, 20)
    ```
    """

    lang: Annotated[
        Literal["python", "command", "jinja", "pdl"], BeforeValidator(_ensure_lower)
    ]
    """Programming language of the code.
    """
    code: "BlockType"
    """Code to execute.
    """

lang: Annotated[Literal['python', 'command', 'jinja', 'pdl'], BeforeValidator(_ensure_lower)] instance-attribute

Programming language of the code.

code: BlockType instance-attribute

Code to execute.

ArgsBlock

Bases: BaseCodeBlock

Execute a command line, which will spawn a subprocess with the given argument vector. Note: if you need a shell script execution, you must wrap your command line in /bin/sh or somne shell of your choosing.

Example:

args:
- /bin/sh
- "-c"
- "if [[ $x = 1 ]]; then echo y; else echo n; fi"

Attributes:

Name	Type	Description
args	list[ExpressionType[str]]	The argument vector to spawn.

Source code in src/pdl/pdl_ast.py

class ArgsBlock(BaseCodeBlock):
    """
    Execute a command line, which will spawn a subprocess with the given argument vector. Note: if you need a shell script execution, you must wrap your command line in /bin/sh or somne shell of your choosing.

    Example:
    ```PDL
    args:
    - /bin/sh
    - "-c"
    - "if [[ $x = 1 ]]; then echo y; else echo n; fi"
    ```
    """

    lang: Annotated[Literal["command"], BeforeValidator(_ensure_lower)] = "command"
    args: list[ExpressionType[str]]
    """The argument vector to spawn.
    """

args: list[ExpressionType[str]] instance-attribute

The argument vector to spawn.

GetBlock

Bases: LeafBlock

Get the value of a variable.

The GetBlock is deprecated. Use DataBlock instead.

Attributes:

Name	Type	Description
get	str	Name of the variable to access.

Source code in src/pdl/pdl_ast.py

class GetBlock(LeafBlock):
    """
    Get the value of a variable.

    The GetBlock is deprecated.  Use DataBlock instead.
    """

    kind: Literal[BlockKind.GET] = BlockKind.GET
    get: str
    """Name of the variable to access."""

get: str instance-attribute

Name of the variable to access.

DataBlock

Bases: LeafBlock

Arbitrary value, equivalent to JSON.

Example. As part of a defs section, set numbers to the list [1, 2, 3, 4]:

defs:
  numbers:
    data: [1, 2, 3, 4]

Example. Evaluate ${ TEST.answer } in Jinja, passing the result to a regex parser with capture groups. Set EXTRACTED_GROUND_TRUTH to an object with attribute answer, a string, containing the value of the capture group.

- data: ${ TEST.answer }
  parser:
    regex: "(.|\n)*#### (?P<answer>([0-9])*)\n*"
    spec:
      answer: str
  def: EXTRACTED_GROUND_TRUTH

Attributes:

Name	Type	Description
data	ExpressionType[Any]	Value defined.
raw	bool	Do not evaluate expressions inside strings.

Source code in src/pdl/pdl_ast.py

class DataBlock(LeafBlock):
    """
    Arbitrary value, equivalent to JSON.

    Example. As part of a `defs` section, set `numbers` to the list `[1, 2, 3, 4]`:
    ```PDL
    defs:
      numbers:
        data: [1, 2, 3, 4]
    ```

    Example.  Evaluate `${ TEST.answer }` in
    [Jinja](https://jinja.palletsprojects.com/en/stable/), passing
    the result to a regex parser with capture groups.  Set
    `EXTRACTED_GROUND_TRUTH` to an object with attribute `answer`,
    a string, containing the value of the capture group.
    ```PDL
    - data: ${ TEST.answer }
      parser:
        regex: "(.|\\n)*#### (?P<answer>([0-9])*)\\n*"
        spec:
          answer: str
      def: EXTRACTED_GROUND_TRUTH
    ```
    """

    kind: Literal[BlockKind.DATA] = BlockKind.DATA
    data: ExpressionType[Any]
    """Value defined."""
    raw: bool = False
    """Do not evaluate expressions inside strings."""

data: ExpressionType[Any] instance-attribute

Value defined.

raw: bool = False class-attribute instance-attribute

Do not evaluate expressions inside strings.

TextBlock

Bases: StructuredBlock

Create the concatenation of the stringify version of the result of each block of the list of blocks.

Attributes:

Name	Type	Description
text	BlockOrBlocksType	Body of the text.

Source code in src/pdl/pdl_ast.py

class TextBlock(StructuredBlock):
    """Create the concatenation of the stringify version of the result of each block of the list of blocks."""

    kind: Literal[BlockKind.TEXT] = BlockKind.TEXT
    text: "BlockOrBlocksType"
    """Body of the text.
    """

text: BlockOrBlocksType instance-attribute

Body of the text.

LastOfBlock

Bases: StructuredBlock

Return the value of the last block if the list of blocks.

Attributes:

Name	Type	Description
lastOf	list[BlockType]	Sequence of blocks to execute.

Source code in src/pdl/pdl_ast.py

class LastOfBlock(StructuredBlock):
    """Return the value of the last block if the list of blocks."""

    kind: Literal[BlockKind.LASTOF] = BlockKind.LASTOF
    lastOf: list["BlockType"]
    """Sequence of blocks to execute."""

lastOf: list[BlockType] instance-attribute

Sequence of blocks to execute.

ArrayBlock

Bases: StructuredBlock

Return the array of values computed by each block of the list of blocks.

Attributes:

Name	Type	Description
array	list[BlockType]	Elements of the array.

Source code in src/pdl/pdl_ast.py

class ArrayBlock(StructuredBlock):
    """Return the array of values computed by each block of the list of blocks."""

    kind: Literal[BlockKind.ARRAY] = BlockKind.ARRAY
    array: list["BlockType"]
    """Elements of the array."""

array: list[BlockType] instance-attribute

Elements of the array.

ObjectBlock

Bases: StructuredBlock

Return the object where the value of each field is defined by a block. If the body of the object is an array, the resulting object is the union of the objects computed by each element of the array.

Source code in src/pdl/pdl_ast.py

class ObjectBlock(StructuredBlock):
    """Return the object where the value of each field is defined by a block. If the body of the object is an array, the resulting object is the union of the objects computed by each element of the array."""

    kind: Literal[BlockKind.OBJECT] = BlockKind.OBJECT
    object: dict[str, "BlockType"] | list["BlockType"]

MessageBlock

Bases: StructuredBlock

Create a message.

Attributes:

Name	Type	Description
role	RoleType	Role of associated to the message.
content	BlockType	Content of the message.

Source code in src/pdl/pdl_ast.py

class MessageBlock(StructuredBlock):
    """Create a message."""

    kind: Literal[BlockKind.MESSAGE] = BlockKind.MESSAGE
    role: RoleType  # pyright: ignore
    """Role of associated to the message.
    Typical roles are `system`, `user`, and `assistant`,
    but there may be other roles such as `available_tools`.
    """  # pyright: ignore
    content: "BlockType"
    """Content of the message."""

role: RoleType instance-attribute

Role of associated to the message. Typical roles are system, user, and assistant, but there may be other roles such as available_tools.

content: BlockType instance-attribute

Content of the message.

IfBlock

Bases: StructuredBlock

Conditional control structure.

Example:

defs:
  answer:
    read:
    message: "Enter a number? "
if: ${ (answer | int) == 42 }
then: You won!

Attributes:

Name	Type	Description
condition	ExpressionType[bool]	Condition.
then	BlockType	Branch to execute if the condition is true.
else_	Optional[BlockType]	Branch to execute if the condition is false.

Source code in src/pdl/pdl_ast.py

class IfBlock(StructuredBlock):
    """
    Conditional control structure.

    Example:
    ```PDL
    defs:
      answer:
        read:
        message: "Enter a number? "
    if: ${ (answer | int) == 42 }
    then: You won!
    ```
    """

    kind: Literal[BlockKind.IF] = BlockKind.IF
    condition: ExpressionType[bool] = Field(alias="if")
    """Condition.
    """
    then: "BlockType"
    """Branch to execute if the condition is true.
    """
    else_: Optional["BlockType"] = Field(default=None, alias="else")
    """Branch to execute if the condition is false.
    """
    # Field for internal use
    if_result: Optional[bool] = None

condition: ExpressionType[bool] = Field(alias='if') class-attribute instance-attribute

Condition.

then: BlockType instance-attribute

Branch to execute if the condition is true.

else_: Optional[BlockType] = Field(default=None, alias='else') class-attribute instance-attribute

Branch to execute if the condition is false.

MatchCase

Bases: BaseModel

Case of a match.

Attributes:

Name	Type	Description
case	Optional[PatternType]	Value to match.
if_	Optional[ExpressionType[bool]]	Boolean condition to satisfy.
then	BlockType	Branch to execute if the value is matched and the condition is satisfied.

Source code in src/pdl/pdl_ast.py

class MatchCase(BaseModel):
    """Case of a match."""

    model_config = ConfigDict(extra="forbid")
    case: Optional[PatternType] = None
    """Value to match.
    """
    if_: Optional[ExpressionType[bool]] = Field(default=None, alias="if")
    """Boolean condition to satisfy.
    """
    then: "BlockType"
    """Branch to execute if the value is matched and the condition is satisfied.
    """
    # Field for internal use
    pdl__case_result: Optional[bool] = None
    pdl__if_result: Optional[bool] = None
    pdl__matched: Optional[bool] = None

case: Optional[PatternType] = None class-attribute instance-attribute

Value to match.

if_: Optional[ExpressionType[bool]] = Field(default=None, alias='if') class-attribute instance-attribute

Boolean condition to satisfy.

then: BlockType instance-attribute

Branch to execute if the value is matched and the condition is satisfied.

MatchBlock

Bases: StructuredBlock

Match control structure.

Example: ```PDL defs: answer: read: message: "Enter a number? " match: ${ (answer | int) } with: - case: 42 then: You won! - case: any: def: x if: ${ x > 42 } then: Too high - then: Too low

Attributes:

Name	Type	Description
match_	ExpressionType[Any]	Matched expression.
with_	list[MatchCase]	List of cases to match.

Source code in src/pdl/pdl_ast.py

class MatchBlock(StructuredBlock):
    """Match control structure.

    Example:
    ```PDL
    defs:
      answer:
        read:
        message: "Enter a number? "
    match: ${ (answer | int) }
    with:
    - case: 42
      then: You won!
    - case:
        any:
        def: x
      if: ${ x > 42 }
      then: Too high
    - then: Too low
    """

    kind: Literal[BlockKind.MATCH] = BlockKind.MATCH
    match_: ExpressionType[Any] = Field(alias="match")
    """Matched expression.
    """
    with_: list[MatchCase] = Field(alias="with")
    """List of cases to match.
    """

match_: ExpressionType[Any] = Field(alias='match') class-attribute instance-attribute

Matched expression.

with_: list[MatchCase] = Field(alias='with') class-attribute instance-attribute

List of cases to match.

JoinConfig

Bases: BaseModel

Configure how loop iterations should be combined.

Source code in src/pdl/pdl_ast.py

class JoinConfig(BaseModel):
    """Configure how loop iterations should be combined."""

    model_config = ConfigDict(extra="forbid", use_attribute_docstrings=True)

JoinText

Bases: JoinConfig

Attributes:

Name	Type	Description
as_	Literal[TEXT]	String concatenation of the result of each iteration.
with_	str	String used to concatenate each iteration of the loop.

Source code in src/pdl/pdl_ast.py

class JoinText(JoinConfig):
    as_: Literal[IterationType.TEXT] = Field(alias="as", default=IterationType.TEXT)
    """String concatenation of the result of each iteration.
    """

    with_: str = Field(alias="with", default="")
    """String used to concatenate each iteration of the loop.
    """

as_: Literal[IterationType.TEXT] = Field(alias='as', default=IterationType.TEXT) class-attribute instance-attribute

String concatenation of the result of each iteration.

with_: str = Field(alias='with', default='') class-attribute instance-attribute

String used to concatenate each iteration of the loop.

JoinArray

Bases: JoinConfig

Attributes:

Name	Type	Description
as_	Literal[ARRAY]	Return the result of each iteration as an array.

Source code in src/pdl/pdl_ast.py

class JoinArray(JoinConfig):
    as_: Literal[IterationType.ARRAY] = Field(alias="as")
    """Return the result of each iteration as an array.
    """

as_: Literal[IterationType.ARRAY] = Field(alias='as') class-attribute instance-attribute

Return the result of each iteration as an array.

JoinObject

Bases: JoinConfig

Attributes:

Name	Type	Description
as_	Literal[OBJECT]	Return the union of the objects created at each iteration.

Source code in src/pdl/pdl_ast.py

class JoinObject(JoinConfig):
    as_: Literal[IterationType.OBJECT] = Field(alias="as")
    """Return the union of the objects created at each iteration.
    """

as_: Literal[IterationType.OBJECT] = Field(alias='as') class-attribute instance-attribute

Return the union of the objects created at each iteration.

JoinLastOf

Bases: JoinConfig

Attributes:

Name	Type	Description
as_	Literal[LASTOF]	Return the result of the last iteration.

Source code in src/pdl/pdl_ast.py

class JoinLastOf(JoinConfig):
    as_: Literal[IterationType.LASTOF] = Field(alias="as")
    """Return the result of the last iteration.
    """

as_: Literal[IterationType.LASTOF] = Field(alias='as') class-attribute instance-attribute

Return the result of the last iteration.

RepeatBlock

Bases: StructuredBlock

Repeat the execution of a block.

For loop example:

for:
    number: [1, 2, 3, 4]
    name: ["Bob", "Carol", "David", "Ernest"]
repeat:
    "${ name }'s number is ${ number }\n"

Attributes:

Name	Type	Description
for_	Optional[dict[str, ExpressionType[list]]]	Arrays to iterate over.
while_	ExpressionType[bool]	Condition to stay at the beginning of the loop.
repeat	BlockType	Body of the loop.
until	ExpressionType[bool]	Condition to exit at the end of the loop.
max_iterations	Optional[ExpressionType[int]]	Maximal number of iterations to perform.
join	JoinType	Define how to combine the result of each iteration.

Source code in src/pdl/pdl_ast.py

class RepeatBlock(StructuredBlock):
    """
    Repeat the execution of a block.

    For loop example:
    ```PDL
    for:
        number: [1, 2, 3, 4]
        name: ["Bob", "Carol", "David", "Ernest"]
    repeat:
        "${ name }'s number is ${ number }\\n"
    ```
    """

    kind: Literal[BlockKind.REPEAT] = BlockKind.REPEAT
    for_: Optional[dict[str, ExpressionType[list]]] = Field(default=None, alias="for")
    """Arrays to iterate over.
    """
    while_: ExpressionType[bool] = Field(default=True, alias="while")
    """Condition to stay at the beginning of the loop.
    """
    repeat: "BlockType"
    """Body of the loop.
    """
    until: ExpressionType[bool] = False
    """Condition to exit at the end of the loop.
    """
    max_iterations: Optional[ExpressionType[int]] = None
    """Maximal number of iterations to perform.
    """
    join: JoinType = JoinText()
    """Define how to combine the result of each iteration.
    """
    # Field for internal use
    pdl__trace: Optional[list["BlockType"]] = None

for_: Optional[dict[str, ExpressionType[list]]] = Field(default=None, alias='for') class-attribute instance-attribute

Arrays to iterate over.

while_: ExpressionType[bool] = Field(default=True, alias='while') class-attribute instance-attribute

Condition to stay at the beginning of the loop.

repeat: BlockType instance-attribute

Body of the loop.

until: ExpressionType[bool] = False class-attribute instance-attribute

Condition to exit at the end of the loop.

max_iterations: Optional[ExpressionType[int]] = None class-attribute instance-attribute

Maximal number of iterations to perform.

join: JoinType = JoinText() class-attribute instance-attribute

Define how to combine the result of each iteration.

ReadBlock

Bases: LeafBlock

Read from a file or standard input.

Example. Read from the standard input with a prompt starting with >.

read:
message: "> "

Example. Read the file ./data.yaml in the same directory of the PDL file containing the block and parse it into YAML.

read: ./data.yaml
parser: yaml

Attributes:

Name	Type	Description
read	ExpressionType[str] | None	Name of the file to read. If None, read the standard input.
message	Optional[str]	Message to prompt the user to enter a value.
multiline	bool	Indicate if one or multiple lines should be read.

Source code in src/pdl/pdl_ast.py

class ReadBlock(LeafBlock):
    """Read from a file or standard input.

    Example. Read from the standard input with a prompt starting with `> `.
    ```PDL
    read:
    message: "> "
    ```

    Example. Read the file `./data.yaml` in the same directory of the PDL file containing the block and parse it into YAML.
    ```PDL
    read: ./data.yaml
    parser: yaml
    ```
    """

    kind: Literal[BlockKind.READ] = BlockKind.READ
    read: ExpressionType[str] | None
    """Name of the file to read. If `None`, read the standard input.
    """
    message: Optional[str] = None
    """Message to prompt the user to enter a value.
    """
    multiline: bool = False
    """Indicate if one or multiple lines should be read.
    """

read: ExpressionType[str] | None instance-attribute

Name of the file to read. If None, read the standard input.

message: Optional[str] = None class-attribute instance-attribute

Message to prompt the user to enter a value.

multiline: bool = False class-attribute instance-attribute

Indicate if one or multiple lines should be read.

IncludeBlock

Bases: StructuredBlock

Include a PDL file.

Attributes:

Name	Type	Description
include	str	Name of the file to include.

Source code in src/pdl/pdl_ast.py

class IncludeBlock(StructuredBlock):
    """Include a PDL file."""

    kind: Literal[BlockKind.INCLUDE] = BlockKind.INCLUDE
    include: str
    """Name of the file to include.
    """
    # Field for internal use
    pdl__trace: Optional["BlockType"] = None

include: str instance-attribute

Name of the file to include.

ImportBlock

Bases: LeafBlock

Import a PDL file.

Attributes:

Name	Type	Description
import_	str	Name of the file to import.

Source code in src/pdl/pdl_ast.py

class ImportBlock(LeafBlock):
    """Import a PDL file."""

    kind: Literal[BlockKind.IMPORT] = BlockKind.IMPORT
    import_: str = Field(alias="import")
    """Name of the file to import.
    """
    # Field for internal use
    pdl__trace: Optional["BlockType"] = None

import_: str = Field(alias='import') class-attribute instance-attribute

Name of the file to import.

ErrorBlock

Bases: LeafBlock

Block representing an error generated at runtime.

Attributes:

Name	Type	Description
msg	str	Error message.
program	BlockType	Block that raised the error.

Source code in src/pdl/pdl_ast.py

class ErrorBlock(LeafBlock):
    """Block representing an error generated at runtime."""

    kind: Literal[BlockKind.ERROR] = BlockKind.ERROR
    msg: str
    """Error message.
    """
    program: "BlockType"
    """Block that raised the error.
    """

msg: str instance-attribute

Error message.

program: BlockType instance-attribute

Block that raised the error.

EmptyBlock

Bases: LeafBlock

Block without an action. It can contain definitions.

Source code in src/pdl/pdl_ast.py

class EmptyBlock(LeafBlock):
    """Block without an action. It can contain definitions."""

    kind: Literal[BlockKind.EMPTY] = BlockKind.EMPTY

Program

Bases: RootModel

Prompt Declaration Language program (PDL)

Attributes:

Name	Type	Description
root	BlockType	Entry point to parse a PDL program using Pydantic.

Source code in src/pdl/pdl_ast.py

class Program(RootModel):
    """
    Prompt Declaration Language program (PDL)
    """

    root: BlockType
    """Entry point to parse a PDL program using Pydantic.
    """

root: BlockType instance-attribute

Entry point to parse a PDL program using Pydantic.

get_default_model_parameters() -> list[dict[str, Any]]

Model-specific defaults to apply

Source code in src/pdl/pdl_ast.py

def get_default_model_parameters() -> list[dict[str, Any]]:
    """Model-specific defaults to apply"""
    return [
        {
            "*watsonx/*": {
                "temperature": 0,
            },
        },
        {
            "*watsonx_text*": {
                "decoding_method": DECODING_METHOD,
                "max_tokens": MAX_NEW_TOKENS,
                "min_new_tokens": MIN_NEW_TOKENS,
                "repetition_penalty": REPETITION_PENALTY,
            },
        },
        # Note that Replicate may no longer support granite 3.0
        {
            "*granite-3.0*": {
                "temperature": 0,
                "roles": {
                    "system": {
                        "pre_message": "<|start_of_role|>system<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "user": {
                        "pre_message": "<|start_of_role|>user<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "assistant": {
                        "pre_message": "<|start_of_role|>assistant<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "available_tools": {
                        "pre_message": "<|start_of_role|>available_tools<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "tool_response": {
                        "pre_message": "<|start_of_role|>tool_response<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                },
                "final_prompt_value": "<|start_of_role|>assistant<|end_of_role|>",
            }
        },
        # Note that we match both granite-3.0 and 3.1 rather than using a granite-3.* wildcard
        {
            "*granite-3.1*": {
                "temperature": 0,
                "roles": {
                    "system": {
                        "pre_message": "<|start_of_role|>system<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "user": {
                        "pre_message": "<|start_of_role|>user<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "assistant": {
                        "pre_message": "<|start_of_role|>assistant<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "tools": {
                        "pre_message": "<|start_of_role|>tools<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "tool_response": {
                        "pre_message": "<|start_of_role|>tool_response<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "documents": {
                        "pre_message": "<|start_of_role|>documents<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                },
                "final_prompt_value": "<|start_of_role|>assistant<|end_of_role|>",
            }
        },
        {
            "*granite-3.2*": {
                "temperature": 0,
                "roles": {
                    "system": {
                        "pre_message": "<|start_of_role|>system<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "user": {
                        "pre_message": "<|start_of_role|>user<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "assistant": {
                        "pre_message": "<|start_of_role|>assistant<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "tools": {
                        "pre_message": "<|start_of_role|>tools<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "tool_response": {
                        "pre_message": "<|start_of_role|>tool_response<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                    "documents": {
                        "pre_message": "<|start_of_role|>documents<|end_of_role|>",
                        "post_message": "<|end_of_text|>",
                    },
                },
                "final_prompt_value": "<|start_of_role|>assistant<|end_of_role|>",
            }
        },
        # models on Ollama (e.g. granite-code, granite3-dense, granite3.1-dense)
        {
            "ollama/*": {
                "temperature": 0,
            },
        },
        {
            "ollama_chat/*": {
                "temperature": 0,
            },
        },
    ]

get_sampling_defaults() -> list[dict[str, Any]]

Model-specific defaults to apply if we are sampling.

Source code in src/pdl/pdl_ast.py

def get_sampling_defaults() -> list[dict[str, Any]]:
    """Model-specific defaults to apply if we are sampling."""
    return [
        {
            "*": {
                "temperature": TEMPERATURE_SAMPLING,
                "top_k": TOP_K_SAMPLING,
                "top_p": TOP_P_SAMPLING,
            }
        }
    ]

Interpreter

Classes:

Name	Description
InterpreterConfig	Configuration parameters of the PDL interpreter.

Functions:

Name	Description
exec_program	Execute a PDL program given as a value of type pdl.pdl_ast.Program.
exec_dict	Execute a PDL program given as a dictionary.
exec_str	Execute a PDL program given as YAML string.
exec_file	Execute a PDL program given as YAML file.

InterpreterConfig

Bases: TypedDict

Configuration parameters of the PDL interpreter.

Attributes:

Name	Type	Description
yield_result	bool	Print incrementally result of the execution.
yield_background	bool	Print the program background messages during the execution.
batch	int	Model inference mode:
role	RoleType	Default role.
cwd	Path	Path considered as the current working directory for file reading.

Source code in src/pdl/pdl.py

class InterpreterConfig(TypedDict, total=False):
    """Configuration parameters of the PDL interpreter."""

    yield_result: bool
    """Print incrementally result of the execution.
    """
    yield_background: bool
    """Print the program background messages during the execution.
    """
    batch: int
    """Model inference mode:
         - 0: streaming
         - 1: non-streaming
    """
    role: RoleType
    """Default role.
    """
    cwd: Path
    """Path considered as the current working directory for file reading."""

yield_result: bool instance-attribute

Print incrementally result of the execution.

yield_background: bool instance-attribute

Print the program background messages during the execution.

batch: int instance-attribute

Model inference mode: - 0: streaming - 1: non-streaming

role: RoleType instance-attribute

Default role.

cwd: Path instance-attribute

Path considered as the current working directory for file reading.

exec_program(prog: Program, config: Optional[InterpreterConfig] = None, scope: Optional[ScopeType | dict[str, Any]] = None, loc: Optional[PdlLocationType] = None, output: Literal['result', 'all'] = 'result') -> Any

Execute a PDL program given as a value of type pdl.pdl_ast.Program.

Parameters:

Name	Type	Description	Default
prog	Program	Program to execute.	required
config	Optional[InterpreterConfig]	Interpreter configuration. Defaults to None.	None
scope	Optional[ScopeType | dict[str, Any]]	Environment defining the initial variables in scope to execute the program. Defaults to None.	None
loc	Optional[PdlLocationType]	Source code location mapping. Defaults to None.	None
output	Literal['result', 'all']	Configure the output of the returned value of this function. Defaults to "result"	'result'

Returns:

Type	Description
Any	Return the final result if output is set to "result". If set of all, it returns a dictionary containing, result, scope, and trace.

Source code in src/pdl/pdl.py

def exec_program(
    prog: Program,
    config: Optional[InterpreterConfig] = None,
    scope: Optional[ScopeType | dict[str, Any]] = None,
    loc: Optional[PdlLocationType] = None,
    output: Literal["result", "all"] = "result",
) -> Any:
    """Execute a PDL program given as a value of type `pdl.pdl_ast.Program`.

    Args:
        prog: Program to execute.
        config: Interpreter configuration. Defaults to None.
        scope: Environment defining the initial variables in scope to execute the program. Defaults to None.
        loc: Source code location mapping. Defaults to None.
        output: Configure the output of the returned value of this function. Defaults to `"result"`

    Returns:
        Return the final result if `output` is set to `"result"`. If set of `all`, it returns a dictionary containing, `result`, `scope`, and `trace`.
    """
    config = config or {}
    state = InterpreterState(**config)
    if not isinstance(scope, PdlDict):
        scope = PdlDict(scope or {})
    loc = loc or empty_block_location
    future_result, _, future_scope, trace = process_prog(state, scope, prog, loc)
    result = future_result.result()
    match output:
        case "result":
            return result
        case "all":
            scope = future_scope.result()
            return {"result": result, "scope": scope, "trace": trace}
        case _:
            assert False, 'The `output` variable should be "result" or "all"'

exec_dict(prog: dict[str, Any], config: Optional[InterpreterConfig] = None, scope: Optional[ScopeType | dict[str, Any]] = None, loc: Optional[PdlLocationType] = None, output: Literal['result', 'all'] = 'result') -> Any

Execute a PDL program given as a dictionary.

Parameters:

Name	Type	Description	Default
prog	dict[str, Any]	Program to execute.	required
config	Optional[InterpreterConfig]	Interpreter configuration. Defaults to None.	None
scope	Optional[ScopeType | dict[str, Any]]	Environment defining the initial variables in scope to execute the program. Defaults to None.	None
loc	Optional[PdlLocationType]	Source code location mapping. Defaults to None.	None
output	Literal['result', 'all']	Configure the output of the returned value of this function. Defaults to "result"	'result'

Returns:

Type	Description
Any	Return the final result.

Source code in src/pdl/pdl.py

def exec_dict(
    prog: dict[str, Any],
    config: Optional[InterpreterConfig] = None,
    scope: Optional[ScopeType | dict[str, Any]] = None,
    loc: Optional[PdlLocationType] = None,
    output: Literal["result", "all"] = "result",
) -> Any:
    """Execute a PDL program given as a dictionary.

    Args:
        prog: Program to execute.
        config: Interpreter configuration. Defaults to None.
        scope: Environment defining the initial variables in scope to execute the program. Defaults to None.
        loc: Source code location mapping. Defaults to None.
        output: Configure the output of the returned value of this function. Defaults to `"result"`

    Returns:
        Return the final result.
    """
    program = Program.model_validate(prog)
    result = exec_program(program, config, scope, loc, output)
    return result

exec_str(prog: str, config: Optional[InterpreterConfig] = None, scope: Optional[ScopeType | dict[str, Any]] = None, output: Literal['result', 'all'] = 'result') -> Any

Execute a PDL program given as YAML string.

Parameters:

Name	Type	Description	Default
prog	str	Program to execute.	required
config	Optional[InterpreterConfig]	Interpreter configuration. Defaults to None.	None
scope	Optional[ScopeType | dict[str, Any]]	Environment defining the initial variables in scope to execute the program. Defaults to None.	None
output	Literal['result', 'all']	Configure the output of the returned value of this function. Defaults to "result"	'result'

Returns:

Type	Description
Any	Return the final result.

Source code in src/pdl/pdl.py

def exec_str(
    prog: str,
    config: Optional[InterpreterConfig] = None,
    scope: Optional[ScopeType | dict[str, Any]] = None,
    output: Literal["result", "all"] = "result",
) -> Any:
    """Execute a PDL program given as YAML string.

    Args:
        prog: Program to execute.
        config: Interpreter configuration. Defaults to None.
        scope: Environment defining the initial variables in scope to execute the program. Defaults to None.
        output: Configure the output of the returned value of this function. Defaults to `"result"`

    Returns:
        Return the final result.
    """
    program, loc = parse_str(prog)
    result = exec_program(program, config, scope, loc, output)
    return result

exec_file(prog: str | Path, config: Optional[InterpreterConfig] = None, scope: Optional[ScopeType | dict[str, Any]] = None, output: Literal['result', 'all'] = 'result') -> Any

Execute a PDL program given as YAML file.

Parameters:

Name	Type	Description	Default
prog	str | Path	Program to execute.	required
config	Optional[InterpreterConfig]	Interpreter configuration. Defaults to None.	None
scope	Optional[ScopeType | dict[str, Any]]	Environment defining the initial variables in scope to execute the program. Defaults to None.	None
output	Literal['result', 'all']	Configure the output of the returned value of this function. Defaults to "result"	'result'

Returns:

Type	Description
Any	Return the final result.

Source code in src/pdl/pdl.py

def exec_file(
    prog: str | Path,
    config: Optional[InterpreterConfig] = None,
    scope: Optional[ScopeType | dict[str, Any]] = None,
    output: Literal["result", "all"] = "result",
) -> Any:
    """Execute a PDL program given as YAML file.

    Args:
        prog: Program to execute.
        config: Interpreter configuration. Defaults to None.
        scope: Environment defining the initial variables in scope to execute the program. Defaults to None.
        output: Configure the output of the returned value of this function. Defaults to `"result"`

    Returns:
        Return the final result.
    """
    program, loc = parse_file(prog)
    if config is None:
        config = InterpreterConfig()
    if config.get("cwd") is None:
        config["cwd"] = Path(prog).parent
    result = exec_program(program, config, scope, loc, output)
    return result