Vidya Chat Agent

An advanced AI-powered educational chat system built with CrewAI and FastAPI, featuring intelligent Subject Matter Expert (SME) agents, web search capabilities, and comprehensive PostgreSQL persistence for educational chatrooms.

🚀 Features

🤖 Multi-Agent AI System

• Subject Matter Expert (SME) Agents: Specialized AI agents for different subjects (Python, JavaScript, DSA, etc.)
• Web Search Agent: Real-time web research and information gathering using DuckDuckGo
• Enhanced RAG System: Combines vector database, web search, and knowledge base for comprehensive responses
• Educational Chatrooms: Subject-specific learning environments with persistent chat history

🗄️ Database & Persistence

• PostgreSQL Integration: Full database persistence for chatrooms, messages, and users
• Vector Database (Qdrant): Semantic search and knowledge retrieval capabilities
• Alembic Migrations: Database schema management and versioning
• Docker Compose: Easy setup with PostgreSQL, Redis, pgAdmin, and Qdrant

🌐 Web Search & Knowledge

• Real-time Web Search: DuckDuckGo integration for current information
• Knowledge Base: Vector-based semantic search for educational content
• Source Citations: Proper attribution and credibility assessment
• Current Information: Always up-to-date responses with web research

📚 Educational Features

• Lesson Plan Generation: AI-generated comprehensive lesson plans with web research
• Practice Exercises: Interactive learning materials (coming soon)
• Subject-Specific Chatrooms: Dedicated learning environments for different topics
• Chat History: Persistent conversation history with full message tracking

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   FastAPI       │    │   CrewAI Agents  │    │   PostgreSQL    │
│   Web Server    │◄──►│   - SME Agents   │◄──►│   Database      │
│                 │    │   - Web Search   │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         ▼                       ▼                       ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Educational   │    │   Enhanced RAG   │    │   Qdrant        │
│   Chatrooms     │    │   System         │    │   Vector DB     │
└─────────────────┘    └──────────────────┘    └─────────────────┘

📋 Prerequisites

• Python 3.11 or higher
• Google Gemini API key
• Docker and Docker Compose (for database services)
• UV package manager (recommended) or pip

🛠️ Installation

1. Clone the repository

git clone <your-repo-url>
cd vidya-chat-agent

2. Set up environment variables

cp config.example .env
# Edit .env and add your configuration

3. Install dependencies

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

4. Set up databases with Docker

# Start PostgreSQL, Redis, pgAdmin, and Qdrant
docker-compose up -d

# Run database migrations
uv run alembic upgrade head

5. Configure your API keys

# Required: Google Gemini API key
export GEMINI_API_KEY="your_gemini_api_key_here"

# Optional: Additional configuration
export GEMINI_MODEL="gemini/gemini-1.5-flash"
export GEMINI_TEMPERATURE="0.7"

⚙️ Configuration

Create a .env file with the following variables:

# Required
GEMINI_API_KEY=your_gemini_api_key_here

# Database Configuration
DATABASE_URL=postgresql+asyncpg://postgres:password@localhost:5432/vidya_chat_agent
POSTGRES_PASSWORD=password
POSTGRES_DB=vidya_chat_agent

# Vector Database (Qdrant)
QDRANT_API_URL=http://localhost:6333
QDRANT_COLLECTION=vidya_knowledge

# Optional
GEMINI_MODEL=gemini/gemini-1.5-flash
GEMINI_TEMPERATURE=0.7
HOST=0.0.0.0
PORT=8000
DEBUG=False
AGENT_VERBOSE=True

🚀 Running the Application

Quick Start

# Start the application
uv run python main.py

Alternative Methods

# Using uvicorn directly
uvicorn src.vidya_chat_agent.api:app --host 0.0.0.0 --port 8000 --reload

# Using UV run
uv run uvicorn src.vidya_chat_agent.api:app --host 0.0.0.0 --port 8000 --reload

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

