feat: structuredDecoding field on the model block (#1250)

Author: mandel

.vscode/settings.json

@@ -4,5 +4,10 @@
     },
     "files.associations": {
         "*.pdl": "yaml",
-    }
+    },
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
 }

examples/tutorial/parser-regex.pdl

@@ -5,7 +5,6 @@ text:
   parameters:
     # Tell the LLM to stop after generating an exclamation point.
     stop: ['!']
-  spec: {"name": string}
   parser:
     spec:
       name: string

examples/tutorial/structured_decoding.pdl

@@ -1,8 +1,28 @@
+# Expected not to type check
+description: Creating JSON Data
+defs:
+  data:
+    read: type_checking_data.yaml
+    parser: yaml
+    spec: { questions: [string], answers: [object] }
 text:
-- role: system
-  text: You are an AI language model developed by IBM Research. You are a cautious assistant. You carefully follow instructions. You are helpful and harmless and you follow ethical guidelines and promote positive behavior.
-  contribute: [context]
-- "\nWhat is the color of the sky? Write it as JSON\n"
-- model: watsonx/ibm/granite-34b-code-instruct
-  parser: json
-  spec: { color: string }
+  - model: ollama_chat/granite3.2:2b
+    def: model_output
+    input:
+      array:
+      - role: user
+        content:
+          text:
+          - for:
+              question: ${ data.questions }
+              answer: ${ data.answers }
+            repeat: |
+              ${ question }
+              ${ answer }
+          - >
+            Question: Generate only a JSON object with fields 'name' and 'age' and set them appropriately. Write the age all in letters. Only generate a single JSON object and nothing else.
+    spec: {name: string, age: integer}
+    parser: json
+    parameters:
+      stop: ["Question"]
+      temperature: 0

examples/tutorial/type_checking.pdl

@@ -8,7 +8,6 @@ defs:
 text:
   - model: ollama_chat/granite3.2:2b
     def: model_output
-    spec: {name: string, age: integer}
     input:
       array:
       - role: user
@@ -22,7 +21,7 @@ text:
               ${ answer }
           - >
             Question: Generate only a JSON object with fields 'name' and 'age' and set them appropriately. Write the age all in letters. Only generate a single JSON object and nothing else.
-    parser: yaml
+    parser: json
     parameters:
       stop: ["Question"]
       temperature: 0

examples/tutorial/type_error.pdl

@@ -0,0 +1,29 @@
+# Expected not to type check
+description: Creating JSON Data
+defs:
+  data:
+    read: type_checking_data.yaml
+    parser: yaml
+    spec: { questions: [string], answers: [object] }
+text:
+  - model: ollama_chat/granite3.2:2b
+    def: model_output
+    input:
+      array:
+      - role: user
+        content:
+          text:
+          - for:
+              question: ${ data.questions }
+              answer: ${ data.answers }
+            repeat: |
+              ${ question }
+              ${ answer }
+          - >
+            Question: Generate only a JSON object with fields 'name' and 'age' and set them appropriately. Write the age all in letters. Only generate a single JSON object and nothing else.
+    spec: {name: string, age: integer}
+    parser: json
+    structuredDecoding: false
+    parameters:
+      stop: ["Question"]
+      temperature: 0

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

@@ -264,9 +264,6 @@ export type Anyof = PatternType[]
 export type Array = PatternType[]
 export type Any = null
 export type ExpressionBool = LocalizedExpression | boolean | string
-export type PdlCaseResult = boolean | null
-export type PdlIfResult = boolean | null
-export type PdlMatched = boolean | null
 /**
  * List of cases to match.
  *
@@ -463,7 +460,7 @@ export type Aggregator = "context" | FileAggregatorConfig
  * Documentation associated to the aggregator config.
  *
  */
-export type Description1 = string | null
+export type Description = string | null
 /**
  * Name of the file to which contribute.
  */
