[SCHEDULER-TA] - Project Optimization suite

Advanced Academic Grading & Pairing Optimizer.

(OVERVIEW)

The system transforms raw campus schedules into an economic convenience model. It uses a weighted penalty system to rank potential scheduling options:

• Each Day of Turnaround: 1 Point
• Each "Special" Campus Trip: 10 Points
• Wait Time (Same-Day): 0.1 Points per Hour
• External Workload: Dynamic (User-Defined)

By minimizing the total penalty score, the system identifies the most "human- friendly" schedules for Graders and Professors.

(COMMANDS)

• db: Manage the persistent staff database (init, reset, export, add-person, list).
• quiz: Generate ranked collection/pickup windows for a specific pair.
• heatmap: Generate a convenience score for every assignment day (Pop quiz mode).
• pair: Calculate department-wide best matches (Global Matchmaking).
• timeline: Generate chronological turnaround guidance for onboarding.
• cadence: Evaluate weekly collection schedules over a semester for syllabus design.

CLI Usage Examples

Database Management (Adding Staff)

./scheduler-ta db init
./scheduler-ta db add-person --name "Euler" --role "Teacher" --sched "MWF 10am-11am"
# Note: Re-running add-person on an existing name gracefully updates their schedule!
./scheduler-ta db list

# To back up the database into a raw SQL dump:
./scheduler-ta db export

# To wipe the database clean and start over:
./scheduler-ta db reset

Individual Turnaround Mode (Shane Catch-up Scenario)

./scheduler-ta quiz --prof "MWF 10am-11am" --grader "TTh 1pm-2pm" --load 50

Global Matchmaking Mode (Department-Wide Optimization)

./scheduler-ta pair --prof "MW 1pm-2pm" --prof "TTh 9am-10am" \
                        --grader "MWF 10am-11am" --grader "TTh 2pm-3pm" \
                        --global-opt --date "04/06"

Heatmap Mode (Prof. Euler's Dashboard)

./scheduler-ta heatmap --prof "MWF 10am-12pm" --grader "TTh 1pm-2pm"

Syllabus Cadence Advisor Mode (Designing the Semester)

Helps a Professor decide which day of the week to place weekly assignments on.

# Using the staff added to the database during setup
./scheduler-ta cadence --prof-name "Euler" --grader-name "Shane" --weeks 16

# Or using on-the-fly schedules without the database
./scheduler-ta cadence \
    --prof "MWF 10am-12pm" \
    --grader "TTh 1pm-2pm"

(MODELING CAPABILITIES)

What it CAN model

• (PERSISTENCE) Uses a local SQLite database (~/.scheduler_ta/data.db) via SQLAlchemy for centralized staff management.
• (TIME-AWARE) Calculates the hour-gap between class ends and grader arrival.
• (WEEKLY) Supports complex, multi-block weekly schedules (e.g. MWF + TTh).
• (CONVENIENCE) Automatically identifies when a Grader is already on campus.
• (OPTIMAL) Solves for the best pairings across a department using the Hungarian Algorithm (Scipy Backend).
• (DYNAMIC) Supports short-term, date-aware matchmaking with the --date flag.
• (WORKLOAD) Penalizes specific dates where a Grader has external commitments (like Shane's catch-up period).

What it CANNOT model

• (REAL-TIME) Does not yet integrate directly with live University registrar data.

(FUTURE ROADMAP)

• (IMPORT) Bulk CSV/JSON import for department-wide scheduling.
• (DB-SYNC) Integration with university enrollment & registrar databases.
• (WEB-PORTAL) Front-end (HTML/JS) for slot viewing and student requests.
• (PERSIST) SQL-based backend for persistent staff and section data.
• (UI) Visual heatmap dashboard (Streamlit/FastAPI).
• (QUANTITY) Support for n_students and time_per_student to scale grading load penalty.

(DEVELOPMENT)

License

This project is licensed under the MIT License.

Packaging & Releasing

To package this application and deploy to PyPI via twine (if configured):

# Compile source and wheel distribution
python3 -m build

# Check bundle health
twine check dist/*

# Upload to TestPyPI
twine upload --repository testpypi dist/*

This project maintains strict quality standards:

• [Pylint] 10.00/10 Score
• [Pytest] 97.5% Project Minimum Test Coverage
• [Flake8] Standardized Compliance

make test   # Run full test suite with coverage reports
make test-v # Run verbose tests (visualize matchmaking solutions)
make lint   # Run all quality checks
make format # Auto-format source and documentation