🌐 API Endpoints

Core Chat Endpoints

• GET / - API information and welcome message
• GET /health - Health check and system status
• POST /chat - Main chat endpoint for user queries

Educational Chatroom Endpoints

• GET /educational/subjects - Get available subjects
• GET /educational/chatrooms - List all chatrooms
• POST /educational/chatrooms - Create a new chatroom
• GET /educational/chatrooms/{room_id} - Get chatroom information
• POST /educational/chatrooms/{room_id}/chat - Send message to chatroom
• GET /educational/chatrooms/{room_id}/history - Get chat history
• POST /educational/chatrooms/{room_id}/lesson-plan - Generate lesson plan
• DELETE /educational/chatrooms/{room_id} - Delete chatroom

API Documentation

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

💬 Using the Educational Chatrooms

1. Create a Chatroom

curl -X POST "http://localhost:8000/educational/chatrooms" \
     -H "Content-Type: application/json" \
     -d '{
       "subject": "python",
       "title": "Python Learning Session",
       "description": "Learn Python programming with AI assistance",
       "owner_id": "user123",
       "enable_rag": true
     }'

2. Send a Message

curl -X POST "http://localhost:8000/educational/chatrooms/python_abc123/chat" \
     -H "Content-Type: application/json" \
     -d '{
       "message": "What are Python decorators?",
       "user_id": "student456"
     }'

3. Generate a Lesson Plan

curl -X POST "http://localhost:8000/educational/chatrooms/python_abc123/lesson-plan" \
     -H "Content-Type: application/json" \
     -d '{
       "topic": "Python Lists",
       "difficulty": "beginner"
     }'

4. Get Chat History

curl "http://localhost:8000/educational/chatrooms/python_abc123/history"

🗄️ Database Schema

Users Table

• id (UUID) - Primary key
• username (String) - Unique username
• email (String) - User email
• created_at (DateTime) - Account creation time
• is_active (Boolean) - Account status

Chatrooms Table

• id (UUID) - Primary key
• room_id (String) - Unique room identifier
• subject (String) - Subject/topic (python, javascript, etc.)
• title (String) - Chatroom title
• description (Text) - Chatroom description
• owner_id (UUID) - User who created the chatroom
• enable_rag (Boolean) - RAG capabilities enabled
• created_at (DateTime) - Creation time

Chat Messages Table

• id (UUID) - Primary key
• chatroom_id (UUID) - Reference to chatroom
• user_id (UUID) - Reference to user (optional)
• message (Text) - User's message
• response (Text) - AI agent's response
• message_type (String) - Type of message (chat, lesson_plan, etc.)
• message_metadata (JSON) - Additional metadata
• created_at (DateTime) - Message timestamp

🔧 Development

Project Structure

vidya-chat-agent/
├── src/
│   └── vidya_chat_agent/
│       ├── __init__.py
│       ├── agents.py              # Basic CrewAI agents
│       ├── api.py                 # Main FastAPI application
│       ├── config.py              # Configuration management
│       ├── database.py            # Database models and configuration
│       ├── educational_api.py     # Educational chatroom endpoints
│       ├── enhanced_rag.py        # Enhanced RAG system
│       ├── sme_agents.py          # Subject Matter Expert agents
│       ├── vector_store.py        # Qdrant vector database integration
│       ├── web_search.py          # Web search engine
│       └── web_search_agent.py    # Web search CrewAI agent
├── migrations/                    # Alembic database migrations
├── docker-compose.yml            # Docker services configuration
├── main.py                       # Application entry point
├── pyproject.toml               # Project configuration
└── README.md

Adding New Subjects

To add support for new subjects, modify the get_available_subjects method in src/vidya_chat_agent/sme_agents.py:

# Add new subjects to the default list
subjects = ["python", "javascript", "dsa", "mathematics", "science", "programming", "your_new_subject"]

Customizing SME Agents

