--- title: LearnFlow AI emoji: 📚 short_description: Summarize any text/document for learning! colorFrom: yellow colorTo: red sdk: gradio sdk_version: 5.32.0 python_version: '3.11' app_file: app.py pinned: true license: apache-2.0 tags: - agent-demo-track --- # 🚀 LearnFlow AI: Revolutionizing Learning with AI Agents & MCP LearnFlow AI transforms any document into a comprehensive, interactive learning experience through an innovative multi-agent system. Built with cutting-edge AI technologies and designed for the future of personalized education, it seamlessly integrates advanced RAG capabilities, MCP server functionality, and intelligent content generation. ## 🎯 Video Demo & Overview 🎬 Watch our comprehensive demo: [LearnFlow AI in Action](https://youtu.be/_AsLnPB8pN0) Experience how LearnFlow AI revolutionizes document-based learning through intelligent agent orchestration and seamless user experience. --- ## ✨ Core Innovation & Features LearnFlow AI's architecture and features are meticulously designed to excel according to the Hackathon guidelines, demonstrating innovation, performance, and practical utility, aligning with key award criteria: ### 🤖 Multi-Agent Intelligence System Our sophisticated multi-agent system orchestrates the entire learning process, showcasing a robust and extensible AI framework. * **Planner Agent:** Employs an innovative "LLM-first" document understanding strategy, prioritizing native large language model comprehension for superior content summarization and unit generation. This approach, powered by leading LLMs like **Mistral AI** and others via our unified interface, ensures highly relevant and structured learning paths. * **Explainer Agent:** Generates contextual explanations with interactive visualizations and code execution. This agent's deep integration with **LlamaIndex Tool Integration** allows it to dynamically generate interactive code blocks and relevant visualizations, enhancing engagement and practical understanding. * **Examiner Agent:** Creates comprehensive assessments with instant evaluation capabilities. The optimized non-LLM evaluation for immediate feedback demonstrates high efficiency and responsiveness, aligning with **performance focus**. * **Unified Orchestration:** Central MCP tool coordination ensures seamless agent interaction, a core component of our novel approach to multi-agent coordination through the MCP protocol. ### 🔗 Model Context Protocol (MCP) Server LearnFlow AI functions as a dedicated MCP server, exposing its core functionalities as accessible tools for external AI agents and systems. This integration is a prime example of **Innovative MCP Usage**. * **First-Class MCP Integration:** Our complete Node.js/TypeScript MCP server implementation exposes all learning capabilities, enabling other AI agents to programmatically access LearnFlow's intelligence. * **Automatic Background Launch:** Seamless Node.js server integration with the Python application, featuring a bidirectional Python-Node.js communication bridge with automatic lifecycle management, contributes to a production-ready architecture. * **Cross-Platform Compatibility:** Designed to work flawlessly on local development and cloud deployment environments, including Hugging Face Spaces. ### 🔍 Advanced RAG & Document Processing Our robust Retrieval-Augmented Generation (RAG) foundation is a key innovation, for powering LearnFlow AI. * **Smart Processing Strategy:** Features an LLM-native understanding with sophisticated semantic chunking fallback, ensuring comprehensive content ingestion. * **Vector-Enhanced Context:** Utilizes FAISS-powered semantic search with sentence transformers for efficient and accurate document retrieval. * **Cross-Reference Intelligence:** Contextual unit generation prevents overlap and builds intelligent connections between learning topics, enhancing the overall learning flow. * **Multi-Format Support:** Supports PDF, DOCX, PPTX, and TXT documents with seamless **LlamaIndex** integration for diverse content processing. ### 🎨 Rich Content Generation LearnFlow AI delivers a superior learning experience through its ability to generate diverse and high-quality content. * **Interactive Visualizations:** AI-generated Plotly charts offer both interactive and static export options, providing dynamic data representation. * **Executable Code Blocks:** Live code generation with syntax highlighting and execution capabilities allows for hands-on learning. * **Perfect LaTeX Rendering:** Achieves professional mathematical notation in both web and PDF exports, crucial for technical and academic content. * **Professional PDF Export:** Our headless browser rendering ensures publication-quality PDF documents, a significant technical achievement. ### ⚡ Performance & User Experience LearnFlow AI prioritizes a responsive and intuitive user experience, demonstrating high performance and practical utility, keeping a **User First** design in mind. * **Instantaneous Quiz Evaluation:** Optimized non-LLM evaluation for immediate feedback on multiple-choice, true/false, and fill-in-the-blank questions, showcasing efficient AI. * **Multi-Provider LLM Support:** Our unified interface supports **OpenAI**, **Mistral AI**, **Gemini**, and local models, offering flexibility and advanced utilization of cutting-edge language models. This multi-provider architecture, highlights flexible and advanced utilization of cutting-edge language models for diverse content generation tasks. * **Session Persistence:** Users can save and load learning sessions with comprehensive progress tracking, ensuring continuity and a seamless learning journey. * **Responsive UI:** A modern Gradio interface with real-time updates and status indicators provides an intuitive and engaging user experience. * **Scalability Foundation:** The multi-agent architecture is designed for horizontal scaling with independent agent processes, async processing for non-blocking content generation, and efficient resource optimization, reflecting a focus on **efficient and scalable AI solutions**. --- ## 🚀 Quick Start ### Prerequisites * Python 3.9+ * Node.js 16+ (for MCP server) * 4GB+ RAM recommended ### Installation 1. **Clone the repository** ```bash git clone https://huggingface.co/spaces/Kyo-Kai/LearnFlow-AI cd LearnFlow-AI ``` 2. **Set up Python environment** ```bash python -m venv .venv # Windows .venv\Scripts\activate # macOS/Linux source .venv/bin/activate pip install -r requirements.txt ``` 3. **Configure MCP Server** ```bash cd mcp_server/learnflow-mcp-server npm install npm run build ``` 4. **Environment Configuration** ```bash # Copy example environment file cp .env.example .env # Add your API keys OPENAI_API_KEY=your_openai_key MISTRAL_API_KEY=your_mistral_key GEMINI_API_KEY=your_gemini_key ``` 5. **Launch Application** ```bash python app.py ``` The application will automatically launch the MCP server in the background and open the Gradio interface. --- ## 📋 Usage Guide ### Basic Workflow 1. 📄 **Plan:** Upload documents and generate structured learning units. 2. 📚 **Learn:** Access detailed explanations with interactive content. 3. 📝 **Quiz:** Take comprehensive assessments with instant feedback. 4. 📊 **Progress:** Track learning progress and export results. ### Advanced Features * **Multi-Format Export:** JSON, Markdown, HTML, and professional PDF. * **Session Management:** Save and resume learning sessions. * **Custom AI Models:** Configure different LLM providers per task. * **Interactive Content:** Execute code blocks and view dynamic visualizations. --- ## 🏗️ Architecture Overview ``` LearnFlow AI/ ├── agents/ # Multi-agent system core │ ├── planner/ # Document processing & unit generation │ ├── explainer/ # Content explanation & visualization │ ├── examiner/ # Quiz generation & evaluation │ └── learnflow_mcp_tool/ # Central orchestration ├── mcp_server/ # Node.js MCP server wrapped on the orchestrator ├── services/ # LLM factory & vector store ├── components/ # UI components & state management └── utils/ # Modular helper functions ``` ### Key Technologies * **Frontend:** Gradio 5.32.0 with custom CSS * **AI/ML:** LlamaIndex, sentence-transformers, FAISS * **LLM Integration:** LiteLLM with multi-provider support * **MCP Server:** Node.js/TypeScript with MCP SDK * **Export:** Plotly, pyppeteer for PDF generation * **State Management:** Pydantic models for type safety --- ## 🚀 Deployment ### Hugging Face Spaces 1. **Create `packages.txt`** ``` nodejs chromium ``` 2. **Configure Space Settings** * SDK: Gradio * Python Version: 3.8+ * Hardware: CPU Basic (recommended) 3. **Environment Variables** Set your API keys in the Space settings. ### Docker Deployment ```dockerfile FROM python:3.9-slim # Install Node.js and Chromium RUN apt-get update && apt-get install -y nodejs npm chromium # Copy and install dependencies COPY requirements.txt . RUN pip install -r requirements.txt COPY . . # Build MCP server RUN cd mcp_server/learnflow-mcp-server && npm install && npm run build EXPOSE 7860 CMD ["python", "app.py"] ``` --- ## 🤝 Contributing We welcome contributions! ### Development Setup 1. Fork the repository. 2. Create a feature branch 3. Make your changes and ensure all features are tested. 4. Submit a pull request. ### Reporting Issues Please report bugs or request features if encountered. --- ## 📄 License This project is licensed under the Apache License 2.0 - see the license file for details. http://www.apache.org/licenses/LICENSE-2.0 --- ## 🙏 Acknowledgments * **LlamaIndex Team** for the powerful RAG framework. * **Mistral AI** for advanced language model capabilities. * **Gradio Team** for the excellent UI framework. * **MCP Community** for the innovative protocol specification. * **HuggingFace** for making this Hackathon possible, free hosting and API credits. * **Generous API Credits from:** * Anthropic * OpenAI * Nebius * Hyperbolic Labs * Sambanova * Open Source Contributors who make projects like this possible. ---
Built with ❤️ for the future of AI-powered education 🌟 Star this repo • 🐛 Report Bug • 💡 Request Feature