guap-alice: the SUAI timetable by voice
A voice skill for Yandex Alice: a weekly timetable, dialogue context and an answer before the timeout runs out.
In September 2026 I built a voice interface for the SUAI (GUAP) timetable. I wanted to ask “what time do I start tomorrow” and get the time of the first class, the room and the building, with my group remembered between conversations. That task became guap-alice, also called Guapik: a Python service with a webhook for Yandex Dialogs, the skills platform of the Alice voice assistant.
A conversation that keeps context
The skill understands the timetable for a day, the number of classes, the first and last class, start and end times, gaps and lecturers. After “what’s on tomorrow”, a short “how many classes” continues the conversation about tomorrow. “And on Thursday” changes the day and keeps the chosen group.
The project documentation gives this scenario (the skill itself speaks Russian):
| Phrase | What the skill does |
|---|---|
| “My group is 3437k” | Saves the group for future conversations |
| “What’s on tomorrow” | Names the classes, subjects, rooms and buildings |
| “What time” | Returns the start of the first class on the same day |
| “Any gaps” | Checks the intervals between classes |
A permanent group choice is kept apart from a one-off question. “For 2210 tomorrow” looks up someone else’s timetable and keeps your own group. There is a separate lecturer context: “what does Fomicheva have on Thursday”, then “and on Friday”. If surnames match, the skill asks for initials, and it also clarifies ambiguous dates and class numbers.
From a weekly template to a specific date
The SUAI source returns a weekly template with upper and lower weeks. To answer about a date, the provider reads the number and parity of the current week, works out the needed week and picks the matching classes. The directory has 581 groups and 775 lecturers, and updating it is a separate script.
1
2
3
4
5
6
7
Alice / Yandex Dialogs
↓ HTTPS
FastAPI → group, date and conversation context
↓
timetable provider → cache → public SUAI page
↓
choosing classes → response template → Alice
Dates, dialogue, timetable loading and Russian speech are split into modules. The answer is assembled from templates that can be tested. Buildings matter at SUAI: when classes are at different addresses, the skill warns about the move. I also had to work through Russian grammatical cases and fix a bug where the word for “Friday” was recognised as “fifth class”.
Surviving a slow source
The whole handler gets 2.8 seconds and the timetable request 1.8 seconds. A fresh cache is used for an hour, and if the source fails, the previous timetable can be served for up to a day. After that the service explains that the data is unavailable. These limits are set in the configuration, and the cache behaviour is implemented in the provider.
The webhook checks JSON, the request size and, when configured, a list of allowed skills. Phrases and user identifiers are not written to logs, and the chosen group is stored by Yandex.
What came out and how to check it
The dialogue, calendar calculation and HTTP service are implemented. The tests cover week parity, a one-off choice of another group, gaps, moving between buildings, ambiguous requests and source failure. They use synthetic timetables, so changes to the real HTML markup still need checking against the live source.
The timetable for exams, retakes and separate subgroups is limited by what the university publishes. So the next step depends on the quality of the source and on clarifications in the dialogue.
guap-alice open source code · Project page · Data source description