readme changes (#605)

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

Author: vazirim

README.md

@@ -46,6 +46,8 @@ and run it:
 pdl <path/to/example.pdl>
 ```
 
+For more information on the `pdl` CLI see [here](https://ibm.github.io/prompt-declaration-language/).
+
 ## Key Features
 
 - **LLM Integration**: Compatible with any LLM, including IBM watsonx
@@ -65,8 +67,9 @@ pdl <path/to/example.pdl>
 ## Documentation
 
 - [Documentation](https://ibm.github.io/prompt-declaration-language/)
-- [API References](https://ibm.github.io/prompt-declaration-language/api_reference/)
 - [Tutorial](https://ibm.github.io/prompt-declaration-language/tutorial/)
+- [API References](https://ibm.github.io/prompt-declaration-language/api_reference/)
+
 
 ### Quick Reference
 
@@ -90,11 +93,13 @@ pip install 'prompt-declaration-language[examples]'
 ### Environment Setup
 
 You can run PDL with LLM models in local using [Ollama](https://ollama.com), or other cloud service.
+See [here](https://ibm.github.io/prompt-declaration-language/tutorial/#using-ollama-models) for 
+instructions on how to install an Ollama model locally.
 
 If you use watsonx:
 ```bash
-export WATSONX_URL="https://{region}.ml.cloud.ibm.com"
-export WATSONX_APIKEY="your-api-key"
+export WX_URL="https://{region}.ml.cloud.ibm.com"
+export WX_API_KEY="your-api-key"
 export WATSONX_PROJECT_ID="your-project-id"
 ```
 
@@ -105,6 +110,7 @@ export REPLICATE_API_TOKEN="your-token"
 
 ### IDE Configuration 
 
+Install the `YAML Language Support by Red Hat` extension in VSCode.
 VSCode setup for syntax highlighting and validation:
 
 ```json
@@ -128,13 +134,13 @@ In this example we use external content _data.yaml_ and watsonx as an LLM provid
 ```yaml
 description: Template with variables
 defs:
-  USER_INPUT:
-    read: ../examples/code/data.yaml
+  user_input:
+    read: ../code/data.yaml
     parser: yaml
 text:
 - model: watsonx/ibm/granite-34b-code-instruct
   input: |
-    Process this input: ${USER_INPUT}
+    Process this input: ${user_input}
     Format the output as JSON.
 ```
 
@@ -174,20 +180,14 @@ text:
   until: ${ user_input == '/bye'}
 ```
 
-## Debugging Tools
-
-### Log Inspection
-```bash
-pdl --log <my-logfile> <my-example.pdl>
-```
 
-### Trace Generation and Live Document Visualization
+## Trace Generation and Live Document Visualization
 
 ```bash
 pdl --trace <file.json> <my-example.pdl> 
 ```
 
-Upload trace files to the [Live Document Viewer](https://ibm.github.io/prompt-declaration-language/viewer/) for visual debugging.
+Upload trace files to the [Live Document Viewer](https://ibm.github.io/prompt-declaration-language/viewer/) for visual debugging, trace exploration, and live programming.
 
 
 ## Contributing

docs/README.md

@@ -49,16 +49,19 @@ To install the dependencies for development of PDL and execute all the example,
 pip install 'prompt-declaration-language[examples]'
 ```
 
-Most examples in this repository use IBM Granite models on [Replicate](https://replicate.com/).
-In order to run these examples, you need to create a free account
+You can run PDL with LLM models in local using [Ollama](https://ollama.com), or other cloud service.
+See [here](https://ibm.github.io/prompt-declaration-language/tutorial/#using-ollama-models) for 
+instructions on how to install an Ollama model locally.
+
+Most examples in this repository use IBM Granite models on [Ollama](https://ollama.com) and some are on [Replicate](https://replicate.com/). In order to run these examples, you need to create a free account
 on Replicate, get an API key and store it in the environment variable:
 
-- `REPLICATE_API_KEY`
+- `REPLICATE_API_TOKEN`
 
 In order to use foundation models hosted on [watsonx](https://www.ibm.com/watsonx) via LiteLLM, you need a watsonx account (a free plan is available) and set up the following environment variables:
 
-- `WATSONX_URL`, the API url (set to `https://{region}.ml.cloud.ibm.com`) of your watsonx instance. The region can be found by clicking in the upper right corner of the watsonx dashboard (for example a valid region is `us-south` ot `eu-gb`).
-- `WATSONX_APIKEY`, the API key (see information on [key creation](https://cloud.ibm.com/docs/account?topic=account-userapikey&interface=ui#create_user_key))
+- `WX_URL`, the API url (set to `https://{region}.ml.cloud.ibm.com`) of your watsonx instance. The region can be found by clicking in the upper right corner of the watsonx dashboard (for example a valid region is `us-south` ot `eu-gb`).
+- `WX_API_KEY`, the API key (see information on [key creation](https://cloud.ibm.com/docs/account?topic=account-userapikey&interface=ui#create_user_key))
 - `WATSONX_PROJECT_ID`, the project hosting the resources (see information about [project creation](https://www.ibm.com/docs/en/watsonx/saas?topic=projects-creating-project) and [finding project ID](https://dataplatform.cloud.ibm.com/docs/content/wsj/analyze-data/fm-project-id.html?context=wx)).
 
 For more information, see [documentation](https://docs.litellm.ai/docs/providers/watsonx).
@@ -93,13 +96,8 @@ and all code is executed locally. To use the `--sandbox` flag, you need to have
 The interpreter prints out a log by default in the file `log.txt`. This log contains the details of inputs and outputs to every block in the program. It is useful to examine this file when the program is behaving differently than expected. The log displays the exact prompts submitted to models by LiteLLM (after applying chat templates), which can be
 useful for debugging.
 
-To change the log filename, you can pass it to the interpreter as follows:
-
-```
-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:
+We can pass initial data to the interpreter to populate variables used in a PDL program, as follows:
 
 ```
 pdl --data <JSON-or-YAML-data> <my-example>