smart-study-planner 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- smart_study_planner-0.5.0/CHANGELOG.md +50 -0
- smart_study_planner-0.5.0/CONTRIBUTING.md +13 -0
- smart_study_planner-0.5.0/GETTING_STARTED.md +39 -0
- smart_study_planner-0.5.0/MANIFEST.in +10 -0
- smart_study_planner-0.5.0/PKG-INFO +199 -0
- smart_study_planner-0.5.0/README.md +182 -0
- smart_study_planner-0.5.0/docs/ALGORITHM.md +61 -0
- smart_study_planner-0.5.0/docs/PUBLISHING_AND_DEMO.md +95 -0
- smart_study_planner-0.5.0/examples/jupyterhub_demo.ipynb +56 -0
- smart_study_planner-0.5.0/examples/quickstart.py +31 -0
- smart_study_planner-0.5.0/pyproject.toml +34 -0
- smart_study_planner-0.5.0/setup.cfg +4 -0
- smart_study_planner-0.5.0/smart_study_planner.egg-info/PKG-INFO +199 -0
- smart_study_planner-0.5.0/smart_study_planner.egg-info/SOURCES.txt +33 -0
- smart_study_planner-0.5.0/smart_study_planner.egg-info/dependency_links.txt +1 -0
- smart_study_planner-0.5.0/smart_study_planner.egg-info/entry_points.txt +2 -0
- smart_study_planner-0.5.0/smart_study_planner.egg-info/top_level.txt +1 -0
- smart_study_planner-0.5.0/study_plan/__init__.py +15 -0
- smart_study_planner-0.5.0/study_plan/__main__.py +53 -0
- smart_study_planner-0.5.0/study_plan/calendar_view.py +70 -0
- smart_study_planner-0.5.0/study_plan/exports.py +96 -0
- smart_study_planner-0.5.0/study_plan/input_ui.py +83 -0
- smart_study_planner-0.5.0/study_plan/planner.py +356 -0
- smart_study_planner-0.5.0/study_plan/scheduler.py +43 -0
- smart_study_planner-0.5.0/study_plan/static/app.js +328 -0
- smart_study_planner-0.5.0/study_plan/static/index.html +132 -0
- smart_study_planner-0.5.0/study_plan/static/style.css +24 -0
- smart_study_planner-0.5.0/study_plan/web_app.py +86 -0
- smart_study_planner-0.5.0/tests/test_fairness.py +102 -0
- smart_study_planner-0.5.0/tests/test_pacing.py +115 -0
- smart_study_planner-0.5.0/tests/test_planner.py +185 -0
- smart_study_planner-0.5.0/tests/test_priority.py +109 -0
- smart_study_planner-0.5.0/tests/test_public_api.py +49 -0
- smart_study_planner-0.5.0/tests/test_study_plan.py +138 -0
- smart_study_planner-0.5.0/tests/test_time_windows.py +122 -0
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 0.5.0 — Within-day availability balancing (PyPI release candidate)
|
|
4
|
+
|
|
5
|
+
- Spread sessions **across morning, afternoon, and other available time windows**, instead of filling the first window of each day first.
|
|
6
|
+
- Allocate study proportionally to window capacity; a three-hour afternoon window may receive more work than a one-hour morning window.
|
|
7
|
+
- Rotate tie-breaks across **active study days**, so light days with a single session do not always fall in the morning.
|
|
8
|
+
- Keep date-aware pacing, user-defined subject priority, study breaks, strict daily subject caps, and exam cutoffs.
|
|
9
|
+
- Sort all generated events chronologically before exporting the calendar.
|
|
10
|
+
- Add eight regression tests for time-window balance, overrides, pacing, and scheduling invariants.
|
|
11
|
+
- Bump version to 0.5.0; **not published to PyPI**.
|
|
12
|
+
|
|
13
|
+
## 0.4.0 — Date-aware balanced pacing (PyPI release candidate)
|
|
14
|
+
|
|
15
|
+
- Spread study requirements across the entire eligible planning period instead of filling the earliest days first.
|
|
16
|
+
- Preserve highest-first subject priority, subject rotation, hard daily caps, rest intervals, and exam cutoffs.
|
|
17
|
+
- Weight the target study pace by each date's availability; exclude days off and dates after exams.
|
|
18
|
+
- Explain date-aware pacing in the English web interface and package documentation.
|
|
19
|
+
- Add regression tests for long plans, exam dates, sparse availability, and scheduling invariants.
|
|
20
|
+
- Rebuild versioned source and wheel distributions; **not yet uploaded to PyPI**.
|
|
21
|
+
|
|
22
|
+
## v0.3.0 — Priority-aware international release candidate
|
|
23
|
+
|
|
24
|
+
- Subject list order now controls priority (first is highest); up/down buttons allow reordering.
|
|
25
|
+
- Priority-weighted fair queuing favors higher-ranked subjects under limited capacity, without abandoning rotation.
|
|
26
|
+
- Retains the strict per-subject daily cap and exam cutoff, including warnings for unscheduled work.
|
|
27
|
+
- Localized web UI, validation, command-line modes, and legacy HTML output to English.
|
|
28
|
+
- Added priority regression tests and updated documentation and onboarding guide.
|
|
29
|
+
- Build artifacts updated to 0.3.0; this package has **not** been published to PyPI.
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
## 0.3.0 — fairness and daily-limit update (PyPI release candidate)
|
|
33
|
+
|
|
34
|
+
- Fixed severe starvation where a high-demand subject (e.g. MA1508 at 300h) monopolized every day because its deadline pressure overrode rotation.
|
|
35
|
+
- Added **hard configurable per-subject daily study limit**, default 2h/day, from 1–8 hours.
|
|
36
|
+
- Fairly alternates subjects across sessions and across days, including days with only one available slot.
|
|
37
|
+
- Maintained exam awareness: exams occurring within two days influence equal-usage ties; no scheduling on/after exam dates.
|
|
38
|
+
- Added explicit feasibility warnings and per-subject theoretical maximum before exams (upper bound, not guaranteed).
|
|
39
|
+
- Added web form setting and visible warnings above the calendar.
|
|
40
|
+
- Added nine fairness/limits regression tests; all original tests retained.
|
|
41
|
+
- Bumped distribution and import versions to 0.3.0. **Not yet published to PyPI.**
|
|
42
|
+
|
|
43
|
+
## 0.1.0 — initial packaging candidate
|
|
44
|
+
|
|
45
|
+
- Turned original local planner into an installable standard-library Python distribution.
|
|
46
|
+
- Retained terminal and local browser interfaces.
|
|
47
|
+
- Added reusable importable API, Jupyter notebook HTML calendar, summary and ICS export.
|
|
48
|
+
- Added tests and documentation for PyPI, JupyterHub, algorithm and team workflow.
|
|
49
|
+
|
|
50
|
+
This is a packaging **candidate**, not proof of a published PyPI release.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Contributing (team CS1302 group06)
|
|
2
|
+
|
|
3
|
+
The course requires a **real public Git repository** and regular, attributable collaboration. Everyone should contribute genuinely; do not fabricate Git history or authorship. Coordinate tasks, test changes and explain each person's contribution in the presentation.
|
|
4
|
+
|
|
5
|
+
Suggested division of work (adapt to actual team skills):
|
|
6
|
+
|
|
7
|
+
1. **Scheduling**: refine `study_plan/planner.py` and add cases in `tests/test_planner.py`.
|
|
8
|
+
2. **Reusable exports and notebooks**: maintain `study_plan/exports.py`, `examples/`, and API tests.
|
|
9
|
+
3. **Web UI, packaging and documentation**: maintain `study_plan/static/`, `pyproject.toml`, `README.md` and publishing checks.
|
|
10
|
+
|
|
11
|
+
Workflow: create an issue, branch from main, make a small reviewed PR, run `python -m unittest discover -s tests -v`, merge, and repeat. At the end verify visible contributions from all team members.
|
|
12
|
+
|
|
13
|
+
Please agree on a software license as a group before public publication. This project intentionally does not choose a license on behalf of all contributors.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Getting started — Smart Study Planner v0.5.0
|
|
2
|
+
|
|
3
|
+
## PyCharm (macOS / Windows)
|
|
4
|
+
|
|
5
|
+
1. Extract the ZIP file, and open the extracted folder containing `pyproject.toml` in PyCharm.
|
|
6
|
+
2. Configure a Python 3.9+ interpreter (a project-specific virtual environment is recommended).
|
|
7
|
+
3. Open PyCharm Terminal in the project root and run:
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
python -m pip install -e .
|
|
11
|
+
python -m unittest discover -s tests -v
|
|
12
|
+
python run.py --port 8768
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
4. Open <http://127.0.0.1:8768/>. If port 8768 is occupied, choose another number.
|
|
16
|
+
5. Enter subjects **from highest to lowest priority** or use the ↑ / ↓ buttons to reorder them. The first subject is the highest priority.
|
|
17
|
+
6. Set required study hours, optional exam dates, planning dates, and free time. Click **Generate study plan**.
|
|
18
|
+
7. The 2-hour default daily per-subject cap is a hard limit; increasing priority does not override it.
|
|
19
|
+
8. Study sessions are **spread across the full planning range** (up to the day before each subject's exam). Check later weeks with the week arrows; a long plan will no longer be front-loaded.
|
|
20
|
+
9. With multiple availability windows, the scheduler **balances study sessions across the day**, so mornings and afternoons are both used when possible. A single session on a light day may be placed in either window, alternating over active days.
|
|
21
|
+
|
|
22
|
+
## Priority behavior
|
|
23
|
+
|
|
24
|
+
The scheduler uses **priority-weighted fair scheduling**, not a strict subject-by-subject fill. When study time is limited, earlier subjects tend to receive more hours. Subjects rotate instead of dominating one day. If enough time exists for all subjects to hit their individual daily caps, totals may be equal: the planner does not intentionally leave time idle.
|
|
25
|
+
|
|
26
|
+
Priority and completion percentages are not identical: a subject needing 200 hours may show a lower completion percentage than a subject needing 20 hours even after receiving more scheduled hours.
|
|
27
|
+
|
|
28
|
+
## Testing and packaging
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
python -m unittest discover -s tests -v
|
|
32
|
+
python -m pip install --upgrade build twine
|
|
33
|
+
python -m build
|
|
34
|
+
python -m twine check dist/*
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Use a clean environment to test a built wheel before publishing. Publishing to PyPI or GitHub is **not** performed by this ZIP.
|
|
38
|
+
|
|
39
|
+
For international demos and PyPI instructions, see `README.md` and `docs/PUBLISHING_AND_DEMO.md`.
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
include README.md
|
|
2
|
+
recursive-include study_plan/static *.html *.css *.js
|
|
3
|
+
recursive-include examples *.py *.ipynb
|
|
4
|
+
recursive-include docs *.md
|
|
5
|
+
prune build
|
|
6
|
+
prune dist
|
|
7
|
+
recursive-exclude * __pycache__ *.py[cod]
|
|
8
|
+
include CONTRIBUTING.md CHANGELOG.md
|
|
9
|
+
|
|
10
|
+
include GETTING_STARTED.md
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: smart-study-planner
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Priority-aware study scheduling balanced across dates and daily time windows
|
|
5
|
+
Project-URL: Homepage, https://github.com/Justin-Liu080606/1302A-projecct-spare
|
|
6
|
+
Project-URL: Repository, https://github.com/Justin-Liu080606/1302A-projecct-spare
|
|
7
|
+
Project-URL: Documentation, https://github.com/Justin-Liu080606/1302A-projecct-spare#readme
|
|
8
|
+
Keywords: study,planner,scheduling,calendar,education
|
|
9
|
+
Classifier: Development Status :: 3 - Alpha
|
|
10
|
+
Classifier: Intended Audience :: Education
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
13
|
+
Classifier: Topic :: Education
|
|
14
|
+
Classifier: Topic :: Office/Business :: Scheduling
|
|
15
|
+
Requires-Python: >=3.9
|
|
16
|
+
Description-Content-Type: text/markdown
|
|
17
|
+
|
|
18
|
+
[README.md](https://github.com/user-attachments/files/35005946/README.md)
|
|
19
|
+
# Smart Study Planner · CS1302 Group 06
|
|
20
|
+
|
|
21
|
+
> **Installable Python package** for automatic, explainable exam-aware study scheduling, with a colored weekly calendar, optional local web UI, and `.ics` calendar export.
|
|
22
|
+
|
|
23
|
+
Smart Study Planner is an open-source Python package for building balanced, priority-aware study schedules. Its scheduling engine works directly in Python and Jupyter notebooks, while an optional local web interface displays a weekly calendar. This repository contains the source code, usage examples, tests, and documentation.
|
|
24
|
+
|
|
25
|
+
## Motivation & innovation
|
|
26
|
+
|
|
27
|
+
Students often know how many hours they need to study but struggle to fit them into irregular daily availability. Existing calendar tools generally require users to arrange every event manually. Our package converts subject workloads, exam deadlines, available dates and breaks into a feasible schedule. The scheduling engine is reusable from Python/JupyterHub — not tied to the webpage. See [algorithm explanation](docs/ALGORITHM.md) for the heuristic's tradeoffs and limitations.
|
|
28
|
+
|
|
29
|
+
### Main features
|
|
30
|
+
|
|
31
|
+
- Schedule up to 20 subjects over up to 63 days with user-defined study hours.
|
|
32
|
+
- Multiple available windows per day; custom exceptions (including days off), with overlap merging.
|
|
33
|
+
- **Hard per-subject daily cap**, default **2h per subject per day**, configurable from 1h to 8h. No deadline can override it.
|
|
34
|
+
- **Priority-weighted multi-subject rotation** within and across days; subject order influences scheduling without letting any subject monopolize the timetable.
|
|
35
|
+
- **Date-aware pacing:** study sessions are distributed over the complete selected period instead of always filling the first days. Exam deadlines limit how far each subject can be spread.
|
|
36
|
+
- **Within-day window balance:** study sessions are distributed across available morning, afternoon, and other time windows based on their capacity, rather than always starting in the first window. Light days rotate the preferred window.
|
|
37
|
+
- Configurable study sessions and rest intervals; events never overlap or exceed availability.
|
|
38
|
+
- Report **unmet** study hours and calculate each subject's theoretical capacity before its exam, instead of promising an impossible timetable.
|
|
39
|
+
- Reuse results as JSON-compatible Python data, embedded JupyterHub HTML, or `.ics` calendar.
|
|
40
|
+
- Optional local browser UI with a colorful navigable weekly calendar, requiring no web framework.
|
|
41
|
+
|
|
42
|
+
## Installation
|
|
43
|
+
|
|
44
|
+
Python **3.9+** is required. No mandatory runtime third-party dependencies.
|
|
45
|
+
|
|
46
|
+
**Before the first PyPI release:** open a terminal in the project's root directory:
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
python -m pip install .
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
**After the official PyPI release** (not yet available until the team publishes it):
|
|
53
|
+
|
|
54
|
+
```bash
|
|
55
|
+
python -m pip install smart-study-planner==0.5.0
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
The distribution name in `pip install` differs from the Python **import name**, which remains `study_plan`.
|
|
59
|
+
|
|
60
|
+
## Python package usage (also works in JupyterHub)
|
|
61
|
+
|
|
62
|
+
```python
|
|
63
|
+
from study_plan import generate_plan, summarize_plan, render_week_html, to_ics
|
|
64
|
+
|
|
65
|
+
request = {
|
|
66
|
+
"start_date": "2026-11-16",
|
|
67
|
+
"end_date": "2026-11-22",
|
|
68
|
+
"subjects": [
|
|
69
|
+
{"name": "CS1302 Python", "hours": 5, "exam_date": "2026-11-21"},
|
|
70
|
+
{"name": "Math", "hours": 6},
|
|
71
|
+
],
|
|
72
|
+
"daily_windows": [
|
|
73
|
+
{"start": "08:00", "end": "11:00"},
|
|
74
|
+
{"start": "14:00", "end": "17:00"},
|
|
75
|
+
],
|
|
76
|
+
"date_overrides": [{"date": "2026-11-18", "windows": []}],
|
|
77
|
+
"session_minutes": 60,
|
|
78
|
+
"break_minutes": 10,
|
|
79
|
+
"daily_subject_limit_minutes": 120, # 2 hours / subject / day
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
plan = generate_plan(request)
|
|
83
|
+
print(summarize_plan(plan))
|
|
84
|
+
print(plan["sessions"][:2])
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
For **JupyterHub**, after installing the package in the notebook environment, show the weekly calendar **inline**, without needing to expose a web port:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from IPython.display import display, HTML
|
|
91
|
+
display(HTML(render_week_html(plan)))
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
For calendar apps, save an ICS file (times are floating local times, not automatically timezone-adjusted):
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
from pathlib import Path
|
|
98
|
+
Path("my_plan.ics").write_bytes(to_ics(plan).encode("utf-8"))
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
See [`examples/quickstart.py`](examples/quickstart.py) and [`examples/jupyterhub_demo.ipynb`](examples/jupyterhub_demo.ipynb) for full examples.
|
|
102
|
+
|
|
103
|
+
## Web interface (PyCharm)
|
|
104
|
+
|
|
105
|
+
In PyCharm, open the project folder and run `run.py`, or from a terminal:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
python -m study_plan
|
|
109
|
+
# Equivalent after installation:
|
|
110
|
+
study-plan
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
The application opens at **http://127.0.0.1:8765/**. Enter subjects and planned hours, choose the date range and free time windows, then click **Generate Plan**. Review study sessions, subject progress and available/remaining hours in the weekly view. Use **Previous/Next Week** to navigate.
|
|
114
|
+
|
|
115
|
+
Options:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
study-plan --no-browser # print URL without opening a browser
|
|
119
|
+
study-plan --port 8766 # choose another port
|
|
120
|
+
study-plan --cli # original terminal input mode
|
|
121
|
+
study-plan --demo # original static HTML example
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Press **Ctrl+C** in your terminal to shut down the server. It only binds to `127.0.0.1`, so it is designed for local use, not public deployment or remote JupyterHub hosting.
|
|
125
|
+
|
|
126
|
+
## Inputs, outputs and constraints
|
|
127
|
+
|
|
128
|
+
`generate_plan(request)` accepts a dictionary with these fields:
|
|
129
|
+
|
|
130
|
+
| Field | Description |
|
|
131
|
+
|---|---|
|
|
132
|
+
| `start_date`, `end_date` | Inclusive dates, `YYYY-MM-DD` |
|
|
133
|
+
| `subjects` | List of `{name, hours, exam_date?}` objects; hours in 0.5h increments |
|
|
134
|
+
| `daily_windows` | Default list of `{start, end}` windows in `HH:MM` local time |
|
|
135
|
+
| `date_overrides` | Optional list of `{date, windows}` replacing defaults for that date; `[]` means a day off |
|
|
136
|
+
| `session_minutes` | `30`, `60`, or `90` (default `60`) |
|
|
137
|
+
| `break_minutes` | `0`, `5`, `10`, or `15` (default `10`) |
|
|
138
|
+
| `daily_subject_limit_minutes` | Hard per-subject daily cap, in minutes, from `60` to `480` in 30-minute increments (default `120` = 2h); applies even if a subject has an imminent exam |
|
|
139
|
+
|
|
140
|
+
The result includes `sessions`, `subjects`, `availability`, `start_date`, `end_date`, `settings`, `warnings`, and `summary`. Each `subjects` item has `individual_capacity_upper_bound_minutes`, a theoretical maximum for that subject before its exam, accounting for its daily cap and free days **but not** breaks or competition with other subjects. `warnings` explain incomplete plans. The planner intentionally spaces work across eligible dates, so early free time may remain empty even while future days are scheduled. Sometimes the calendar also leaves empty slots because all remaining subjects hit their daily caps; this is correct behavior, not a missing event. Each session has a subject, day, start/end times, and an integer subject ID. Errors raise `study_plan.InputError` for invalid requests. An examination on a particular date means the study must be scheduled **before** that date.
|
|
141
|
+
|
|
142
|
+
Output can be displayed in a notebook with `render_week_html(plan)`, summarized with `summarize_plan(plan)` or exported with `to_ics(plan)`.
|
|
143
|
+
|
|
144
|
+
## Development & testing
|
|
145
|
+
|
|
146
|
+
```bash
|
|
147
|
+
python -m unittest discover -s tests -v
|
|
148
|
+
python -m pip install .
|
|
149
|
+
study-plan --help
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
The package layout:
|
|
153
|
+
|
|
154
|
+
```text
|
|
155
|
+
pyproject.toml PyPI metadata, build config, console command
|
|
156
|
+
study_plan/ Importable Python package
|
|
157
|
+
planner.py Validation + hard daily cap + priority-aware scheduling
|
|
158
|
+
exports.py Jupyter HTML, ICS export, progress summary
|
|
159
|
+
web_app.py Local HTTP interface
|
|
160
|
+
static/ Shipped HTML/CSS/JS assets
|
|
161
|
+
__main__.py Command-line entry point
|
|
162
|
+
scheduler.py Original algorithm retained for compatibility
|
|
163
|
+
input_ui.py Original terminal interface retained
|
|
164
|
+
calendar_view.py Original HTML export retained
|
|
165
|
+
tests/ Standard-library unit and API tests (incl. MA1508 regression)
|
|
166
|
+
examples/ Python and JupyterHub examples
|
|
167
|
+
docs/ALGORITHM.md Algorithm, innovation, limitations
|
|
168
|
+
docs/PUBLISHING_AND_DEMO.md Publish + verify on JupyterHub, 1-min presentation
|
|
169
|
+
run.py Simple PyCharm runner
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
## Publishing, teamwork and one-minute demo
|
|
173
|
+
|
|
174
|
+
**Please read [`docs/PUBLISHING_AND_DEMO.md`](docs/PUBLISHING_AND_DEMO.md).** The team must still (1) use its public Git repository with regular genuine contributions by members, (2) create a versioned wheel/source distribution, (3) upload those artifacts to PyPI with an authorized account, (4) verify fresh installation in course JupyterHub, and (5) submit/present as instructed by the course.
|
|
175
|
+
|
|
176
|
+
## Honest limitations
|
|
177
|
+
|
|
178
|
+
This is a deterministic heuristic, **not an AI predictor** or a guarantee of optimal scheduling. It cannot infer learning needs or solve impossible schedules. The included web UI runs locally and is separate from the importable package API. The package is a classroom project that may require further hardening for general production use.
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
## Priority-aware planning
|
|
182
|
+
|
|
183
|
+
**Enter subjects from highest to lowest priority.** The first card is priority #1; use the ↑ and ↓ controls to change their order without retyping. The API similarly treats the first `subjects` entry as highest priority.
|
|
184
|
+
|
|
185
|
+
The scheduler uses weighted fair queuing. It favors higher priority subjects when hours are scarce, alternates subjects when possible, and never violates daily study caps or schedules on/after exam days. When enough free time exists to accommodate all subjects up to their caps, some subjects may receive equal hours. Required-hours completion percentages are not guaranteed to be strictly ordered.
|
|
186
|
+
|
|
187
|
+
For a concise setup walkthrough, see [GETTING_STARTED.md](GETTING_STARTED.md).
|
|
188
|
+
|
|
189
|
+
## Spreading sessions across a long date range
|
|
190
|
+
|
|
191
|
+
The scheduler distributes each subject's study requirement across all dates on which that subject is eligible. More available time on a date can attract a larger share; days off have no allocations. A short workload over several weeks remains visible in later weeks, rather than being packed into the beginning.
|
|
192
|
+
|
|
193
|
+
**Exam dates take precedence over spreading:** a subject's study blocks can only appear before its exam date. Priority order still controls how competing subjects share limited hours, with the strict per-subject daily cap and session breaks unchanged. A small workload cannot fill every date when each session requires at least 30 minutes.
|
|
194
|
+
|
|
195
|
+
## Morning / afternoon balance
|
|
196
|
+
|
|
197
|
+
The scheduler balances study sessions over multiple available windows **within each day**. For example, with free periods at 08:00–11:00 and 14:00–17:00, it avoids placing all daily sessions in the morning when both windows have room. Long and short windows receive study time in proportion to their capacity; if there is only one short session on a given day, the preferred window rotates across active study days. All existing subject priorities, daily limits, exam cutoffs and date-aware pacing remain in effect.
|
|
198
|
+
|
|
199
|
+
This is a heuristic for practical distribution, not a promise of exactly equal morning and afternoon totals for every possible set of availability windows.
|
|
@@ -0,0 +1,182 @@
|
|
|
1
|
+
[README.md](https://github.com/user-attachments/files/35005946/README.md)
|
|
2
|
+
# Smart Study Planner · CS1302 Group 06
|
|
3
|
+
|
|
4
|
+
> **Installable Python package** for automatic, explainable exam-aware study scheduling, with a colored weekly calendar, optional local web UI, and `.ics` calendar export.
|
|
5
|
+
|
|
6
|
+
Smart Study Planner is an open-source Python package for building balanced, priority-aware study schedules. Its scheduling engine works directly in Python and Jupyter notebooks, while an optional local web interface displays a weekly calendar. This repository contains the source code, usage examples, tests, and documentation.
|
|
7
|
+
|
|
8
|
+
## Motivation & innovation
|
|
9
|
+
|
|
10
|
+
Students often know how many hours they need to study but struggle to fit them into irregular daily availability. Existing calendar tools generally require users to arrange every event manually. Our package converts subject workloads, exam deadlines, available dates and breaks into a feasible schedule. The scheduling engine is reusable from Python/JupyterHub — not tied to the webpage. See [algorithm explanation](docs/ALGORITHM.md) for the heuristic's tradeoffs and limitations.
|
|
11
|
+
|
|
12
|
+
### Main features
|
|
13
|
+
|
|
14
|
+
- Schedule up to 20 subjects over up to 63 days with user-defined study hours.
|
|
15
|
+
- Multiple available windows per day; custom exceptions (including days off), with overlap merging.
|
|
16
|
+
- **Hard per-subject daily cap**, default **2h per subject per day**, configurable from 1h to 8h. No deadline can override it.
|
|
17
|
+
- **Priority-weighted multi-subject rotation** within and across days; subject order influences scheduling without letting any subject monopolize the timetable.
|
|
18
|
+
- **Date-aware pacing:** study sessions are distributed over the complete selected period instead of always filling the first days. Exam deadlines limit how far each subject can be spread.
|
|
19
|
+
- **Within-day window balance:** study sessions are distributed across available morning, afternoon, and other time windows based on their capacity, rather than always starting in the first window. Light days rotate the preferred window.
|
|
20
|
+
- Configurable study sessions and rest intervals; events never overlap or exceed availability.
|
|
21
|
+
- Report **unmet** study hours and calculate each subject's theoretical capacity before its exam, instead of promising an impossible timetable.
|
|
22
|
+
- Reuse results as JSON-compatible Python data, embedded JupyterHub HTML, or `.ics` calendar.
|
|
23
|
+
- Optional local browser UI with a colorful navigable weekly calendar, requiring no web framework.
|
|
24
|
+
|
|
25
|
+
## Installation
|
|
26
|
+
|
|
27
|
+
Python **3.9+** is required. No mandatory runtime third-party dependencies.
|
|
28
|
+
|
|
29
|
+
**Before the first PyPI release:** open a terminal in the project's root directory:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
python -m pip install .
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
**After the official PyPI release** (not yet available until the team publishes it):
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
python -m pip install smart-study-planner==0.5.0
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
The distribution name in `pip install` differs from the Python **import name**, which remains `study_plan`.
|
|
42
|
+
|
|
43
|
+
## Python package usage (also works in JupyterHub)
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from study_plan import generate_plan, summarize_plan, render_week_html, to_ics
|
|
47
|
+
|
|
48
|
+
request = {
|
|
49
|
+
"start_date": "2026-11-16",
|
|
50
|
+
"end_date": "2026-11-22",
|
|
51
|
+
"subjects": [
|
|
52
|
+
{"name": "CS1302 Python", "hours": 5, "exam_date": "2026-11-21"},
|
|
53
|
+
{"name": "Math", "hours": 6},
|
|
54
|
+
],
|
|
55
|
+
"daily_windows": [
|
|
56
|
+
{"start": "08:00", "end": "11:00"},
|
|
57
|
+
{"start": "14:00", "end": "17:00"},
|
|
58
|
+
],
|
|
59
|
+
"date_overrides": [{"date": "2026-11-18", "windows": []}],
|
|
60
|
+
"session_minutes": 60,
|
|
61
|
+
"break_minutes": 10,
|
|
62
|
+
"daily_subject_limit_minutes": 120, # 2 hours / subject / day
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
plan = generate_plan(request)
|
|
66
|
+
print(summarize_plan(plan))
|
|
67
|
+
print(plan["sessions"][:2])
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
For **JupyterHub**, after installing the package in the notebook environment, show the weekly calendar **inline**, without needing to expose a web port:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
from IPython.display import display, HTML
|
|
74
|
+
display(HTML(render_week_html(plan)))
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
For calendar apps, save an ICS file (times are floating local times, not automatically timezone-adjusted):
|
|
78
|
+
|
|
79
|
+
```python
|
|
80
|
+
from pathlib import Path
|
|
81
|
+
Path("my_plan.ics").write_bytes(to_ics(plan).encode("utf-8"))
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
See [`examples/quickstart.py`](examples/quickstart.py) and [`examples/jupyterhub_demo.ipynb`](examples/jupyterhub_demo.ipynb) for full examples.
|
|
85
|
+
|
|
86
|
+
## Web interface (PyCharm)
|
|
87
|
+
|
|
88
|
+
In PyCharm, open the project folder and run `run.py`, or from a terminal:
|
|
89
|
+
|
|
90
|
+
```bash
|
|
91
|
+
python -m study_plan
|
|
92
|
+
# Equivalent after installation:
|
|
93
|
+
study-plan
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
The application opens at **http://127.0.0.1:8765/**. Enter subjects and planned hours, choose the date range and free time windows, then click **Generate Plan**. Review study sessions, subject progress and available/remaining hours in the weekly view. Use **Previous/Next Week** to navigate.
|
|
97
|
+
|
|
98
|
+
Options:
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
study-plan --no-browser # print URL without opening a browser
|
|
102
|
+
study-plan --port 8766 # choose another port
|
|
103
|
+
study-plan --cli # original terminal input mode
|
|
104
|
+
study-plan --demo # original static HTML example
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Press **Ctrl+C** in your terminal to shut down the server. It only binds to `127.0.0.1`, so it is designed for local use, not public deployment or remote JupyterHub hosting.
|
|
108
|
+
|
|
109
|
+
## Inputs, outputs and constraints
|
|
110
|
+
|
|
111
|
+
`generate_plan(request)` accepts a dictionary with these fields:
|
|
112
|
+
|
|
113
|
+
| Field | Description |
|
|
114
|
+
|---|---|
|
|
115
|
+
| `start_date`, `end_date` | Inclusive dates, `YYYY-MM-DD` |
|
|
116
|
+
| `subjects` | List of `{name, hours, exam_date?}` objects; hours in 0.5h increments |
|
|
117
|
+
| `daily_windows` | Default list of `{start, end}` windows in `HH:MM` local time |
|
|
118
|
+
| `date_overrides` | Optional list of `{date, windows}` replacing defaults for that date; `[]` means a day off |
|
|
119
|
+
| `session_minutes` | `30`, `60`, or `90` (default `60`) |
|
|
120
|
+
| `break_minutes` | `0`, `5`, `10`, or `15` (default `10`) |
|
|
121
|
+
| `daily_subject_limit_minutes` | Hard per-subject daily cap, in minutes, from `60` to `480` in 30-minute increments (default `120` = 2h); applies even if a subject has an imminent exam |
|
|
122
|
+
|
|
123
|
+
The result includes `sessions`, `subjects`, `availability`, `start_date`, `end_date`, `settings`, `warnings`, and `summary`. Each `subjects` item has `individual_capacity_upper_bound_minutes`, a theoretical maximum for that subject before its exam, accounting for its daily cap and free days **but not** breaks or competition with other subjects. `warnings` explain incomplete plans. The planner intentionally spaces work across eligible dates, so early free time may remain empty even while future days are scheduled. Sometimes the calendar also leaves empty slots because all remaining subjects hit their daily caps; this is correct behavior, not a missing event. Each session has a subject, day, start/end times, and an integer subject ID. Errors raise `study_plan.InputError` for invalid requests. An examination on a particular date means the study must be scheduled **before** that date.
|
|
124
|
+
|
|
125
|
+
Output can be displayed in a notebook with `render_week_html(plan)`, summarized with `summarize_plan(plan)` or exported with `to_ics(plan)`.
|
|
126
|
+
|
|
127
|
+
## Development & testing
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
python -m unittest discover -s tests -v
|
|
131
|
+
python -m pip install .
|
|
132
|
+
study-plan --help
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
The package layout:
|
|
136
|
+
|
|
137
|
+
```text
|
|
138
|
+
pyproject.toml PyPI metadata, build config, console command
|
|
139
|
+
study_plan/ Importable Python package
|
|
140
|
+
planner.py Validation + hard daily cap + priority-aware scheduling
|
|
141
|
+
exports.py Jupyter HTML, ICS export, progress summary
|
|
142
|
+
web_app.py Local HTTP interface
|
|
143
|
+
static/ Shipped HTML/CSS/JS assets
|
|
144
|
+
__main__.py Command-line entry point
|
|
145
|
+
scheduler.py Original algorithm retained for compatibility
|
|
146
|
+
input_ui.py Original terminal interface retained
|
|
147
|
+
calendar_view.py Original HTML export retained
|
|
148
|
+
tests/ Standard-library unit and API tests (incl. MA1508 regression)
|
|
149
|
+
examples/ Python and JupyterHub examples
|
|
150
|
+
docs/ALGORITHM.md Algorithm, innovation, limitations
|
|
151
|
+
docs/PUBLISHING_AND_DEMO.md Publish + verify on JupyterHub, 1-min presentation
|
|
152
|
+
run.py Simple PyCharm runner
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
## Publishing, teamwork and one-minute demo
|
|
156
|
+
|
|
157
|
+
**Please read [`docs/PUBLISHING_AND_DEMO.md`](docs/PUBLISHING_AND_DEMO.md).** The team must still (1) use its public Git repository with regular genuine contributions by members, (2) create a versioned wheel/source distribution, (3) upload those artifacts to PyPI with an authorized account, (4) verify fresh installation in course JupyterHub, and (5) submit/present as instructed by the course.
|
|
158
|
+
|
|
159
|
+
## Honest limitations
|
|
160
|
+
|
|
161
|
+
This is a deterministic heuristic, **not an AI predictor** or a guarantee of optimal scheduling. It cannot infer learning needs or solve impossible schedules. The included web UI runs locally and is separate from the importable package API. The package is a classroom project that may require further hardening for general production use.
|
|
162
|
+
|
|
163
|
+
|
|
164
|
+
## Priority-aware planning
|
|
165
|
+
|
|
166
|
+
**Enter subjects from highest to lowest priority.** The first card is priority #1; use the ↑ and ↓ controls to change their order without retyping. The API similarly treats the first `subjects` entry as highest priority.
|
|
167
|
+
|
|
168
|
+
The scheduler uses weighted fair queuing. It favors higher priority subjects when hours are scarce, alternates subjects when possible, and never violates daily study caps or schedules on/after exam days. When enough free time exists to accommodate all subjects up to their caps, some subjects may receive equal hours. Required-hours completion percentages are not guaranteed to be strictly ordered.
|
|
169
|
+
|
|
170
|
+
For a concise setup walkthrough, see [GETTING_STARTED.md](GETTING_STARTED.md).
|
|
171
|
+
|
|
172
|
+
## Spreading sessions across a long date range
|
|
173
|
+
|
|
174
|
+
The scheduler distributes each subject's study requirement across all dates on which that subject is eligible. More available time on a date can attract a larger share; days off have no allocations. A short workload over several weeks remains visible in later weeks, rather than being packed into the beginning.
|
|
175
|
+
|
|
176
|
+
**Exam dates take precedence over spreading:** a subject's study blocks can only appear before its exam date. Priority order still controls how competing subjects share limited hours, with the strict per-subject daily cap and session breaks unchanged. A small workload cannot fill every date when each session requires at least 30 minutes.
|
|
177
|
+
|
|
178
|
+
## Morning / afternoon balance
|
|
179
|
+
|
|
180
|
+
The scheduler balances study sessions over multiple available windows **within each day**. For example, with free periods at 08:00–11:00 and 14:00–17:00, it avoids placing all daily sessions in the morning when both windows have room. Long and short windows receive study time in proportion to their capacity; if there is only one short session on a given day, the preferred window rotates across active study days. All existing subject priorities, daily limits, exam cutoffs and date-aware pacing remain in effect.
|
|
181
|
+
|
|
182
|
+
This is a heuristic for practical distribution, not a promise of exactly equal morning and afternoon totals for every possible set of availability windows.
|
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Algorithm and novelty
|
|
2
|
+
|
|
3
|
+
## Problem
|
|
4
|
+
|
|
5
|
+
Traditional to-do lists usually record *what* to study, but leave the learner to calculate *when*. This package converts a desired workload into collision-free study sessions constrained by actual free-time windows.
|
|
6
|
+
|
|
7
|
+
## Algorithm, explained (v0.5.0)
|
|
8
|
+
|
|
9
|
+
1. Validate study subjects, deadlines and availability. Merge overlapping and adjacent availability windows.
|
|
10
|
+
2. Read `daily_subject_limit_minutes` (default **120 = 2 hours**). It is a **hard cap** per `(date, subject_id)`; even an urgent exam may not break it.
|
|
11
|
+
3. **Pace the workload over the full eligible period.** For every subject, calculate its available dates and an individual capacity upper bound. Create cumulative study targets across these dates, proportional to the free time available on each date, rounded to 30-minute increments. Exam dates shorten that subject's eligible period. This prevents a short workload from being packed into the first few days of a long plan.
|
|
12
|
+
4. Group the available windows by day. At each study session, consider only subjects with unfinished workload, before their exam date, below the daily cap **and behind their cumulative pacing target**. Choose the available time window with the **lowest fraction of study time already allocated**. This balances morning, afternoon, and other windows according to their lengths, rather than filling the first window. Break equal-usage ties by rotating the preferred window across *active* study days.
|
|
13
|
+
5. **Priority-weighted fair queuing:** the first subject has the highest priority weight (`n` for `n` subjects); each next subject has a weight one lower. Select the eligible subject with the smallest ratio `total_scheduled_minutes / priority_weight`. Break ties by already scheduled minutes today and then input order. Alternate subjects within the same day whenever another eligible subject is available. Deadline dates constrain eligibility, but do not override the user's chosen ordering.
|
|
14
|
+
6. Limit each generated event by available time, unfinished demand, session length and remaining daily subject allowance. Add a configured break before the next event in the same or nearly touching windows. Since windows can be filled in a nonchronological order, sort the output sessions by date and start time before returning results.
|
|
15
|
+
7. Report scheduled and remaining hours. For each subject, calculate a *theoretical upper bound* of `sum(min(daily_free_minutes, daily_subject_limit_minutes))` over dates before its exam. This bound deliberately ignores breaks and competition and must not be reported as a guaranteed allocation. Display warnings if required time exceeds the bound or if work remains unscheduled.
|
|
16
|
+
|
|
17
|
+
This intentionally favors a diverse and workable calendar over filling all free time. If only one subject remains and it has reached 2h that day, further time slots stay empty. The user may change the cap or extend dates, but the engine never silently violates the chosen cap.
|
|
18
|
+
|
|
19
|
+
The algorithm is deterministic and explainable, **not an AI predictor or an optimality guarantee**. It uses 30-minute workload increments, which may leave small gaps unused.
|
|
20
|
+
|
|
21
|
+
## Distinguishing reusable features
|
|
22
|
+
|
|
23
|
+
- `generate_plan(request)`: pure Python JSON-like input/output, independent of a GUI or notebook
|
|
24
|
+
- Date-aware workload pacing across the full available period, with within-day time-window balance, hard daily caps and priority-weighted fair rotation
|
|
25
|
+
- Per-date availability overrides, overlapping-window handling, no-overlap guarantees
|
|
26
|
+
- Transparent unmet demand, theoretical per-subject capacity before exams, and completion percentage
|
|
27
|
+
- `render_week_html(plan)` for JupyterHub notebooks, `to_ics(plan)` for calendar import
|
|
28
|
+
- Optional polished local web UI using no third-party web framework
|
|
29
|
+
|
|
30
|
+
## Complexity
|
|
31
|
+
|
|
32
|
+
For `S` subjects, `D` planning dates, and `K` generated sessions, eligibility and priority selection take approximately O(K*S), plus O(S*D) to calculate subject pacing targets and theoretical capacity bounds. Inputs are bounded to 20 subjects and 63 dates.
|
|
33
|
+
|
|
34
|
+
## Limitations
|
|
35
|
+
|
|
36
|
+
The algorithm does not know study difficulty, individual energy levels or actual learning outcomes; user-supplied hours are estimates. Calendar exports use floating local times: importers assume their local timezone. It cannot guarantee the full plan fits when demand exceeds capacity.
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
## Priority order (v0.4.0)
|
|
40
|
+
|
|
41
|
+
Input order is meaningful: first subject is highest priority. The browser lets users move subject cards up and down; the JSON API uses the `subjects` list order.
|
|
42
|
+
|
|
43
|
+
Each subject receives a weight of `number_of_subjects - zero_based_index` (for example, 3 / 2 / 1). For each eligible time slot, the planner picks the subject with the lowest `(total_allocated_minutes / priority_weight)` value, with stable input-order tie-breaking. Whenever possible, it avoids selecting the same subject for two consecutive sessions on one day. This is **weighted fair scheduling**, subject to hard daily per-subject limits and exam-date cutoffs.
|
|
44
|
+
|
|
45
|
+
**Fairness qualification:** the system favors higher-ranked subjects when study time is scarce, but cannot guarantee strictly greater allocated hours or completion percentages in every scenario. If availability allows every subject to reach the daily cap, equal total hours are expected. No subject is scheduled on or after its exam date.
|
|
46
|
+
|
|
47
|
+
## Date-aware pacing (v0.4.0)
|
|
48
|
+
|
|
49
|
+
The old behavior filled the earliest days until all requested hours were consumed, leaving the rest of a long plan empty. Version 0.4.0 sets a **cumulative target per subject per date**, then allocates only the study time needed to stay on pace. For example, a 10-hour requirement over 28 eligible days is spread through several weeks, not scheduled in the first five days.
|
|
50
|
+
|
|
51
|
+
Pacing is weighted by each day's available minutes (capped by the per-subject daily limit), rather than assuming that every date offers equal time. Date-specific days off are ignored. Subjects with an exam date pace only until the day before the exam; after the deadline they cannot receive events. Short tasks are discretized into 30-minute units, so a very light workload over many weeks will naturally leave some days empty.
|
|
52
|
+
|
|
53
|
+
If study time is scarce, the priority-weighted scheduler still selects higher-ranked subjects more often when competing for the same available window. Actual completion may be lower than the theoretical pacing target because breaks, simultaneous subject demands and deadline conflicts can constrain feasibility. This is a heuristic: it is not a formal optimality guarantee.
|
|
54
|
+
|
|
55
|
+
## Within-day time-window balance (v0.5.0)
|
|
56
|
+
|
|
57
|
+
Earlier versions paced sessions across calendar dates but filled a day's first availability window before touching later windows. If a student had 08:00–11:00 and 14:00–17:00 available, all daily tasks could end up in the morning.
|
|
58
|
+
|
|
59
|
+
Version 0.5.0 tracks the actual study minutes assigned to each daily availability window and chooses the window with the **lowest utilization fraction** (`study_minutes_in_window / window_minutes`). For equal-length morning and afternoon windows, two sessions usually go to different halves of the day. Longer windows can receive more work than shorter ones. If a day has just one session, the preferred starting window rotates across active study days so the same time of day is not always chosen.
|
|
60
|
+
|
|
61
|
+
The daily workload is still governed by the existing cumulative pacing targets. The algorithm does not create extra hours, violate exam deadlines, overlap events, or bypass per-subject daily limits. Some windows may be empty if the total demand is small, availability is limited, or a session cannot fit into the remaining space.
|