TimmyTutorials

An interactive AI-powered coding tutor that guides learners through code in approachable, incremental blocks. Upload a PDF brief or write a free-form prompt to generate step-by-step lessons with code samples, written explanations, and optional speech features.

Features

• PDF Upload Support: Extract text from PDFs using hybrid OCR (Tesseract + OpenAI Vision fallback)
• AI-Powered Lessons: GPT-4o-mini generates step-by-step tutorials tailored to your needs
• Interactive Code Blocks: View, download, and explore code with line-by-line explanations
• Voice Integration: Text-to-speech narration and speech-to-text input via Deepgram
• Multi-File Support: Handle complex tutorials with multiple code files
• Real-time Q&A: Ask questions about specific lines or concepts during the lesson
• Session Persistence: Continue your learning across page refreshes

Prerequisites

• Python 3.13 or higher
• Tesseract OCR installed and available on your PATH
• uv package manager (recommended) or pip

Environment Variables

Create a .env file in the flask-app directory with the following:

OPENAI_API_KEY=your_openai_api_key_here
DEEPGRAM_API_KEY=your_deepgram_api_key_here
SECRET_KEY=your_flask_secret_key_here  # Optional: defaults to 'dev-secret'

Getting API Keys

• OpenAI: Sign up at platform.openai.com
• Deepgram: Get a free API key at deepgram.com

Dependencies

Core Dependencies

flask>=3.1.2
gunicorn>=23.0.0
openai>=2.7.2
pillow>=12.0.0
pypdf2>=3.0.1
pytesseract>=0.3.13
python-dotenv>=1.2.1
requests>=2.32.5

These are automatically installed when using uv sync or can be installed via pip using the methods above.

Using uv (Recommended)

cd flask-app
uv sync

Using pip

First, generate requirements.txt from pyproject.toml:

cd flask-app
pip install uv
uv pip compile pyproject.toml -o requirements.txt
pip install -r requirements.txt

Or install directly from pyproject.toml:

cd flask-app
pip install -e .

Running the Application

Local Development

cd flask-app
uv run flask --app app run --debug

Or with Python directly:

cd flask-app
uv run python run.py

The application will be available at http://localhost:5000

Using Docker Compose

docker-compose up --build

Services:

• Flask API: http://localhost:5000
• VSCode Extension (if configured): http://localhost:3000

Project Structure

TimmyTutorials/
├── flask-app/
│   ├── app/
│   │   ├── __init__.py           # Flask app factory
│   │   ├── config.py             # Configuration management
│   │   ├── routes.py             # API endpoints
│   │   ├── tutorial.py           # Tutorial orchestration logic
│   │   ├── pdf_utils.py          # Hybrid OCR pipeline
│   │   └── deepgram_client.py    # Text-to-speech & speech-to-text
│   ├── static/
│   │   ├── css/style.css         # Custom styles
│   │   └── js/main.js            # Frontend logic
│   ├── templates/
│   │   ├── index.html            # Landing page
│   │   └── tutorial.html         # Interactive tutorial workspace
│   ├── Dockerfile                # Flask app containerization
│   ├── pyproject.toml            # Python dependencies
│   ├── run.py                    # Application entry point
│   └── .env                      # Environment variables (not tracked)
├── vscode-app/                   # VSCode extension (optional)
├── docker-compose.yml            # Multi-service orchestration
└── README.md                     # This file

API Endpoints

Endpoint	Method	Description
/	GET	Landing page for starting tutorials
/tutorial	GET	Interactive tutorial workspace
/start_tutorial	POST	Initialize a new tutorial session
/continue_tutorial	POST	Get the next step or answer questions
/session/<id>	GET	Retrieve session history
/tts	POST	Text-to-speech conversion
/stt	POST	Speech-to-text transcription

Usage

Starting a Tutorial

