docs: AST documentation (#963)

Signed-off-by: Louis Mandel <[email protected]>

Author: mandel

pdl-live-react/src/pdl_ast.d.ts

@@ -158,6 +158,9 @@ export type Description20 = string | null
  *
  */
 export type Def = string | null
+/**
+ * Values allowed in the `contribute` field.
+ */
 export type ContributeTarget = "result" | "context"
 export type Value = LocalizedExpression | unknown[] | string
 export type Path = string[]
@@ -3075,9 +3078,9 @@ export interface Defs1 {
  *
  * Example:
  * ```PDL
- * - model: ollama/granite-code:8b
- *   parameters:
- *     stop: ['!']
+ * model: ollama/granite-code:8b
+ * parameters:
+ *   stop: ['!']
  * ```
  */
 export interface LitellmModelBlock {
@@ -4688,6 +4691,9 @@ export interface Defs20 {
     | EmptyBlock
     | null
 }
+/**
+ * Contribution of a specific value instead of the default one.
+ */
 export interface ContributeValue {
   value: Value
 }
@@ -4710,6 +4716,9 @@ export interface PdlLocationType {
 export interface Table {
   [k: string]: number
 }
+/**
+ * Use a PDL program as a parser specification (experimental).
+ */
 export interface PdlParser {
   description?: Description21
   spec?:
@@ -4734,7 +4743,7 @@ export interface PdlParser {
   pdl: Pdl
 }
 /**
- * A regular expression parser
+ * A regular expression parser.
  */
 export interface RegexParser {
   description?: Description22
@@ -4769,16 +4778,28 @@ export interface PdlTiming {
   first_use_nanos?: FirstUseNanos
   timezone?: Timezone
 }
+/**
+ * Join loop iterations as a string.
+ */
 export interface JoinText {
   as?: As
   with?: With
 }
+/**
+ * Join loop iterations as an array.
+ */
 export interface JoinArray {
   as: As1
 }
+/**
+ * Join loop iterations as an object.
+ */
 export interface JoinObject {
   as: As2
 }
+/**
+ * Join loop iterations as the value of the last iteration.
+ */
 export interface JoinLastOf {
   as: As3
 }
@@ -4793,14 +4814,23 @@ export interface MatchCase {
   pdl__if_result?: PdlIfResult
   pdl__matched?: PdlMatched
 }
+/**
+ * Match any of the patterns.
+ */
 export interface OrPattern {
   def?: Def12
   anyOf: Anyof
 }
+/**
+ * Match an array.
+ */
 export interface ArrayPattern {
   def?: Def13
   array: Array1
 }
+/**
+ * Match an object.
+ */
 export interface ObjectPattern {
   def?: Def14
   object: Object2
@@ -4816,6 +4846,9 @@ export interface Object2 {
     | AnyPattern
     | null
 }
+/**
+ * Match any value.
+ */
 export interface AnyPattern {
   def?: Def15
   any: Any

src/pdl/pdl-schema.json

@@ -2,6 +2,7 @@
   "$defs": {
     "AnyPattern": {
       "additionalProperties": false,
+      "description": "Match any value.",
       "properties": {
         "def": {
           "anyOf": [
@@ -897,6 +898,7 @@
     },
     "ArrayPattern": {
       "additionalProperties": false,
+      "description": "Match an array.",
       "properties": {
         "def": {
           "anyOf": [
@@ -1917,6 +1919,7 @@
       "type": "object"
     },
     "ContributeTarget": {
+      "description": "Values allowed in the `contribute` field.",
       "enum": [
         "result",
         "context"
@@ -1926,6 +1929,7 @@
     },
     "ContributeValue": {
       "additionalProperties": false,
+      "description": "Contribution of a specific value instead of the default one.",
       "properties": {
         "value": {
           "anyOf": [
@@ -6185,6 +6189,7 @@
     },
     "JoinArray": {
       "additionalProperties": false,
+      "description": "Join loop iterations as an array.",
       "properties": {
         "as": {
           "const": "array",
@@ -6201,6 +6206,7 @@
     },
     "JoinLastOf": {
       "additionalProperties": false,
+      "description": "Join loop iterations as the value of the last iteration.",
       "properties": {
         "as": {
           "const": "lastOf",
@@ -6217,6 +6223,7 @@
     },
     "JoinObject": {
       "additionalProperties": false,
+      "description": "Join loop iterations as an object.",
       "properties": {
         "as": {
           "const": "object",
@@ -6233,6 +6240,7 @@
     },
     "JoinText": {
       "additionalProperties": false,
+      "description": "Join loop iterations as a string.",
       "properties": {
         "as": {
           "const": "text",
@@ -6747,7 +6755,7 @@
     },
     "LitellmModelBlock": {
       "additionalProperties": false,
-      "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```",
+      "description": "Call an LLM through [the LiteLLM API](https://docs.litellm.ai/).\n\nExample:\n```PDL\nmodel: ollama/granite-code:8b\nparameters:\n  stop: ['!']\n```",
       "properties": {
         "description": {
           "anyOf": [
@@ -9365,6 +9373,7 @@
     },
     "ObjectPattern": {
       "additionalProperties": false,
+      "description": "Match an object.",
       "properties": {
         "def": {
           "anyOf": [
@@ -9454,6 +9463,7 @@
     },
     "OrPattern": {
       "additionalProperties": false,
+      "description": "Match any of the patterns.",
       "properties": {
         "def": {
           "anyOf": [
@@ -9625,6 +9635,7 @@
     },
     "PdlParser": {
       "additionalProperties": false,
+      "description": "Use a PDL program as a parser specification (experimental).",
       "properties": {
         "description": {
           "anyOf": [
@@ -10360,7 +10371,7 @@
     },
     "RegexParser": {
       "additionalProperties": false,
-      "description": "A regular expression parser",
+      "description": "A regular expression parser.",
       "properties": {
         "description": {
           "anyOf": [

src/pdl/pdl_ast.py

@@ -100,10 +100,11 @@ class LocalizedExpression(BaseModel, Generic[LocalizedExpressionT]):
 
 ExpressionTypeT = TypeVar("ExpressionTypeT")
 ExpressionType: TypeAlias = LocalizedExpression[ExpressionTypeT] | ExpressionTypeT | str
+"""Expressions are represented Jinja as strings in between `${` and `}`."""
 
 
 class Pattern(BaseModel):
-    """Patterns allowed to match values in a `case` clause."""
+    """Common fields for structured patterns."""
 
     model_config = ConfigDict(extra="forbid")
     def_: Optional[str] = Field(default=None, alias="def")
@@ -112,24 +113,31 @@ class Pattern(BaseModel):
 
 
 class OrPattern(Pattern):
-    anyOf: list["PatternType"]
     """Match any of the patterns."""
 
+    anyOf: list["PatternType"]
+    """List of possible patterns."""
+
 
 class ArrayPattern(Pattern):
-    array: list["PatternType"]
     """Match an array."""
 
+    array: list["PatternType"]
+    """Shape of the array to match."""
+
 
 class ObjectPattern(Pattern):
-    object: dict[str, "PatternType"]
     """Match an object."""
 
+    object: dict[str, "PatternType"]
+    """Shape of the object to match."""
+
 
 class AnyPattern(Pattern):
-    any: Literal[None]
     """Match any value."""
 
+    any: Literal[None]
+
 
 PatternType: TypeAlias = (
     None
@@ -142,11 +150,13 @@ class AnyPattern(Pattern):
     | ObjectPattern
     | AnyPattern
 )
+"""Patterns allowed to match values in a `case` clause."""
 
 
 BasePdlType: TypeAlias = Literal[
     "null", "boolean", "string", "number", "integer", "array", "object"
 ]
+"""Base types."""
 
 
 class PdlType(BaseModel):
@@ -201,6 +211,7 @@ class ObjectPdlType(PdlType):
         Field(union_mode="left_to_right"),
     ],
 )
+"""Types."""
 
 pdl_type_adapter = TypeAdapter(PdlTypeType)
 
@@ -218,12 +229,14 @@ class Parser(BaseModel):
 
 
 class PdlParser(Parser):
+    """Use a PDL program as a parser specification (experimental)."""
+
     pdl: "BlockType"
-    """Use a PDL program as a parser specification."""
+    """PDL program describing the shape of the expected value."""
 
 
 class RegexParser(Parser):
-    """A regular expression parser"""
+    """A regular expression parser."""
 
     regex: str
     """Regular expression to parse the value."""
@@ -238,17 +251,24 @@ class RegexParser(Parser):
 
 
 RoleType: TypeAlias = Optional[str]
+"""Role name."""
 
 
 class ContributeTarget(StrEnum):
+    """Values allowed in the `contribute` field."""
+
     RESULT = "result"
     CONTEXT = "context"
 
 
 class ContributeValue(BaseModel):
-    value: ExpressionType[list[Any]]
+    """Contribution of a specific value instead of the default one."""
+
     model_config = ConfigDict(extra="forbid")
 
+    value: ExpressionType[list[Any]]
+    """Value to contribute."""
+
 
 class PdlTiming(BaseModel):
     """Internal data structure to record timing information in the trace."""
@@ -505,9 +525,9 @@ class LitellmModelBlock(ModelBlock):
 
     Example:
     ```PDL
-    - model: ollama/granite-code:8b
-      parameters:
-        stop: ['!']
+    model: ollama/granite-code:8b
+    parameters:
+      stop: ['!']
     ```
     """
 
@@ -771,6 +791,8 @@ class JoinConfig(BaseModel):
 
 
 class JoinText(JoinConfig):
+    """Join loop iterations as a string."""
+
     as_: Literal[IterationType.TEXT] = Field(alias="as", default=IterationType.TEXT)
     """String concatenation of the result of each iteration.
     """
@@ -781,24 +803,31 @@ class JoinText(JoinConfig):
 
 
 class JoinArray(JoinConfig):
+    """Join loop iterations as an array."""
+
     as_: Literal[IterationType.ARRAY] = Field(alias="as")
     """Return the result of each iteration as an array.
     """
 
 
 class JoinObject(JoinConfig):
+    """Join loop iterations as an object."""
+
     as_: Literal[IterationType.OBJECT] = Field(alias="as")
     """Return the union of the objects created at each iteration.
     """
 
 
 class JoinLastOf(JoinConfig):
+    """Join loop iterations as the value of the last iteration."""
+
     as_: Literal[IterationType.LASTOF] = Field(alias="as")
     """Return the result of the last iteration.
     """
 
 
 JoinType: TypeAlias = JoinText | JoinArray | JoinObject | JoinLastOf
+"""Different ways to join loop iterations."""
 
 
 class RepeatBlock(StructuredBlock):