Join loop iterations as objects (#580)

* Join loop iterations as objects

* Fix dumper

Author: mandel

docs/tutorial.md

@@ -421,14 +421,8 @@ This program outputs:
 ```
 
 To output a number of each line, we can specify which string to use to join the results.
-```
-description: for loop
-for:
-  i: [1, 2, 3, 4]
-repeat:
-  ${ i }
-join:
-  with: "\n"
+```yaml
+--8<-- "./examples/tutorial/for_with.pdl"
 ```
 
 ```
@@ -440,14 +434,8 @@ join:
 
 
 To creates an array as a result of iteration, we would write:
-```
-description: for loop
-for:
-  i: [1, 2, 3, 4]
-repeat:
-  - ${ i }
-join:
-  as: array
+```yaml
+--8<-- "./examples/tutorial/for_array.pdl"
 ```
 
 which outputs the following list:
@@ -456,14 +444,8 @@ which outputs the following list:
 ```
 
 To retain only the result of the last iteration of the loop, we would write:
-```
-description: for loop
-for:
-  i: [1, 2, 3, 4]
-repeat:
-  - ${ i }
-join:
-  as: lastOf
+```yaml
+--8<-- "./examples/tutorial/for_lastOf.pdl"
 ```
 
 which outputs:
@@ -484,20 +466,10 @@ meaning that result of each iteration is stringified and concatenated with that
 Note that `join` can be added to any looping construct (`repeat`) not just `for` loops.
 
 
-The `for` loop constructs also allows iterating over 2 or more lists of the same length simultaneously:
+The `for` loop construct also allows iterating over 2 or more lists of the same length simultaneously:
 
-```
-description: for loop
-defs:
-  numbers:
-    data: [1, 2, 3, 4]
-  names:
-    data: ["Bob", "Carol", "David", "Ernest"]
-for:
-  number: ${ numbers }
-  name: ${ names }
-repeat:
-  "${ name }'s number is ${ number }\n"
+```yaml
+--8<-- "./examples/tutorial/for_multiple_lists.pdl"
 ```
 
 This results in the following output:
@@ -509,6 +481,18 @@ David's number is 3
 Ernest's number is 4
 ```
 
+The loop constructs also allow to build an object:
+```yaml
+--8<-- "./examples/tutorial/for_object.pdl"
+```
+
+This results in the following output:
+
+```
+{"Bob": 1, "Carol": 2, "David": 3, "Ernest": 4}
+```
+
+
 ## Roles and Chat Templates
 
 Consider again the chatbot example ([file](https://github.com/IBM/prompt-declaration-language//blob/main/examples/tutorial/conditionals_loops.pdl)). By default blocks have role `user`, except for model call blocks, which have role `assistant`.

examples/tutorial/for.pdl

@@ -1,4 +1,4 @@
-description: for loop
+description: for loop creating a string
 for:
   i: [1, 2, 3, 4]
 repeat: 

examples/tutorial/for_array.pdl

@@ -1,4 +1,4 @@
-description: for loop
+description: array comprehension
 for:
   i: [1, 2, 3, 4]
 repeat:

examples/tutorial/for_lastOf.pdl

@@ -0,0 +1,7 @@
+description: loop where the result is the result of the last iteration
+for:
+  i: [1, 2, 3, 4]
+repeat:
+  ${ i }
+join:
+  as: lastOf

examples/tutorial/for_multiplie_lists.pdl

@@ -1,4 +1,4 @@
-description: for loop
+description: for loop over multiple lists
 defs:
   numbers:
     data: [1, 2, 3, 4]

examples/tutorial/for_object.pdl

@@ -0,0 +1,14 @@
+description: for loop creating an object
+defs:
+  numbers:
+    data: [1, 2, 3, 4]
+  names:
+    data: ["Bob", "Carol", "David", "Ernest"]
+for:
+  number: ${ numbers }
+  name: ${ names }
+repeat:
+  data:
+    ${ name }: ${ number }
+join:
+  as: object

examples/tutorial/for_with.pdl

@@ -1,4 +1,4 @@
-description: for loop
+description: for loop with new lines between iterations
 for:
   i: [1, 2, 3, 4]
 repeat: 

src/pdl/pdl-schema.json

@@ -5245,6 +5245,22 @@
       "title": "JoinLastOf",
       "type": "object"
     },
+    "JoinObject": {
+      "additionalProperties": false,
+      "properties": {
+        "as": {
+          "const": "object",
+          "description": "Return the union of the objects created at each iteration.\n    ",
+          "title": "As",
+          "type": "string"
+        }
+      },
+      "required": [
+        "as"
+      ],
+      "title": "JoinObject",
+      "type": "object"
+    },
     "JoinText": {
       "additionalProperties": false,
       "properties": {
@@ -9439,6 +9455,9 @@
             {
               "$ref": "#/$defs/JoinArray"
             },
+            {
+              "$ref": "#/$defs/JoinObject"
+            },
             {
               "$ref": "#/$defs/JoinLastOf"
             }

src/pdl/pdl_ast.py

@@ -477,6 +477,7 @@ class MatchBlock(Block):
 class IterationType(StrEnum):
     LASTOF = "lastOf"
     ARRAY = "array"
+    OBJECT = "object"
     TEXT = "text"
 
 
@@ -504,13 +505,19 @@ class JoinArray(JoinConfig):
     """
 
 
+class JoinObject(JoinConfig):
+    iteration_type: Literal[IterationType.OBJECT] = Field(alias="as")
+    """Return the union of the objects created at each iteration.
+    """
+
+
 class JoinLastOf(JoinConfig):
     iteration_type: Literal[IterationType.LASTOF] = Field(alias="as")
     """Return the result of the last iteration.
     """
 
 
-JoinType: TypeAlias = JoinText | JoinArray | JoinLastOf
+JoinType: TypeAlias = JoinText | JoinArray | JoinObject | JoinLastOf
 
 
 class RepeatBlock(Block):

src/pdl/pdl_dumper.py

@@ -23,8 +23,6 @@
     IfBlock,
     ImportBlock,
     IncludeBlock,
-    JoinArray,
-    JoinLastOf,
     JoinText,
     JoinType,
     LastOfBlock,
@@ -287,7 +285,7 @@ def join_to_dict(join: JoinType) -> dict[str, Any]:
     match join:
         case JoinText():
             d["with"] = join.join_string
-        case JoinArray() | JoinLastOf():
+        case _:
             d["as"] = str(join.iteration_type)
     return d