Skip to content

Commit d42f070

Browse files
authored
Removed API block (#86)
* removed API Block Signed-off-by: Mandana Vaziri <[email protected]> * cleanup Signed-off-by: Mandana Vaziri <[email protected]> --------- Signed-off-by: Mandana Vaziri <[email protected]>
1 parent 360b9bb commit d42f070

18 files changed

+213
-1620
lines changed

README.md

+12-14
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,13 @@ PDL provides the following features:
1111
- Control structures: variable definitions and use, conditionals, loops, functions
1212
- Ability to read from files, including JSON data
1313
- 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
1515
- Type checking input and output of model calls
1616
- Python SDK
1717
- Support for chat APIs and chat templates
1818
- Live Document visualization
1919

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...).
2121

2222
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).
2323

@@ -53,7 +53,7 @@ For more information, see [documentation](https://docs.litellm.ai/docs/providers
5353
To run the interpreter:
5454

5555
```
56-
pdl <path/to/example.yaml>
56+
pdl-local <path/to/example.yaml>
5757
```
5858

5959
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.
6666
To change the log filename, you can pass it to the interpreter as follows:
6767

6868
```
69-
pdl --log <my-logfile> <my-example>
69+
pdl-local --log <my-logfile> <my-example>
7070
```
7171

7272
We can also pass initial data to the interpreter to populate variables used in a PDL program, as follows:
7373

7474
```
75-
pdl --data <JSON-or-YAML-data> <my-example>
75+
pdl-local --data <JSON-or-YAML-data> <my-example>
7676
```
7777

7878
This can also be done by passing a JSON or YAML file:
7979

8080
```
81-
pdl --data-file <JSON-or-YAML-file> <my-example>
81+
pdl-local --data-file <JSON-or-YAML-file> <my-example>
8282
```
8383

8484
The interpreter can also output a trace file that is used by the Live Document visualization tool (see [Live Document](#live_document)):
8585

8686
```
87-
pdl --trace <file.json> <my-example>
87+
pdl-local --trace <file.json> <my-example>
8888
```
8989

9090
For more information:
9191
```
92-
pdl --help
92+
pdl-local --help
9393
```
9494

9595
## Overview
@@ -113,7 +113,7 @@ The `description` field is a description for the program. Field `text` contains
113113
When we execute this program using the PDL interpreter:
114114

115115
```
116-
pdl examples/hello/hello.pdl
116+
pdl-local examples/hello/hello.pdl
117117
```
118118

119119
we obtain the following document:
@@ -122,14 +122,14 @@ we obtain the following document:
122122
Hello, World!
123123
```
124124

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).
126126

127127
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.
128128

129129
The PDL interpreter can also stream the background conversation instead of the result:
130130

131131
```
132-
pdl --stream background examples/hello/hello.pdl
132+
pdl-local --stream background examples/hello/hello.pdl
133133
```
134134

135135
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.
381381
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.
382382

383383

384-
## Additional Notes and Future Work
384+
## Additional Notes
385385

386386
When using Granite models on Watsonx, we use the following defaults for model parameters:
387387
- `decoding_method`: `greedy`
@@ -394,8 +394,6 @@ When using Granite models on Watsonx, we use the following defaults for model pa
394394
- `top_p`: 0.85
395395
- `top_k`: 50
396396

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-
399397
For a complete list of issues see [here](https://github.com/IBM/prompt-declaration-language/issues).
400398

401399

docs/README.md

+15-17
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,13 @@ PDL provides the following features:
1616
- Control structures: variable definitions and use, conditionals, loops, functions
1717
- Ability to read from files, including JSON data
1818
- 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
2020
- Type checking input and output of model calls
2121
- Python SDK
2222
- Support for chat APIs and chat templates
2323
- Live Document visualization
2424

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...).
2626

2727
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).
2828

@@ -58,7 +58,7 @@ For more information, see [documentation](https://docs.litellm.ai/docs/providers
5858
To run the interpreter:
5959

6060
```
61-
pdl <path/to/example.yaml>
61+
pdl-local <path/to/example.yaml>
6262
```
6363

6464
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.
7171
To change the log filename, you can pass it to the interpreter as follows:
7272

7373
```
74-
pdl --log <my-logfile> <my-example>
74+
pdl-local --log <my-logfile> <my-example>
7575
```
7676

7777
We can also pass initial data to the interpreter to populate variables used in a PDL program, as follows:
7878

7979
```
80-
pdl --data <JSON-or-YAML-data> <my-example>
80+
pdl-local --data <JSON-or-YAML-data> <my-example>
8181
```
8282

8383
This can also be done by passing a JSON or YAML file:
8484

8585
```
86-
pdl --data-file <JSON-or-YAML-file> <my-example>
86+
pdl-local --data-file <JSON-or-YAML-file> <my-example>
8787
```
8888

8989
The interpreter can also output a trace file that is used by the Live Document visualization tool (see [Live Document](#live_document)):
9090

9191
```
92-
pdl --trace <file.json> <my-example>
92+
pdl-local --trace <file.json> <my-example>
9393
```
9494

9595
For more information:
9696
```
97-
pdl --help
97+
pdl-local --help
9898
```
9999

100100
## Overview
@@ -113,12 +113,12 @@ text:
113113
include_stop_sequence: true
114114
```
115115
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`).
117117

118118
When we execute this program using the PDL interpreter:
119119

120120
```
121-
pdl examples/hello/hello.pdl
121+
pdl-local examples/hello/hello.pdl
122122
```
123123

124124
we obtain the following document:
@@ -127,14 +127,14 @@ we obtain the following document:
127127
Hello, World!
128128
```
129129

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).
131131

132132
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.
133133

134134
The PDL interpreter can also stream the background conversation instead of the result:
135135

136136
```
137-
pdl --stream background examples/hello/hello.pdl
137+
pdl-local --stream background examples/hello/hello.pdl
138138
```
139139

140140
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`.
218218

219219
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`.
220220

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.
222222

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:
224224

225225
```
226226
@@ -386,7 +386,7 @@ in the right pane.
386386
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.
387387

388388

389-
## Additional Notes and Future Work
389+
## Additional Notes
390390

391391
When using Granite models on Watsonx, we use the following defaults for model parameters:
392392
- `decoding_method`: `greedy`
@@ -399,8 +399,6 @@ When using Granite models on Watsonx, we use the following defaults for model pa
399399
- `top_p`: 0.85
400400
- `top_k`: 50
401401

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-
404402
For a complete list of issues see [here](https://github.com/IBM/prompt-declaration-language/issues).
405403

406404

docs/tutorial.md

+12-8
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ This program has a `description` field, which contains a title. The `description
2121
To render the program into an actual document, we have a PDL interpreter that can be invoked as follows:
2222

2323
```
24-
pdl examples/tutorial/simple_program.pdl
24+
pdl-local examples/tutorial/simple_program.pdl
2525
```
2626

2727
This results in the following output:
@@ -364,7 +364,7 @@ Hello, r!
364364

365365
## Calling REST APIs
366366

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)):
368368