@@ -1015,9 +1012,9 @@ export interface RegexParser {
  * Single requirement definition.
  */
 export interface RequirementType {
-  description: unknown
-  evaluate: Evaluate
-  transformContext: Transformcontext
+  expect: unknown
+  evaluate?: Evaluate
+  transformContext?: Transformcontext
 }
 export interface LocalizedExpression {
   pdl__expr: PdlExpr
@@ -1191,6 +1188,10 @@ export interface LitellmModelBlock {
    */
   model: LocalizedExpression | string
   parameters?: Parameters1
+  /**
+   * Perform structured decoding if possible (i.e., `parser` and `spec` are provided and the inference platform supports it).
+   */
+  structuredDecoding?: boolean | null
 }
 /**
  * Set of definitions executed before the execution of the block.
@@ -2068,9 +2069,9 @@ export interface MatchCase {
   case?: PatternType | null
   if?: ExpressionBool | null
   then: BlockType
-  pdl__case_result?: PdlCaseResult
-  pdl__if_result?: PdlIfResult
-  pdl__matched?: PdlMatched
+  pdl__case_result?: boolean | null
+  pdl__if_result?: boolean | null
+  pdl__matched?: boolean | null
 }
 /**
  * Match any of the patterns.
@@ -3384,7 +3385,7 @@ export interface Defs20 {
   [k: string]: BlockType
 }
 export interface FileAggregatorConfig {
-  description?: Description1
+  description?: Description
   file: File1
   mode?: Mode1
   encoding?: Encoding

src/pdl/pdl-schema.json

@@ -2645,6 +2645,11 @@
           "default": null,
           "description": "Parameters to send to the model.\n    ",
           "title": "Parameters"
+        },
+        "structuredDecoding": {
+          "$ref": "#/$defs/OptionalBool",
+          "default": true,
+          "description": "Perform structured decoding if possible (i.e., `parser` and `spec` are provided and the inference platform supports it)."
         }
       },
       "required": [
@@ -3430,40 +3435,16 @@
           "$ref": "#/$defs/BlockType"
         },
         "pdl__case_result": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Pdl  Case Result"
+          "$ref": "#/$defs/OptionalBool",
+          "default": null
         },
         "pdl__if_result": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Pdl  If Result"
+          "$ref": "#/$defs/OptionalBool",
+          "default": null
         },
         "pdl__matched": {
-          "anyOf": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "null"
-            }
-          ],
-          "default": null,
-          "title": "Pdl  Matched"
+          "$ref": "#/$defs/OptionalBool",
+          "default": null
         }
       },
       "required": [
@@ -3798,6 +3779,16 @@
         }
       ]
     },
+    "OptionalBool": {
+      "anyOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
     "OptionalBoolOrStr": {
       "anyOf": [
         {

src/pdl/pdl_ast.py

@@ -41,6 +41,8 @@ def _ensure_lower(value):
 """Optional string."""
 OptionalInt = TypeAliasType("OptionalInt", Optional[int])
 """Optional integer."""
+OptionalBool = TypeAliasType("OptionalBool", Optional[bool])
+"""Optional Boolean."""
 OptionalBoolOrStr = TypeAliasType("OptionalBoolOrStr", Optional[Union[bool, str]])
 """Optional boolean or string."""
 OptionalAny = TypeAliasType("OptionalAny", Optional[Any])
@@ -629,6 +631,8 @@ class LitellmModelBlock(ModelBlock):
     parameters: Optional[LitellmParameters | ExpressionType[dict]] = None
     """Parameters to send to the model.
     """
+    structuredDecoding: OptionalBool = True
+    """Perform structured decoding if possible (i.e., `parser` and `spec` are provided and the inference platform supports it)."""
 
 
 class GraniteioProcessor(BaseModel):
@@ -835,9 +839,9 @@ class MatchCase(BaseModel):
     """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
+    pdl__case_result: OptionalBool = None
+    pdl__if_result: OptionalBool = None
+    pdl__matched: OptionalBool = None
 
 
 class MatchBlock(StructuredBlock):

src/pdl/pdl_dumper.py

@@ -154,6 +154,8 @@ def block_to_dict(  # noqa: C901
                     d["parameters"] = expr_to_dict(block.parameters, json_compatible)
             if block.modelResponse is not None:
                 d["modelResponse"] = block.modelResponse
+            if not block.structuredDecoding:
+                d["structuredDecoding"] = block.structuredDecoding
             if block.pdl__usage is not None:
                 d["pdl__usage"] = usage_to_dict(block.pdl__usage)
             if block.pdl__model_input is not None:

src/pdl/pdl_interpreter.py

@@ -1923,9 +1923,9 @@ def generate_client_response_streaming(
                 scope.get("pdl_model_default_parameters", []),
             )
             msg_stream = LitellmModel.generate_text_stream(
+                block,
                 model_id=value_of_expr(block.model),
                 messages=model_input,
-                spec=block.spec,
                 parameters=litellm_parameters_to_dict(parameters),
             )
         case GraniteioModelBlock():