changed mode to trace, added documentation for Live Document (#5)

Signed-off-by: Mandana Vaziri <[email protected]>

README.md

@@ -62,21 +62,28 @@ The interpreter prints out a log by default in the file `log.txt`. This log cont
 To change the log filename, you can pass it to the interpreter as follows:
 
 ```
-python3 -m pdl.pdl --log <my-logfile> <my-example>
+python -m pdl.pdl --log <my-logfile> <my-example>
 ```
 
 We can also pass initial data to the interpreter to populate variables used in a PDL program, as follows:
 
 ```
-python3 -m pdl.pdl --data <JSON-or-YAML-data> <my-example>
+python -m pdl.pdl --data <JSON-or-YAML-data> <my-example>
 ```
 
 This can also be done by passing a JSON or YAML file:
 
 ```
-python3 -m pdl.pdl --data_file <JSON-or-YAML-file> <my-example>
+python -m pdl.pdl --data_file <JSON-or-YAML-file> <my-example>
 ```
 
+The interpreter can also output a trace file that is used by the Live Document visualization tool (see [Live Document](#live_document)):
+
+```
+python -m pdl.pdl --trace <json | yaml> <my-example>
+```
+
+
 ## Overview
 
 In PDL, we can write some YAML to create a prompt and call an LLM:
@@ -335,6 +342,20 @@ The data block takes various variables and combines their values into a JSON obj
 See [PDL Language Tutorial](https://ibm.github.io/prompt-declaration-language/tutorial)
 
 
+## Live Document Visualizer
+
+PDL has a Live Document visualizer to help in program understanding given an execution trace.
+To produce an execution trace consumable by the Live Document, you can run the interpreter with the `--trace` argument and set the value to either `json` or `yaml`:
+
+```
+python -m pdl.pdl --trace <json | yaml> <my-example>
+```
+
+This produces an additional file named `my-example_result.json` or `my-example_result.yaml` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
+in the right pane. 
+
+This is similar to a spreadsheet for tabular data, where data is in the forefront and the user can inspect the formula that generates the data in each cell. In the Live Document, cells are not uniform but can take arbitrary extents. Clicking on them similarly reveals the part of the code that produced them.
+
 
 ## Additional Notes and Future Work
 TODO

docs/README.md

@@ -339,6 +339,19 @@ The data block takes various variables and combines their values into a JSON obj
 
 See [PDL Language Tutorial](https://ibm.github.io/prompt-declaration-language/tutorial)
 
+## Live Document Visualizer
+
+PDL has a Live Document visualizer to help in program understanding given an execution trace.
+To produce an execution trace consumable by the Live Document, you can run the interpreter with the `--trace` argument and set the value to either `json` or `yaml`:
+
+```
+python -m pdl.pdl --trace <json | yaml> <my-example>
+```
+
+This produces an additional file named `my-example_result.json` or `my-example_result.yaml` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
+in the right pane. 
+
+This is similar to a spreadsheet for tabular data, where data is in the forefront and the user can inspect the formula that generates the data in each cell. In the Live Document, cells are not uniform but can take arbitrary extents. Clicking on them similarly reveals the part of the code that produced them.
 
 
 ## Additional Notes and Future Work

docs/tutorial.md

@@ -1277,6 +1277,21 @@ result, document, _, _ = process_prog(state, empty_scope, data)
 where `result` is a JSON object, and `document` is a string, both corresponding to the result of the program.
 
 
+## Live Document Visualizer
+
+PDL has a Live Document visualizer to help in program understanding given an execution trace.
+To produce an execution trace consumable by the Live Document, you can run the interpreter with the `--trace` argument and set the value to either `json` or `yaml`:
+
+```
+python -m pdl.pdl --trace <json | yaml> <my-example>
+```
+
+This produces an additional file named `my-example_result.json` or `my-example_result.yaml` that can be uploaded to the [Live Document](https://ibm.github.io/prompt-declaration-language/viewer/) visualizer tool. Clicking on different parts of the Live Document will show the PDL code that produced that part 
+in the right pane. 
+
+This is similar to a spreadsheet for tabular data, where data is in the forefront and the user can inspect the formula that generates the data in each cell. In the Live Document, cells are not uniform but can take arbitrary extents. Clicking on them similarly reveals the part of the code that produced them.
+
+
 
 
 

pdl/pdl.py

@@ -34,7 +34,9 @@ def main():
     )
 
     parser.add_argument("-o", "--output", help="output file")
-    parser.add_argument("-m", "--mode", help="output mode", choices=["json", "yaml"])
+    parser.add_argument(
+        "-m", "--trace", help="output trace for live document", choices=["json", "yaml"]
+    )
     parser.add_argument("--json", help="json file")
     parser.add_argument("--yaml", help="yaml file")
     parser.add_argument("pdl", nargs="?", help="pdl file", type=str)
@@ -65,7 +67,7 @@ def main():
         args.pdl,
         args.log,
         initial_scope,
-        args.mode,
+        args.trace,
         args.output,
     )
 

pdl/pdl_interpreter.py

@@ -90,7 +90,7 @@ def generate(
     pdl_file: str,
     log_file: Optional[str],
     initial_scope: ScopeType,
-    output_mode: Optional[Literal["json", "yaml"]],
+    output_trace: Optional[Literal["json", "yaml"]],
     output_file: Optional[str],
 ):
     """Execute the PDL program defined in `pdl_file`.
@@ -99,7 +99,7 @@ def generate(
         pdl_file: Program to execute.
         log_file: File where the log is written. If `None`, use `log.txt`.
         initial_scope: Environment defining the variables in scope to execute the program.
-        output_mode: Format in which the execution trace must be produced.
+        output_trace: Format in which the execution trace must be produced.
         output_file: File to save the execution trace.
     """
     if log_file is None:
@@ -112,8 +112,8 @@ def generate(
         with open(log_file, "w", encoding="utf-8") as log_fp:
             for line in state.log:
                 log_fp.write(line)
-        if output_mode is not None and trace is not None:
-            write_trace(pdl_file, output_mode, output_file, trace)
+        if output_trace is not None and trace is not None:
+            write_trace(pdl_file, output_trace, output_file, trace)
     except PDLParseError as e:
         print("\n".join(e.msg))