📚 Personal Tutor Planner (Agentic AI)

An AI-powered study scheduling system that generates personalized weekly study plans by analyzing syllabus topics, quiz performance, and student preferences. Features both an agentic LLM mode (with tool calling and autonomous reasoning) and a deterministic rule-based mode for reliable, cost-free planning.

---

Problem

Students juggling multiple courses often struggle to prioritize what to study and when. Static study schedules don't adapt to actual performance — a student falling behind in one topic continues to allocate equal time across all topics. Existing tools are either too rigid (fixed calendars) or too vague (generic advice).

Tutor Planner solves this by combining urgency-aware scheduling, quiz-driven weakness detection, and an LLM agent that can reason about a student's situation and dynamically adjust the plan.

---

Key Features

• Dual Planning Modes — Switch between an agentic LLM-driven planner (Groq/Llama 3.3 70B) and a deterministic algorithm, giving users control over cost and reliability tradeoffs.
• Weighted Priority Scoring — A composite scoring formula (0.45 × urgency + 0.35 × weakness + 0.20 × weight) ranks topics by combining due-date proximity, quiz-based weakness scores, and syllabus weight.
• Quiz Performance Analysis — Tracks per-topic score trends (improving, declining, stable), flags weak areas (score < 0.6), and feeds weakness maps into the planner.
• Agentic Tool Calling — The LLM agent autonomously inspects topics, quiz scores, weakness maps, and current plans through registered tools before generating or adjusting schedules.
• Conversational Study Agent — A chat interface where students can ask questions like "Why is Logistic Regression ranked so high?" or "Give me more time on Linear Regression" and the agent responds with context-aware adjustments.
• Smart Slot Scheduling — A greedy scheduler fills configurable time windows (focus days, study hours, session/break lengths) with priority-sorted study sessions.
• Calendar Export — Generates .ics files importable into Google Calendar, Apple Calendar, or Outlook.
• Per-Course Preferences — Timezone, daily study hours, focus days, session duration, and break intervals — all configurable per course.
• SQLite Persistence — Full relational schema with courses, topics, quiz results, tasks, preferences, and agent run logging.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Streamlit UI (app.py)                 │
│         Course selection · Inputs · Preferences         │
│         Plan controls · Task actions · Agent chat        │
└────────────────┬──────────────────────┬─────────────────┘
                 │                      │
        Agentic Mode             Deterministic Mode
                 │                      │
    ┌────────────▼────────────┐   ┌─────▼──────────────┐
    │   Orchestrator          │   │  Orchestrator       │
    │   (LLM + Tool Loop)    │   │  (Direct Pipeline)  │
    │                         │   │                     │
    │  ┌───────────────────┐  │   │  planner.py         │
    │  │  llm_client.py    │  │   │  slot_finder.py     │
    │  │  Groq API (Llama) │  │   │  calendar_ics.py    │
    │  │  Tool call loop   │  │   └─────────────────────┘
    │  └────────┬──────────┘  │
    │           │              │
    │  ┌────────▼──────────┐  │
    │  │  tools.py         │  │
    │  │  10 registered    │  │
    │  │  tool functions   │  │
    │  └───────────────────┘  │
    └─────────────────────────┘
                 │
        ┌────────▼────────┐
        │   SQLite (db/)  │
        │   store.py      │
        │   schema.sql    │
        └─────────────────┘

Core Modules

Module	Purpose
app.py	Streamlit frontend — course management, plan controls, task actions, agent chat
core/orchestrator.py	Entry points for both agentic (LLM-driven) and deterministic planning pipelines
core/llm_client.py	Groq API wrapper with automatic tool-call execution loop (up to 6 rounds)
core/tools.py	10 LLM-callable tools registered via decorator pattern — data inspection, plan generation, task mutations, topic replanning
core/planner.py	Priority scoring engine and weekly task builder with budget-constrained allocation
core/slot_finder.py	Time slot generation and greedy scheduling algorithm
core/quiz_analyzer.py	Performance trend analysis with declining/improving detection and weakness flagging
core/syllabus_parser.py	Flexible text parser supporting Topic | due=YYYY-MM-DD | weight=N | minutes=N format
db/store.py	SQLite data access layer — CRUD for courses, topics, quizzes, tasks, preferences
db/schema.sql	Relational schema with 6 tables, foreign keys, and cascading deletes
integrations/calendar_ics.py	ICS calendar file generation for study session export

---

Tech Stack

