🚀 TurnIn - Automated Assignment Completion System

This repository is licensed under a proprietary license. See LICENSE.

TurnIn is a revolutionary Django-based system that automates student assignments using AI agents and Browser Use technology. It provides a seamless, intelligent solution for completing academic work through advanced browser automation.

✨ Features

• 🤖 AI-Powered Assignment Completion: Automatically completes assignments using advanced AI models (GPT-4, Claude, etc.)
• 🌐 Browser Use Integration: Real-time browser automation using the Browser Use library
• 📺 Live Browser Monitoring: Watch the AI agent complete assignments in real-time
• 🧠 Multiple AI Models: Support for OpenAI, Anthropic, Google, and DeepSeek models
• ⚡ WebSocket Support: Real-time updates and live monitoring
• 👥 User Management: Secure user authentication and credential management
• 📊 Admin Interface: Complete admin dashboard for monitoring and management

🎯 How It Works

1. 💬 Natural Conversation: Students chat with the AI assistant about their assignment
2. 🔍 Smart Requirements Gathering: The assistant naturally asks follow-up questions to understand:
   • Assignment type (essay, presentation, research, etc.)
   • Platform to use (Google Docs, Slides, Canvas, etc.)
   • Topic and specific requirements
   • Login credentials (username/password)
3. 🚀 Automatic Trigger: When enough information is gathered, automation starts seamlessly
4. 🌐 Browser Automation: Browser Use agent logs in and completes the assignment
5. 📱 Real-time Monitoring: Watch the AI work through live browser streaming
6. ✅ Completion: Assignment is saved/submitted automatically

Example Conversation:

User: "I need help with my history assignment"
Assistant: "I'd love to help! What type of assignment is it and what's the topic?"
User: "It's a 10-slide presentation about the Irish Potato Famine for Google Slides"
Assistant: "Perfect! I'll need your Google account to create the slides. What are your login credentials?"
User: "username: student@iusd.org, password: mypassword123"
Assistant: "🚀 Perfect! I have everything I need. Starting the automation now - you can watch the progress in real-time!"
[Automation begins automatically]

🚀 Quick Start

1. Installation

# Activate virtual environment (already created)
source venv/bin/activate

# Install dependencies (already done)
pip install -r requirements.txt

# Install Playwright browsers (already done)
playwright install chromium

2. Configuration

IMPORTANT: Create a .env file in the project root with your API keys:

# AI Provider API Keys (REQUIRED for automation)
# At minimum, you need OPENAI_API_KEY for the system to work
OPENAI_API_KEY=sk-your-actual-openai-key-here

# Optional: Other AI providers
ANTHROPIC_API_KEY=your-anthropic-api-key-here
GOOGLE_API_KEY=your-google-api-key-here
DEEPSEEK_API_KEY=your-deepseek-api-key-here

# Optional: Browser Use Cloud (for remote automation)
BROWSER_USE_CLOUD_API_KEY=your-browser-use-cloud-key-here

# Django Configuration
SECRET_KEY=django-insecure-change-this-key-in-production
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Browser Use Configuration
BROWSER_USE_HEADLESS=False
BROWSER_USE_TIMEOUT=300
BROWSER_USE_SCREENSHOT_QUALITY=90

# IUSD Configuration
IUSD_LOGIN_URL=https://iusd.k12.ca.us/login
ALLOWED_DOMAINS=iusd.k12.ca.us,google.com,classroom.google.com

3. Database Setup (Already Done)

# Migrations already created and applied
python manage.py makemigrations
python manage.py migrate

# Superuser already created (admin/admin123)
python manage.py createsuperuser

4. Start the Server

python manage.py runserver

Visit http://localhost:8000 to access the application!

2.1 Email delivery (SMTP)

To send real emails, add SMTP settings to your .env (dotenv is loaded by turnin/settings.py). Example:

EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USE_TLS=True
EMAIL_USE_SSL=False
EMAIL_HOST_USER=your_email@yourdomain.com
EMAIL_HOST_PASSWORD=your_app_password_or_smtp_key
DEFAULT_FROM_EMAIL="Turnin <no-reply@yourdomain.com>"
SERVER_EMAIL="Turnin Server <server@yourdomain.com>"

Notes:

• Use only one of EMAIL_USE_TLS or EMAIL_USE_SSL.
• For Gmail/Workspace, use an App Password (with 2FA) or SMTP relay — normal account password won’t work.
• In DEBUG, the default backend is the console backend (prints emails to terminal). Override EMAIL_BACKEND to SMTP to actually send.

Test delivery:

python manage.py sendtestemail you@example.com

