adding components

README.md

@@ -1,8 +1,8 @@
 ---
 title: Chabo Dev
-emoji: 🌍
-colorFrom: yellow
-colorTo: green
+emoji: 🤖 [⚙️]
+colorFrom: indigo
+colorTo: purple
 sdk: gradio
 sdk_version: 5.47.2
 app_file: app.py

app.py

@@ -1,5 +1,9 @@
 import gradio as gr
-
+from vectorDB import vectordbText
+from retriever import retriverText
+from fileingestor import fileingestorText
+from generator import generatorText
+from orchestrator import orchestratorText
 # Define the HTML template for embedding an external Hugging Face Space
 # Replace <space-url> with your actual Space URLs (e.g., "https://hf.co/spaces/user/app-name")
 def embed_space(space_url: str, height: int = 800) -> gr.HTML:
@@ -16,41 +20,130 @@ def embed_space(space_url: str, height: int = 800) -> gr.HTML:
     return gr.HTML(iframe_html)
 
 # --- Define the Layout ---
-with gr.Blocks(theme=gr.themes.Monochrome()) as dashboard_app:
+with gr.Blocks(theme=gr.themes.Monochrome(), fill_width = True) as dashboard_app:
     gr.Markdown(
         """
-        # 🚀 Professional ML Dashboard Hub
-        Welcome to the central hub for all our machine learning applications.
+        # 🚀 ChaBo: Modular chatbot framework 
+        Discover the essential microservices hub designed for the modular development and efficient deployment of Retrieval-Augmented Generation (RAG) chatbots
         """
     )
     
     with gr.Tabs():
         