Modify the SubjectMatterExpert class in src/vidya_chat_agent/sme_agents.py to customize agent behavior:

class SubjectMatterExpert:
    def __init__(self, subject: str, expertise_level: str = "expert", enable_rag: bool = True):
        # Customize agent initialization
        self.subject = subject.lower()
        self.expertise_level = expertise_level
        self.enable_rag = enable_rag

🧪 Testing

Health Check

curl http://localhost:8000/health

Test Educational Features

# List available subjects
curl http://localhost:8000/educational/subjects

# List chatrooms
curl http://localhost:8000/educational/chatrooms

# Test chat functionality
curl -X POST "http://localhost:8000/educational/chatrooms/python_abc123/chat" \
     -H "Content-Type: application/json" \
     -d '{"message": "Hello, can you help me learn Python?", "user_id": "test_user"}'

Database Testing

# Check database connection
docker exec -it vidya_chat_postgres psql -U postgres -d vidya_chat_agent -c "SELECT COUNT(*) FROM chatrooms;"

# Check chat messages
docker exec -it vidya_chat_postgres psql -U postgres -d vidya_chat_agent -c "SELECT COUNT(*) FROM chat_messages;"

🚨 Troubleshooting

Common Issues

1. Database Connection Error:

   • Ensure Docker services are running: docker-compose up -d
   • Check database URL in .env file
   • Verify PostgreSQL is accessible on port 5432

2. Gemini API Key Error:

   • Ensure GEMINI_API_KEY is set in your environment
   • Check that the API key is valid and has sufficient credits

3. Web Search Not Working:

   • Verify DuckDuckGo tool is properly initialized
   • Check internet connectivity
   • Review web search agent logs

4. Vector Database Issues:

   • Ensure Qdrant is running: docker-compose ps
   • Check Qdrant API URL in configuration
   • Verify collection exists

5. Migration Errors:

   • Run migrations: uv run alembic upgrade head
   • Check database schema: docker exec -it vidya_chat_postgres psql -U postgres -d vidya_chat_agent -c "\d"

Debug Mode

Enable debug mode for more verbose logging:

export DEBUG=true
export AGENT_VERBOSE=true
uv run python main.py

📚 Dependencies

Core Dependencies

• CrewAI: Multi-agent AI framework
• FastAPI: Modern web framework for building APIs
• LangChain: Framework for developing applications with LLMs
• Google Gemini: Access to Gemini models
• SQLAlchemy: Python SQL toolkit and ORM
• Alembic: Database migration tool
• Pydantic: Data validation using Python type annotations
• Uvicorn: ASGI server implementation

Database & Storage

• PostgreSQL: Primary database
• asyncpg: Async PostgreSQL driver
• Qdrant: Vector database for semantic search
• Redis: Caching (optional)

Web Search & Tools

• DuckDuckGo: Web search capabilities
• requests: HTTP client for API calls
• sentence-transformers: Text embeddings

🚀 UV Package Manager

This project is optimized for UV, the fast Python package manager:

• Faster: 10-100x faster than pip
• Reliable: Deterministic dependency resolution
• Modern: Native support for pyproject.toml
• Simple: uv sync installs everything you need

🐳 Docker Services

The project includes Docker Compose configuration for easy development:

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Stop services
docker-compose down

# Services included:
# - PostgreSQL (port 5432)
# - Redis (port 6379)
# - pgAdmin (port 5050)
# - Qdrant (port 6333)

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Update documentation
6. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with CrewAI
• Powered by FastAPI
• AI capabilities provided by Google Gemini
• Vector database by Qdrant
• Database management with SQLAlchemy

📞 Support

For support and questions:

• Open an issue on GitHub
• Check the API documentation at /docs
• Review the troubleshooting section above
• Check the database status with Docker Compose

🎯 Roadmap

• User authentication and authorization
• Student progress tracking
• Practice exercise generation
• Multi-language support
• Mobile app integration
• Advanced analytics and reporting
• Integration with learning management systems