If you receive the message, SMTP is working.

🎮 Usage Guide

For Students

1. 🌐 Access the Website: Open http://localhost:8000 in your browser
2. 💬 Chat Interface: Use the chat interface to describe your assignment
3. 🚀 Start Automation: Click "Start Automation" when prompted
4. 📝 Fill Task Form: Enter your assignment details and IUSD credentials
5. 👀 Live Browser: Watch the AI agent work in the live browser window
6. 📊 Monitor Progress: Track task completion in real-time

For Administrators

1. 🔧 Admin Panel: Access http://localhost:8000/admin (username: admin, password: admin123)
2. 📊 Monitor Tasks: View all automation tasks and their statuses
3. 👥 Manage Users: Handle user accounts and profiles
4. 📋 View Logs: Check system logs for debugging and monitoring
5. ⚙️ System Settings: Configure system-wide settings and preferences

🏗️ Architecture

The system consists of several key components:

• 🏢 Django Backend: Main application server and REST API
• 🤖 Browser Use Service: Handles browser automation and AI agent management
• ⚡ WebSocket Consumers: Real-time updates for live monitoring
• 📋 Task Management: Async task processing and queue management
• 📊 Admin Interface: Management dashboard for monitoring and control

📊 Database Models

• 👤 UserProfile: Extended user information and preferences
• 🌐 BrowserSession: Browser automation session tracking
• 📋 AutomationTask: Individual task records and metadata
• 👣 TaskStep: Detailed step-by-step execution logs
• 📊 TaskResult: Final results and outcomes
• 📝 SystemLog: System-wide logging and debugging

🔌 API Endpoints

Task Management

• POST /api/tasks/create/: Create new automation task
• GET /api/tasks/: List user's tasks
• GET /api/tasks/{id}/: Get task status and details
• POST /api/tasks/{id}/cancel/: Cancel running task
• GET /api/tasks/{id}/result/: Get task results

User Management

• POST /api/credentials/: Save user credentials
• GET /api/logs/: Get system logs (admin only)

WebSocket Endpoints

• ws/task/{task_id}/: Real-time task updates
• ws/browser/{session_id}/: Browser session monitoring

🛡️ Security Features

• 🔐 Secure Authentication: User credentials are stored securely
• 🔑 API Key Management: All API keys stored in environment variables
• 🔒 WebSocket Security: Authenticated WebSocket connections
• 👮 Admin Protection: Admin access restricted to superusers
• 🛡️ API Security: All endpoints require proper authentication

📁 Project Structure

turnin/
├── turnin/                 # Django project settings
│   ├── settings.py        # Updated with Browser Use config
│   ├── urls.py           # URL routing
│   └── asgi.py           # WebSocket support
├── turnin_app/            # Main application
│   ├── models.py         # Database models
│   ├── views.py          # API endpoints
│   ├── browser_service.py # Browser Use integration
│   ├── consumers.py      # WebSocket consumers
│   ├── routing.py        # WebSocket routing
│   ├── admin.py          # Admin interface
│   └── templates/        # Frontend templates
├── requirements.txt      # Python dependencies
├── .env                  # Environment variables
└── README.md            # This file

🚀 Ready to Use!

The system is now fully configured and ready to use:

1. ✅ Dependencies: All packages installed
2. ✅ Database: Models created and migrated
3. ✅ Admin User: Created (admin/admin123)
4. ✅ Browser Support: Playwright browsers installed
5. ✅ Configuration: Environment variables set up
6. ✅ Server: Running on http://localhost:8000

🎯 Next Steps

1. 🔑 Add API Keys: Update the .env file with your actual AI provider API keys
2. 🧪 Test the System: Create a test assignment and watch the AI agent work
3. 👥 Create Users: Set up user accounts for students
4. 📊 Monitor Performance: Use the admin interface to track system performance
5. 🔧 Customize: Modify the system to fit your specific needs

⚠️ Important Notes

• API Keys Required: You need valid API keys for AI providers (OpenAI, Anthropic, etc.)
• Browser Support: System works best with Chrome/Chromium browsers
• IUSD Integration: Designed for IUSD school district (customizable)
• Educational Use: Ensure compliance with academic integrity policies

🆘 Support

For support and questions:

• 📊 Check the admin interface for system logs
• ⚡ Review WebSocket connections for real-time issues
• 👀 Monitor task execution through the live browser feature
• 📧 Contact the development team for technical support

⚠️ Disclaimer

This system is for educational purposes. Users are responsible for ensuring compliance with their institution's academic integrity policies.

---

Made with ❤️ for automating student assignments using AI and Browser Use technology.