Spaces:
Sleeping
Sleeping
| 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. | |
| --- | |
| <div align="center"> | |
| Built with ❤️ for the future of AI-powered education | |
| 🌟 Star this repo • 🐛 Report Bug • 💡 Request Feature | |
| </div> | |