Metadata-Version: 2.4
Name: scheduler-ta
Version: 0.1.1
Summary: TA Scheduling & Quiz Pickup Optimizer
Author-email: Shane Jaroch <chown_tee@proton.me>
License: MIT
Requires-Python: >=3.10
Requires-Dist: argcomplete>=3.5.3
Requires-Dist: scipy>=1.10.0
Requires-Dist: sqlalchemy>=2.0.0
Provides-Extra: dev
Requires-Dist: black; extra == 'dev'
Requires-Dist: build; extra == 'dev'
Requires-Dist: flake8; extra == 'dev'
Requires-Dist: isort; extra == 'dev'
Requires-Dist: pylint; extra == 'dev'
Requires-Dist: pytest; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: ruff; extra == 'dev'
Requires-Dist: twine; extra == 'dev'
Description-Content-Type: text/markdown

# [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)

```bash
./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)

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

#### Global Matchmaking Mode (Department-Wide Optimization)

```bash
./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)

```bash
./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.

```bash
# 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.
- [x] (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):

```bash
# 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

```bash
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
```