• Language: Python 3.11+
• Frontend: Streamlit
• LLM: Llama 3.3 70B via Groq API (OpenAI-compatible client)
• Database: SQLite with raw SQL schema
• Data Processing: Pandas
• Calendar: ICS file generation
• Architecture Patterns: Tool-calling agent loop, decorator-based tool registry, greedy scheduling

---

Database Schema

Six normalized tables with referential integrity:

• courses — Course registry
• topics — Syllabus items with due dates, weights, and time estimates
• quiz_results — Per-topic scores (0–1) with timestamps for trend analysis
• preferences — Per-course scheduling configuration
• study_tasks — Generated plan tasks with status tracking (planned → scheduled → done/skipped), priority scores, and calendar UIDs
• agent_runs — Audit log of all agent interactions (type, input/output summaries)

---

How the Priority Scoring Works

Each topic receives a composite priority score:

priority = 0.45 × urgency + 0.35 × weakness + 0.20 × weight_factor

• Urgency (45%) — Derived from days until due date on a week-scale curve. Topics due within a week score ~1.0; topics weeks away score ~0.2. Past-due topics are pinned at 1.0.
• Weakness (35%) — Computed as 1 - average_quiz_score for the topic. No quiz data defaults to 0.3 (mild weakness). Lower scores on quizzes push topics higher in priority.
• Weight (20%) — Syllabus-defined importance, normalized to [0, 1] via min(1.0, weight / 3.0).

The planner then allocates study sessions within a weekly time budget (hours_per_day × focus_days), sorted by priority, ensuring at least 30-minute sessions.

---

Agentic Tool-Calling Flow

In agentic mode, the LLM doesn't just generate text — it acts:

1. Inspect — The agent calls get_topics, get_quiz_scores, get_weakness_map, and get_current_plan to understand the student's current state.
2. Reason — Based on the data, it identifies weak areas, overdue topics, and scheduling conflicts.
3. Act — It calls generate_study_plan, replan_topic, mark_task_done, mark_task_too_hard, or skip_task to modify the plan.
4. Explain — It returns a natural-language summary of what it did and why.

The tool-call loop in llm_client.py supports up to 6 rounds of autonomous tool invocation before requiring a final text response.

---

Getting Started

Prerequisites

• Python 3.11+
• A Groq API key (free tier available)

Installation

git clone https://github.com/<your-username>/tutor-planner.git
cd tutor-planner
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

Configuration

Create a .env file in the project root:

GROQ_API_KEY=your_groq_api_key_here

Run

streamlit run app.py

The app opens at http://localhost:8501.

Quick Start

1. Create a new course (e.g., "CS5200")
2. Paste syllabus topics in the sidebar using the format: Topic Name | due=2026-03-15 | weight=2 | minutes=120
3. Optionally upload a quiz scores CSV with columns: date, topic_tag, score
4. Set your study preferences (hours/day, focus days, study window)
5. Click Generate Plan + Calendar (ICS)
6. Download the .ics file and import it into your calendar

---

Project Structure

Tutor_planner/
├── app.py                      # Streamlit entry point
├── .env                        # API keys (not committed)
├── core/
│   ├── __init__.py
│   ├── llm_client.py           # Groq API wrapper + tool-call loop
│   ├── orchestrator.py         # Agentic + deterministic pipelines
│   ├── planner.py              # Priority scoring + task builder
│   ├── quiz_analyzer.py        # Performance trend analysis
│   ├── slot_finder.py          # Time slot generation + greedy scheduler
│   ├── syllabus_parser.py      # Syllabus text parser
│   └── tools.py                # 10 registered LLM-callable tools
├── data/
│   ├── sample_quiz_scores.csv  # Example quiz data
│   └── sample_syllabus.txt     # Example syllabus input
├── db/
│   ├── __init__.py
│   ├── schema.sql              # SQLite schema (6 tables)
│   └── store.py                # Data access layer
├── integrations/
│   ├── __init__.py
│   └── calendar_ics.py         # ICS file generation
└── venv/                       # Virtual environment (not committed)

---

Future Improvements

• Multi-course scheduling — Unified weekly plans across all active courses with cross-course priority balancing
• Spaced repetition integration — Layer SM-2 or similar algorithms on top of the priority scoring for long-term retention
• Google Calendar API sync — Two-way sync instead of one-time ICS export
• Progress dashboard — Visual analytics showing study hours completed, score trends, and plan adherence over time
• Collaborative mode — Share plans with study groups and compare coverage

---

License

This project is for educational and portfolio purposes.

---

Built by Mohammed Sameer Sarfaraz as part of coursework and independent AI engineering projects at Northeastern University.