Adds validation for the examples

.github/workflows/python-package.yml

@@ -37,3 +37,16 @@ jobs:
       - name: Run tests
         run: |
           python -m pytest tests
+
+  validate-examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          python -m pip install -e ".[tests]"
+      - name: Validate examples
+        working-directory: ./examples
+        run: |
+          python -m pytest validate_examples.py

README.md

@@ -30,7 +30,7 @@ environment variable to be set, but you can still see how it works if you don't
 Next, start coding / running examples:
 
 ```bash
-git clone https://github.com/dagworks-inc/burr && cd burr/examples/counter
+git clone https://github.com/dagworks-inc/burr && cd burr/examples/hello-world-counter
 python application.py
 ```
 You'll see the counter example running in the terminal, along with the trace being tracked in the UI.

burr/tracking/server/examples/chatbot.py

@@ -1,12 +1,16 @@
 import functools
+import importlib
 from typing import List, Literal
 
 import pydantic
 from fastapi import FastAPI
 from starlette.requests import Request
 
 from burr.core import Application
-from burr.examples.gpt import application as chat_application
+
+chat_application = importlib.import_module(
+    "burr.examples.multi-modal-chatbot.application"
+)  # noqa: F401
 
 
 class ChatItem(pydantic.BaseModel):
@@ -17,7 +21,7 @@ class ChatItem(pydantic.BaseModel):
 
 @functools.lru_cache(maxsize=128)
 def _get_application(project_id: str, app_id: str) -> Application:
-    app = chat_application.application(use_hamilton=False, app_id=app_id, project_id=project_id)
+    app = chat_application.application(app_id=app_id, project_id=project_id)
     return app
 
 
@@ -45,7 +49,7 @@ async def create_new_application(request: Request, project_id: str, app_id: str)
     In a better chatbot you'd want to either have the frontend store this and create on demand or return
     the actual application model"""
     # side-effect creates the logging so it exists
-    chat_application.application(use_hamilton=False, app_id=app_id, project_id=project_id)
+    chat_application.application(app_id=app_id, project_id=project_id)
     return app_id  # just return it for now
 
 

docs/contributing/contributing.rst

@@ -22,6 +22,18 @@ Please:
 #. Ensure all new features have tests
 #. Add documentation for new features
 
+Examples
+--------
+
+All examples must have the following files:
+1. A ``README.md`` file that describes the example -- this should follow the pattern of the others
+2. A ``requirements.txt`` file that lists the dependencies for the example
+3. An ``application.py`` file whose mainline runs a simple version of the example + generates the DAG to
+4. A ``statemachine.png`` file that shows the DAG for the example
+3. A `notebook.ipynb` file that uses the example in a
+
+The ``notebook.ipynb`` can import stuff from the ``application.py``, or redefine it as an example. If you have something
+that does not fit this, or is a prototype but you want to push it in, you can fit in under the ``half-baked`` directory.
 
 ---------------
 Developer notes

examples/README.md

@@ -0,0 +1,32 @@
+# Examples
+
+This contains a series of examples. Each example is meant to demonostrate a feature/use-case of the Burr library.
+
+Each example contains:
+1. A `README.md` file that explains the example (what its teaching/how it works)
+2. A `application.py` file that contains the code for the example. This will have a function `application` that creates the example, and a mainline that demonstrates it.
+3. A `requirements.txt` file that contains the dependencies for the example
+4. A `notebook.ipynb` file that contains the example in a Jupyter notebook
+5. A `statemachine.png` file that contains the graphical representation of the state machine
+6. A `__init__.py` file that allows the example to be imported as a module
+
+You can run any example with the following commands:
+
+```python
+pip install -r examples/<example>/requirements.txt # use your favorite package manager/venv tool
+python examples/<example>/application.py
+```
+
+Note we have a few more in [other-examples](other-examples/), but those do not yet adhere to the same format/are as well documented.
+
+# Index
+
+- [simple-chatbot-intro](simple-chatbot-intro/) - This is a simple chatbot that shows how to use Burr to create a simple chatbot. This is a good starting point for understanding how to use Burr -- the notebook follows the original [blog post](https://blog.dagworks.io/p/burr-develop-stateful-ai-applications).
+- [conversational-rag](conversational-rag/) - This example shows how to use Burr to create a conversational RAG chatbot. This shows how to use state/prior knowledge to augment your LLM call with Burr.
+- [hello-world-counter](hello-world-counter/) - This is an example of a simple state machine, used in the docs.
+- [llm-adventure-game](llm-adventure-game/) - This is an example of a simple text-based adventure game using LLMs -- it shows how to progress through hidden states while reusing components.
+- [ml-training](ml-training/) - This is an example of a simple ML training pipeline. It shows how to use Burr to track the training of a model. This is not complete.
+- [multi-agent-collaboration](multi-agent-collaboration/) - This example shows how to use Burr to create a multi-agent collaboration. This is a clone of the following [LangGraph example](https://github.com/langchain-ai/langgraph/blob/main/examples/multi_agent/multi-agent-collaboration.ipynb).
+- [multi-modal-chatbot](multi-modal-chatbot/) - This example shows how to use Burr to create a multi-modal chatbot. This demonstrates how to use a model to delegate to other models conditionally.
+- [streaming-overview](streaming-overview/) - This example shows how we can use the streaming API to respond to return quicker results to the user and build a seamless experience
+- [tracing-and-spans](tracing-and-spans/) - This example shows how to use Burr to create a simple chatbot with additional visibility. This is a good starting point for understanding how to use Burr's tracing functionality.