From 1799b6e422a81259c7fcbcdb05f9cee9d80dc2fc Mon Sep 17 00:00:00 2001 From: Ed Snible Date: Thu, 6 Mar 2025 09:17:29 -0500 Subject: [PATCH] Docstrings and examples for PDL concepts (#693) * Docstrings and examples for PDL concepts --- pdl-live-react/src/pdl_ast.d.ts | 140 +++++++++++++++++++++++++------- src/pdl/pdl-schema.json | 67 +++++++-------- src/pdl/pdl_ast.py | 108 ++++++++++++++++++++---- 3 files changed, 240 insertions(+), 75 deletions(-) diff --git a/pdl-live-react/src/pdl_ast.d.ts b/pdl-live-react/src/pdl_ast.d.ts index df6857ce..03eae542 100644 --- a/pdl-live-react/src/pdl_ast.d.ts +++ b/pdl-live-react/src/pdl_ast.d.ts @@ -225,7 +225,8 @@ export type Fallback = | null /** * 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`. */ export type Role = string | null /** @@ -303,7 +304,8 @@ export type Fallback1 = | null /** * 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`. */ export type Role1 = string | null /** @@ -409,7 +411,8 @@ export type Fallback2 = | null /** * 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`. */ export type Role2 = string | null /** @@ -511,7 +514,8 @@ export type Fallback3 = | null /** * 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`. */ export type Role3 = string | null /** @@ -613,7 +617,8 @@ export type Fallback4 = | null /** * 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`. */ export type Role4 = string | null /** @@ -642,7 +647,7 @@ export type Read = string | LocalizedExpression | null */ export type Message = string | null /** - * Indicate if one or multiple lines shoud be read. + * Indicate if one or multiple lines should be read. * */ export type Multiline = boolean @@ -700,6 +705,8 @@ export type Fallback5 = | null /** * Role of associated to the message. + * Typical roles are `system`, `user`, and `assistant`, + * but there may be other roles such as `available_tools`. */ export type Role5 = string | null /** @@ -799,7 +806,8 @@ export type Fallback6 = | null /** * 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`. */ export type Role6 = string | null /** @@ -925,7 +933,8 @@ export type Fallback7 = | null /** * 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`. */ export type Role7 = string | null /** @@ -1026,7 +1035,8 @@ export type Fallback8 = | null /** * 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`. */ export type Role8 = string | null /** @@ -1127,7 +1137,8 @@ export type Fallback9 = | null /** * 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`. */ export type Role9 = string | null /** @@ -1254,7 +1265,8 @@ export type Fallback10 = | null /** * 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`. */ export type Role10 = string | null /** @@ -1435,7 +1447,8 @@ export type Fallback11 = | null /** * 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`. */ export type Role11 = string | null /** @@ -1575,7 +1588,8 @@ export type Fallback12 = | null /** * 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`. */ export type Role12 = string | null /** @@ -1599,7 +1613,7 @@ export type Kind12 = "if" */ export type If1 = boolean | string | LocalizedExpression /** - * Branch to exectute if the condition is true. + * Branch to execute if the condition is true. * */ export type Then1 = @@ -1711,7 +1725,8 @@ export type Fallback13 = | null /** * 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`. */ export type Role13 = string | null /** @@ -1787,7 +1802,8 @@ export type Fallback14 = | null /** * 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`. */ export type Role14 = string | null /** @@ -1863,7 +1879,8 @@ export type Fallback15 = | null /** * 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`. */ export type Role15 = string | null /** @@ -1969,7 +1986,8 @@ export type Fallback16 = | null /** * 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`. */ export type Role16 = string | null /** @@ -2052,7 +2070,7 @@ export type PdlTrace3 = */ export type Platform = "granite-io" /** - * Backend name and configuartion. + * Backend name and configuration. * */ export type Backend = @@ -2062,7 +2080,7 @@ export type Backend = } | LocalizedExpression /** - * IO Processir name. + * IO Processor name. * */ export type Processor = string | LocalizedExpression | null @@ -2131,7 +2149,8 @@ export type Fallback17 = | null /** * 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`. */ export type Role17 = string | null /** @@ -2150,7 +2169,7 @@ export type Context17 = export type PdlId17 = string | null export type Kind17 = "model" /** - * Name of he model following the LiteLLM convension. + * Name of the model following the LiteLLM convention. * */ export type Model1 = string | LocalizedExpression @@ -2331,7 +2350,8 @@ export type Fallback18 = | null /** * 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`. */ export type Role18 = string | null /** @@ -2428,7 +2448,8 @@ export type Fallback19 = | null /** * 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`. */ export type Role19 = string | null /** @@ -2628,7 +2649,14 @@ export interface Defs1 { | null } /** - * Call a LLM through the LiteLLM API: https://docs.litellm.ai/. + * Call an LLM through [the LiteLLM API](https://docs.litellm.ai/). + * + * Example: + * ```PDL + * - model: ollama/granite-code:8b + * parameters: + * stop: ['!'] + * ``` */ export interface LitellmModelBlock { description?: Description2 @@ -2691,7 +2719,7 @@ export interface Defs2 { | null } /** - * Call a LLM through the granite-io API. + * Call an LLM through the granite-io API. */ export interface GraniteioModelBlock { description?: Description3 @@ -2757,6 +2785,16 @@ export interface Defs3 { } /** * Execute a piece of code. + * + * Example: + * ```PDL + * - def: N + * lang: python + * code: | + * import random + * # (In PDL, set `result` to the output you wish for your code block.) + * result = random.randint(1, 20) + * ``` */ export interface CodeBlock { description?: Description4 @@ -2816,6 +2854,8 @@ export interface Defs4 { } /** * Get the value of a variable. + * + * The GetBlock is deprecated. Use DataBlock instead. */ export interface GetBlock { description?: Description5 @@ -2873,7 +2913,28 @@ export interface Defs5 { | null } /** - * Arbitrary JSON value. + * 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([0-9])*)\n*" + * spec: + * answer: str + * def: EXTRACTED_GROUND_TRUTH + * ``` */ export interface DataBlock { description?: Description6 @@ -2933,6 +2994,15 @@ export interface Defs6 { } /** * Conditional control structure. + * + * Example: + * ```PDL + * - if: ${ eval == 'no' } + * then: + * text: + * - read: + * message: "Why not?\n" + * ``` */ export interface IfBlock { description?: Description7 @@ -3053,6 +3123,15 @@ export interface Defs8 { } /** * 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" + * ``` */ export interface RepeatBlock { description?: Description9 @@ -3707,6 +3786,9 @@ export interface PdlParser { spec?: Spec20 pdl: Pdl } +/** + * A regular expression parser + */ export interface RegexParser { description?: Description21 spec?: Spec21 @@ -3792,7 +3874,9 @@ export interface AnyPattern { any: Any } /** - * Parameters passed to LiteLLM. More details at https://docs.litellm.ai/docs/completion/input. + * 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. */ export interface LitellmParameters { timeout?: Timeout diff --git a/src/pdl/pdl-schema.json b/src/pdl/pdl-schema.json index 8661f0e7..8f5bea8d 100644 --- a/src/pdl/pdl-schema.json +++ b/src/pdl/pdl-schema.json @@ -285,7 +285,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -762,7 +762,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -950,7 +950,7 @@ }, "CodeBlock": { "additionalProperties": false, - "description": "Execute a piece of code.", + "description": "Execute a piece of code.\n\nExample:\n```PDL\n- def: N\n lang: python\n code: |\n import random\n # (In PDL, set `result` to the output you wish for your code block.)\n result = random.randint(1, 20)\n```", "properties": { "description": { "anyOf": [ @@ -1206,7 +1206,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -1402,7 +1402,7 @@ }, "DataBlock": { "additionalProperties": false, - "description": "Arbitrary JSON value.", + "description": "Arbitrary value, equivalent to JSON.\n\nExample. As part of a `defs` section, set `numbers` to the list `[1, 2, 3, 4]`:\n```PDL\ndefs:\n numbers:\n data: [1, 2, 3, 4]\n```\n\nExample. Evaluate `${ TEST.answer }` in\n[Jinja](https://jinja.palletsprojects.com/en/stable/), passing\nthe result to a regex parser with capture groups. Set\n`EXTRACTED_GROUND_TRUTH` to an object with attribute `answer`,\na string, containing the value of the capture group.\n```PDL\n- data: ${ TEST.answer }\n parser:\n regex: \"(.|\\n)*#### (?P([0-9])*)\\n*\"\n spec:\n answer: str\n def: EXTRACTED_GROUND_TRUTH\n```", "properties": { "description": { "anyOf": [ @@ -1658,7 +1658,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -2013,7 +2013,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -2346,7 +2346,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -2769,7 +2769,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -2943,7 +2943,7 @@ }, "GetBlock": { "additionalProperties": false, - "description": "Get the value of a variable.", + "description": "Get the value of a variable.\n\nThe GetBlock is deprecated. Use DataBlock instead.", "properties": { "description": { "anyOf": [ @@ -3199,7 +3199,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -3284,7 +3284,7 @@ }, "GraniteioModelBlock": { "additionalProperties": false, - "description": "Call a LLM through the granite-io API.", + "description": "Call an LLM through the granite-io API.", "properties": { "description": { "anyOf": [ @@ -3540,7 +3540,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -3819,7 +3819,7 @@ "$ref": "#/$defs/LocalizedExpression_TypeVar_" } ], - "description": "Backend name and configuartion.\n ", + "description": "Backend name and configuration.\n ", "title": "Backend" }, "processor": { @@ -3835,7 +3835,7 @@ } ], "default": null, - "description": "IO Processir name.\n ", + "description": "IO Processor name.\n ", "title": "Processor" }, "parameters": { @@ -3867,7 +3867,7 @@ }, "IfBlock": { "additionalProperties": false, - "description": "Conditional control structure.", + "description": "Conditional control structure.\n\nExample:\n```PDL\n- if: ${ eval == 'no' }\n then:\n text:\n - read:\n message: \"Why not?\\n\"\n```", "properties": { "description": { "anyOf": [ @@ -4123,7 +4123,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -4287,7 +4287,7 @@ "type": "null" } ], - "description": "Branch to exectute if the condition is true.\n ", + "description": "Branch to execute if the condition is true.\n ", "title": "Then" }, "else": { @@ -4650,7 +4650,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -5072,7 +5072,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -5562,7 +5562,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -5726,7 +5726,7 @@ }, "LitellmModelBlock": { "additionalProperties": false, - "description": "Call a LLM through the LiteLLM API: https://docs.litellm.ai/.", + "description": "Call an LLM through [the LiteLLM API](https://docs.litellm.ai/).\n\nExample:\n```PDL\n- model: ollama/granite-code:8b\n parameters:\n stop: ['!']\n```", "properties": { "description": { "anyOf": [ @@ -5982,7 +5982,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -6062,7 +6062,7 @@ "$ref": "#/$defs/LocalizedExpression_TypeVar_" } ], - "description": "Name of he model following the LiteLLM convension.\n ", + "description": "Name of the model following the LiteLLM convention.\n ", "title": "Model" }, "input": { @@ -6279,7 +6279,7 @@ }, "LitellmParameters": { "additionalProperties": true, - "description": "Parameters passed to LiteLLM. More details at https://docs.litellm.ai/docs/completion/input.", + "description": "Parameters passed to LiteLLM. More details at [https://docs.litellm.ai/docs/completion/input](https://docs.litellm.ai/docs/completion/input).\n\nNote that not all models and platforms accept all parameters.", "properties": { "timeout": { "anyOf": [ @@ -6957,7 +6957,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -7492,7 +7492,7 @@ "type": "null" } ], - "description": "Role of associated to the message.", + "description": "Role of associated to the message.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -7910,7 +7910,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -8891,7 +8891,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -8992,7 +8992,7 @@ }, "multiline": { "default": false, - "description": "Indicate if one or multiple lines shoud be read.\n ", + "description": "Indicate if one or multiple lines should be read.\n ", "title": "Multiline", "type": "boolean" } @@ -9005,6 +9005,7 @@ }, "RegexParser": { "additionalProperties": false, + "description": "A regular expression parser", "properties": { "description": { "anyOf": [ @@ -9055,7 +9056,7 @@ }, "RepeatBlock": { "additionalProperties": false, - "description": "Repeat the execution of a block.", + "description": "Repeat the execution of a block.\n\nFor loop example:\n```PDL\nfor:\n number: [1, 2, 3, 4]\n name: [\"Bob\", \"Carol\", \"David\", \"Ernest\"]\nrepeat:\n \"${ name }'s number is ${ number }\\n\"\n```", "properties": { "description": { "anyOf": [ @@ -9311,7 +9312,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { @@ -9919,7 +9920,7 @@ } ], "default": null, - "description": "Role associated to the block and sub-blocks.\n ", + "description": "Role associated to the block and sub-blocks.\nTypical roles are `system`, `user`, and `assistant`,\nbut there may be other roles such as `available_tools`.", "title": "Role" }, "context": { diff --git a/src/pdl/pdl_ast.py b/src/pdl/pdl_ast.py index 075256a8..eacf5398 100644 --- a/src/pdl/pdl_ast.py +++ b/src/pdl/pdl_ast.py @@ -152,6 +152,8 @@ class PdlParser(Parser): class RegexParser(Parser): + """A regular expression parser""" + regex: str """Regular expression to parse the value.""" mode: Annotated[ @@ -229,6 +231,8 @@ class Block(BaseModel): """ 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 @@ -272,7 +276,10 @@ class CallBlock(Block): class LitellmParameters(BaseModel): - """Parameters passed to LiteLLM. More details at https://docs.litellm.ai/docs/completion/input.""" + """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 @@ -382,13 +389,22 @@ class ModelBlock(Block): class LitellmModelBlock(ModelBlock): - """Call a LLM through the LiteLLM API: https://docs.litellm.ai/.""" + """ + 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 he model following the LiteLLM convension. + """Name of the model following the LiteLLM convention. """ parameters: Optional[LitellmParameters | ExpressionType[dict]] = None """Parameters to send to the model. @@ -396,7 +412,7 @@ class LitellmModelBlock(ModelBlock): class GraniteioModelBlock(ModelBlock): - """Call a LLM through the granite-io API.""" + """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. @@ -405,10 +421,10 @@ class GraniteioModelBlock(ModelBlock): """Model name used by the backend. """ backend: ExpressionType[str | dict[str, Any]] - """Backend name and configuartion. + """Backend name and configuration. """ processor: Optional[ExpressionType[str]] = None - """IO Processir name. + """IO Processor name. """ parameters: Optional[ExpressionType[dict[str, Any]]] = None """Parameters sent to the model. @@ -416,7 +432,19 @@ class GraniteioModelBlock(ModelBlock): class CodeBlock(Block): - """Execute a piece of code.""" + """ + Execute a piece of code. + + Example: + ```PDL + - def: N + lang: python + code: | + import random + # (In PDL, set `result` to the output you wish for your code block.) + result = random.randint(1, 20) + ``` + """ kind: Literal[BlockKind.CODE] = BlockKind.CODE lang: Annotated[ @@ -430,7 +458,11 @@ class CodeBlock(Block): class GetBlock(Block): - """Get the value of a variable.""" + """ + Get the value of a variable. + + The GetBlock is deprecated. Use DataBlock instead. + """ kind: Literal[BlockKind.GET] = BlockKind.GET get: str @@ -438,7 +470,30 @@ class GetBlock(Block): class DataBlock(Block): - """Arbitrary JSON value.""" + """ + 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([0-9])*)\\n*" + spec: + answer: str + def: EXTRACTED_GROUND_TRUTH + ``` + """ kind: Literal[BlockKind.DATA] = BlockKind.DATA data: ExpressionType[Any] @@ -484,20 +539,34 @@ class MessageBlock(Block): kind: Literal[BlockKind.MESSAGE] = BlockKind.MESSAGE role: RoleType # pyright: ignore - """Role of associated to the message.""" # 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.""" class IfBlock(Block): - """Conditional control structure.""" + """ + Conditional control structure. + + Example: + ```PDL + - if: ${ eval == 'no' } + then: + text: + - read: + message: "Why not?\\n" + ``` + """ kind: Literal[BlockKind.IF] = BlockKind.IF condition: ExpressionType[bool] = Field(alias="if") """Condition. """ then: "BlockType" - """Branch to exectute if the condition is true. + """Branch to execute if the condition is true. """ else_: Optional["BlockType"] = Field(default=None, alias="else") """Branch to execute if the condition is false. @@ -582,7 +651,18 @@ class JoinLastOf(JoinConfig): class RepeatBlock(Block): - """Repeat the execution of a block.""" + """ + 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") @@ -618,7 +698,7 @@ class ReadBlock(Block): """Message to prompt the user to enter a value. """ multiline: bool = False - """Indicate if one or multiple lines shoud be read. + """Indicate if one or multiple lines should be read. """