-        # 1. Local App Tab (Integrated Directly)
-        # This is for apps whose code is running within this main Gradio instance
-        with gr.Tab("Data Analyzer"):
-            gr.Markdown("## Local Data Analysis Tool")
-            
-            with gr.Row():
-                name_input = gr.Textbox(label="Enter Name")
-                greeting_output = gr.Textbox(label="Greeting")
-            
-            def greet(name):
-                return f"Hello, {name}! Ready to analyze your data."
-                
-            name_input.change(fn=greet, inputs=name_input, outputs=greeting_output)
-            
-        # 2. External Space 1 Tab (Embedded via iframe)
-        # Replace the placeholder URL with your actual Space URL
-        with gr.Tab("Image Classifier"):
-            gr.Markdown("## External Image Classification Space")
-            embed_space("https://hf.co/spaces/gradio/image-classification", height=700)
+        # 1. About us 
+        # This is info page
+        with gr.Tab("About ChaBo"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                gr.Markdown("""## ChaBo: A modular chatbot framework 
+                This framework is designed around a microservices architecture \
+                allowing different conversational components (like Vector database, Retrieval, Generator and other components)\
+                to be developed, deployed, and scaled independently. \
+                This design promotes flexibility and robust, complex chatbot development \
+                by enabling developers to easily swap out or upgrade individual services.         
+
+                **Note**: As of now this is more adapted towards delpoyment of these services \
+                    individually as individual spaces on HF infra, soon we will be releasing \
+                    the docker-compose method for dedicated deployment             
+                """)
+  
+        # 2. Vector DB
+        with gr.Tab("Vector Database: Qdrant"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                with gr.Column(scale=1):
+                    gr.Markdown("### What is a Vector Database?")
+                    gr.Markdown("""
+                    A Vector Database is a specialized database designed to efficiently store, manage, \
+                    and retrieve **vector embeddings**—high-dimensional numerical representations of \
+                    unstructured data like text, images, or audio.It is the cornerstone of modern AI \ 
+                    applications like semantic search and Retrieval-Augmented Generation (RAG). \
+                    Unlike traditional databases, a vector database excels at **Nearest Neighbor Search (NNS)**, \
+                    allowing it to quickly find semantically similar data points, which is essential for \
+                    grounding large language models with external knowledge.
+                    """)
+                    gr.Markdown(vectordbText)
+                    gr.Image(
+                        value="qdrant.png", # <- Change this file path
+                        label="Qdrant Dashboard",             
+                        show_label=True,
+                        container=False,)
+        
             
-        # 3. External Space 2 Tab (Embedded via iframe)
-        # Replace the placeholder URL with your actual Space URL
-        with gr.Tab("LLM Chatbot"):
-            gr.Markdown("## External LLM Chatbot Space")
-            embed_space("https://hf.co/spaces/HuggingFaceH4/open-llm-leaderboard", height=700)
+        # 3. Retriever and Reranker (Embedded via iframe)
+        with gr.Tab("Retriever and Reranker"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                with gr.Column(scale=1):
+                    gr.Markdown("## What is Retriever ?")
+                    gr.Markdown("""It is the crucial process of efficiently finding and extracting relevant \
+                        information from a vast knowledge base to ground and inform the chatbot's final answer.""")
+                    gr.Markdown(retriverText)
+                    embed_space("https://giz-chatfed-retriever0-3.hf.space", height=700)
+        
+        # 4. File Ingestor (Embedding via iframe pending due to compliance and Readme documentation missing)
+        with gr.Tab("File Ingestor"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                with gr.Column(scale=1):
+                    gr.Markdown("## What is File Ingestor")
+                    gr.Markdown("""In certain chatbot use-cases it might be that user input can be a file upload,\
+                        on top of existing Vector Database. In this case it's important that we ingest this \
+                        file and use it for next for  relevant use """)
+                    gr.Markdown(fileingestorText)
+        ###  Enables this once space is public: after Proper EU aI act compliance  release embed_space("https://giz-chatfed-whisp.hf.space", height=700)
+        
+        # 5. Generator
+        with gr.Tab("Generator"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                with gr.Column(scale=1):
+                    gr.Markdown("## What is Generator?")
+                    gr.Markdown("""It is the microserviceis the crucial process of efficiently finding and extracting relevant \
+                        information from a vast knowledge base to ground and inform the chatbot's final answer.""")
+                    gr.Markdown(generatorText)  
+        
+        # 6. Orchest
+        with gr.Tab("Orchestrator"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                with gr.Column(scale=1):
+                    gr.Markdown("## What is Orchestrator ?")
+                    gr.Markdown(""" The Orchestrator is the central command module, defining the exact \
+                        steps and flow of data: it sequences the initial user prompt, directs the query \
+                        to the correct vector retrieval module, manages the document reranking (if applicable),\
+                        and finally routes the retrieved context and original prompt to the Large Language Model \
+                        (LLM) for final answer generation..""")
+                    gr.Markdown(orchestratorText)  
+
+        with gr.Tab("HuggingFace Chat UI"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                with gr.Column(scale=1):
+                    gr.Markdown("## What is Retriever ?")
+                    gr.Markdown("""It is the crucial process of efficiently finding and extracting relevant \
+                        information from a vast knowledge base to ground and inform the chatbot's final answer.""")
+                    gr.Markdown(""" This mciroservice integrates with the vector database to retrieve semantically relevant documents,\
+                        with optional reranking for precision, ready for seamless use in ChaBo RAG workflows.  \
+                        
+                        For more info on Retriever and code base visit the following links:
+                        - ChaBo_Retriever : [**ReadMe**](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3/blob/main/README.md)
+                        - ChaBo_Retriever: [**Codebase**](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3/tree/main)""")
+                    embed_space("https://giz-chatfed-retriever0-3.hf.space", height=700) 
 
+        with gr.Tab("Integrated UI"):
+            with gr.Row(elem_classes = "centered-content-row"):
+                with gr.Column(scale=1):
+                    gr.Markdown("## What is Retriever ?")
+                    gr.Markdown("""It is the crucial process of efficiently finding and extracting relevant \
+                        information from a vast knowledge base to ground and inform the chatbot's final answer.""")
+                    gr.Markdown(""" This mciroservice integrates with the vector database to retrieve semantically relevant documents,\
+                        with optional reranking for precision, ready for seamless use in ChaBo RAG workflows.  \
+                        
+                        For more info on Retriever and code base visit the following links:
+                        - ChaBo_Retriever : [**ReadMe**](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3/blob/main/README.md)
+                        - ChaBo_Retriever: [**Codebase**](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3/tree/main)""")
+                    embed_space("https://giz-chatfed-retriever0-3.hf.space", height=700)            
+        
+
+dashboard_app.css = """
+        .centered-content-row {
+            max-width: 1000px; /* Adjust this value for your desired max width */
+            margin: 0 auto;    /* Centers the container horizontally */
+        }
+        """
 # Launch the app
 dashboard_app.launch()

fileingestor.py

@@ -0,0 +1,27 @@
+fileingestorText = """ This mciroservice integrates with the Orchestrator and HuggingFace Chat UI and \
+                         uses the deterministic tool for further processing/actions.  \
+                        
+                        [ChaBo_FileIngestor](https://huggingface.co/spaces/GIZ/eudr_chabo_ingestor) hosts a microservice which takes the \
+                        Geojson file input and calls [WHISP API]("https://whisp.openforis.org/api/submit/geojson").
+                        
+                        **API documentation**: 1 API Endpoint
+                        
+                        ### api_name: /ingest
+
+                        Params:
+                        - filepath(filepath): Required
+
+                        Returns(str): Relevant response base don internal code of the microservice.
+                        
+                        **How to Connect**
+
+                        ```python
+
+                        from gradio_client import Client, handle_file
+                        client = Client("https://giz-eudr-chabo-ingestor.hf.space/")
+                        result = client.predict(
+                                file=handle_file('https://github.com/gradio-app/gradio/raw/main/test/test_files/sample_file.pdf'),
+                                api_name="/ingest"
+                        )
+                        ```
+                        """

generator.py

@@ -0,0 +1,64 @@
+generatorText = """ This microservice integrates with the Retriever to answer the user query in ChaBo RAG workflows.  \
+                    
+                    # ChaBo Generator on Hugging Face Spaces
+
+                    [ChaBo_Generator](https://huggingface.co/spaces/GIZ/eudr_chabo_generator/blob/main/README.md) Space hosts \
+                    a Generator microservice for answering user query. This is just a Infrastructural component and doesnt\
+                    not serve any user application through its User Interfaceas the its consumed in ChaBo workflow thorugh Orchestrator.
+                        
+                    ChaBo Generator - MCP Server
+
+                    A language model-based generation service designed for ChatFed RAG\
+                    (Retrieval-Augmented Generation) pipelines. This module serves as an \
+                    **MCP (Model Context Protocol) server** that generates contextual responses \
+                    using configurable LLM providers with support for retrieval result processing.
+
+                    **API Endpoint**: 1 API which provides context-aware text generation using \
+                        configurable LLM providers when properly configured with API credentials.
+
+                    ### api_name: /generate
+
+                    Parameters:
+                    - `query` (str, required): The question or query to be answered
+                    - `context` (str|list, required): Context for answering - can be plain text or list of retrieval result dictionaries
+
+                    Returns: String containing the generated answer based on the provided context and query.
+
+                    **Hot to connect**:
+                    ```python
+                    from gradio_client import Client
+
+                    client = Client("ENTER CONTAINER URL / SPACE ID")
+                    result = client.predict(
+                            query="What are the key findings?",
+                            context="Your relevant documents or context here...",
+                            api_name="/generate"
+                    )
+                    print(result)
+                    ```
+
+                    #### Configuration
+
+                    LLM Provider Configuration:
+                    1. Set your preferred inference provider in `params.cfg`
+                    2. Configure the model and generation parameters  
+                    3. Set the required API key environment variable
+                    4. [Optional] Adjust temperature and max_tokens settings
+                    5. Run the app:
+
+                    ```bash
+                    docker build -t chatfed-generator .
+                    docker run -p 7860:7860 chatfed-generator
+                    ```
+
+                    #### Environment Variables Required
+
+                    Make sure to set the appropriate environment variables:
+                    - OpenAI: `OPENAI_API_KEY`
+                    - Anthropic: `ANTHROPIC_API_KEY`
+                    - Cohere: `COHERE_API_KEY`
+                    - HuggingFace: `HF_TOKEN` 
+
+                    For more info on Retriever and code base visit the following links:
+                    - ChaBo_Generator : [**ReadMe**](https://huggingface.co/spaces/GIZ/eudr_chabo_generator/blob/main/README.md)
+                    - ChaBo_Generator: [**Codebase**](https://huggingface.co/spaces/GIZ/eudr_chabo_generator/tree/main)"""

orchestrator.py

@@ -0,0 +1,532 @@
+orchestratorText = """ # Chabo Orchestrator Documentation 
+                ## Table of Contents
+                1. Overview
+                2. System Architecture
+                3. Components
+                4. Configuration
+                5. Deployment Guide
+                6. API Reference
+                7. Usage Examples
+                8. Troubleshooting
+
+                ## Overview
+
+                The Chabo Orchestrator is the central coordination module of the Chabo RAG system. It orchestrates the flow between multiple microservices to provide intelligent document processing and question-answering capabilities. The system is designed for deployment on Huggingface Spaces.
+
+                ### Key Features
+                    - **Workflow Orchestration**: Uses LangGraph to manage complex processing pipelines
+                    - **Multi-Modal Support**: Handles files dependent on ChatUI and Ingestor config (e.g. PDF, DOCX, GeoJSON, and JSON )
+                    - **Streaming Responses**: Real-time response generation with Server-Sent Events (SSE)
+                    - **Dual Processing Modes**:
+                    - **Direct Output Mode**: Returns ingestor results immediately (e.g. EUDR use case)
+                    - **Standard RAG Mode**: Full retrieval-augmented generation pipeline
+                    - **Intelligent Caching**: Prevents redundant file processing (e.g. EUDR use case)
+                    - **Multiple Interfaces**: FastAPI endpoints for modules; LangServe endpoints for ChatUI; Gradio UI for testing
+
+
+                    ## System Architecture
+
+                    ### High-Level Architecture
+
+                    ```
+                    ┌─────────────────┐
+                    │   ChatUI        │
+                    │   Frontend      │
+                    └────────┬────────┘
+                            │ HTTP/SSE
+                            ▼
+                    ┌─────────────────────────────────┐
+                    │   Chabo Orchestrator            │
+                    │   ┌─────────────────────────┐   │
+                    │   │   LangGraph Workflow    │   │
+                    │   │   ┌─────────────────┐   │   │
+                    │   │   │ Detect File     │   │   │
+                    │   │   │ Type            │   │   │
+                    │   │   └────────┬────────┘   │   │
+                    │   │            │            │   │
+                    │   │   ┌────────▼────────┐   │   │
+                    │   │   │ Ingest File     │   │   │
+                    │   │   └────────┬────────┘   │   │
+                    │   │            │            │   │
+                    │   │      ┌─────┴──────┐     │   │
+                    │   │      │            │     │   │
+                    │   │   ┌──▼───┐   ┌────▼───┐ │   │
+                    │   │   │Direct│   │Retrieve│ │   │
+                    │   │   │Output│   │Context │ │   │
+                    │   │   └──┬───┘   └────┬───┘ │   │
+                    │   │      │            │     │   │
+                    │   │      │       ┌────▼───┐ │   │
+                    │   │      │       │Generate│ │   │
+                    │   │      │       │Response│ │   │
+                    │   │      │       └────────┘ │   │
+                    │   └──────┴──────────────────┘   │
+                    └──────┬───────────┬──────────┬───┘
+                        │           │          │
+                    ┌───▼──┐   ┌───▼───┐   ┌──▼────┐
+                    │Ingest│   │Retrie-│   │Genera-│
+                    │or    │   │ver    │   │tor    │
+                    └──────┘   └───────┘   └───────┘
+                    ```
+
+                    ### Component Communication
+
+                    All communication between modules happens over HTTP:
+                    - **Orchestrator ↔ Ingestor**: Gradio Client (file upload, processing)
+                    - **Orchestrator ↔ Retriever**: Gradio Client (semantic search)
+                    - **Orchestrator ↔ Generator**: HTTP streaming (SSE for real-time responses)
+                    - **ChatUI ↔ Orchestrator**: LangServe streaming endpoints
+
+                    ### Workflow Logic
+
+                    The orchestrator implements two distinct workflows:
+
+                    **Direct Output Workflow** (when `DIRECT_OUTPUT=True` and file is new):
+                    ```
+                    File Upload → Detect Type → Ingest → Direct Output → Return Results
+                    ```
+
+                    **Standard RAG Workflow** (default or cached files):
+                    ```
+                    Query → Retrieve Context → Generate Response → Stream to User
+                    ```
+
+                    ## Components
+
+                    ### 1. Main Application (`main.py`)
+
+                    - LangServe endpoints for ChatUI integration
+                    - Gradio web interface for testing
+                    - FastAPI endpoints for diagnostics and future use (e.g. /health)
+                    - Cache management endpoint (for direct output use cases)
+
+                    **Key Functions:**
+                    - `chatui_adapter()`: Handles text-only queries
+                    - `chatui_file_adapter()`: Handles file uploads with queries
+                    - `create_gradio_interface()`: Test UI
+
+                    ### 2. Workflow Nodes (`nodes.py`)
+
+                    LangGraph nodes that implement the processing pipeline:
+
+                    **Node Functions:**
+
+                    - `detect_file_type_node()`: Identifies file type and determines routing
+                    - `ingest_node()`: Processes files through appropriate ingestor
+                    - `direct_output_node()`: Returns raw ingestor results
+                    - `retrieve_node()`: Fetches relevant context from vector store
+                    - `generate_node_streaming()`: Streams LLM responses
+                    - `route_workflow()`: Conditional routing logic
+
+                    **Helper Functions:**
+
+                    - `process_query_streaming()`: Unified streaming interface
+                    - `compute_file_hash()`: SHA256 hashing for deduplication
+                    - `clear_direct_output_cache()`: Cache management
+
+                    ### 3. Data Models (`models.py`)
+
+                    Pydantic models for type validation
+
+                    ### 4. Retriever Adapter (`retriever_adapter.py`)
+
+                    Abstraction layer for managing different retriever configurations:
+                    - Handles authentication
+                    - Formats queries and filters
+
+                    ### 5. Utilities (`utils.py`)
+
+                    Helper functions
+
+                    #### Conversation Context Management
+
+                    The `build_conversation_context()` function manages conversation history to provide relevant context to the generator while respecting token limits and conversation flow.
+
+                    **Key Features:**
+
+                    - **Context Selection**: Always includes the first user and assistant messages to maintain conversation context
+                    - **Recent Turn Limiting**: Includes only the last N complete turns (user + assistant pairs) to focus on recent conversation (default: 3)
+                    - **Character Limit Management**: Truncates to maximum character limits to prevent context overflow
+
+
+                    **Function Parameters:**
+
+                    ```python
+                    def build_conversation_context(
+                        messages,           # List of Message objects from conversation
+                        max_turns: int = 3, # Maximum number of recent turns to include
+                        max_chars: int = 8000  # Maximum total characters in context
+                    ) -> str
+                    ```
+
+                    ## Configuration
+
+                    ### Configuration File (`params.cfg`)
+
+                    ```ini
+                    [file_processing]
+                    # Enable direct output mode: when True, ingestor results are returned directly
+                    # without going through the generator. When False, all files go through full RAG pipeline.
+                    # This also prevents ChatUI from resending the file in the conversation history with each turn
+                    # Note: File type validation is handled by the ChatUI frontend
+                    DIRECT_OUTPUT = True
+
+                    [conversation_history]
+                    # Limit the context window for the conversation history
+                    MAX_TURNS = 3
+                    MAX_CHARS = 12000
+
+                    [retriever]
+                    RETRIEVER = https://giz-chatfed-retriever0-3.hf.space/
+                    # Optional
+                    COLLECTION_NAME = EUDR  
+
+                    [generator]
+                    GENERATOR = https://giz-eudr-chabo-generator.hf.space
+
+                    [ingestor]
+                    INGESTOR = https://giz-eudr-chabo-ingestor.hf.space
+
+                    [general]
+                    # need to include this for HF inference endpoint limits
+                    MAX_CONTEXT_CHARS = 15000 
+                    ```
+
+                    ### Environment Variables
+
+                    Create a `.env` file with:
+
+                    ```bash
+                    # Required for private HuggingFace Spaces
+                    HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxx
+
+                    ```
+
+                    ### ChatUI Configuration
+
+                    ChatUI `DOTENV_LOCAL` example deployment configuration:
+
+                    ```javascript
+                    MODELS=`[
+                    {
+                        "name": "asistente_eudr",
+                        "displayName": "Asistente EUDR",
+                        "description": "Retrieval-augmented generation on EUDR Whisp API powered by ChatFed modules.",
+                    "instructions": {
+                        "title": "EUDR Asistente: Instructiones",
+                        "content": "Hola, soy Asistente EUDR, un asistente conversacional basado en inteligencia artificial diseñado para ayudarle a comprender el cumplimiento y el análisis del Reglamento de la UE sobre la deforestación. Responderé a sus preguntas utilizando los informes EUDR y los archivos GeoJSON cargados.\n\n💡 **Cómo utilizarlo (panel a la derecha)**\n\n**Modo de uso:** elija entre subir un archivo GeoJSON para su análisis o consultar los informes EUDR filtrados por país.\n\n**Ejemplos:** seleccione entre preguntas de ejemplo seleccionadas de diferentes categorías.\n\n**Referencias:** consulte las fuentes de contenido utilizadas para la verificación de datos.\n\n⚠️ Para conocer las limitaciones y la información sobre la recopilación de datos, consulte la pestaña «Exención de responsibilidad».\n\n⚠️ Al utilizar esta aplicación, usted acepta que recopilemos estadísticas de uso (como preguntas formuladas, comentarios realizados, duración de la sesión, tipo de dispositivo e información geográfica anónima) para comprender el rendimiento y mejorar continuamente la herramienta, basándonos en nuestro interés legítimo por mejorar nuestros servicios."
+                    },
+                        "multimodal": true,
+                        "multimodalAcceptedMimetypes": [
+                        "application/geojson"
+                        ],
+                        "chatPromptTemplate": "{{#each messages}}{{#ifUser}}{{content}}{{/ifUser}}{{#ifAssistant}}{{content}}{{/ifAssistant}}{{/each}}",
+                        "parameters": {
+                        "temperature": 0.0,
+                        "max_new_tokens": 2048
+                        },
+                        "endpoints": [{
+                        "type": "langserve-streaming",
+                        "url": "https://giz-eudr-chabo-orchestrator.hf.space/chatfed-ui-stream",
+                        "streamingFileUploadUrl": "https://giz-eudr-chabo-orchestrator.hf.space/chatfed-with-file-stream",
+                        "inputKey": "text",
+                        "fileInputKey": "files"
+                        }]
+                    }
+                    ]`
+
+                    PUBLIC_ANNOUNCEMENT_BANNERS=`[
+                        {
+                        "title": "This is Chat Prototype for DSC users",
+                        "linkTitle": "Keep it Clean"
+                    }
+                    ]`
+
+                    PUBLIC_APP_DISCLAIMER_MESSAGE="Disclaimer: AI is an area of active research with known problems such as biased generation and misinformation. Do not use this application for high-stakes decisions or advice. Do not insert your personal data, especially sensitive, like health data."
+                    PUBLIC_APP_DESCRIPTION="Internal Chat-tool for DSC users for testing"
+
+                    PUBLIC_APP_NAME="EUDR ChatUI" 
+                    ENABLE_ASSISTANTS=false
+                    ENABLE_ASSISTANTS_RAG=false
+                    COMMUNITY_TOOLS=false
+                    MONGODB_URL=mongodb://localhost:27017
+
+                    # Disable LLM-based title generation to prevent template queries
+                    LLM_SUMMARIZATION=false
+                    ```
+
+                    Key things to ensure here:
+                    - multimodalAcceptedMimetypes: file types to accept for upload via ChatUI
+                    - endpoints: orchestrator url + endpoints
+
+                    ## Deployment Guide
+
+                    ### Local Development
+
+                    **Prerequisites:**
+                    - Python 3.10+
+                    - pip
+
+                    **Steps:**
+
+                    1. Clone the repository:
+                    ```bash
+                    git clone <your-repo-url>
+                    cd chabo-orchestrator
+                    ```
+
+                    2. Install dependencies:
+                    ```bash
+                    pip install -r requirements.txt
+                    ```
+
+                    3. Configure the system:
+                    ```bash
+                    # Create .env file
+                    echo "HF_TOKEN=your_token_here" > .env
+
+                    # Edit params.cfg with your service URLs
+                    nano params.cfg
+                    ```
+
+                    4. Run the application:
+                    ```bash
+                    python app/main.py
+                    ```
+
+                    5. Access interfaces:
+                    - Gradio UI: http://localhost:7860/gradio
+                    - API Docs: http://localhost:7860/docs
+                    - Health Check: http://localhost:7860/health
+
+                    ### Docker Deployment
+
+                    **Build the image:**
+
+                    ```bash
+                    docker build -t chabo-orchestrator .
+                    ```
+
+                    **Run the container:**
+
+                    ```bash
+                    docker run -d \
+                    --name chabo-orchestrator \
+                    -p 7860:7860 \
+                    chabo-orchestrator
+                    ```
+
+                    ### HuggingFace Spaces Deployment
+
+                    **Repository Structure:**
+                    ```
+                    your-space/
+                    ├── app/
+                    │   ├── main.py
+                    │   ├── nodes.py
+                    │   ├── models.py
+                    │   ├── retriever_adapter.py
+                    │   └── utils.py
+                    ├── Dockerfile
+                    ├── requirements.txt
+                    ├── params.cfg
+                    └── README.md
+                    ```
+
+                    **Steps:**
+
+                    1. Create a new Space on HuggingFace
+                    2. Select "Docker" as the SDK
+                    3. Push your code to the Space repository
+                    4. Add secrets in Space settings:
+                    - `HF_TOKEN`: Your HuggingFace token
+                    5. The Space will automatically build and deploy
+
+                    **Important:** Ensure all service URLs in `params.cfg` are publicly accessible.
+
+                    ### Docker Compose (Multi-Service)
+
+                    Example orchestrated deployment for the entire Chabo stack (*NOTE - docker-compose will not run on Huggingface spaces*)
+
+                    ```yaml
+                    version: '3.8'
+
+                    services:
+                    orchestrator:
+                        build: ./orchestrator
+                        ports:
+                        - "7860:7860"
+                        environment:
+                        - HF_TOKEN=${HF_TOKEN}
+                        - RETRIEVER=http://retriever:7861
+                        - GENERATOR=http://generator:7862
+                        - INGESTOR=http://ingestor:7863
+                        depends_on:
+                        - retriever
+                        - generator
+                        - ingestor
+
+                    retriever:
+                        build: ./retriever
+                        ports:
+                        - "7861:7861"
+                        environment:
+                        - QDRANT_API_KEY=${QDRANT_API_KEY}
+
+                    generator:
+                        build: ./generator
+                        ports:
+                        - "7862:7862"
+                        environment:
+                        - HF_TOKEN=${HF_TOKEN}
+
+                    ingestor:
+                        build: ./ingestor
+                        ports:
+                        - "7863:7863"
+                    ```
+
+                    ## API Reference
+
+                    ### Endpoints
+
+                    #### Health Check
+                    ```
+                    GET /health
+                    ```
+                    Returns service health status.
+
+                    **Response:**
+                    ```json
+                    {
+                    "status": "healthy"
+                    }
+                    ```
+
+                    #### Root Information
+                    ```
+                    GET /
+                    ```
+                    Returns API metadata and available endpoints.
+
+                    #### Text Query (Streaming)
+                    ```
+                    POST /chatfed-ui-stream/stream
+                    Content-Type: application/json
+                    ```
+
+                    **Request Body:**
+                    ```json
+                    {
+                    "input": {
+                        "text": "What are EUDR requirements?"
+                    }
+                    }
+                    ```
+
+                    **Response:** Server-Sent Events stream
+                    ```
+                    event: data
+                    data: "The EUDR requires..."
+
+                    event: sources
+                    data: {"sources": [...]}
+
+                    event: end
+                    data: ""
+                    ```
+
+                    #### File Upload Query (Streaming)
+                    ```
+                    POST /chatfed-with-file-stream/stream
+                    Content-Type: application/json
+                    ```
+
+                    **Request Body:**
+                    ```json
+                    {
+                    "input": {
+                        "text": "Analyze this GeoJSON",
+                        "files": [
+                        {
+                            "name": "boundaries.geojson",
+                            "type": "base64",
+                            "content": "base64_encoded_content"
+                        }
+                        ]
+                    }
+                    }
+                    ```
+
+                    #### Clear Cache
+                    ```
+                    POST /clear-cache
+                    ```
+                    Clears the direct output file cache.
+
+                    **Response:**
+                    ```json
+                    {
+                    "status": "cache cleared"
+                    }
+                    ```
+
+                    ### Gradio Interface
+
+                    #### Interactive Query
+
+                    Gradio's default API endpoint for UI interactions. If running on huggingface spaces, access via: https://[ORG_NAME]-[SPACE_NAME].hf.space/gradio/
+
+
+                    ## Troubleshooting
+
+                    ### Common Issues
+
+                    #### 1. File Upload Fails
+
+                    **Symptoms:** "Error reading file" or "Failed to decode uploaded file"
+
+                    **Solutions:**
+                    - Verify file is properly base64 encoded
+                    - Check file size limits (default: varies by deployment)
+                    - Ensure MIME type is in `multimodalAcceptedMimetypes`
+
+                    #### 2. Slow Responses
+
+                    **Symptoms:** Long wait times for responses
+
+                    **Solutions:**
+                    - Check network latency to external services
+                    - Verify `MAX_CONTEXT_CHARS` isn't too high
+                    - Consider enabling `DIRECT_OUTPUT` for suitable file types
+                    - Check logs for retrieval/generation bottlenecks
+
+                    #### 3. Cache Not Clearing
+
+                    **Symptoms:** Same file shows cached results when it shouldn't
+
+                    **Solutions:**
+                    - Call `/clear-cache` endpoint
+                    - Restart the service (clears in-memory cache)
+                    - Check if `DIRECT_OUTPUT=True` in config
+
+                    #### 4. Service Connection Errors
+
+                    **Symptoms:** "Connection refused" or timeout errors
+
+                    **Solutions:**
+                    - Verify all service URLs in `params.cfg` are accessible
+                    - Check HF_TOKEN is valid and has access to private spaces (*NOTE - THE ORCHESTRATOR CURRENTLY MUST BE PUBLIC*)
+                    - Test each service independently with health checks
+                    - Review firewall/network policies
+
+
+                    ### Version History
+
+                    - **v1.0.0**: Initial release with LangGraph orchestration
+                    - Current implementation supports streaming, caching, and dual-mode processing
+
+                    ---
+
+                    **Documentation Last Updated:** 2025-10-01  
+                    **Compatible With:** Python 3.10+, LangGraph 0.2+, FastAPI 0.100+
+                    """

retriever.py

@@ -0,0 +1,64 @@
+retriverText = """ This mciroservice integrates with the vector database to retrieve semantically relevant documents,\
+                        with optional reranking for precision, ready for seamless use in ChaBo RAG workflows. 
+
+                        # Retriever and Reranker Microservice on Hugging Face Spaces 
+
+                        [ChaBo_Retrieval](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3) hosts a Retrieval and Reranker mciroservice.\
+                        Some of key feature of Retrieval service are:
+                        - The embedding of the user query is done by retriever itself using Sentence-Transformer.
+                        - ReRanker is available as optional component.
+                        - This is rate determining step as the emedding of user query can be compute intensive if using dedicated model.
+                        - Model config, Qdrant server url and other params can be set through \
+                            [params.cfg](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3/blob/main/params.cfg)
+                        
+                        ```
+                        [vectorstore]
+                        # Qdrant-Server usage:
+                        PROVIDER = qdrant
+                        URL = giz-chatfed-qdrantserver.hf.space  
+                        COLLECTION_NAME = EUDR
+
+                        [embeddings]
+                        MODEL_NAME = BAAI/bge-m3
+
+                        [retriever]
+                        TOP_K = 10
+                        SCORE_THRESHOLD = 0.6
+
+                        [reranker]
+                        MODEL_NAME = BAAI/bge-reranker-v2-m3
+                        TOP_K = 10
+                        ENABLED = true
+                        # use this to scale out the total docs retrieved prior to reranking (i.e. retriever top_k * TOP_K_SCALE_FACTOR)
+                        TOP_K_SCALE_FACTOR = 2
+                        ```
+                        
+                        **API documentation**: 1 API Endpoint
+                        
+                        ### api_name: /retrieve
+
+                        Params:
+                        - query(str): Required
+                        - collection_name(str): collection_name in the Qdrant server which need to be queried. Defualts to None.
+                        - filter_metadata(dict): metadata filtering for Qdrant vector store which will be 
+                                                applied to the collection mentioned above. Defuals to None
+
+                        Returns: List of retrieved context along with metadata as string, 
+                        where each context is dict with two key 'answer' and 'answer_metadata'
+                        
+                        **How to Connect**
+
+                        ```python
+                        from gradio_client import Client
+
+                        client = Client("https://giz-chatfed-retriever0-3.hf.space/")
+                        result = client.predict(
+                                query="What is Circular Economy",
+                                collection_name="Humboldt",
+                                filter_metadata=None,
+                                api_name="/retrieve"
+                        )
+                        ```
+                        For more info on Retriever and code base visit the following links:
+                        - ChaBo_Retriever : [**ReadMe**](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3/blob/main/README.md)
+                        - ChaBo_Retriever: [**Codebase**](https://huggingface.co/spaces/GIZ/chatfed_retriever0.3/tree/main)"""

vectorDB.py

@@ -0,0 +1,35 @@
+vectordbText = """
+                    We will use the [Qdrant](https://qdrant.tech/documentation/) server deployment as microservice. \
+                    You can either deploy it as individually or you can use it as one server to serve multiple \
+                    chatbots (like in image below) by having multiple collections (multiple collection can also serve one chatbot)
+
+
+                    # Qdrant Vector Database Server on Hugging Face Spaces
+
+                    [ChaBo_QdrantServer](https://huggingface.co/spaces/GIZ/chatfed_QdrantServer/blob/main/README.md) Space hosts \
+                    a Qdrant vector database instance. This is just a Infrastructural component and doesnt\
+                    not serve any user application through its User Interface. However the admin task can be performed by\
+                     accessing "<embedded space url>/dashboard" Ex:https://giz-chatfed-qdrantserver.hf.space/dashboard \
+                    which is passsword protected.
+
+                    **Persistence:** Data is stored persistently in the `/data/qdrant_data` directory due to enabled persistent storage.
+
+                    **How to connect:**
+                    From your client application (e.g., your retrieval microservice), use the `qdrant-client` \
+                    with the host set to your Space's direct URL and the appropriate port:
+
+                    ```python
+                    from qdrant_client import QdrantClient
+
+                    # Replace with your actual Space URL (e.g., [https://your-username-qdrant-server.hf.space](https://your-username-qdrant-server.hf.space))
+                    QDRANT_HOST = "giz-chatfed-qdrantserver.hf.space"
+                    client = QdrantClient(
+                        host = QDRANT_HOST,
+                        port=443,  # very important that port to be used for python client
+                        https=True,
+                        api_key = <QDRANT_API_KEY>,)
+                    ```
+
+                    API Documentation: https://api.qdrant.tech/api-reference
+
+                    """