add examples docs

README.md

@@ -19,11 +19,11 @@
 - [X] **[Core](packages/ragbits-core)** - Fundamental tools for working with prompts and LLMs.
 - [X] **[Document Search](packages/ragbits-document-search)** - Handles vector search to retrieve relevant documents.
 - [X] **[CLI](packages/ragbits-cli)** - The `ragbits` shell command, enabling tools such as GUI prompt management.
+- [x] **[Guardrails](packages/ragbits-guardrails)** - Ensures response safety and relevance.
+- [x] **[Evaluation](packages/ragbits-evaluate)** - Unified evaluation framework for Ragbits components.
 - [ ] **Flow Controls** - Manages multi-stage chat flows for performing advanced actions *(coming soon)*.
 - [ ] **Structured Querying** - Queries structured data sources in a predictable manner *(coming soon)*.
 - [ ] **Caching** - Adds a caching layer to reduce costs and response times *(coming soon)*.
-- [ ] **Observability & Audit** - Tracks user queries and events for easier troubleshooting *(coming soon)*.
-- [ ] **Guardrails** - Ensures response safety and relevance *(coming soon)*.
 
 ## Installation
 

examples/document-search/basic.py

@@ -1,10 +1,35 @@
+"""
+Ragbits Document Search Example: Basic
+
+This example demonstrates how to use the `DocumentSearch` class to search for documents with a minimal setup.
+We will use the `LiteLLMEmbeddings` class to embed the documents and the query and the `InMemoryVectorStore` class
+to store the embeddings.
+
+The script performs the following steps:
+
+    1. Create a list of documents.
+    2. Initialize the `LiteLLMEmbeddings` class with the OpenAI `text-embedding-3-small` embedding model.
+    3. Initialize the `InMemoryVectorStore` class.
+    4. Initialize the `DocumentSearch` class with the embedder and the vector store.
+    5. Ingest the documents into the `DocumentSearch` instance.
+    6. Search for documents using a query.
+    7. Print the search results.
+
+To run the script, execute the following command:
+
+    ```bash
+    uv run examples/document-search/basic.py
+    ```
+"""
+
 # /// script
 # requires-python = ">=3.10"
 # dependencies = [
 #     "ragbits-document-search",
 #     "ragbits-core[litellm]",
 # ]
 # ///
+
 import asyncio
 
 from ragbits.core.embeddings.litellm import LiteLLMEmbeddings

examples/document-search/chroma.py

@@ -1,10 +1,36 @@
+"""
+Ragbits Document Search Example: Chroma
+
+This example demonstrates how to use the `DocumentSearch` class to search for documents with a more advanced setup.
+We will use the `LiteLLMEmbeddings` class to embed the documents and the query, the `ChromaVectorStore` class to store
+the embeddings.
+
+The script performs the following steps:
+
+    1. Create a list of documents.
+    2. Initialize the `LiteLLMEmbeddings` class with the OpenAI `text-embedding-3-small` embedding model.
+    3. Initialize the `ChromaVectorStore` class with a `PersistentClient` instance and an index name.
+    4. Initialize the `DocumentSearch` class with the embedder and the vector store.
+    5. Ingest the documents into the `DocumentSearch` instance.
+    6. List all documents in the vector store.
+    7. Search for documents using a query.
+    8. Print the list of all documents and the search results.
+
+To run the script, execute the following command:
+
+    ```bash
+    uv run examples/document-search/chroma.py
+    ```
+"""
+
 # /// script
 # requires-python = ">=3.10"
 # dependencies = [
 #     "ragbits-document-search",
 #     "ragbits-core[chroma,litellm]",
 # ]
 # ///
+
 import asyncio
 
 from chromadb import PersistentClient

examples/document-search/chroma_otel.py

@@ -1,10 +1,54 @@
+"""
+Ragbits Document Search Example: Chroma x OpenTelemetry
+
+This example demonstrates how to use the `DocumentSearch` class to search for documents with a more advanced setup.
+We will use the `LiteLLMEmbeddings` class to embed the documents and the query, the `ChromaVectorStore` class to store
+the embeddings, and the OpenTelemetry SDK to trace the operations.
+
+The script performs the following steps:
+
+    1. Create a list of documents.
+    2. Initialize the `LiteLLMEmbeddings` class with the OpenAI `text-embedding-3-small` embedding model.
+    3. Initialize the `ChromaVectorStore` class with a `PersistentClient` instance and an index name.
+    4. Initialize the `DocumentSearch` class with the embedder and the vector store.
+    5. Ingest the documents into the `DocumentSearch` instance.
+    6. List all documents in the vector store.
+    7. Search for documents using a query.
+    8. Print the list of all documents and the search results.
+
+To run the script, execute the following command:
+
+    ```bash
+    uv run examples/document-search/chroma_otel.py
+    ```
+
+The script exports traces to the local OTLP collector running on `http://localhost:4317`. To visualize the traces,
+you can use Jeager. The recommended way to run it is using the official Docker image:
+
+    1. Run Jaeger Docker container:
+
+        ```bash
+        docker run -d --rm --name jaeger \
+            -p 16686:16686 \
+            -p 4317:4317 \
+            jaegertracing/all-in-one:1.62.0
+        ```
+
+    2. Open the Jaeger UI in your browser:
+
+        ```
+        http://localhost:16686
+        ```
+"""
+
 # /// script
 # requires-python = ">=3.10"
 # dependencies = [
 #     "ragbits-document-search",
 #     "ragbits-core[chroma,litellm,otel]",
 # ]
 # ///
+
 import asyncio
 
 from chromadb import PersistentClient

examples/document-search/from_config.py

@@ -1,10 +1,33 @@
+"""
+Ragbits Document Search Example: DocumentSearch from Config
+
+This example demonstrates how to use the `DocumentSearch` class to search for documents with a more advanced setup.
+We will use the `LiteLLMEmbeddings` class to embed the documents and the query, the `ChromaVectorStore` class to store
+the embeddings, and the `LiteLLMReranker` class to rerank the search results. We will also use the `LLMQueryRephraser`
+class to rephrase the query.
+
+The script performs the following steps:
+
+        1. Create a list of documents.
+        2. Initialize the `DocumentSearch` class with the predefined configuration.
+        3. Ingest the documents into the `DocumentSearch` instance.
+        4. Search for documents using a query.
+        5. Print the search results.
+
+To run the script, execute the following command:
+
+    ```bash
+    uv run examples/document-search/from_config.py
+    ```
+"""
 # /// script
 # requires-python = ">=3.10"
 # dependencies = [
 #     "ragbits-document-search",
 #     "ragbits-core[chroma,litellm]",
 # ]
 # ///
+
 import asyncio
 
 from ragbits.document_search import DocumentSearch