docs: update tutorial

docs/README.md

@@ -201,7 +201,7 @@ text:
 ```
 
 
-A PDL program computes 2 data structures. The first is a JSON corresponding to the result of the overall program, obtained by aggregating the results of each block. This is what is printed by default when we run the interpreter. The second is a conversational background context, which is a list of role/content pairs, where we implicitly keep track of roles and content for the purpose of communicating with models that support chat APIs. The contents in the latter correspond to the results of each block. The conversational background context is the list of messages used to make calls to LLMs via LiteLLM.
+A PDL program computes two data structures. The first is a JSON corresponding to the result of the overall program, obtained by aggregating the results of each block. This is what is printed by default when we run the interpreter. The second is a conversational background context, which is a list of role/content pairs, where we implicitly keep track of roles and content for the purpose of communicating with models that support chat APIs. The contents in the latter correspond to the results of each block. The conversational background context is the list of messages used to make calls to LLMs via LiteLLM.
 
 The PDL interpreter can also stream the background conversation instead of the result:
 

examples/tutorial/calling_llm.pdl

@@ -1,6 +1,6 @@
-description: Hello world calling a model
+description: Calling a model on the implicit background context
 text:
 - "Hello\n"
 - model: ollama_chat/granite3.2:2b
   parameters:
-    stop: ['!']
+    stop: ['!']

examples/tutorial/calling_llm_with_input.pdl

@@ -1,4 +1,4 @@
-description: Hello world calling a model
+description: Calling a model with an input text
 text:
 - "Hello\n"
 - model: ollama_chat/granite3.2:2b

examples/tutorial/calling_llm_with_input_messages.pdl

@@ -1,4 +1,4 @@
-description: Hello world calling a model
+description: Calling a model with an explicit list of messages
 text:
 - "Hello\n"
 - model: ollama_chat/granite3.2:2b

examples/tutorial/calling_llm_with_input_messages_var.pdl

@@ -3,8 +3,10 @@ defs:
   prompt:
     array:
     - role: system
-      content: You are a helpful software engineer. You write clear, concise, well-commented code.
+      content: You are a helpful assistant that is fluent in French.
     - role: user
-      content: Write a Python function that implement merge sort.
-model: ollama_chat/granite3.2:2b
-input: ${ prompt }
+      content: Translate the word 'Hello' to French
+text:
+- "Hello\n"
+- model: ollama_chat/granite3.2:2b
+  input: ${ prompt }

examples/tutorial/defs.pdl

@@ -1,22 +1,16 @@
-description: Function def and call
-defs:
-  translate:
-    function:
-      sentence: string
-      language: string
-    return:
+text:
+- "Hello\n"
+- defs:
+    fr:
       lastOf:
-      - "\nTranslate the sentence '${ sentence }' to ${ language }.\n"
+      - "\nTranslate to French\n"
       - model: ollama_chat/granite3.2:2b
-        parameters:
-          stop: ["\n"]
-text:
-- call: ${ translate }
-  args:
-    sentence: I love Paris!
-    language: French
-- "\n"
-- call: ${ translate }
-  args:
-    sentence: I love Madrid!
-    language: Spanish
+    es:
+      lastOf:
+      - "\nTranslate to Spanish\n"
+      - model: ollama_chat/granite3.2:2b
+  text: |
+
+    In Fench: ${ fr }
+
+    In Spanish: ${ es }

examples/tutorial/function_alias.pdl

@@ -1,4 +1,4 @@
-description: Hello function
+description: Use a function as a value
 defs:
   hello:
     function:

examples/tutorial/function_call_in_jinja.pdl

@@ -0,0 +1,14 @@
+description: Calling a PDL function from Jinja
+defs:
+  translate:
+    function:
+      sentence: string
+      language: string
+    return:
+      lastOf:
+      - |
+        Translate the sentence '${ sentence }' to ${ language }.
+        Only give the result of the translation.
+      - model: ollama_chat/granite3.2:2b
+text: |
+  The way to say hello in French is ${ translate("Hello", language="French") }.

examples/tutorial/function_definition.pdl

@@ -1,16 +1,16 @@
-description: Function def and call
+description: Function definition and call
+defs:
+  translate:
+    function:
+      sentence: string
+      language: string
+    return:
+      lastOf:
+      - |
+        Translate the sentence '${ sentence }' to ${ language }.
+        Only give the result of the translation.
+      - model: ollama_chat/granite3.2:2b
 text:
-- def: translate
-  function:
-    sentence: string
-    language: string
-  return:
-    lastOf:
-    - "\nTranslate the sentence '${ sentence }' to ${ language }.\n"
-    - model: ollama_chat/granite3.2:2b
-      parameters:
-        stop: ["\n"]
-        temperature: 0
 - call: ${ translate }
   args:
     sentence: I love Paris!

examples/tutorial/function_empty_context.pdl

@@ -1,13 +1,24 @@
-description: Hello world with function definition and call
+description: Function call with an empty context
+defs:
+  translate:
+    function:
+      sentence: string
+      language: string
+    return:
+      lastOf:
+      - |
+        Translate the sentence '${ sentence }' to ${ language }.
+        Only give the result of the translation.
+      - model: ollama_chat/granite3.2:2b
 text:
-- def: hello
-  function:
-    name: string
-  return:
-    text:
-    -  Hello ${ name }!
-    - model: ollama_chat/granite3.2:8b
-- call: ${ hello }
+- call: ${ translate }
   args:
-    name: World
+    sentence: I love Paris!
+    language: French
+    pdl_context: []
+- "\n"
+- call: ${ translate }
+  args:
+    sentence: I love Madrid!
+    language: Spanish
     pdl_context: []

examples/tutorial/function_optional_params.pdl

@@ -1,14 +1,19 @@
-description: Hello world with function definition and call
+description: Function with optional parameter
+defs:
+  hello:
+    function:
+      name: string
+      lastName: {optional: string} # optional parameter
+    return:
+      if: ${ lastName is defined }
+      then: Hello ${ name } ${ lastName }!
+      else: Hello ${ name }!
 text:
-- def: hello
-  function:
-    name: string
-    lastName: {optional: string} # optional parameter
-  return:
-    if: ${ lastName is defined }
-    then: Hello ${ name } ${ lastName }!
-    else: Hello ${ name }!
 - call: ${ hello }
   args:
     name: World
-    lastName: Universe
+- "\n"
+- call: ${ hello }
+  args:
+    name: Earth
+    lastName: Planet

examples/tutorial/lastOf.pdl

@@ -0,0 +1,8 @@
+description: Explicit use of role
+role: user
+text:
+- "Hello\n"
+- lastOf:
+  - role: system
+    text: "You are a polite assistant that likes to answer very formally."
+  - model: ollama_chat/granite3.2:2b

examples/tutorial/local_computation.pdl

@@ -0,0 +1,9 @@
+description: Local computations using defs
+text:
+- "Hello\n"
+- defs:
+    GEN:
+      model: ollama_chat/granite3.2:2b
+      parameters:
+        stop: ['!']
+- "The variable GEN is equal to: ${ GEN }"

examples/tutorial/muting_block_output.pdl

@@ -1,21 +1,11 @@
-description: Function def and call
-defs:
-  translate:
-    function:
-      sentence: string
-      language: string
-    return:
-      text:
-      - text: "\nTranslate the sentence '${ sentence }' to ${ language }.\n"
-        contribute: [context]
-      - model: ollama_chat/granite3.2:2b
-        parameters:
-          stop: ["\n"]
+description: Control block outputs with `contribute`
 text:
-- call: ${ translate }
+- "Hello\n"
+- text: "\nTranslate to French\n"
+  contribute: [context]
+- model: ollama_chat/granite3.2:2b
   contribute: []
-  def: FRENCH
-  args:
-    sentence: I love Paris!
-    language: French
-- "The french sentence was: ${ FRENCH }"
+  def: fr
+- |
+
+  In Fench: ${ fr }

examples/tutorial/role.pdl

@@ -0,0 +1,7 @@
+description: Explicit use of role
+role: user
+text:
+- "Hello\n"
+- role: system
+  text: "You are a polite assistant that likes to answer very formally."
+- model: ollama_chat/granite3.2:2b

examples/tutorial/sdk/hello_dict.py

@@ -0,0 +1,21 @@
+from pdl.pdl import exec_dict
+
+
+def main():
+    hello = {
+        "text": [
+            "Hello\n",
+            {
+                "model": "ollama_chat/granite3.2:2b",
+                "parameters": {
+                    "stop": ["!"],
+                },
+            },
+        ]
+    }
+    result = exec_dict(hello)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()

examples/tutorial/sdk/hello_parallel.py

@@ -0,0 +1,37 @@
+import concurrent.futures
+
+from pdl.pdl import exec_str
+
+HELLO = """
+text:
+- >+
+  Hello, my name is ${name}
+- model: ollama_chat/granite3.2:2b
+"""
+
+
+def _run_agent(name):
+    pdl_output = exec_str(
+        HELLO,
+        scope={"name": name},
+        config={
+            "yield_result": False,
+            "yield_background": False,
+            "batch": 1,  # disable streaming
+        },
+    )
+    return pdl_output
+
+
+if __name__ == "__main__":
+    data = ["Alice", "Nicolas", "Rosa", "Remi"]
+    with concurrent.futures.ProcessPoolExecutor() as executor:
+        futures = {executor.submit(_run_agent, name) for name in data}
+        executor.map(_run_agent, data)
+        for future in concurrent.futures.as_completed(futures):
+            try:
+                result = future.result()
+            except Exception as e:
+                print(f"Task raised an exception: {e}")
+            else:
+                print(result)