Turn trusted learning material into focused quizzes — locally.
A local-first desktop study app powered by Flutter, FastAPI, Ollama and Microsoft Learn.
Public alpha: the local-first architecture and core quiz pipeline are tested, while signed desktop distribution and the broader model compatibility matrix are still being expanded. See known limitations.
Quiz Machine Local is an open-source desktop study application for Microsoft AI certifications. It turns certification-scoped learning material into validated practice sessions using a model that already runs on your computer.
The application currently supports five Microsoft AI certification paths. It requires no account and includes no advertising, analytics, or publisher-operated backend. Imported corpora, generated questions, answers, and learning progress remain on the user's computer in the supported configuration.
| Path | Focus |
|---|---|
| AI-901 | AI concepts and Microsoft Foundry fundamentals |
| AI-103 | Building AI applications and agents on Azure |
| AI-200 | Developing cloud-native AI solutions on Azure |
| AI-300 | Operationalizing machine learning and generative AI |
| AI-500 | Designing and implementing production multi-agent systems |
Quiz Machine is an independent educational tool. It is not affiliated with, endorsed by, sponsored by, or an official product of Microsoft or any certification provider. It does not contain official exam questions and cannot guarantee an exam result.
| Local model | Prepared sessions | Explicit boundaries |
|---|---|---|
| Use a compatible Ollama model already installed on the machine. Nothing is downloaded silently. | Questions are generated, checked and stored before revision starts. No waiting on the model after each answer. | Learner answers, scores, imported corpora and progress remain local in the supported configuration. |
Desktop quiz workspace with safe demonstration content.
Responsive onboarding and local environment checks.
- retrieves the current measured skills and supporting pages from the public Microsoft Learn MCP service;
- persists one certification-scoped canonical corpus locally;
- builds a small evidence packet for one learning objective at a time;
- generates, validates, fingerprints, and explains questions with Ollama;
- reuses a validated local question bank before generating missing questions;
- completes the entire batch before revision, so answering never waits for an LLM call;
- tracks mastery, streaks, response time, coverage, and recurring confusions by certification objective;
- imports strictly structured, certification-scoped Markdown supplied by the user.
Question generation, factual validation, and explanation are separate model
calls. Stable opt_* identifiers are the correctness keys; A-D labels are
derived only from presentation order. The canonical question is frozen before
its explanation is generated, and the final artifact is checked again before
display and scoring.
flowchart LR
U["Learner"] --> F["Flutter desktop app"]
F -->|"loopback HTTP + token"| B["FastAPI backend"]
B --> Q["Validated question bank"]
B --> P["Local progress"]
B -->|"generation & validation"| O["Local Ollama model"]
B -->|"public documentation only"| M["Microsoft Learn MCP"]
classDef local fill:#e2f1ef,stroke:#0b6b68,color:#161a1b;
classDef external fill:#fff1e8,stroke:#a94f24,color:#161a1b;
class U,F,B,Q,P,O local;
class M external;
Flutter presents state and user intent. The backend owns retrieval, generation, validation, correctness and persistence. Ollama stays behind one provider boundary, and packaged builds expose the backend only on loopback with a random token. See the full architecture guide.
There is currently no stable end-user release. Source builds are available now; signed installers will appear on the GitHub Releases page after the first release candidate passes clean-machine verification. Do not use binary downloads from third-party mirrors.
- macOS or Windows for the supported desktop experience;
- Python 3.10 or newer;
- Flutter with desktop support;
- Ollama with at least one local text-generation model already installed;
curl.
On first launch, the app inventories the models already available through the
local Ollama API. It excludes embedding-only and cloud-backed entries and
recommends the strongest compatible model estimated to fit the machine's memory
budget. Before saving the selection it runs a small local structured-output
probe. No model is downloaded or replaced by Quiz Machine. The choice can be
changed later from the quiz workspace; QUIZ_MACHINE_LLM_MODEL remains
available as a locked developer or administrator override.
The model probe validates basic JSON-schema support, not educational quality.
Model and platform expectations are documented in
docs/COMPATIBILITY.md.
The legacy offline AI-103 mode additionally requires nomic-embed-text by
default. That embedding model must also be installed explicitly before launch.
Check the existing toolchain, prepare the source build and launch the complete development stack:
./scripts/doctor.sh
./start.shThe setup script creates .venv, installs the pinned Python dependencies when
needed, prepares the Flutter desktop runner, starts the loopback backend, and
launches Flutter. Onboarding then verifies Ollama, lets the user select an
installed generation model, and checks the Microsoft Learn connection. Neither
start.sh nor onboarding downloads Ollama models.
Run the backend and Flutter separately
./run_backend.sh
cd flutter_app
./bootstrap.sh
flutter pub get
flutter run -d macosWindows source build
Native Windows source builds use PowerShell and the Windows Flutter desktop toolchain. Generate the runner once from Git Bash, then launch the app:
bash .\flutter_app\bootstrap.sh
bash .\run_backend.sh
cd flutter_app
flutter run -d windowsThe repository currently provides run_backend.sh, so Windows contributors may
also start it from Git Bash. A native PowerShell launcher is tracked on the
roadmap.
Runtime state is ignored by Git and stored under storage/ during development
or in the operating system's application-data directory in packaged builds.
This includes the Microsoft Learn cache, the validated question bank, progress,
indexes, and logs.
By default, the application sends certification and objective search requests
to the public Microsoft Learn MCP endpoint. It does not send imported corpora,
answers, scores, or personal identifiers there. Ollama is called through its
local API at 127.0.0.1. Pointing Ollama at a remote endpoint changes that
privacy boundary and is the user's responsibility.
Set the following value to use the legacy local AI-103 corpus/index path and disable Microsoft Learn retrieval:
QUIZ_MACHINE_KNOWLEDGE_PROVIDER=localThe import format and content-rights rules are documented in
docs/CORPUS_FORMAT.md and
docs/PUBLISHABLE_CORPUS.md.
Run the smallest complete local checks from the repository root:
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q backend tests build_index.py quiz.py
bash -n setup.sh start.sh run_backend.sh scripts/*.sh
cd flutter_app
flutter analyze
flutter testThe tests use fakes for Ollama and Microsoft Learn. They do not download models or alter a real user corpus. A separate scheduled workflow performs a bounded live contract check against the public Microsoft Learn MCP endpoint.
backend/ local FastAPI API, corpus pipeline, RAG, quiz engine and stores
flutter_app/ Flutter desktop application and widget tests
tests/ Python unit and contract tests
scripts/ diagnostics and release packaging
packaging/ PyInstaller configuration
data/reference/ redistributable demonstration corpus, licensed separately
docs/ corpus, retrieval, contribution and release documentation
Generated platform runners, virtual environments, private corpora, runtime state, builds, releases, and Graphify indexes are intentionally excluded.
Read CONTRIBUTING.md before opening a pull request. Keep
changes local-first: no hosted account dependency, telemetry, secret, copied
exam content, or unlicensed training material belongs in this repository.
Every change to main goes through a pull request, automated checks and owner
review. Contributors can propose freely; repository approval and merge access
remain with the maintainer.
For help and public maintenance expectations, read SUPPORT.md.
Planned work is listed in ROADMAP.md, and release-facing changes
are recorded in CHANGELOG.md.
The application source is licensed under
GNU AGPL version 3 only, SPDX identifier AGPL-3.0-only.
The demonstration corpus under data/reference/ is offered separately under
CC0 1.0. Doto is distributed under the SIL Open Font License 1.1. Other
dependencies and Ollama models remain subject to their respective licences; see
THIRD_PARTY_NOTICES.md.