369369
```yaml
370370
description: Using a weather API and LLM to make a small weather app
@@ -390,18 +390,22 @@ text:
390390
include_stop_sequence: false
391391
def: LOCATION
392392
contribute: []
393-
- api: https
394-
url: https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q=
395-
input: '{{ LOCATION }}'
393+
- lan: python
394+
code: |
395+
import requests
396+
response = requests.get('https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q={{ LOCATION }}')
397+
result = response.content
396398
def: WEATHER
399+
parser: json
397400
contribute: []
401+
398402
- model: watsonx/ibm/granite-34b-code-instruct
399403
input: |
400-
Explain the weather from the following JSON.
401-
`{{ WEATHER }}`
404+
Explain the weather from the following JSON:
405+
{{ WEATHER }}
402406
```
403407

404-
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.
405409

406410

407411
## Data Block

examples/demo/3-weather.pdl

+9-6
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,17 @@ text:
2121
include_stop_sequence: false
2222
def: LOCATION
2323
contribute: []
24-
- api: https
25-
url: https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q=
26-
input: '{{ LOCATION }}'
24+
- lan: python
25+
code: |
26+
import requests
27+
response = requests.get('https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q={{ LOCATION }}')
28+
result = response.content
2729
def: WEATHER
30+
parser: json
2831
contribute: []
32+
2933
- model: watsonx/ibm/granite-34b-code-instruct
3034
input: |
31-
Explain the weather from the following JSON.
32-
`{{ WEATHER }}`
33-
35+
Explain the weather from the following JSON:
36+
{{ WEATHER }}
3437

examples/prompt_library/tools.pdl

+5-3
Original file line numberDiff line numberDiff line change
@@ -74,10 +74,12 @@ defs:
7474
function:
7575
subject: str
7676
return:
77-
- api: https
78-
url: https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q=
79-
input: "{{ subject }}"
77+
- lan: python
8078
contribute: []
79+
code: |
80+
import requests
81+
response = requests.get('https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q={{ subject }}')
82+
result = response.content
8183

8284
default_tools:
8385
data:

examples/tutorial/calling_apis.pdl

+9-5
Original file line numberDiff line numberDiff line change
@@ -21,12 +21,16 @@ text:
2121
include_stop_sequence: false
2222
def: LOCATION
2323
contribute: []
24-
- api: https
25-
url: https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q=
26-
input: '{{ LOCATION }}'
24+
- lan: python
25+
code: |
26+
import requests
27+
response = requests.get('https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q={{ LOCATION }}')
28+
result = response.content
2729
def: WEATHER
30+
parser: json
2831
contribute: []
32+
2933
- model: watsonx/ibm/granite-34b-code-instruct
3034
input: |
31-
Explain the weather from the following JSON.
32-
`{{ WEATHER }}`
35+
Explain the weather from the following JSON:
36+
{{ WEATHER }}

examples/weather/weather.pdl

+9-5
Original file line numberDiff line numberDiff line change
@@ -21,14 +21,18 @@ text:
2121
include_stop_sequence: false
2222
def: LOCATION
2323
contribute: []
24-
- api: https
25-
url: https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q=
26-
input: '{{ LOCATION }}'
24+
- lan: python
25+
code: |
26+
import requests
27+
response = requests.get('https://api.weatherapi.com/v1/current.json?key=cf601276764642cb96224947230712&q={{ LOCATION }}')
28+
result = response.content
2729
def: WEATHER
30+
parser: json
2831
contribute: []
32+
2933
- model: watsonx/ibm/granite-34b-code-instruct
3034
input: |
31-
Explain the weather from the following JSON.
32-
`{{ WEATHER }}`
35+
Explain the weather from the following JSON:
36+
{{ WEATHER }}
3337

3438

0 commit comments

Comments
 (0)