|
|
--- |
|
|
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> |
|
|
|
|
|
|
