Added hackathon deliverables

LICENSE

@@ -0,0 +1,201 @@
+# Apache License
+                        Version 2.0, January 2004
+                    http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined by Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity
+    exercising permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or
+    Object form, made available under the License, as indicated by a
+    copyright notice that is included in or attached to the work
+    (an example is provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original version of the Work and any modifications or additions
+    to that Work or Derivative Works thereof, that is intentionally
+    submitted to Licensor for inclusion in the Work by the copyright owner
+    or by an individual or Legal Entity authorized to submit on behalf of
+    the copyright owner. For the purposes of this definition, "submitted"
+    means any form of electronic, verbal, or written communication sent
+    to the Licensor or its representatives, including but not limited to
+    communication on electronic mailing lists, source code control systems,
+    and issue tracking systems that are managed by, or on behalf of, the
+    Licensor for the purpose of discussing and improving the Work, but
+    excluding communication that is conspicuously marked or otherwise
+    designated in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any individual or Legal Entity
+    on behalf of whom a Contribution has been received by Licensor and
+    subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+        Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+        stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+        that You distribute, all copyright, patent, trademark, and
+        attribution notices from the Source form of the Work,
+        excluding those notices that do not pertain to any part of
+        the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file as part of its
+        distribution, then any Derivative Works that You distribute must
+        include a readable copy of the attribution notices contained
+        within such NOTICE file, excluding those notices that do not
+        pertain to any part of the Derivative Works, in at least one
+        of the following places: within a NOTICE text file distributed
+        as part of the Derivative Works; within the Source form or
+        documentation, if provided along with the Derivative Works; or,
+        within a display generated by the Derivative Works, if and
+        wherever such third-party notices normally appear. The contents
+        of the NOTICE file are for informational purposes only and
+        do not modify the License. You may add Your own attribution
+        notices within Derivative Works that You distribute, alongside
+        or as an addendum to the NOTICE text from the Work, provided
+        that such additional attribution notices cannot be construed
+        as modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to the Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+    To apply the Apache License to your work, attach the following
+    boilerplate notice, with the fields enclosed by brackets "[]"
+    replaced with your own identifying information. (Don't include
+    the brackets!)  The text should be enclosed in the appropriate
+    comment syntax for the file format. We also recommend that a
+    file or class name and description of purpose be included on the
+    same "printed page" as the copyright notice for easier
+    identification within third-party archives.
+
+Copyright [yyyy] [name of copyright owner]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -8,67 +8,223 @@ sdk_version: 5.32.0
 app_file: app.py
 pinned: false
 license: apache-2.0
+tags:
+  - agent-demo-track
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🚀 LearnFlow AI: Revolutionizing Learning with AI Agents & MCP
 
-## LearnFlow AI: An AI-Powered Learning Platform with MCP Server Integration
+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.
 
-LearnFlow AI is an interactive learning platform that leverages AI to generate personalized learning units, explanations, and quizzes from your content. This project also features an integrated Model Context Protocol (MCP) server, enabling its functionalities to be exposed as tools for other AI agents and systems.
+## 🎯 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.
 
-### Features:
-- **Content Planning:** Upload documents (PDF, DOC, TXT, PPTX, MD) or paste text to generate structured learning units.
-- **Interactive Learning:** Get AI-powered explanations tailored to your preferred learning style (concise or detailed).
-- **Knowledge Assessment:** Test your understanding with AI-generated quizzes of various types (Multiple Choice, Open-Ended, True/False, Fill in the Blank) and difficulties.
-- **Progress Tracking:** Monitor your learning journey with detailed analytics and overall progress.
-- **Session Management:** Save and load your learning sessions.
-- **Export Options:** Export your learning content as Markdown, HTML, or PDF.
-- **MCP Server Integration:** Exposes core LearnFlow AI functionalities as MCP tools, allowing external agents to interact with the platform programmatically.
+---
+## ✨ 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.
 
-### Running Locally:
+### ⚡ 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**.
 
-1.  **Clone the repository:**
+---
+## 🚀 Quick Start
+
+### Prerequisites
+*   Python 3.8+
+*   Node.js 16+ (for MCP server)
+*   4GB+ RAM recommended
+
+### Installation
+1.  **Clone the repository**
     ```bash
-    git clone https://github.com/your-repo/LearnFlow-AI.git
+    git clone https://huggingface.co/spaces/Kyo-Kai/LearnFlow-AI
     cd LearnFlow-AI
     ```
-
-2.  **Set up the Python environment:**
+2.  **Set up Python environment**
     ```bash
     python -m venv .venv
-    # On Windows:
+
+    # Windows
     .venv\Scripts\activate
-    # On macOS/Linux:
+
+    # macOS/Linux
     source .venv/bin/activate
+
     pip install -r requirements.txt
     ```
-
-3.  **Set up the Node.js MCP Server:**
-    The MCP server is located in the `mcp_server/learnflow-mcp-server` directory.
+3.  **Configure MCP Server**
     ```bash
     cd mcp_server/learnflow-mcp-server
     npm install
     npm run build
     ```
-    Ensure that the `LEARNFLOW_AI_ROOT` environment variable is correctly set to the project root directory when running the MCP server. The `app.py` script handles launching the MCP server automatically with the correct environment variables when the Gradio app starts.
+4.  **Environment Configuration**
+    ```bash
+    # Copy example environment file
+    cp .env.example .env
 
-4.  **Run the Gradio Application:**
+    # 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 Gradio application will launch, and the MCP server will automatically start in the background.
+    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
+```
 
-### Deployment on Hugging Face Spaces:
+### 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
 
-To deploy LearnFlow AI on Hugging Face Spaces, you need to ensure both the Python Gradio app and the Node.js MCP server are correctly set up.
+---
+## 🚀 Deployment
 
-1.  **`app.py`:** The main Gradio application file. It is configured to automatically launch the Node.js MCP server as a background process.
-2.  **`requirements.txt`:** Lists all Python dependencies.
-3.  **`packages.txt`:** (Create this file if it doesn't exist) This file is crucial for Hugging Face Spaces to install system-level dependencies, including Node.js. Add `nodejs` to this file:
+### Hugging Face Spaces
+1.  **Create `packages.txt`**
     ```
     nodejs
+    chromium
     ```
-4.  **MCP Server Directory:** Ensure the `mcp_server/learnflow-mcp-server` directory (or its equivalent path within your project structure) is included in your Hugging Face Space. The `app.py` script expects the compiled server to be at `learnflow-mcp-server/build/index.js` relative to the project root.
-5.  **Environment Variables:** The `app.py` script sets `LEARNFLOW_AI_ROOT` automatically for the MCP server subprocess. No manual configuration is typically needed for this specific variable on Spaces if the directory structure is maintained.
+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.
 
-By following these steps, your LearnFlow AI application, including its MCP server, should be ready for deployment and interaction on Hugging Face Spaces.
+---
+## 📄 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>