📚 AI Study Assistant using CrewAI & Pinecone

Learn faster with intelligent document-based AI agents.

An advanced, production-ready AI-powered Study Assistant built with Streamlit, CrewAI, Pinecone Vector Database, Groq API, HuggingFace Sentence-Transformers, PyPDF, and SQLite.

📋 Table of Contents

• 🚀 Project Overview
• ✨ Key Features
• 🏗️ System Architecture
• 🤖 Multi-Agent Architecture
• 🌲 Vector Database & Embeddings
• 📁 Project Structure
• ⚙️ Installation & Setup
• 🔑 API Key Configuration
• 🚀 Running the Application
• 🎮 Usage Walkthrough
• 🛠️ Troubleshooting
• 🏆 Credits & License

🚀 Project Overview

The AI Study Assistant empowers students and researchers to upload study PDFs (textbooks, lecture slides, research papers), automatically chunk and embed the content into a high-performance Pinecone vector index, and receive verified, hallucination-free answers through a CrewAI multi-agent workflow (Research Agent → Analysis Agent → Review Agent).

Unlike basic single-prompt RAG wrappers, this application uses a true multi-agent architecture where each agent possesses distinct roles, goals, backstories, and task dependencies.

✨ Key Features

• 📄 Multi-PDF Document Ingestion: Upload single or multiple PDF documents with automatic page text extraction and cleaning.
• ✂️ Smart Text Chunking: RecursiveCharacterTextSplitter preserving source filename, page numbers, and chunk IDs.
• ⚡ Local Vector Embeddings: Utilizes HuggingFace sentence-transformers/all-MiniLM-L6-v2 (384 dimensions) for local, fast vector generation.
• 🌲 Pinecone Vector DB Integration: Automated index creation (cosine metric), metadata indexing, and similarity search.
• 🤖 CrewAI Multi-Agent Workflow: Sequential agent execution with Research, Analysis, and Review agents.
• 🎯 Multiple Study Modes:
  • Ask Question: Standard Q&A with key points and sources.
  • Summarize: Structured academic topic summaries.
  • Explain Simply: Everyday analogies for complex concepts.
  • Generate Quiz: Practice multiple-choice questions with answers.
  • Generate Flashcards: Q&A flashcards for exam preparation.
• 🔍 Grounded Citations & Zero Hallucination: Review Agent fact-checks every claim against retrieved document chunks and attaches page citations.
• 📊 Observability & Analytics: Real-time agent status tracker, execution telemetry, vector query inspector, and system logs.

🏗️ System Architecture

                                  USER INTERFACE (Streamlit)
                                              │
                                              ▼
                                 📄 Document Ingestion Pipeline
                                 ┌───────────────────────────┐
                                 │ 1. PyPDF Text Extraction  │
                                 │ 2. Text Cleaning          │
                                 │ 3. Text Chunking          │
                                 └─────────────┬─────────────┘
                                               │
                                               ▼
                              🧠 Sentence-Transformers Embedding
                                (all-MiniLM-L6-v2 - 384 Dim)
                                               │
                                               ▼
                             🌲 Pinecone Vector Database Index
                                               │
               ┌───────────────────────────────┴───────────────────────────────┐
               │                  User Question & Query Vector                 │
               └───────────────────────────────┬───────────────────────────────┘
                                               │
                                               ▼
                                  🤖 CREWAI MULTI-AGENT CREW
               ┌───────────────────────────────────────────────────────────────┐
               │ 1. 🔎 Research Agent: Context & evidence retrieval            │
               │ 2. 🧠 Analysis Agent: Concept synthesis & response drafting   │
               │ 3. ✅ Review Agent: Fact-checking & citation enforcement      │
               └───────────────────────────────┬───────────────────────────────┘
                                               │
                                               ▼
                                 💬 Final Answer & Page Sources

🤖 Multi-Agent Architecture & Agent Responsibilities

| Agent | Role | Goal | Responsibility | |---|---|---|---| | 🔎 Research Agent | Study Research Specialist | Retrieve the most relevant information from uploaded study materials without hallucinating. | Searches Pinecone, extracts factual excerpts, organizes evidence with page metadata. | | 🧠 Analysis Agent | Academic Analysis Specialist | Analyze retrieved study material and formulate clear, accurate responses. | Connects concepts, provides student-friendly explanations, tailors output to selected Study Mode. | | ✅ Review Agent | Academic Review Specialist | Verify that generated answer is strictly supported by retrieved study material. | Fact-checks draft answer against context, eliminates unsupported claims, formats final response with citations. |

