Initial version

.gitattributes

@@ -0,0 +1,36 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.pdf filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,95 @@
+---
+title: Conductor RAG
+emoji: 🚀
+colorFrom: pink
+colorTo: green
+sdk: gradio
+sdk_version: "5.23.1"
+app_file: app.py
+pinned: false
+---
+
+# Conductor RAG - Document Question-Answering System
+🚀 A Retrieval-Augmented Generation (RAG) powered chat interface for document Q&A using Arcee Conductor
+
+## Overview
+This application provides an interactive chat interface that allows users to ask questions about their documents. It combines the power of Large Language Models with document retrieval to provide accurate, source-backed answers.
+
+## Features
+- **RAG-Powered Responses**: Leverages document context to provide accurate, factual answers
+- **Flexible Query Modes**: Switch between RAG and vanilla LLM responses
+- **Source Citations**: Automatically includes relevant document sources and page numbers
+- **Interactive Interface**: Clean, user-friendly Gradio-based chat interface
+- **Context Visibility**: View the retrieved document chunks used to generate responses
+
+## Technical Details
+- Built with Langchain and Gradio
+- Uses Arcee Conductor API for LLM capabilities
+- Document embedding via BAAI/bge-small-en-v1.5
+- ChromaDB for vector storage
+- Supports PDF document processing
+
+## Included Papers
+The following research papers are included in the `pdf` directory:
+
+- [arXiv:2306.13649v3](https://arxiv.org/abs/2306.13649)
+- [arXiv:2309.16609v1](https://arxiv.org/abs/2309.16609)
+- [arXiv:2312.06795v1](https://arxiv.org/abs/2312.06795)
+- [arXiv:2403.19522v1](https://arxiv.org/abs/2403.19522)
+- [arXiv:2405.04434v5](https://arxiv.org/abs/2405.04434)
+- [arXiv:2406.11617v1](https://arxiv.org/abs/2406.11617)
+- [arXiv:2410.21228v1](https://arxiv.org/abs/2410.21228)
+- [arXiv:2411.05059v2](https://arxiv.org/abs/2411.05059)
+- [arXiv:2501.09223v1](https://arxiv.org/abs/2501.09223)
+- [arXiv:2501.12948v1](https://arxiv.org/abs/2501.12948)
+- [arXiv:2503.04872v1](https://arxiv.org/abs/2503.04872)
+
+## Deployment
+This application is hosted as a Hugging Face Space. Configuration details can be found in the [spaces config reference](https://huggingface.co/docs/hub/spaces-config-reference).
+
+## Creating Your Own Hugging Face Space Using CLI
+
+You can easily deploy this application as your own Hugging Face Space using the Hugging Face CLI. Follow these steps:
+
+1. **Install the Hugging Face CLI**:
+   ```bash
+   pip install huggingface_hub
+   ```
+
+2. **Login to Hugging Face**:
+   ```bash
+   huggingface-cli login
+   ```
+   You'll be prompted to enter your Hugging Face token, which you can find in your account settings.
+
+3. **Clone this Repository**:
+   ```bash
+   git clone https://github.com/username/conductor-rag.git
+   cd conductor-rag
+   ```
+
+4. **Create a New Space**:
+   ```bash
+   huggingface-cli repo create conductor-rag-your-name --type space --space-sdk gradio
+   ```
+
+5. **Add Your Environment Variables**:
+   The application uses the following environment variables, which you need to set in the Space settings:
+   - `OPENAI_API_KEY`: Your Arcee Conductor API key
+
+7. **Push Your Code to the Space**:
+   ```bash
+   git remote add space https://huggingface.co/spaces/your-username/conductor-rag
+   git push space main
+   ```
+
+8. **Add Your PDF Documents**:
+   You can either add PDFs directly to the repository before pushing, or upload them later through git.
+
+9. **Monitor Deployment**:
+   Visit `https://huggingface.co/spaces/your-username/conductor-rag-your-name` to see your Space being built and deployed.
+
+Your Space will automatically build and deploy the application. Once complete, you can access it via the provided URL and share it with others.
+
+---
+Built with 💖 using Arcee Conductor

app.py

@@ -0,0 +1,136 @@
+import gradio as gr
+from demo import create_llm, create_embeddings, load_or_create_vectorstore, create_qa_chain
+
+def initialize_chain():
+    """Initialize the RAG chain and return it."""
+    llm = create_llm()
+    embeddings = create_embeddings()
+    vectorstore = load_or_create_vectorstore(embeddings)
+    return create_qa_chain(llm, vectorstore)
+
+def chat_response(message, history, query_type):
+    """Process chat messages and return responses using either RAG or vanilla LLM.
+    
+    Args:
+        message (str): The user's input message
+        history (list): List of previous message-response pairs
+        query_type (str): Either "RAG" or "Vanilla LLM"
+    
+    Returns:
+        str: The formatted response text including sources for RAG queries
+    """
+    # Convert Gradio history to list of tuples
+    chat_history = [(msg, resp) for msg, resp in history] if history else []
+    
+    if query_type == "RAG":
+        result = qa_chain.invoke({
+            "question": message,
+            "chat_history": chat_history
+        })
+        response_text = result["answer"]
+        
+        # Add source citations if available
+        if result.get("source_documents"):
+            sources = []
+            seen_sources = set()
+            
+            # Deduplicate sources while preserving order
+            for doc in result["source_documents"]:
+                source = doc.metadata.get('source', 'Unknown')
+                page = doc.metadata.get('page', 'unknown')
+                source_key = f"{source}:{page}"
+                
+                if source_key not in seen_sources:
+                    sources.append(f"- {source}, page {page}")
+                    seen_sources.add(source_key)
+            
+            if sources:
+                response_text += "\n\nSources:\n" + "\n".join(sources)
+    else:
+        # Use vanilla LLM for direct responses
+        result = llm.invoke(message)
+        response_text = result.content
+    
+    return response_text
+
+# Initialize components globally
+llm = create_llm()
+qa_chain = initialize_chain()
+
+# Create the Gradio interface
+with gr.Blocks() as demo:
+    # UI Setup
+    gr.Markdown("# RAG-Powered Document Chat with Arcee Conductor")
+    gr.Markdown("Ask questions about your documents. The system will provide answers based on the content of your PDFs.")
+    
+    rag_enabled = gr.Checkbox(
+        value=True,
+        label="Enable RAG",
+        info="Toggle between RAG-powered document search or vanilla LLM responses"
+    )
+    
+    chatbot = gr.Chatbot()
+    context_box = gr.Textbox(
+        label="Retrieved Context",
+        interactive=False,
+        visible=True,
+        lines=5
+    )
+    
+    # Input controls
+    with gr.Row():
+        msg = gr.Textbox(label="Query", scale=8)
+        with gr.Column(scale=1):
+            submit = gr.Button("Submit")
+            clear = gr.Button("Clear")
+    
+    def respond(message, chat_history, is_rag_enabled):
+        """Handle user messages and generate responses.
+        
+        Args:
+            message (str): User input message
+            chat_history (list): Previous conversation history
+            is_rag_enabled (bool): Whether to use RAG or vanilla LLM
+            
+        Returns:
+            tuple: (cleared message, updated history, context, RAG state)
+        """
+        if not message:
+            return "", chat_history, "", is_rag_enabled
+        
+        query_type = "RAG" if is_rag_enabled else "Vanilla LLM"
+        bot_message = chat_response(message, chat_history, query_type)
+        
+        # Create new history to avoid modifying the original
+        new_history = list(chat_history)
+        new_history.append((message, bot_message))
+        
+        # Get relevant context for RAG queries
+        context = ""
+        if is_rag_enabled and qa_chain.retriever:
+            docs = qa_chain.retriever.get_relevant_documents(message)
+            context = "\n\n".join(doc.page_content for doc in docs)
+        
+        return "", new_history, context, is_rag_enabled
+
+    def update_context_visibility(is_rag_enabled):
+        """Update context box visibility based on RAG toggle."""
+        return gr.update(visible=is_rag_enabled, value="" if not is_rag_enabled else None)
+
+    # Wire up event handlers
+    msg.submit(respond, [msg, chatbot, rag_enabled], [msg, chatbot, context_box, rag_enabled])
+    submit.click(respond, [msg, chatbot, rag_enabled], [msg, chatbot, context_box, rag_enabled])
+    clear.click(lambda: [[], "", True], None, [chatbot, context_box, rag_enabled], queue=False)
+    rag_enabled.change(update_context_visibility, rag_enabled, context_box)
+
+    # Add example queries
+    gr.Examples(
+        examples=[
+            "Tell me about Arcee Fusion.",
+            "How does deepseek-R1 differ from deepseek-v3?"
+        ],
+        inputs=msg
+    )
+
+if __name__ == "__main__":
+    demo.launch(share=False)

demo.py

@@ -0,0 +1,280 @@
+import os
+import glob
+# Set tokenizers parallelism before importing other libraries
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+from langchain_openai import ChatOpenAI
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_community.document_loaders import DirectoryLoader, PyPDFLoader
+from langchain.text_splitter import RecursiveCharacterTextSplitter
+from langchain_chroma import Chroma
+from langchain.chains import ConversationalRetrievalChain
+from langchain_huggingface import HuggingFaceEmbeddings
+from concurrent.futures import ThreadPoolExecutor, TimeoutError
+import time
+
+# Constants
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
+OPENAI_URL = "https://conductor.arcee.ai/v1"
+OPENAI_MODEL = "auto"
+CHROMA_PATH = "vectorstore"
+PDF_PATH = "pdf"
+
+def create_llm(streaming=False):
+    """Initialize the OpenAI language model.
+    
+    Args:
+        streaming (bool): Whether to enable response streaming
+        
+    Returns:
+        ChatOpenAI: Configured language model instance
+    """
+    return ChatOpenAI(
+        model=OPENAI_MODEL,
+        openai_api_key=OPENAI_API_KEY,
+        base_url=OPENAI_URL,
+        streaming=streaming
+    )
+
+def create_embeddings():
+    """Initialize the embedding model."""
+    return HuggingFaceEmbeddings(
+        model_name="BAAI/bge-small-en-v1.5",
+        model_kwargs={'device': 'cpu'},
+        encode_kwargs={'normalize_embeddings': True}
+    )
+
+def get_text_splitter():
+    """Create text splitter with optimal settings."""
+    return RecursiveCharacterTextSplitter(
+        chunk_size=512,
+        chunk_overlap=129,
+        length_function=len,
+        add_start_index=True,
+    )
+
+def get_pdf_files():
+    """Get list of PDF files from the specified directory."""
+    if not os.path.exists(PDF_PATH):
+        os.makedirs(PDF_PATH)
+        return []
+    return list(glob.glob(os.path.join(PDF_PATH, "*.pdf")))
+
+def filter_metadata(doc):
+    """Filter out unwanted sections from documents.
+    
+    Args:
+        doc: Document object with metadata
+        
+    Returns:
+        bool: True if document should be kept, False if filtered out
+    """
+    skip_sections = {
+        'references',
+        'acknowledgments', 
+        'appendix'
+    }
+    section = doc.metadata.get('section', '').lower()
+    return not any(s in section for s in skip_sections)
+
+def process_documents(documents, text_splitter):
+    """Process and filter documents into chunks."""
+    chunks = text_splitter.split_documents(documents)
+    return [chunk for chunk in chunks if filter_metadata(chunk)]
+
+def load_or_create_vectorstore(embeddings):
+    """Load existing vectorstore or create a new one."""
+    if os.path.exists(CHROMA_PATH):
+        return handle_existing_vectorstore(embeddings)
+    return create_new_vectorstore(embeddings)
+
+def handle_existing_vectorstore(embeddings):
+    """Handle loading and updating existing vectorstore.
+    
+    Args:
+        embeddings: Embedding model instance
+        
+    Returns:
+        Chroma: Loaded and potentially updated vectorstore
+        
+    Exits if no PDF files are found.
+    """
+    print("Loading existing Chroma database...")
+    vectorstore = Chroma(
+        persist_directory=CHROMA_PATH,
+        embedding_function=embeddings
+    )
+    
+    current_pdfs = get_pdf_files()
+    if not current_pdfs:
+        print("No PDF files found in directory.")
+        exit(1)
+    
+    collection = vectorstore.get()
+    processed_files = {
+        meta.get('source') 
+        for meta in collection['metadatas'] 
+        if meta and meta.get('source')
+    }
+    
+    new_pdfs = [pdf for pdf in current_pdfs if pdf not in processed_files]
+    
+    if new_pdfs:
+        update_vectorstore(vectorstore, new_pdfs, processed_files)
+    else:
+        print("No new PDF files to process.")
+    
+    return vectorstore
+
+def update_vectorstore(vectorstore, new_pdfs, processed_files):
+    """Update existing vectorstore with new documents."""
+    print(f"Found {len(new_pdfs)} new PDF files to process...")
+    loader = DirectoryLoader(PDF_PATH, glob="**/*.pdf", loader_cls=PyPDFLoader)
+    documents = loader.load()
+    new_documents = [doc for doc in documents if doc.metadata.get('source') not in processed_files]
+    
+    filtered_chunks = process_documents(new_documents, get_text_splitter())
+    if filtered_chunks:
+        print("Adding new documents to existing database...")
+        vectorstore.add_documents(filtered_chunks)
+        print("Database updated successfully!")
+
+def create_new_vectorstore(embeddings):
+    """Create a new vectorstore from documents."""
+    print("Creating new Chroma database...")
+    pdf_files = get_pdf_files()
+    if not pdf_files:
+        print(f"No PDF files found in '{PDF_PATH}' directory!")
+        print(f"Please add your PDF files to the '{PDF_PATH}' directory and run again.")
+        exit(1)
+    
+    print(f"Found {len(pdf_files)} PDF files to process...")
+    print("(This may take a while as documents need to be processed and embedded)")
+    
+    os.makedirs(CHROMA_PATH, exist_ok=True)
+    
+    loader = DirectoryLoader(PDF_PATH, glob="**/*.pdf", loader_cls=PyPDFLoader)
+    documents = loader.load()
+    filtered_chunks = process_documents(documents, get_text_splitter())
+    
+    return Chroma.from_documents(
+        documents=filtered_chunks,
+        embedding=embeddings,
+        persist_directory=CHROMA_PATH
+    )
+
+def create_qa_chain(llm, vectorstore):
+    """Create the question-answering chain."""
+    prompt_template = """Answer the question using your own knowledge and the provided context.
+
+Context:
+{context}
+
+Question: {question}
+
+Previous conversation:
+{chat_history}
+
+Answer:"""
+
+    prompt = ChatPromptTemplate.from_template(prompt_template)
+    
+    return ConversationalRetrievalChain.from_llm(
+        llm=llm,
+        retriever=vectorstore.as_retriever(
+            search_type="similarity", 
+            search_kwargs={'k': 3}    
+        ),
+        return_source_documents=True,
+        combine_docs_chain_kwargs={'prompt': prompt},
+        chain_type="stuff",
+        verbose=True
+    )
+
+def get_vanilla_response(llm, query):
+    """Get response from vanilla chain without RAG with streaming."""
+    streaming_llm = create_llm(streaming=True)
+    
+    vanilla_prompt = ChatPromptTemplate.from_template("""
+Question: {question}
+
+Instructions:
+- If you don't know the answer, say so
+- Be concise and clear
+- Only state what you're confident about
+
+Answer:""")
+    
+    chain = vanilla_prompt | streaming_llm
+    
+    print("\n=== Vanilla Response (No RAG) ===")
+    
+    try:
+        print("Answer: ", end="", flush=True)
+        for chunk in chain.stream({"question": query}):
+            print(chunk.content, end="", flush=True)
+        print()  # New line after streaming completes
+        
+    except Exception as e:
+        print(f"\nError getting vanilla response: {str(e)}")
+
+def get_rag_response(qa_chain, query, chat_history):
+    """Get response from RAG-powered chain with streaming.
+    
+    Args:
+        qa_chain: The QA chain instance
+        query (str): User's question
+        chat_history (list): Previous conversation history
+    """
+    print("\n=== RAG Response ===")
+    
+    try:
+        result = qa_chain.invoke({
+            "question": query,
+            "chat_history": chat_history
+        })
+        
+        # Print answer with streaming
+        print("\nAnswer: ", end="", flush=True)
+        for chunk in result["answer"]:
+            print(chunk, end="", flush=True)
+        print()
+        
+        # Print unique sources
+        if result.get("source_documents"):
+            print("\nSources:")
+            seen_sources = set()
+            for doc in result["source_documents"]:
+                source = doc.metadata.get('source', 'Unknown')
+                page = doc.metadata.get('page', 'unknown')
+                source_key = f"{source}:{page}"
+                
+                if source_key not in seen_sources:
+                    print(f"- {source}, page {page}")
+                    seen_sources.add(source_key)
+                    
+    except Exception as e:
+        print(f"\nError: {str(e)}")
+
+def main():
+    """Main execution function."""
+    # Create streaming LLM for RAG
+    llm = create_llm(streaming=True)
+    embeddings = create_embeddings()
+    vectorstore = load_or_create_vectorstore(embeddings)
+    qa_chain = create_qa_chain(llm, vectorstore)
+    
+    chat_history = []
+    query = "Tell me about Arcee Fusion?"
+    
+    # Get both vanilla and RAG responses
+    get_vanilla_response(llm, query)
+    get_rag_response(qa_chain, query, chat_history)
+
+if __name__ == "__main__":
+    main()
+
+
+
+
+

requirements.txt

@@ -0,0 +1,11 @@
+langchain
+langchain-openai
+langchain-huggingface
+langchain-chroma
+sentence-transformers
+torch
+transformers
+langchain-community
+chromadb
+pypdf
+gradio