---
title: AI Python Tutor
emoji: 📚
colorFrom: pink
colorTo: indigo
sdk: gradio
sdk_version: 5.49.1
app_file: app.py
pinned: false
short_description: AI Python Tutor
---

# 🏷️ Track Tag
mcp-in-action-track-consumer

# 📚 AI-Python-Tutor

An **Autonomous Python Tutor** that teaches through hands-on code execution — writing Python files, running them, analyzing errors, and providing curated learning resources using MCP tools and autonomous reasoning.

> use openai/gpt-oss-120b for better results.
 
---

# 🚀 Project Overview

**AI-Python-Tutor ("Vibe Coding Academy")** is an **AI-powered educational agent** that uses MCP (Model Context Protocol) servers to deliver interactive coding lessons.
Unlike standard chatbots, this agent can:

* **Write real Python files** to a sandbox environment
* **Execute Python code** and show real output
* **Debug errors live** with explanations
* **Curate videos, articles, quizzes,** and documentation dynamically
* **Use LangGraph** for structured and modular lesson planning

It demonstrates the power of **MCP tools** (`write_file`, `run_python_script`) combined with autonomous reasoning to create a full teaching workflow.

---

# 🎯 Key Features

* **Interactive Coding Lessons**
    Ask the tutor to teach any topic (e.g., Decorators, Recursion), and it explains the concept using live code.
* **Live Code Execution**
    The agent writes `.py` files and executes them using MCP tools, showing real output.
* **Learning Dashboard**
    A dedicated panel showing:
    * 📺 Recommended Videos
    * 📚 Articles & Documentation
    * 🧠 Knowledge Check Quizzes
* **Focus Mode UI**
    A “Slate” themed distraction-free full-screen learning interface.
* **MCP Integration**
    Modular architecture using `server.py` to handle safe file operations and code execution.

---

# 🛠️ How to Use

1.  **Open the HuggingFace Space**
2.  **Ask a question** such as:
    * "How do Python dictionaries work?"
    * "Write a script for Fibonacci numbers."
3.  **Watch the agent:**
    * Explain the concept
    * Write the Python file (e.g., `demo_dict.py`)
    * Execute it and show the output
4.  **Explore the Learning Dashboard** for videos, articles, and quizzes
5.  **Use Focus Mode** to switch to a clean, immersive UI

---

# 🎥 Demo Video

Watch the agent in action:[![Watch the demo](https://img.youtube.com/vi/FRq1u_0WkiM/0.jpg)](https://youtu.be/FRq1u_0WkiM)

---

## 👥 Team
| Name | HuggingFace Username |
|------|--------------------|
| Ahmed Samir | @ABO4SAMRA |
| Omar Ahmed | @omarash2016 |
| Mohamed Ahmed | @Mohamed-Hosny |

> All members have joined the Hackathon organization and registered for the event.

---

## 📱 Social Media
Check our project post: https://www.linkedin.com/posts/omar-ahmed-5738ab332_hackathon-ai-python-activity-7400683397657899008-vp5h?utm_source=share&utm_medium=member_desktop&rcm=ACoAAFPIN2cB-lsuDIEpLKFLGfsM6T0lhAr8tl4

---

# ⚙️ Requirements

* Gradio app with **MCP server support**
* `NEBIUS_API_KEY` environment variable for LLM inference (`openai/gpt-oss-20b`)
* **Python dependencies:** `gradio`, `langgraph`, `mcp`, `langchain_openai`