Mini AI Agent

A robust, developer-friendly AI agent built with FastAPI that leverages Gemini and RAG (Retrieval-Augmented Generation) to provide grounded, context-aware answers.

---

📺 Video Demo

Interested in seeing the agent in action? Watch the technical walkthrough below:

Watch Project Demo Video

---

Project Gallery

• Semantic Search: Utilizes sentence-transformers to retrieve highly relevant context from a local knowledge base.
• Agent Reasoning: Explicit decision-making logic determines whether to explain, compare, or fallback based on retrieved data.
• FastAPI Core: High-performance, REST API.
• Gemini Powered: Uses Google's Gemini model for high-quality, grounded responses.
• Zero Hallucination: Strict prompting ensures the agent only answers from provided context.

---

📁 Project Structure

.
├── agent/              # Core agent logic and tool definitions
│   ├── core.py         # Main Agent class with decision logic and LLM integration
│   └── tools.py        # Tool definitions (e.g., search_docs)
├── knowledge/          # Knowledge base and retrieval layer
│   ├── documents.json  # Raw document storage (JSON)
│   └── store.py        # Semantic search and embedding management
├── images/             # Documentation assets and demo video
├── tests/              # Unit tests for agent verification
├── main.py             # FastAPI application and endpoint definitions
├── config.py           # Global configuration settings
├── requirements.txt    # Python dependencies
└── .env.example        # Environment variable template

---

Setup & Installation

1. Clone & Navigate

git clone https://github.com/soumyaGhoshh/mini-rag-agent
cd mini-rag-agent

2. Set Up Virtual Environment

For macOS & Linux:

# Create the virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

For Windows:

# Create the virtual environment
python -m venv venv

# Activate the virtual environment
venv\Scripts\activate

3. Environment Configuration

Create a .env file in the root directory:

GEMINI_API_KEY=your_api_key_here
LLM_MODEL=gemini-2.0-flash

Note

Ensure you have a valid Gemini API key from Google AI Studio.

4. Install Dependencies

pip install -r requirements.txt

---

Running the Agent

Once the environment is active, run the following command:

uvicorn main:app --reload

The API will be available at http://localhost:8000. Interactive docs: http://localhost:8000/docs.

---

Troubleshooting

Port Conflict

If port 8000 is occupied, you can kill the existing process:

lsof -ti:8000 | xargs kill -9

Or run on a different port:

uvicorn main:app --reload --port 8001

Usage

Endpoint: POST /agent/query

Request:

{
  "query": "What is FastAPI?"
}

Response:

{
  "answer": "FastAPI is a modern, fast (high-performance), web framework for building APIs...",
  "documents_used": ["FastAPI Basics"],
  "agent_decision": "answered_with_explanation"
}

Implementation Logic

1. Knowledge Base (RAG)

• Documents: Stored in knowledge/documents.json.
• Embeddings: Generated on startup using sentence-transformers/all-MiniLM-L6-v2.
• Retrieval: Uses cosine similarity to find the top-k most relevant documents for a given query.

2. Agent Workflow

1. Receive Query: The agent receives a user question.
2. Tool Usage: Calls the search_docs tool to retrieve potential context.
3. Decision Making:
   • Relevance Check: If the similarity score of the top result is below a threshold (default 0.3), the agent decides it lacks information and returns a fallback message.
   • Classification: If context is found, the agent classifies the intent (Explanation vs Comparison) based on keywords (heuristic for this mini-agent, can be LLM-based).
4. Generation: Constructs a prompt with the retrieved context and queries the LLM to generate the final answer.

Trade-offs & Assumptions

• In-Memory Vector Store: For simplicity and speed in this "mini" scale, embeddings are stored in memory (NumPy arrays). For production with millions of docs, a dedicated Vector DB like Chroma or Pinecone is required.
• Model Loading: The embedding model is loaded on startup. This increases startup time but ensures fast query processing.
• Heuristic Decision: The decision to "explain" or "compare" is currently based on simple keyword matching for visibility. A more complex agent would use the LLM to classify intent explicitly.
• Synchronous Processing: The current implementation is largely synchronous. For high traffic, async database/vector store calls would be preferred.

---