README.md

metadata

title: Gnosis Tutor
emoji: 🎓
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.0.0
app_file: app.py
pinned: false
license: mit
short_description: AI tutor that parses lectures and creates quizzes
tags:
  - mcp-in-action-track-consumer
  - mcp-in-action-track-creative
  - education
  - quiz
  - nlp
  - llm

🎓 Gnosis Tutor - AI-Powered Learning Platform

Gnosis (Greek: Γνώση - Knowledge) is an intelligent tutoring system that transforms lecture slides, research papers, and educational documents into interactive learning experiences. Built with Gradio 6 and MCP (Model Context Protocol) for seamless AI-powered tutoring.

🎥 Demo Video: Check out the demo video in the Welcome tab of the app! The video file (demo.mp4) is included in this repository and can be viewed directly from the application interface.

📱 Social Media: View my LinkedIn post about building Gnosis for the hackathon

🌟 Features

Web Application Features

• 📄 Document Analysis: Upload PDF lecture slides and automatically extract key concepts, topics, and structure
• 🎯 Concept Extraction: AI-powered extraction of programming and CS concepts from educational content
• ❓ Interactive Quiz Generation: Generate multiple-choice quizzes based on extracted concepts with immediate feedback
• 📚 Curriculum Builder: Create structured learning paths with progressive exercises
• 🔍 Resource Discovery: Find relevant documentation, tutorials, and learning materials
• 💬 Socratic Tutoring: Get guided learning through questions instead of direct answers
• 🤖 Multi-LLM Support: Choose from Gemini, OpenAI, Anthropic, or HuggingFace models

MCP Server Integration

• 🔌 MCP Server: Connect Gnosis to Cursor IDE or Claude Desktop via SSE/HTTP
• 🛠️ Coding Exercises: Generate complete exercise packages with starter code, tests, and hints
• 📝 Code Analysis: Get feedback on your code and understand what you've learned
• 🎓 Guided Learning: Socratic method tutoring for programming concepts

🚀 How It Works

Web Application Flow

1. Setup: Select your LLM provider and enter your API key in the Welcome tab
2. Learn: Chat with Gnosis about what you want to learn, or upload a PDF document
3. Extract: AI automatically extracts concepts, topics, and key points from your content
4. Practice: Generate interactive quizzes to test your understanding
5. Explore: Use curriculum builder, resource search, or Socratic tutoring for deeper learning

MCP Integration Flow

1. Connect: Add Gnosis to your ~/.cursor/mcp.json or Claude config
2. Use: Simply ask the AI to generate quizzes, exercises, or learning paths
3. Learn: Complete coding exercises with real-time feedback and guidance

🛠️ Technology Stack

• Gradio 6.0: Modern, interactive web interface with built-in MCP server support
• MCP (Model Context Protocol): Enables seamless integration with Cursor IDE and Claude Desktop
• Multi-LLM Support: Gemini, OpenAI, Anthropic, and HuggingFace API integration
• PDF Processing: Document parsing and concept extraction from educational materials
• Python: Core backend with modular architecture for extensibility

📖 Documentation

Getting Started

1. Access the App: Visit the HuggingFace Space
2. Watch the Demo: Check out the demo video in the Welcome tab
3. Set Up API Key:
   • Choose your LLM provider (Gemini recommended for free tier)
   • Enter your API key
   • Click "Save & Connect"

Using the Web Application

Chat Interface

• Type questions or topics you want to learn about
• Upload PDF documents for automatic concept extraction
• Get instant responses with explanations and examples

Quiz Generation

• Ask "Generate a quiz on [topic]" or use the Quick Actions panel
• Answer questions and get immediate feedback
• Navigate through questions with Previous/Next buttons
• View your score and explanations

Sidebar Features

• Extracted Data: View concepts, topics, and key points from uploaded documents
• MCP Server: Setup instructions for connecting to Cursor or Claude Desktop
• Quick Actions: One-click quiz, curriculum, or resource generation

MCP Server Setup

For Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gnosis": {
      "url": "https://mcp-1st-birthday-gnosis.hf.space/gradio_api/mcp/sse"
    }
  }
}

For Claude Desktop

Add similar configuration to your Claude config file.

Available MCP Tools

• generate_quiz: Create quizzes on any topic
• generate_curriculum: Build progressive learning paths
• generate_exercise: Create coding exercises with tests
• search_resources: Find documentation and tutorials
• ask_guiding_question: Get Socratic tutoring help
• analyze_code: Get feedback on your code

API Endpoints

The app exposes several API endpoints for MCP integration:

• submit_chat: Main chat endpoint
• generate_quiz: Generate quiz questions
• generate_curriculum: Create learning curriculum
• generate_exercise: Create coding exercises
• search_resources: Search for learning resources
• ask_guiding_question: Get guiding questions
• analyze_code: Analyze student code
• handle_quiz_submit: Submit quiz answers
• next_question / prev_question: Navigate quiz questions
• save_api_key: Save LLM provider API key

📚 Use Cases

• Students: Transform lecture notes into practice quizzes
• Educators: Quickly generate quiz questions from course materials
• Self-Learners: Create personalized study materials from any educational PDF
• Review Sessions: Generate targeted practice questions for exam preparation

🎯 Hackathon Submission

This project is submitted to the MCP 1st Birthday Hackathon organized by Hugging Face and Gradio.

Submission Details

• Track: MCP in Action (Consumer & Creative categories)
• Project Name: Gnosis Tutor
• Demo Video: Available in the Welcome tab of the app (demo.mp4 in repository)
• Social Media: LinkedIn Post

Key Features Demonstrated

• ✅ Autonomous agent behavior through intelligent document analysis
• ✅ MCP server integration with SSE/HTTP transport
• ✅ Multiple MCP tools for educational purposes
• ✅ Practical educational value for students and learners
• ✅ Beautiful, modern UI with glassmorphism design
• ✅ Multi-LLM provider support

Project Journey

Built in one week as my first hackathon project, learning MCP and Gradio from scratch. The project demonstrates rapid learning and application of new technologies under tight time constraints.

🔧 Setup & Installation

Running on HuggingFace Spaces

The app is automatically deployed and runs on HuggingFace Spaces. No setup required!

Running Locally

1. Clone the repository:

git clone https://huggingface.co/spaces/MCP-1st-Birthday/Gnosis
cd Gnosis

2. Install dependencies:

pip install -r requirements.txt

3. Run the application:

python app.py

4. Set up API keys (optional, can be set in the UI):
   • Set environment variables or use the in-app API key configuration
   • Supported providers: Gemini, OpenAI, Anthropic, HuggingFace

Project Structure

Gnosis/
├── app.py                 # Main Gradio application
├── mcp_server.py         # MCP server implementation
├── core/                 # Core functionality
│   ├── state.py          # Global state management
│   ├── mcp_client.py     # MCP client integration
│   └── helpers.py        # Helper functions
├── handlers/             # Event handlers
│   ├── chat_handlers.py  # Chat interaction handlers
│   ├── quiz_handlers.py  # Quiz generation and management
│   ├── content_handlers.py # Content extraction handlers
│   └── mcp_handlers.py   # MCP tool handlers
├── ui/                   # UI components and styling
│   ├── components.py     # UI component functions
│   └── styles.css        # Custom CSS styling
├── utils/                # Utility modules
│   ├── tutor.py          # Core tutoring logic
│   ├── quiz_generator.py # Quiz generation
│   └── llm_client.py     # LLM client wrapper
└── demo.mp4             # Demo video (viewable in app)

📝 License

MIT License - Feel free to use and modify for your own projects!

📝 License

MIT