Merge pull request #20 from The-AI-Alliance/deanw/misc-cleanups

Minor refinements to the READMEs. Missing dependency in requirements.txt

Author: deanwampler

README.md

@@ -1,13 +1,23 @@
 # Llama Stack Example Apps
 
-This repo contains a growing suite of example applications for <a href="https://github.com/meta-llama/llama-stack">Llama Stack</a> that demonstrate various stack features and common application patterns:
+This repo contains a growing suite of example applications for <a href="https://github.com/meta-llama/llama-stack">Llama Stack</a> that demonstrate various stack features and common application patterns.
+
+See the corresponding README for each example for more information. Here we summarize the examples.
+
+## Application Examples
+
+These applications are in the [`apps`](apps/) directory.
 
 * [`01-chatbot`](apps/01-chatbot): A getting-start chatbot app, which shows how to build and deploy Llama Stack applications. It includes two different UI options and inference with an [ollama](https://ollama.com)-hosted [Llama 3](https://www.llama.com/models/llama-3/) model.
-* [`02-deep-research`](apps/02-deep-research/README.md): A _deep research_ app (under development), which illustrates an emerging, common application pattern for AI. The user asks for detailed information about a topic, for example the market performance and financials for a publicly-traded company, agents find relevant data from diverse sources, and finally an LLM digests the information retrieved and prepares a report. This example will demonstrate Llama Stack support for agent-based application development, including the use of protocols like [MCP](https://modelcontextprotocol.io/introduction).
+* [`02-deep-research`](apps/02-deep-research): A _deep research_ app (under development), which illustrates an emerging, common application pattern for AI. The user asks for detailed information about a topic, for example the market performance and financials for a publicly-traded company, agents find relevant data from diverse sources, and finally an LLM digests the information retrieved and prepares a report. This example will demonstrate Llama Stack support for agent-based application development, including the use of protocols like [MCP](https://modelcontextprotocol.io/introduction).
+
+## Notebook Examples
+
+These examples use Jupyter notebooks to illustrate their concepts. They are located in the [`notebooks`](notebooks/) directory.
 
-See the READMEs for each example for more information.
+* [`01-responses`](notebooks/01-responses): This notebook demonstrates how to use the Llama Stack _Responses_ API for simple inference, Retrieval-Augmented Generation (RAG), and Model Context Protocol (MCP) tool calling.
 
 > [!NOTE]
-> **Please join us!** We welcome [PRs](https://github.com/The-AI-Alliance/llama-stack-usecase1/pulls) and suggestions as [issues](https://github.com/The-AI-Alliance/llama-stack-usecase1/issues). Use the [discussions](https://github.com/The-AI-Alliance/llama-stack-usecase1/discussions) for general questions and suggestions. For more information about joining this project or other AI Alliance projects, go [here](https://the-ai-alliance.github.io/contributing/). 
+> **Please join us!** We welcome new examples. You can submit them or submit improvements to the current examples using [PRs](https://github.com/The-AI-Alliance/llama-stack-usecase1/pulls), make suggestions or report bugs as [issues](https://github.com/The-AI-Alliance/llama-stack-usecase1/issues), or use the [discussions forum](https://github.com/The-AI-Alliance/llama-stack-usecase1/discussions) for general questions and suggestions. For more information about joining this project or other AI Alliance projects, go [here](https://the-ai-alliance.github.io/contributing/). The main AI Alliance website is [here](https://aialliance.org).
 >
 > If you are interested in running Llama Stack on Kubernetes or OpenShift, see [these examples from opendatahub.io](https://github.com/opendatahub-io/llama-stack-demos).

notebooks/01-responses/README.md

@@ -22,7 +22,32 @@ The Responses API provides a unified interface for AI interactions that can hand
 
 ## Instructions
 
-To see all the prerequisites for running the notebook and how to meet them, see the instructions at the start of the notebook.
+To see all the prerequisites for running the notebook and how to meet them, see the instructions at the start of the notebook. Set up a Python 3.12 environment, e.g., using Anaconda, `venv`, or similar tool. Then do the following steps in one terminal window:
+
+```shell
+# Install the dependencies:
+pip install -r requirements.txt
+# Run the Llama Stack server
+llama stack run run.yaml --image-type venv --port 8321
+```
+
+In a second window, run the National Park Service MCP server:
+
+```shell
+python nps_mcp_server.py --transport sse --port 3005 --log-level DEBUG
+```
+
+Open the notebook [`reponses-api.ipynb`](reponses-api.ipynb) using [Jupyter](https://jupyter.org/), which is not installed as part of the `requirements.txt`. You can install Jupyter Lab as follows:
+
+```shell
+pip install jupyterlab
+```
+
+Then run the lab environment and open the notebook in the left-hand side browser:
+
+```shell
+jupyter lab
+```
 
 ## What You'll Learn
 
@@ -61,17 +86,19 @@ The notebook demonstrates three main approaches to using the Responses API:
    echo $OPENAI_API_KEY  # Should show your key
    ```
 
-3. **Python version issues**: Ensure you're using Python 3.12+:
+3. **Connection Error**: You might need to change the port used for Llama Stack. Notice the URL printed in the terminal window where you are running Llama Stack. Make sure `LLAMA_STACK_URL` uses the same port number in the notebook.
+
+4. **Python version issues**: Ensure you are using Python 3.12+:
    ```bash
    python --version
    ```
 
-4. **Dependency conflicts**: Use a fresh virtual environment if you encounter package conflicts.
+5. **Dependency conflicts**: Use a fresh virtual environment if you encounter package conflicts.
 
 ## Support
 
 This notebook and README were developed with assistance from Google Gemini and Cursor using Claude Sonnet 4. For issues with:
 
-- **Llama Stack**: Check the [official documentation](https://llama-stack.readthedocs.io/)
-- **MCP Protocol**: See [Model Context Protocol docs](https://modelcontextprotocol.io/)
-- **This example**: Review the notebook cells for detailed explanations
+- **The notebook itself**: Review the notebook cells for detailed explanations that may help. Post an [issue](https://github.com/The-AI-Alliance/llama-stack-examples/issues) or open a [discussion](https://github.com/The-AI-Alliance/llama-stack-examples/discussions) if you need more help.
+- **Llama Stack**: Check the [official documentation](https://llama-stack.readthedocs.io/).
+- **MCP Protocol**: See [Model Context Protocol docs](https://modelcontextprotocol.io/).

notebooks/01-responses/requirements.txt

@@ -164,6 +164,7 @@ threadpoolctl==3.6.0
 tiktoken==0.9.0
 tokenizers==0.21.4
 torch==2.8.0
+torchtune=0.6.1
 tornado==6.5.1
 tqdm==4.67.1
 traitlets==5.14.3

notebooks/01-responses/responses-api.ipynb

@@ -4,7 +4,7 @@ This directory contains notebooks and example code for demonstrating various Lla
 
 ## Current Examples
 
-### [01-responses/](./01-responses/)
+### [01-responses/](01-responses/)
 
 An introduction to the Llama Stack Responses API, including: