Turn Brazilian university teaching plans into calendar events.
Give it your teaching-plan PDFs and weekly timetable. It finds tests and activities, assigns dates and class times, then writes files you can import into Google Calendar, Apple Calendar, or Outlook.
git clone https://github.com/raulkolaric/ics-parse.git
cd ics-parse
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
# Add your API key to .env
python run.pyThe terminal guides you through the rest.
Put these in files/:
image.png— your weekly timetable screenshot.- One PDF teaching plan for each subject.
- Optional: an academic calendar as PDF, PNG, JPEG, or WebP.
Name an academic calendar with a word such as calendar, calendario,
academico, or feriado and it will be found automatically. You can also
enter its path in the terminal.
The optional calendar keeps estimated dates from drifting after holidays, recesses, or cancelled class days.
When a calendar has different rules for different campuses, the terminal asks for your campus and, if useful, your unit, course, and shift. A Sorocaba-only recess is excluded for a São Paulo student. If a row is unclear, the tool asks you instead of guessing.
The calendar may be normal text, scanned pages, or a mixture of both. Its page
results are saved under output/academic-calendar-cache/, so rerunning the
tool does not need to process the same pages again. A record of the decisions
is written to output/academic-calendar-review.json.
Only closures explicitly present in the calendar are used. The tool does not invent bridge days around holidays.
The project uses an OpenAI-compatible API for reading documents and images.
Copy .env.example to .env, then set the values for your provider:
API_KEY=your-key
BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
MODEL_TEXT=qwen-turbo
MODEL_VISION=qwen-vl-plusThe defaults work with Alibaba DashScope's Qwen models. Any compatible provider
with a text model and an image-capable model should work. Your key is read from
.env and is not printed or saved in output files.
After a successful run, look in output/:
events.csv— a simple table of events.events.ics— import this into your calendar app.extracted/— Markdown copies of the teaching-plan text used for extraction.academic-calendar-review.json— present only when you use an academic calendar.
Regular classes are not exported. The output contains tests and activities found in the teaching plans. Dates written directly in a plan are used when they look valid; other dates are estimated from the class number and timetable.
files/ input PDFs, timetable image, and optional academic calendar
output/ generated CSV, ICS, cache, and review report
extracted/ extracted teaching-plan Markdown files
src/ parsing and date logic
run.py entry point
MIT