AcadAgent, tailored specifically to the structured application factory version of your code.

AcadAgent is an autonomous AI agent designed to help students and researchers navigate the academic world. From drafting research proposals and generating professional cover images to monitoring emails and communicating with professors on your behalf, AcadAgent acts as your personalized academic concierge.

AcadAgent leverages the full Gemini 3 family in production. Gemini 3 Pro with high-level thinking analyzes incoming emails using function calling to detect 9 action types (acceptance, rejection, forward requests, etc.) and extract structured data. Thought signatures preserve reasoning continuity across multi-turn conversations spanning days. Gemini 3 Flash with search grounding handles fast document drafting and professor email discovery via web search. Gemini 3 Image generates academic diagrams and cover images. Gemini 2.5 Flash Native Audio powers real-time voice tutoring—students show documents to their camera while the AI explains concepts verbally, with audio streaming via PyAudio and video via OpenCV. The system uses code execution for PDF generation, URL context for research retrieval, and structured outputs via function calling schemas. Context flows seamlessly between modalities: text chat history informs voice sessions, email analysis triggers autonomous actions, and thought signatures maintain reasoning chains across server restarts. Gemini isn't just a feature—it's the orchestration brain enabling true autonomy through persistent background monitoring (Celery), intelligent decision-making (function calling), and multimodal interaction (audio + video + text).

• Autonomous Email Agent: Monitors your inbox for professor responses, analyzes sentiment, and drafts/sends follow-up emails or revisions autonomously.
• Research Proposal Generator: Drafts professional academic proposals and generates high-quality PDF documents.
• Multimodal Chat: Interaction via text, image, audio, and video files using Google’s Gemini 3 Pro/Flash.
• 👨‍🏫 Live Teacher Mode: Real-time audio and video interaction. Hold up a document to your camera, and AcadAgent will see it, hear you, and teach you.
• AI Cover Art: Uses Gemini 3 Pro Image to create professional cover art for your research documents.
• Automatic Email Finder: Searches the web to find official contact information for professors and lecturers.
• Task Management: A dashboard that tracks the status of your applications and agent actions in real-time.

• Backend: Python 3.10+, Flask
• Database: SQLite (via SQLAlchemy)
• Real-time: Flask-SocketIO (with Eventlet)
• Task Queue: Celery + Redis
• AI Engine: Google Gemini (3 Pro, 3 Flash, 3 Pro Image, 2.5 Flash Native Audio)
• Document Generation: ReportLab (PDF)
• Media Handling: OpenCV (Video), PyAudio (Audio)
• Auth: Flask-Login + Google OAuth (Authlib)

Before running AcadAgent, ensure you have the following:

1. Redis Server: Installed and running (Required for Celery).
2. Google API Key: An API key from Google AI Studio for Gemini.
3. Gmail App Password: To allow the agent to send/receive emails (Use a Gmail App Password, not your standard password).
4. System Libraries:
   • Linux: sudo apt install libasound-dev portaudio19-dev libgl1
   • macOS: brew install portaudio

1. Clone the repository:

   git clone https://github.com/Jerryblessed/acadagent.git
   cd acadagent

2. Create and activate a virtual environment:

   python -m venv .venv
   # Windows:
   .venv\Scripts\activate
   # Linux/macOS:
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

4. Configuration: Open config.py and update the following:

   • SECRET_KEY: A unique random string.
   • GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET: For Google login.
   • EMAIL_USER & EMAIL_PASS: Your Gmail credentials (App Password).
   • GEMINI_API_KEY: Your Gemini key.

AcadAgent requires three components to be running simultaneously. Open three terminal windows:

redis-server

This handles the background email monitoring and autonomous actions.

celery -A run.celery_app worker --beat --loglevel=info

python run.py

Access the dashboard at: http://localhost:5002

acadagent/
├── app/
│   ├── __init__.py          # App Factory & Extension Init
│   ├── models.py            # Database Schemas
│   ├── tasks.py             # Celery Background Tasks
│   ├── templates.py         # Base HTML Wrapper
│   ├── routes/
│   │   ├── auth.py          # Login/Register/Google OAuth
│   │   ├── main.py          # Dashboard & Proposal Creation
│   │   ├── api.py           # Internal Agent Endpoints
│   │   └── chat.py          # Professor-Agent Chat Interface
│   └── services/
│       ├── gemini_agent.py  # Gemini AI Reasoning Logic
│       ├── email_service.py # SMTP/IMAP Logic
│       └── voice_chat.py    # Real-time Audio/Video Logic
├── uploads/                 # Storage for CVs and media
├── config.py                # Environment Configuration
├── requirements.txt         # Dependencies
└── run.py                   # Entry point

• This application uses Eventlet for WebSockets; avoid using flask run. Always use python run.py.
• Ensure the uploads/ folder is protected and not accessible publicly in a production environment.
• Never commit your config.py with real passwords or API keys to a public repository. Use .env files for production.

MIT License — Created for academic empowerment.