From 355bf42e5181b88bef1bb26436434b87c6ea1d7f Mon Sep 17 00:00:00 2001
From: Luca Beurer-Kellner <lucabeurerkellner@gmail.com>
Date: Thu, 27 Mar 2025 13:12:41 +0100
Subject: [PATCH] documentation on stream instrumentation

---
 gateway/integrations/guardails.py | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/gateway/integrations/guardails.py b/gateway/integrations/guardails.py
index 6067dbc..02bee49 100644
--- a/gateway/integrations/guardails.py
+++ b/gateway/integrations/guardails.py
@@ -118,6 +118,29 @@ class StreamInstrumentor:
     """
     A class to instrument async iterables with hooks for processing
     chunks, before processing, and on completion.
+
+    Use `@on('chunk')`, `@on('start')`, and `@on('end')` decorators
+    to register listeners for different events.
+
+    Listeners can simply process data, or alternatively raise a designated
+    YieldException to yield additional values or stop the stream.
+
+    Example usage:
+
+    ```
+    instrumentor = StreamInstrumentor()
+
+    @instrumentor.on('chunk')
+    async def process_chunk(chunk):
+        # Process the chunk
+        print(f"Processing chunk: {chunk}")
+
+        if some_condition:
+            # Yield an additional value that will be interleaved in the stream
+            # Pass `end_of_stream=True` to stop the stream after yielding
+            # Pass `end_of_stream=False` to continue the stream after the interleaved value
+            raise YieldException("Extra value", end_of_stream=True)
+    ```
     """
 
     def __init__(self):