Add specific README for events example (#141)

Author: mpangrazzi

examples/pipeline_wrappers/open_webui_agent_events/README.md

@@ -0,0 +1,90 @@
+# Open WebUI Agent Events Example
+
+This example demonstrates how to enhance the chat experience in [Open WebUI](https://github.com/open-webui/open-webui) by emitting **events** from a Haystack `Agent` pipeline executed through **Hayhooks**.
+
+The heart of the example is `pipeline_wrapper.py`, which
+
+1. Instantiates a Haystack `Agent` backed by an `OpenAIChatGenerator`.
+2. Implements `run_chat_completion_async` that yields an **async generator** mixing
+   streaming chunks with Open WebUI event objects.
+3. Sends two `status` events – one when the pipeline starts and another when it
+   finishes.
+4. Emits an HTML-like `<details>` block with extra information once the run is
+   complete.
+
+When you invoke the pipeline from Open WebUI you will see:
+
+* A "Running the pipeline!" banner while the agent thinks.
+* The answer streamed token by token.
+* A "Pipeline completed!" success banner.
+* An expandable section labelled *Pipeline completed!* containing additional
+  details.
+
+## Folder structure
+
+```text
+pipeline_wrapper.py        # Pipeline implementation
+README.md                  # You are reading it
+```
+
+No additional dependencies are required besides `hayhooks` (which already pulls
+Haystack).
+
+## Quick start
+
+Create and activate a virtual environment (optional but recommended):
+
+```shell
+python -m venv .venv
+source .venv/bin/activate
+```
+
+Install Hayhooks:
+
+```shell
+pip install hayhooks
+```
+
+Launch Hayhooks:
+
+```shell
+hayhooks run
+# The server will listen on http://localhost:1416
+```
+
+Deploy the pipeline wrapper:
+
+```shell
+hayhooks pipeline deploy-files -n agent_events .
+```
+
+Open *Open WebUI* → *Settings* → *Connections* and add a **Remote Hayhooks
+server** pointing to `http://localhost:1416` (no API key is needed).
+
+Start a new chat, select the *agent_events* pipeline and ask any question.
+
+## Supported Open WebUI events
+
+Hayhooks exposes convenience helpers in `hayhooks.open_webui` to build all event
+kinds supported by Open WebUI. You can yield these objects (or plain strings)
+from your pipeline generator to control the UI in real time.
+
+| Helper function | `type` value | Purpose / UI effect |
+|-----------------|--------------|------------------------------------------------|
+| `create_status_event` | `status` | Show progress indicator (`description`, `done`, `hidden`). |
+| `create_chat_completion_event` | `chat:completion` | Send a full chat-completion payload (usually not needed manually). |
+| `create_message_event` | `message` | Append content to the current assistant message. |
+| `create_replace_event` | `replace` | Replace the entire assistant message content. |
+| `create_source_event` | `source` | Attach citations, code results or other rich blocks. |
+| `create_notification_event` | `notification` | Display toast notifications (`info`, `success`, `warning`, `error`). |
+| `create_details_tag`* | *(string)* | Render an expandable `<details>` block (not a real event). |
+
+\* `create_details_tag` returns raw markup – Open WebUI recognises it and adds a
+collapsible section to the chat.
+
+For a deeper explanation of every event see the official
+[Open WebUI event documentation](https://docs.openwebui.com/features/plugin/events).
+
+---
+
+Feel free to extend the wrapper and experiment with other event types!