Capstone Project - Future Thought PoC - Multi-Agent Learning System

(Mentees)

A Next.js application that uses multiple AI agents to automatically generate contextual learning material from GitHub repositories.

📽️ Demo

Below is a short demo of the application in action:

🚀 Features

• 🔍 FetcherAgent: Clones and processes GitHub repositories
• 🧠 EmbedderAgent: Chunks and embeds content using LangChain
• 🗃️ StorageAgent: Manages PostgreSQL with pgvector for vector storage
• 🧑‍🏫 ContentAgent: Generates domain-specific learning material
• 🔗 PlannerAgent: Orchestrates async task management between agents

🛠️ Tech Stack

• Frontend: Next.js 14+ with React and TypeScript
• Backend: Next.js API routes with server actions
• Database: PostgreSQL with pgvector extension
• AI/ML: LangChain for embeddings and agent orchestration
• Styling: Tailwind CSS with Radix UI components
• Git Operations: simple-git for repository handling

📋 Prerequisites

• Node.js 18+
• PostgreSQL 15+ with pgvector extension
• OpenAI API key
• GitHub personal access token
• npm or yarn package manager

⚡ Quick Start

1. Environment Variables

Create a .env.local file in the root directory with the following variables:

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/future_thought_poc
PGVECTOR_EXTENSION_ENABLED=true

# OpenAI API Configuration
OPENAI_API_KEY=your_openai_api_key_here

# GitHub API Configuration
GITHUB_TOKEN=your_github_token_here

# Application Configuration
NEXT_PUBLIC_APP_URL=http://localhost:3000
NODE_ENV=development

# Agent Configuration
AGENT_MEMORY_STORE_TYPE=postgresql
AGENT_TASK_QUEUE_TYPE=memory

# LangChain Configuration
LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your_langchain_api_key_here
LANGCHAIN_PROJECT=future-thought-poc

# Security
NEXTAUTH_SECRET=your_nextauth_secret_here
NEXTAUTH_URL=http://localhost:3000

2. Database Setup

1. Install PostgreSQL with pgvector extension:

# macOS
brew install postgresql@15
brew install pgvector

# Ubuntu/Debian
sudo apt-get install postgresql-15 postgresql-contrib-15

2. Create database and enable pgvector:

CREATE DATABASE future_thought_poc;
\c future_thought_poc;
CREATE EXTENSION IF NOT EXISTS vector;

3. Run migrations:

npm run db:migrate

3. Installation

# Install dependencies
npm install

# Run development server
npm run dev

4. Usage

1. Open http://localhost:3000 in your browser
2. Enter a GitHub repository URL
3. The agents will automatically:
   • Clone the repository
   • Process and embed the content
   • Generate contextual learning material
   • Present it in an interactive UI

📁 Project Structure

src/
├── agents/           # Multi-agent system implementations
│   ├── fetcher.ts    # GitHub repository fetching
│   ├── embedder.ts   # Content processing and embedding
│   ├── storage.ts    # Database operations
│   ├── content.ts    # Learning material generation
│   └── planner.ts    # Task orchestration
├── components/       # React UI components
├── lib/             # Utility functions and configurations
├── types/           # TypeScript type definitions
├── hooks/           # Custom React hooks
├── store/           # State management
└── app/             # Next.js app router pages

📚 Learning Resources

Documentation

• Key Design Requirements: Comprehensive system architecture and design specifications
• Learning Outcomes: Detailed breakdown of skills and technologies covered
• Processing Progress Analysis: Deep dive into progress tracking system

Interactive Learning

• Coding Challenges: Technical quiz with questions based on the codebase
• Database Schema: Explore the PostgreSQL schema and relationships
• API Documentation: Understand the REST API endpoints and usage

Key Concepts

• Multi-Agent Architecture: Learn about distributed AI systems
• Vector Databases: Understand semantic search with pgvector
• AI-Powered Content Generation: Explore educational content creation
• Real-time Processing: Study progress tracking and monitoring

🔧 Available Scripts

# Development
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint

# Database
npm run db:migrate   # Run database migrations
npm run db:seed      # Seed database with sample data

# Testing
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode

🐛 Troubleshooting

Common Issues

Database Connection Errors

# Check if PostgreSQL is running
brew services list | grep postgresql

# Verify database exists
psql -l | grep future_thought_poc

pgvector Extension Issues

-- Check if extension is installed
SELECT * FROM pg_extension WHERE extname = 'vector';

-- Install if missing
CREATE EXTENSION IF NOT EXISTS vector;

OpenAI API Errors

• Verify your API key is correct
• Check your OpenAI account has sufficient credits
• Ensure the API key has the necessary permissions

GitHub API Rate Limits

• Use a personal access token with appropriate scopes
• Consider implementing rate limiting in your application

Debug Mode

Enable debug logging by setting:

LOG_LEVEL=debug
NODE_ENV=development

🔒 Security Considerations

• API Keys: Never commit API keys to version control
• Database: Use strong passwords and limit database access
• CORS: Configure CORS properly for production deployment
• Rate Limiting: Implement rate limiting to prevent abuse
• Input Validation: Validate all user inputs to prevent injection attacks

📊 Performance Optimization

Database

• Use connection pooling for database connections
• Implement proper indexing for vector similarity searches
• Monitor query performance and optimize slow queries

Application

• Implement caching for frequently accessed data
• Use async processing for long-running tasks
• Monitor memory usage and implement garbage collection

AI/ML

• Optimize embedding generation with batch processing
• Implement retry logic for API failures
• Cache embeddings to avoid redundant API calls

🚀 Deployment

Production Environment

# Build the application
npm run build

# Set production environment variables
NODE_ENV=production
DATABASE_URL=your_production_db_url
OPENAI_API_KEY=your_production_api_key

# Start the application
npm start

Docker Deployment

# Example Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Write meaningful commit messages
• Add tests for new features
• Update documentation as needed
• Follow the existing code style

📈 Roadmap

Planned Features

• User authentication and authorization
• Collaborative learning features
• Advanced content personalization
• Mobile application
• Integration with learning management systems
• Multi-language support
• Advanced analytics and insights

Technical Improvements

• Microservices architecture
• Event-driven communication
• Advanced caching strategies
• Performance monitoring
• Automated testing pipeline

📄 License

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

🙏 Acknowledgments

• OpenAI for providing the GPT models and API
• LangChain for the AI/ML framework
• PostgreSQL and pgvector for vector database capabilities
• Next.js team for the excellent React framework
• Tailwind CSS for the utility-first CSS framework

📞 Support

If you encounter any issues or have questions:

1. Check the troubleshooting section
2. Review the documentation
3. Search existing issues
4. Create a new issue with detailed information

---

Happy Learning! 🎓

Transform any GitHub repository into an interactive learning experience with the power of AI.