PyPal — AI Python Tutor

An AI-powered tutor for absolute-beginner Python programmers, built on an OpenAI-compatible Chat Completions API (Groq by default, OpenAI optional) and a Streamlit chat UI. PyPal covers all five Core Tutoring Modules from the project brief: concept explanation, code examples, debugging, exercise generation, and feedback.

Features

• Concept Explainer — plain-English explanations of Python fundamentals.
• Code Example Generator — annotated examples with line-by-line walkthroughs.
• Error Debugger — finds the bug, explains why it fails, shows the fix.
• Exercise Creator — generates beginner practice problems with hints.
• Feedback Provider — kind, concrete feedback on student attempts.
• Auto-mode detection — keyword-based router picks the right module from the user's message; can be overridden from the sidebar.
• Tokenization + cost analysis — every turn reports prompt/completion tokens and estimated USD cost; the sidebar can show a tokenization breakdown of the user's last message.

Quick start

# 1. Clone and enter the repo
git clone https://github.com/<you>/ai-python-tutor.git
cd ai-python-tutor

# 2. Install deps
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# 3. Add your API key
cp .env.example .env
# then edit .env:
#   - PROVIDER=groq  (default, free tier)  → fill in GROQ_API_KEY
#   - PROVIDER=openai (paid)               → fill in OPENAI_API_KEY
# Get a Groq key at https://console.groq.com/keys (no credit card required).

# 4. Run the app
streamlit run app.py

Open the URL Streamlit prints (usually http://localhost:8501).

Project layout

ai-python-tutor/
├── app.py              # Streamlit entry point
├── src/
│   ├── tutor.py        # Tutor class — wraps the OpenAI client
│   ├── prompts.py      # System prompts for the 5 modules
│   ├── intent.py       # Keyword-based mode detector
│   └── cost.py         # tiktoken-based token + cost analysis
├── report/             # Project report (.docx)
├── requirements.txt
├── .env.example
└── README.md

Demo prompts (one per module)

Use these in the video demo to show each Core Tutoring Module:

Module	Try typing
Concept Explainer	Explain what a Python function is.
Code Example Generator	Show me an example of a for loop.
Error Debugger	This code gives an error, why? python<br>for i in range(3)<br> print(i)<br>
Exercise Creator	Give me a beginner exercise about while loops.
Feedback Provider	Can you give me feedback on my code? python<br>def add(a, b):<br> return a - b<br>

Configuration

• Provider — set PROVIDER=groq or PROVIDER=openai in .env. The sidebar reflects the active provider and exposes its models.
• Model — change in the sidebar. Groq default is llama-3.3-70b-versatile; OpenAI default is gpt-4o-mini. Pricing is set in src/cost.py.
• Mode override — by default the tutor auto-detects intent from your message. Pick a specific mode in the sidebar to force it.

How it works (one-paragraph summary)

The user message is routed to one of five system prompts (see src/prompts.py). Each prompt locks the model to a structured Markdown response so the four required sections (Concept Explanation, Code Example, Practice Exercise, Feedback) appear consistently and are easy to grade. The OpenAI Chat Completions API returns the answer along with usage token counts, which src/cost.py converts to a USD estimate using the per-million-token prices for the selected model. Conversation history is kept in st.session_state and the last six turns are sent back to the model on each call so follow-ups have context without unbounded cost growth.

License

MIT.