winget install --id=Yaksharo.AdviseeDocFiller -e A small tool for UNP CCIT advisers, available as a standalone desktop app or a local web app. It reads Periodic Grades Listing PDFs from the student portal and fills two official forms for every advisee: the Appraisal Sheet (VPAA-CCIT-QF-05) and the Report of Rating (VPAA-CCIT-QF-09).
A small tool for UNP CCIT advisers that turns Periodic Grades Listing PDFs into filled Appraisal Sheets and Reports of Rating - as a standalone desktop app or a local web app.
Every term, CCIT advisers have to turn the registrar's Periodic Grades Listing PDF into two official forms, by hand, for every advisee:
Advisee Document Filler reads the grade listing PDFs, matches students across terms, and generates both documents automatically.
Filling these forms by hand is repetitive, error-prone, and doesn't scale past a handful of advisees. This tool exists so an adviser can point it at the PDFs the SIAS already provides and get correctly formatted, ready-to-print documents back in a few clicks - no copy-pasting names and grades between spreadsheets and Word templates.
flowchart TD
A[Grade Listing PDFs] --> B[Parser extracts students, course, grades]
B --> C[Students matched across terms by ID number]
C --> D[Course code selects Appraisal Sheet template]
D --> E[Documents filled: Appraisal Sheet + Report of Rating]
E --> F[Unused rows trimmed]
F --> G[docx output: individual files or one merged batch]
Language: Python 3
Libraries: Flask · pdfplumber · python-docx · docxcompose · darkdetect
Packaging: PyInstaller (onedir builds), Inno Setup (Windows installer), deb/rpm/pkg (Linux), GitHub Actions, Sigstore/cosign
flowchart LR
subgraph UI
GUI[Desktop wizard - Tkinter]
WEB[Web app - Flask + HTML]
end
GUI --> CORE
WEB --> CORE
subgraph CORE[Shared core]
PARSER[parser.py]
FILLER[filler.py]
STORE[store.py - SQLite]
end
PARSER --> FILLER
STORE --> FILLER
FILLER --> DOCX[templates_docx/*.docx]
DOCX --> OUT[Generated .docx output]
Both the desktop app and the web app are thin UIs over the same parsing and filling logic, so behavior stays identical between the two.
appraisal-filler/
├── app.py # Flask web app
├── gui_app.py # Tkinter desktop wizard
├── parser.py # Periodic Grades Listing PDF parser
├── filler.py # Fills the docx templates
├── store.py # Local SQLite store for remembered names
├── version.py # Resolves the running build's version
├── templates_docx/ # Appraisal Sheet / Report of Rating .docx templates
├── templates/ # Web app HTML
├── static/ # Web app assets (favicon, etc.)
├── assets/ # App icon / logo
├── signing/ # Windows publisher certificate
├── build_windows.bat # Local Windows PyInstaller build
├── build_linux.sh # Local Linux PyInstaller build
├── installer.iss # Inno Setup script for the Windows installer
└── .github/workflows/ # CI: builds executables and Linux packages
A step-by-step wizard, with no web server, no network, nothing exposed.
From source:
pip install -r requirements.txt
python gui_app.py
Tkinter is required once on Linux: sudo apt install python3-tk
Also available as a single-file executable, with no Python needed on the target machine:
build_windows.bat produces dist\AdviseeDocFiller.exebuild_linux.sh produces dist/AdviseeDocFillerEach is built on the OS it targets - PyInstaller does not cross-compile, so the Windows exe is built on Windows and the Linux binary on Linux. A Linux binary runs on distros with the same or newer glibc than the build machine.
Generated documents default to an AdviseeDocuments folder inside the
real Documents folder (Documents\AdviseeDocuments on Windows, resolved
even if OneDrive or a domain policy has redirected it;
~/Documents/AdviseeDocuments on Linux, following the XDG user-dirs
setting). The output location can be changed via "Browse..." on the
Generate step.
pip install -r requirements.txt
python app.py
It binds to 127.0.0.1 only (loopback, not visible to the network) and picks a free port in the dynamic private range (49152-65535), with the exact address printed on start.
Windows, two options from the same build:
AdviseeDocFiller-Setup-1.0.exe installs to
C:\Program Files\Yaksharo Solutions\Advisee Document Filler, adds a
Start Menu entry (and optional desktop icon), and registers a normal
uninstaller in Windows Settings.AdviseeDocFiller-windows-portable.zip extracts once
anywhere (USB stick included), with AdviseeDocFiller.exe runnable
directly inside. The folder can be copy-pasted to move it, as long as
the exe stays next to its _internal folder.Linux portable: AdviseeDocFiller-linux.tar.gz extracts and runs.
Linux packages (built for the three big families, attached to Releases):
sudo apt install ./adviseedocfiller_*.debsudo dnf install ./adviseedocfiller-*.rpmsudo pacman -U adviseedocfiller-*.pkg.tar.zstEach package installs the app to /opt/AdviseeDocFiller, adds an
adviseedocfiller command, and registers a menu entry with the app
icon. Note: the binary inside is built on GitHub's Ubuntu runner, so it
needs a distro with the same or newer glibc. Arch and current Fedora
are fine; very old LTS releases may not be.
Builds use PyInstaller's onedir mode: the app is a folder with the
executable inside, next to an _internal folder. It starts in about a
second - heavy libraries load lazily, so the window appears immediately
and the PDF engine loads in the background the first time you click Next.
Both apps walk through the same steps; the desktop wizard breaks them into pages (PDF Files → Students → Documents → Faculty → Generate), and the web app does the same work on a single page with a "Preview students" button.
CT103 = Cy Burr, MSIT). The PDF has no instructor names, so the
Faculty and Instructor columns stay blank unless you map them - leaving
a faculty field empty also leaves it blank in the generated documents,
it does not fall back to a placeholder name.A visual run-through of the wizard, start to finish. Screenshots live in
docs/screenshots/ - see that folder's README if
you're updating them.
1. Launch the app
Start Menu (if installed) → Yaksharo Solutions → Advisee Document Filler. Portable and Linux builds launch the same way from their extracted folder or menu entry.
2. Step 1 - PDF Files
The wizard opens here. Enter the Adviser and Dean name (both required - printed on the signature lines of both documents and remembered for next time).
3. Add the grade listing PDFs
Click "Add PDF files..." and pick one or more Periodic Grades Listing PDFs from the student portal - 1st and 2nd term (and beyond) can be added together in one go.
4. Ready to parse
With the names filled in and the PDFs listed, click "Next >". Select a file and click "Remove selected" if you added the wrong one.
5. Parsing
The PDFs are read on a background thread, so the window stays responsive while it works.
6. Step 2 - Students
Every student found across the PDFs, matched by ID number. Untick anyone you want to skip, or use Select all / Select none.
7. Step 3 - Documents
Choose which documents to generate, which terms to include on the Report of Rating, and the output format (individual files vs. one merged batch file for bulk printing).
8. Step 4 - Faculty
Every subject code found in the PDFs, with a Faculty name field for each. Pick a name you've used before or type a new one; leaving one blank leaves that column blank in the generated documents.
9. Step 5 - Review and generate
Double-check the summary, set (or Browse to) the output folder, and click "Generate documents".
10. Generating
A progress bar tracks each document as it's written.
11. Done
Click "Open output folder" to jump straight to the generated .docx
files.
The app keeps a small local SQLite database (store.db, in the OS's
standard per-user app-data folder - never bundled, never synced) of every
Adviser, Dean and per-subject-code faculty name you've typed. Next time,
those show up as suggestions: a dropdown you can pick from on the desktop
app, or autocomplete on the web app, and the faculty step pre-fills any
subject code it recognizes from a previous run. You can still type a new
name at any time - nothing is required to already be in the list. Nothing
in this database ever leaves the machine.
BSCS, BSIT, BLIS or DCT) picks
the Appraisal Sheet template. An unrecognized code falls back to the
BSCS template.1st/25-26 style. Change term_sy_label in
filler.py if your format differs.Push this project to a GitHub repository. The included workflow at
.github/workflows/build.yml builds both executables on GitHub's own
Windows and Linux machines, so you never build on your own computer.
v1.0
(git tag v1.0 && git push origin v1.0). GitHub builds both binaries
and attaches them to a proper versioned Release page instead of the
rolling "latest" one.Every release includes SHA256SUMS and SHA256SUMS.bundle. The bundle
proves the published files were built by this repo's build.yml on
GitHub's runners and haven't been altered since, using
Sigstore keyless signing (no private key to
leak, verifiable against the public Rekor transparency log). This is a
supply-chain integrity check, not a Windows/Authenticode signature - it
won't change the SmartScreen or "Unknown Publisher" prompt, which come
from a separate, CA-based trust system.
To verify with cosign:
cosign verify-blob \
--bundle SHA256SUMS.bundle \
--certificate-identity-regexp "^https://github.com/Yaksharo/appraisal-filler/" \
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
SHA256SUMS
Then confirm your downloaded file's hash appears in SHA256SUMS
(sha256sum -c SHA256SUMS on Linux, certutil -hashfile SHA256
on Windows).
Window style
Themes and accessibility
App icon
The logo in assets/ is used everywhere automatically:
assets/logo.png somewhere permanent (e.g. /opt/AdviseeDocFiller/),
adjust the paths inside AdviseeDocFiller.desktop, and copy that file
to ~/.local/share/applications/.templates_docx/. Replace them with updated forms
as long as the table layout stays the same; add a new course by dropping
in a docx and adding it to APPRAISAL_TEMPLATES in filler.py.parser.py.VERSION (bundled by the build
workflow from the git tag) and falling back to git describe when
running from source. See version.py.Developed by Yaksharo a.k.a. Ezer