1. Via Prompt: Enter what you want to learn (e.g., "Build a Flask CRUD API with SQLite")
2. Via PDF: Upload a project brief or specification document
3. Combined: Provide both for enhanced context

Interactive Features

• Line Explanations: Hover over code and click the explain button
• Ask Questions: Use the Q&A input or voice recording
• Modify Code: Request changes or improvements to generated code
• Download: Save individual code files or view in a new tab
• Listen: Use text-to-speech to narrate explanations

Development

Running Tests

cd flask-app
uv run pytest  # Add tests directory as needed

Code Quality

# Format code
uv run black app/

# Lint
uv run flake8 app/

# Type checking
uv run mypy app/

Architecture

AWS Deployment

This application is deployed on AWS using:

• AWS ECS cluster for Orchestration
• VPC network isolation and security groups
• ECR for container registration

PDF Processing Pipeline

1. PyPDF2 Extraction: Fast text extraction for digital PDFs
2. Tesseract OCR: Process scanned documents
3. OpenAI Vision: Fallback for complex layouts or failed extraction
4. Garbage Detection: Heuristics to validate OCR quality

Tutorial Generation

• Incremental Steps: One code block per response
• Context Preservation: Full conversation history maintained
• Smart Parsing: Automatic filename detection from code comments
• Multi-Language Support: Syntax highlighting for various languages

Important Notes

Session Storage

This application uses in-memory storage (Python dictionary) for session management. This is an intentional design choice for simplicity and rapid development.

Characteristics:

• ✅ Fast and simple
• ✅ No external dependencies
• ✅ Perfect for development and demos
• ⚠️ Sessions are lost on server restart
• ⚠️ Not suitable for multi-worker deployments (Gunicorn with multiple processes)
• ⚠️ Limited scalability

For single-user or demo purposes, this is perfectly adequate. The in-memory approach keeps the codebase simple and reduces infrastructure requirements.

If you need persistence or multi-user support, consider:

• Redis for distributed session storage
• PostgreSQL with a session table
• File-based session storage for single-worker deployments

Security Considerations

AWS Deployment

This application is deployed on AWS, which provides infrastructure-level security through:

• AWS ECS cluster for Orchestration
• VPC network isolation and security groups
• ECR for container registration

Application-Level Security

Current implementation includes:

• ✅ File upload size limits (16MB via Flask config)
• ✅ PDF/image file type validation
• ✅ Environment-based secrets management (.env)
• ✅ Input sanitization in frontend
• ✅ HTTPS/TLS via AWS infrastructure

Development Considerations

For local development and testing:

• Keep API keys in .env files (never commit to git)
• Use separate API keys for development vs. production
• Monitor OpenAI API usage to prevent unexpected costs
• Be aware that sessions are stored in-memory and reset on restart

Troubleshooting

Tesseract Not Found

# macOS
brew install tesseract

# Ubuntu/Debian
sudo apt-get install tesseract-ocr

# Windows
# Download installer from https://github.com/UB-Mannheim/tesseract/wiki

OpenAI API Errors

• Verify your API key is valid
• Check your account has sufficient credits
• Ensure you're using a supported model (gpt-4o-mini)

Deepgram Issues

• Confirm your API key is active
• Check microphone permissions in browser
• Verify audio format compatibility (WebM supported)

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Authors

• Nathan Roos
• Shawn Nabizada
• Amir Ghagimi
• Jeremy Roos

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• OpenAI for GPT-4 API
• Deepgram for voice services
• Flask community for excellent documentation
• Tailwind CSS for UI components

Roadmap

• User authentication and profiles
• Tutorial history and bookmarks
• Code execution sandbox
• Real-time collaboration
• Custom tutor personalities
• Mobile-responsive improvements
• Integration with GitHub repositories
• Progress tracking and analytics

Support

For issues, questions, or suggestions:

• Open an issue on GitHub
• Contact the development team

---

Note: This is a prototype application. Use with appropriate security measures and testing before production deployment.