Add comments to examples to make them more obvious

README.md

@@ -148,6 +148,7 @@ text:
   lang: python
   code: |
     import random
+    # (In PDL, set `result` to the output you wish for your code block.)
     result = random.randint(1, 20)
 - "\nthe result is (${ N })\n"
 ```

docs/README.md

@@ -326,6 +326,7 @@ text:
     truth = """
     ${ TRUTH }
     """
+    # (In PDL, set `result` to the output you wish for your code block.)
     result = textdistance.levenshtein.normalized_similarity(expl, truth)
 
 ```
@@ -406,6 +407,7 @@ text:
     truth = """
     ${ TRUTH }
     """
+    # (In PDL, set `result` to the output you wish for your code block.)
     result = textdistance.levenshtein.normalized_similarity(expl, truth)
 - data: 
     input: ${ CODE }

docs/tutorial.md

@@ -135,7 +135,7 @@ Yes, I did. How can I assist you today?
 ## Function Definition
 
 PDL also supports function definitions to make it easier to reuse code.
-Suppose we want to define a translation function that takes a string and calls a falcon model for the translation. This would be written in PDL as follows ([file](https://github.com/IBM/prompt-declaration-language//blob/main/examples/tutorial/function_definition.pdl)):
+Suppose we want to define a translation function that takes a string and calls a Granite model for the translation. This would be written in PDL as follows ([file](https://github.com/IBM/prompt-declaration-language//blob/main/examples/tutorial/function_definition.pdl)):
 
 
 ```yaml

examples/callback/repair_prompt.pdl

@@ -19,6 +19,7 @@ lastOf:
   spec: {thought: str, code_line: str}
   code: |
     import repair_main
+    # (In PDL, set `result` to the output you wish for your code block.)
     result = repair_main.parse_output(raw_output)
 
 - spec: {before: str, after: str}

examples/chatbot/chatbot.pdl

@@ -1,22 +1,24 @@
 description: chatbot
 text:
+# Allow the user to type any question, implicitly adding the question to the context.
 - read:
   message: "What is your query?\n"
-  contribute: [context]
 - repeat:
     text:
+    # Send context to Granite model hosted at replicate.com
     - model: replicate/ibm-granite/granite-3.0-8b-instruct
+    # Allow the user to type 'yes', 'no', or anything else, storing
+    # the input into a variable named `eval`.  The input is also implicitly
+    # added to the context.
     - read:
       def: eval
       message: "\nIs this a good answer[yes/no]?\n"
-      contribute: [context]
+    - "\n"
+    # If the user only typed "no", prompt the user for input to add to the context.
     - if: ${ eval == 'no' }
       then:
         text:
         - read:
           message: "Why not?\n"
-          contribute: []
+  # If the user typed only "yes", finish the `repeat` and end the program
   until: ${ eval == 'yes'}
-
-
-

examples/code/code-eval.pdl

@@ -1,12 +1,17 @@
 description: Code explanation example
 defs:
+  # The variable `CODE` shall be the contents of the parsed YAML file
   CODE:
     read: ./data.yaml
     parser: yaml
+  # The variable `TRUTH` shall be the text of the file
   TRUTH:
     read: ./ground_truth.txt
 text:
+# Print the source code to the console
 - "\n${ CODE.source_code }\n"
+# Use replicate.com to invoke a Granite model with a prompt.  Output AND
+# set the variable `EXPLANATION` to the output.
 - model: replicate/ibm-granite/granite-3.0-8b-instruct
   def: EXPLANATION
   input: |
@@ -21,14 +26,17 @@ text:
       ```
       ${ CODE.source_code }```
   parameters:
+    # Use no LLM creativity.  (Note that 0 is the default; this line has no effect)
     temperature: 0
 - |
 
 
   EVALUATION:
   The similarity (Levenshtein) between this answer and the ground truth is:
+# We aren't only defining `EVAL`, we are also executing it.
 - def: EVAL
   lang: python
+  # (Use `pip install textdistance` if needed to install the textdistance package)
   code: |
     import textdistance
     expl = """
@@ -37,4 +45,5 @@ text:
     truth = """
     ${ TRUTH }
     """
+    # (In PDL, set `result` to the output you wish for your code block.)
     result = textdistance.levenshtein.normalized_similarity(expl, truth)

examples/code/code-json.pdl

@@ -35,6 +35,7 @@ text:
     truth = """
     ${ TRUTH }
     """
+    # (In PDL, set `result` to the output you wish for your code block.)
     result = textdistance.levenshtein.normalized_similarity(expl, truth)
 - data: 
     input: ${ CODE }

examples/code/code.pdl

@@ -1,10 +1,13 @@
 description: Code explanation example
 defs:
+  # Read data.yaml as YAML and store it in a variable `CODE`
   CODE:
     read: ./data.yaml
     parser: yaml
 text:
+# Output the `source_code:` of the YAML to the console
 - "\n${ CODE.source_code }\n"
+# Use replicate.com to invoke a Granite model with a prompt
 - model: replicate/ibm-granite/granite-3.0-8b-instruct
   input: |
     Here is some info about the location of the function in the repo.
@@ -18,4 +21,5 @@ text:
     ```
     ${ CODE.source_code }```
   parameters:
+    # Use no LLM creativity.  (Note that 0 is the default; this line has no effect)
     temperature: 0

examples/fibonacci/fib.pdl

@@ -3,7 +3,8 @@
 description: Fibonacci
 
 text:
-# Use IBM Granite to author a program that computes the Nth Fibonacci number
+# Use IBM Granite to author a program that computes the Nth Fibonacci number,
+# storing the generated program into the variable `CODE`.
 - def: CODE
   model: replicate/ibm-granite/granite-3.0-8b-instruct
   input: "Write a Python function to compute the Fibonacci sequence. Do not include a doc string.\n\n"
@@ -17,6 +18,7 @@ text:
   lang: python
   code: |
     import random
+    # (In PDL, set `result` to the output you wish for your code block.)
     result = random.randint(1, 20)
 
 - "\nNow computing fibonacci(${ N })\n"

examples/granite/README.md

@@ -5,5 +5,5 @@ pdl -f ./prompt.json single_round_chat.pdl
 ```
 
 ```
-pdl -f ./multi-prompts.json multi_round_chat.pdl
+pdl multi_round_chat.pdl
 ```

examples/granite/multi_round_chat.pdl

@@ -1,19 +1,25 @@
 description: Granite Multi-Round Chat
 text:
-- include: ./granite_defs.pdl
+# Define the variable `defs` to contain the parsed multi-prompts.json
 - read: ./multi-prompts.json
   parser: json
   def: prompts
+  # Type-check multi-prompts.json against a specification
   spec: {prompts: [str]}
+  # Don't store these prompts in the PDL context
   contribute: []
+# Pass each prompt to the model
 - for:
     prompt: ${ prompts.prompts }
   repeat:
     text:
+    # Output the question, and add it to the context
     - |
 
       ${ prompt }
+    # Use replicate.com to run the Granite model on the context, outputting the result
     - model: replicate/ibm-granite/granite-3.0-8b-instruct
       parameters:
+        # Use no LLM model creativity (0 is the default)
         temperature: 0
 role: user

examples/granite/single_round_chat.pdl

@@ -1,8 +1,9 @@
 description: Granite Single-Round Chat
 text:
-- include: ./granite_defs.pdl
+# (Note that 'PROMPT' is undefined will happen if you don't invoke pdl with `-f prompt.json`)
 - "${ PROMPT }\n"
 - model: replicate/ibm-granite/granite-3.0-8b-instruct
   parameters:
+    # Use no LLM model creativity (0 is the default)
     temperature: 0
 role: user

examples/hello/hello-def-use.pdl

@@ -1,9 +1,12 @@
 description: Hello world with variable use
 text:
 - "Hello\n"
+# Define GEN to be the result of a Granite LLM using replicate.com
 - model: replicate/ibm-granite/granite-3.0-8b-instruct
   parameters:
+    # "greedy" sampling tells the LLM to use the most likely token at each step
     decoding_method: greedy
+    # Tell the LLM to stop after generating an exclamation point.
     stop_sequences: '!'
   def: GEN
 - |

examples/hello/hello-model-chaining.pdl

@@ -3,7 +3,9 @@ text:
 - "Hello\n"
 - model: replicate/ibm-granite/granite-3.0-8b-instruct
   parameters:
+    # "greedy" sampling tells the LLM to use the most likely token at each step
     decoding_method: greedy
+    # Tell the LLM to stop after generating an exclamation point.
     stop_sequences: '!'
   def: GEN
 - "\nDid you say ${ GEN }?\n"

examples/hello/hello-model-input.pdl

@@ -3,4 +3,5 @@ text:
 - model: replicate/ibm-granite/granite-3.0-8b-instruct
   input: "Hello,"
   parameters:
+    # Tell the LLM to stop after generating an exclamation point.
     stop_sequences: '!'

examples/hello/hello-parser-regex.pdl

@@ -3,11 +3,10 @@ text:
 - model: replicate/ibm-granite/granite-3.0-8b-instruct
   input: "Hello,"
   parameters:
+    # Tell the LLM to stop after generating an exclamation point.
     stop_sequences: '!'
   spec: {"name": str}
   parser:
     spec:
       name: str
     regex: '\s*(?P<name>.*)\s*'
-
-