Skip to content

Commit

Permalink
Docstrings and examples for PDL concepts (#693)
Browse files Browse the repository at this point in the history 
* Docstrings and examples for PDL concepts
  • Loading branch information
@esnible
esnible authored Mar 6, 2025
1 parent 9a52e8a commit 1799b6e
Show file tree
Hide file tree
Showing 3 changed files with 240 additions and 75 deletions.
140 changes: 112 additions & 28 deletions pdl-live-react/src/pdl_ast.d.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand All @@ -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 =
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -2052,7 +2070,7 @@ export type PdlTrace3 =
*/
export type Platform = "granite-io"
/**
* Backend name and configuartion.
* Backend name and configuration.
*
*/
export type Backend =
Expand All @@ -2062,7 +2080,7 @@ export type Backend =
}
| LocalizedExpression
/**
* IO Processir name.
* IO Processor name.
*
*/
export type Processor = string | LocalizedExpression | null
Expand Down Expand Up @@ -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
/**
Expand All @@ -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
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
/**
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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<answer>([0-9])*)\n*"
* spec:
* answer: str
* def: EXTRACTED_GROUND_TRUTH
* ```
*/
export interface DataBlock {
description?: Description6
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -3707,6 +3786,9 @@ export interface PdlParser {
spec?: Spec20
pdl: Pdl
}
/**
* A regular expression parser
*/
export interface RegexParser {
description?: Description21
spec?: Spec21
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 1799b6e

Please sign in to comment.