Hybrid ReAct Retrieval System

A powerful retrieval system that combines text search, vector search, and ReAct (Reasoning and Acting) agent for intelligent document retrieval and analysis.

Overview

This system provides a hybrid search solution using MongoDB Atlas that combines:

1. Text Search - Traditional keyword-based search
2. Vector Search - Semantic similarity search using embeddings
3. ReAct Agent - AI reasoning agent that decides between search and RAG tools
4. RAG (Retrieval-Augmented Generation) - Content-aware responses based on retrieved documents

The system uses Reciprocal Rank Fusion (RRF) to intelligently combine results from different search methods, providing more relevant and comprehensive search results.

Features

• FastAPI-based REST API
• MongoDB Atlas integration for text and vector search
• ReAct agent with reasoning capabilities to choose appropriate tools
• Hybrid search with result fusion using RRF algorithm
• RAG capability for answering complex queries
• Memory component for caching recent searches
• Flexible query filtering
• Docker support for easy deployment

Architecture

├── api/                         # API endpoints
│   └── assistant/              # Assistant-related endpoints
│       └── hybrid_retrieval.py # Hybrid search endpoint with ReAct agent
├── services/                   # Core services
│   ├── query_services/        # Database and query services
│   │   └── db_connection.py   # MongoDB connection handling
│   ├── react/                 # ReAct agent implementation
│   │   └── react_agent.py     # Agent that reasons about tool selection
│   └── tools/                 # Utility tools
│       ├── hybrid_search_tool.py # Text and vector search implementations
│       ├── rag_tool.py        # Retrieval-Augmented Generation tool
│       ├── memory_tool.py     # Memory-based retrieval
│       └── utils.py           # General utilities including embeddings
├── static/                    # Static files for web interface
├── app.py                     # Main FastAPI application
├── Dockerfile                 # Container definition for deployment
├── requirements.txt           # Project dependencies
└── .env                       # Environment variables (not tracked)

Setup

Prerequisites

• Python 3.11+
• MongoDB Atlas account with vector search and Atlas Search configured
• OpenAI API key for embeddings and LLM capabilities

Environment Variables

Create a .env file with the following variables:

MONGODB_URI=your_mongodb_atlas_connection_string
MONGODB_DB_NAME=your_database_name
MONGODB_COLLECTION_NAME=your_collection_name
OPENAI_API_KEY=your_openai_api_key
OPENAI_MODEL_NAME=gpt-4  # Or your preferred LLM model

Installation

Local Development

1. Clone the repository:

   git clone -b master https://github.com/AI-Librarian/Retrieval.git

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

   or

   cd venv
   source Scripts/activate
   cd ..

3. Install dependencies:

   pip install -r requirements.txt

4. Run the application:

   uvicorn app:app --reload

Docker Deployment

1. Build the Docker image:

   docker build -t hybrid-retrieval .

2. Run the container:

   docker run -p 8000:8000 -d hybrid-retrieval

The API will be available at http://localhost:8000

API Usage

Hybrid Search Endpoint

POST /api/assistant/hybrid-search

Request body:

{
  "query": "your search query",
  "filter": {
    "optional_field": "optional value"
  }
}

Response:

{
  "status": "success",
  "query": "your search query",
  "flattened_query": "your search query optional_field:optional value",
  "response": "A comprehensive response based on the documents...",
  "thought_process": [
    {
      "thought": "I should search for relevant documents",
      "action": "Search",
      "action_input": "your search query optional_field:optional value",
      "observation": "Found 3 documents about..."
    }
  ]
}

How It Works

1. When a query is received, the system:

   • Flattens the query with any provided filters (e.g., "your query project:ProjectName")
   • Passes the flattened query to the ReAct agent

2. The ReAct agent:

   • Analyzes the query to determine the best approach
   • Has two main tools at its disposal:
     • Search Tool: Direct document retrieval
     • RAG Tool: Document retrieval + LLM-powered analysis

3. For either tool, the system:

   • Generates an embedding vector for the query
   • Performs parallel text and vector searches in MongoDB Atlas
   • Combines results using Reciprocal Rank Fusion
   • Returns either raw documents or an AI-generated response

4. The RAG tool adds these additional steps:

   • Takes search results and extracts the most relevant content
   • Uses the LLM to analyze document content and generate a response
   • Formats the response with clear structure (bullet points, sections)

License

MIT License

---