From c745012fa2dab96c6111ca84b16725abe84306da Mon Sep 17 00:00:00 2001 From: Mandana Vaziri Date: Sat, 31 Aug 2024 05:43:42 -0400 Subject: [PATCH] changed mode to trace, added documentation for Live Document (#5) Signed-off-by: Mandana Vaziri --- README.md | 27 ++++++++++++++++++++++++--- docs/README.md | 13 +++++++++++++ docs/tutorial.md | 15 +++++++++++++++ pdl/pdl.py | 6 ++++-- pdl/pdl_interpreter.py | 8 ++++---- 5 files changed, 60 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0f0fd7dc..d3b4bdb2 100644 --- a/README.md +++ b/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 +python -m pdl.pdl --log ``` We can also pass initial data to the interpreter to populate variables used in a PDL program, as follows: ``` -python3 -m pdl.pdl --data +python -m pdl.pdl --data ``` This can also be done by passing a JSON or YAML file: ``` -python3 -m pdl.pdl --data_file +python -m pdl.pdl --data_file ``` +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 +``` + + ## 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 +``` + +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 diff --git a/docs/README.md b/docs/README.md index 216c073c..8a2b6d0e 100644 --- a/docs/README.md +++ b/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 +``` + +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 diff --git a/docs/tutorial.md b/docs/tutorial.md index e3478559..18897222 100644 --- a/docs/tutorial.md +++ b/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 +``` + +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. + + diff --git a/pdl/pdl.py b/pdl/pdl.py index c52c04ba..babee7ff 100644 --- a/pdl/pdl.py +++ b/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, ) diff --git a/pdl/pdl_interpreter.py b/pdl/pdl_interpreter.py index 40ae7a6d..126109d1 100644 --- a/pdl/pdl_interpreter.py +++ b/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))