You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+12-14
Original file line number
Diff line number
Diff line change
@@ -11,13 +11,13 @@ PDL provides the following features:
11
11
- Control structures: variable definitions and use, conditionals, loops, functions
12
12
- Ability to read from files, including JSON data
13
13
- Ability to call out to code. At the moment only Python is supported, but this could be any other programming language in principle
14
-
- Ability to call out to REST APIs
14
+
- Ability to call out to REST APIs with Python code
15
15
- Type checking input and output of model calls
16
16
- Python SDK
17
17
- Support for chat APIs and chat templates
18
18
- Live Document visualization
19
19
20
-
The PDL interpreter (`pdl/pdl.py`) takes a PDL program as input and renders it into a document by execution its instructions (calling out to models, code, apis, etc...).
20
+
The PDL interpreter (`pdl/pdl.py`) takes a PDL program as input and renders it into a document by execution its instructions (calling out to models, code, etc...).
21
21
22
22
See below for installation notes, followed by an [overview](#overview) of the language. A more detailed description of the language features can be found in this [tutorial](https://ibm.github.io/prompt-declaration-language/tutorial).
23
23
@@ -53,7 +53,7 @@ For more information, see [documentation](https://docs.litellm.ai/docs/providers
53
53
To run the interpreter:
54
54
55
55
```
56
-
pdl <path/to/example.yaml>
56
+
pdl-local <path/to/example.yaml>
57
57
```
58
58
59
59
The folder `examples` contains many examples of PDL programs. Several of these examples have been adapted from the LMQL [paper](https://arxiv.org/abs/2212.06094) by Beurer-Kellner et al. The examples cover a variety of prompting patterns, see [prompt-library](https://github.com/IBM/prompt-declaration-language/blob/main/examples/prompt_library) for a library of ready-to-use prompting patterns.
@@ -66,30 +66,30 @@ useful for debugging.
66
66
To change the log filename, you can pass it to the interpreter as follows:
67
67
68
68
```
69
-
pdl --log <my-logfile> <my-example>
69
+
pdl-local --log <my-logfile> <my-example>
70
70
```
71
71
72
72
We can also pass initial data to the interpreter to populate variables used in a PDL program, as follows:
73
73
74
74
```
75
-
pdl --data <JSON-or-YAML-data> <my-example>
75
+
pdl-local --data <JSON-or-YAML-data> <my-example>
76
76
```
77
77
78
78
This can also be done by passing a JSON or YAML file:
The interpreter can also output a trace file that is used by the Live Document visualization tool (see [Live Document](#live_document)):
85
85
86
86
```
87
-
pdl --trace <file.json> <my-example>
87
+
pdl-local --trace <file.json> <my-example>
88
88
```
89
89
90
90
For more information:
91
91
```
92
-
pdl --help
92
+
pdl-local --help
93
93
```
94
94
95
95
## Overview
@@ -113,7 +113,7 @@ The `description` field is a description for the program. Field `text` contains
113
113
When we execute this program using the PDL interpreter:
114
114
115
115
```
116
-
pdl examples/hello/hello.pdl
116
+
pdl-local examples/hello/hello.pdl
117
117
```
118
118
119
119
we obtain the following document:
@@ -122,14 +122,14 @@ we obtain the following document:
122
122
Hello, World!
123
123
```
124
124
125
-
where the portion `, World!` was produced by granite. In general, PDL provides blocks for calling models, Python code, as well as REST APIs and makes it easy to compose them together with control structures (sequencing, conditions, loops).
125
+
where the portion `, World!` was produced by granite. In general, PDL provides blocks for calling models, Python code, and makes it easy to compose them together with control structures (sequencing, conditions, loops).
126
126
127
127
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 what is used to make calls to LLMs via LiteLLM.
128
128
129
129
The PDL interpreter can also stream the background conversation instead of the result:
See the [tutorial](https://ibm.github.io/prompt-declaration-language/tutorial) for more information about the conversational background context and how to use roles and chat templates.
@@ -381,7 +381,7 @@ in the right pane.
381
381
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.
382
382
383
383
384
-
## Additional Notes and Future Work
384
+
## Additional Notes
385
385
386
386
When using Granite models on Watsonx, we use the following defaults for model parameters:
387
387
- `decoding_method`: `greedy`
@@ -394,8 +394,6 @@ When using Granite models on Watsonx, we use the following defaults for model pa
394
394
- `top_p`: 0.85
395
395
- `top_k`: 50
396
396
397
-
- Only simple GETs are supported for API calls currently (see example: `examples/hello/weather.json`). We plan to more fully support API calls in the future.
398
-
399
397
For a complete list of issues see [here](https://github.com/IBM/prompt-declaration-language/issues).
Copy file name to clipboardExpand all lines: docs/README.md
+15-17
Original file line number
Diff line number
Diff line change
@@ -16,13 +16,13 @@ PDL provides the following features:
16
16
- Control structures: variable definitions and use, conditionals, loops, functions
17
17
- Ability to read from files, including JSON data
18
18
- Ability to call out to code. At the moment only Python is supported, but this could be any other programming language in principle
19
-
- Ability to call out to REST APIs
19
+
- Ability to call out to REST APIs with Python code
20
20
- Type checking input and output of model calls
21
21
- Python SDK
22
22
- Support for chat APIs and chat templates
23
23
- Live Document visualization
24
24
25
-
The PDL interpreter (`pdl/pdl.py`) takes a PDL program as input and renders it into a document by execution its instructions (calling out to models, code, apis, etc...).
25
+
The PDL interpreter (`pdl/pdl.py`) takes a PDL program as input and renders it into a document by execution its instructions (calling out to models, code, etc...).
26
26
27
27
See below for installation notes, followed by an [overview](#overview) of the language. A more detailed description of the language features can be found in this [tutorial](https://ibm.github.io/prompt-declaration-language/tutorial).
28
28
@@ -58,7 +58,7 @@ For more information, see [documentation](https://docs.litellm.ai/docs/providers
58
58
To run the interpreter:
59
59
60
60
```
61
-
pdl <path/to/example.yaml>
61
+
pdl-local <path/to/example.yaml>
62
62
```
63
63
64
64
The folder `examples` contains many examples of PDL programs. Several of these examples have been adapted from the LMQL [paper](https://arxiv.org/abs/2212.06094) by Beurer-Kellner et al. The examples cover a variety of prompting patterns, see [prompt-library](https://github.com/IBM/prompt-declaration-language/blob/main/examples/prompt_library) for a library of ready-to-use prompting patterns.
@@ -71,30 +71,30 @@ useful for debugging.
71
71
To change the log filename, you can pass it to the interpreter as follows:
72
72
73
73
```
74
-
pdl --log <my-logfile> <my-example>
74
+
pdl-local --log <my-logfile> <my-example>
75
75
```
76
76
77
77
We can also pass initial data to the interpreter to populate variables used in a PDL program, as follows:
78
78
79
79
```
80
-
pdl --data <JSON-or-YAML-data> <my-example>
80
+
pdl-local --data <JSON-or-YAML-data> <my-example>
81
81
```
82
82
83
83
This can also be done by passing a JSON or YAML file:
The interpreter can also output a trace file that is used by the Live Document visualization tool (see [Live Document](#live_document)):
90
90
91
91
```
92
-
pdl --trace <file.json> <my-example>
92
+
pdl-local --trace <file.json> <my-example>
93
93
```
94
94
95
95
For more information:
96
96
```
97
-
pdl --help
97
+
pdl-local --help
98
98
```
99
99
100
100
## Overview
@@ -113,12 +113,12 @@ text:
113
113
include_stop_sequence: true
114
114
```
115
115
116
-
The `description` field is a description for the program. Field `text` contains a list of either strings or *block*s which together form the document to be produced. In this example, the document starts with the string `"Hello"` followed by a block that calls out to a model. In this case, it is model with id `watsonx/ibm/granite-34b-code-instruct` from [watsonx](https://www.ibm.com/watsonx), via LiteLLM, with the indicated parameters: the stop sequence is `!`, which is to be included in the output. The input to the model call is everything that has been produced so far in the document (here `Hello`).
116
+
The `description` field is a description for the program. Field `text` contains a list of either strings or *block*s which together form the text to be produced. In this example, the text starts with the string `"Hello"` followed by a block that calls out to a model. In this case, it is model with id `watsonx/ibm/granite-34b-code-instruct` from [watsonx](https://www.ibm.com/watsonx), via LiteLLM, with the indicated parameters: the stop sequence is `!`, which is to be included in the output. The input to the model call is everything that has been produced so far in the document (here `Hello`).
117
117
118
118
When we execute this program using the PDL interpreter:
119
119
120
120
```
121
-
pdl examples/hello/hello.pdl
121
+
pdl-local examples/hello/hello.pdl
122
122
```
123
123
124
124
we obtain the following document:
@@ -127,14 +127,14 @@ we obtain the following document:
127
127
Hello, World!
128
128
```
129
129
130
-
where the portion `, World!` was produced by granite. In general, PDL provides blocks for calling models, Python code, as well as REST APIs and makes it easy to compose them together with control structures (sequencing, conditions, loops).
130
+
where the portion `, World!` was produced by granite. In general, PDL provides blocks for calling models, Python code, and makes it easy to compose them together with control structures (sequencing, conditions, loops).
131
131
132
132
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 what is used to make calls to LLMs via LiteLLM.
133
133
134
134
The PDL interpreter can also stream the background conversation instead of the result:
See the [tutorial](https://ibm.github.io/prompt-declaration-language/tutorial) for more information about the conversational background context and how to use roles and chat templates.
@@ -218,9 +218,9 @@ assign the result to variable `CODE`.
218
218
219
219
Next we define a `text`, where the first block is simply a string and writes out the source code. This is done by accessing the variable `CODE`. The syntax `{{ var }}` means accessing the value of a variable in the scope. Since `CODE` contains YAML data, we can also access fields such as `CODE.source_code`.
220
220
221
-
The second block calls a granite model on WatsonX via LiteLLM. Here we explicitly provide an `input` field which means that we do not pass the entire document produced so far to the model, but only what is specified in this field. In this case, we specify our template by using the variable `CODE` as shown above.
221
+
The second block calls a granite model on WatsonX via LiteLLM. Here we explicitly provide an `input` field which means that we do not pass the entire text produced so far to the model, but only what is specified in this field. In this case, we specify our template by using the variable `CODE` as shown above.
222
222
223
-
When we execute this program with the PDL interpreter, we obtain the following document:
223
+
When we execute this program with the PDL interpreter, we obtain the following text:
224
224
225
225
```
226
226
@@ -386,7 +386,7 @@ in the right pane.
386
386
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.
387
387
388
388
389
-
## Additional Notes and Future Work
389
+
## Additional Notes
390
390
391
391
When using Granite models on Watsonx, we use the following defaults for model parameters:
392
392
- `decoding_method`: `greedy`
@@ -399,8 +399,6 @@ When using Granite models on Watsonx, we use the following defaults for model pa
399
399
- `top_p`: 0.85
400
400
- `top_k`: 50
401
401
402
-
- Only simple GETs are supported for API calls currently (see example: `examples/hello/weather.json`). We plan to more fully support API calls in the future.
403
-
404
402
For a complete list of issues see [here](https://github.com/IBM/prompt-declaration-language/issues).
Copy file name to clipboardExpand all lines: docs/tutorial.md
+12-8
Original file line number
Diff line number
Diff line change
@@ -21,7 +21,7 @@ This program has a `description` field, which contains a title. The `description
21
21
To render the program into an actual document, we have a PDL interpreter that can be invoked as follows:
22
22
23
23
```
24
-
pdl examples/tutorial/simple_program.pdl
24
+
pdl-local examples/tutorial/simple_program.pdl
25
25
```
26
26
27
27
This results in the following output:
@@ -364,7 +364,7 @@ Hello, r!
364
364
365
365
## Calling REST APIs
366
366
367
-
PDL programs can contain calls to REST APIs. Consider a simple weather app ([file](https://github.com/IBM/prompt-declaration-language//blob/main/examples/tutorial/calling_apis.pdl)):
367
+
PDL programs can contain calls to REST APIs with Python code. Consider a simple weather app ([file](https://github.com/IBM/prompt-declaration-language//blob/main/examples/tutorial/calling_apis.pdl)):
368
368
369
369
```yaml
370
370
description: Using a weather API and LLM to make a small weather app
In this program, we first prompt the user to enter a query about the weather in some location (assigned to variable `QUERY`). The next block is a call to a granite model with few-shot examples to extract the location, which we assign to variable `LOCATION`. The next block makes an API call. Currently we only support simple `GET` calls as shown above, but will improve this interface in the future. Here the `LOCATION` is appended to the `url`. The result is a JSON object, which may be hard to interpret for a human user. So we make a final call to an LLM to interpret the JSON in terms of weather. Notice that many blocks have `contribute` set to `[]` to hide intermediate results.
408
+
In this program, we first prompt the user to enter a query about the weather in some location (assigned to variable `QUERY`). The next block is a call to a granite model with few-shot examples to extract the location, which we assign to variable `LOCATION`. The next block makes an API call with Python. Here the `LOCATION` is appended to the `url`. The result is a JSON object, which may be hard to interpret for a human user. So we make a final call to an LLM to interpret the JSON in terms of weather. Notice that many blocks have `contribute` set to `[]` to hide intermediate results.
0 commit comments