🌲 Vector Database & Embedding Details

• Embedding Model: sentence-transformers/all-MiniLM-L6-v2
• Embedding Dimension: 384
• Vector Metric: Cosine similarity
• Vector Metadata:

  {
      "text": "Supervised learning is a machine learning approach...",
      "source": "Machine_Learning.pdf",
      "page": 15,
      "chunk_id": "Machine_Learning_pdf_p15_c4"
  }
  

📁 Project Structure

ai_study_assistant/
│
├── app.py                      # Main Streamlit Frontend Application
├── requirements.txt            # Python Dependencies
├── .env                        # Active Environment Variables (Git ignored)
├── .env.example                # Template Environment File
├── .gitignore                  # Git Ignore Specifications
├── README.md                   # Technical Documentation
│
├── backend/                    # Backend Logic & Pipeline
│   ├── __init__.py
│   ├── document_processor.py   # PDF text extraction & chunking
│   ├── embeddings.py           # Sentence-transformer embedding manager
│   ├── pinecone_manager.py     # Pinecone vector DB CRUD & search
│   ├── llm.py                  # Groq API LLM integration
│   ├── crew.py                 # CrewAI crew orchestrator & execution
│   ├── tasks.py                # CrewAI task definitions
│   ├── prompts.py              # System prompts & guidelines
│   ├── database.py             # SQLite metadata & system logging
│   │
│   └── agents/                 # Specialized CrewAI Agents
│       ├── __init__.py
│       ├── research_agent.py   # Study Research Specialist
│       ├── analysis_agent.py   # Academic Analysis Specialist
│       └── review_agent.py     # Academic Review Specialist
│
├── data/                       # Local SQLite storage directory
│   └── .gitkeep
│
└── logs/                       # System log storage directory
    └── .gitkeep

⚙️ Installation & Windows Setup

Step 1: Clone Repository

git clone https://github.com/your-username/ai-study-assistant.git
cd ai-study-assistant

Step 2: Create Virtual Environment

python -m venv venv

Step 3: Activate Virtual Environment

On Windows Command Prompt / PowerShell:

venv\Scripts\activate

Step 4: Install Dependencies

pip install -r requirements.txt

🔑 API Key Configuration

Copy .env.example to .env:

cp .env.example .env

Edit .env with your API keys:

# Groq API Credentials
GROQ_API_KEY=gsk_your_groq_api_key_here
MODEL_NAME=llama-3.3-70b-versatile

# Pinecone Vector DB Credentials
PINECONE_API_KEY=your_pinecone_api_key_here
PINECONE_INDEX_NAME=ai-study-assistant
PINECONE_NAMESPACE=default

🚀 Running the Application

Launch the Streamlit application:

streamlit run app.py

Open your web browser at http://localhost:8501.

🎮 Usage Walkthrough

Scenario 1: Uploading Study PDFs

1. Navigate to 📄 Upload Documents in the sidebar.
2. Select your study PDF (e.g., Machine_Learning.pdf).
3. Click 🚀 Process & Index Documents.
4. Observe extraction, text chunking, embedding generation, and Pinecone vector indexing.

Scenario 2: Asking Questions

1. Navigate to 💬 Ask Questions.
2. Select Study Mode (Ask Question, Explain Simply, Generate Quiz, etc.).
3. Type your question: "What is supervised learning?"
4. Watch the real-time agent workflow execution:
   • 🔎 Research Agent: Retrieves relevant chunks from Pinecone.
   • 🧠 Analysis Agent: Synthesizes findings into a clear answer.
   • ✅ Review Agent: Verifies answer and attaches page numbers.
5. Review output with Answer, Key Points, and Verified Sources.

🛠️ Troubleshooting

• Missing API Keys: Verify GROQ_API_KEY and PINECONE_API_KEY are set in .env or UI Settings.
• Empty PDF Extraction: Ensure uploaded PDFs contain selectable text.
• Pinecone Index Dimension: Index dimension must be 384 to match all-MiniLM-L6-v2.

🏆 Credits

Built for academic demonstration, technical presentations, and portfolio showcases using Streamlit, CrewAI, Pinecone, and Groq.