README.md

metadata

title: Document Exam Trainer
emoji: 🎓
colorFrom: blue
colorTo: indigo
sdk: gradio
sdk_version: 6.5.1
app_file: app.py
python_version: '3.12'
pinned: false

Document Exam Trainer v5.0.3

A generic written-or-oral study trainer with a hosted demo and a downloadable local Docker edition. Primary documents define the examinable material; supporting references clarify it. Feedback reports Essential / Important / Minor omissions, without a numerical grade.

Deploy this release

Default target: AngeloUNIMI/document_exam_trainer.

On Windows, run deploy_windows.bat --update. On Linux, run bash deploy_linux.sh --update. The developer deployment script uses a local Python virtual environment and requests a token with write access to that Space. This token is not bundled, sent to students, or stored as a Space secret. Add --create instead of --update only when deliberately creating a new Space. Add --enable-zerogpu to request ZeroGPU on an existing Space. No billed-hardware fallback is used.

The hosted Space remains a Gradio ZeroGPU Space. Docker is for the downloadable local edition, not the Space SDK.

The deployed version adds a Download & install tab and the versioned /trainer_infer_v1 text-only API. Both Windows and Linux buttons download downloads/document_exam_trainer_docker.zip; it contains the application and Docker build recipes, not model weights or a prebuilt image. A SHA-256 checksum is included. The deployment script rebuilds this download from an explicit source allowlist before uploading it.

Local Docker edition

Extract the download and run install_windows.bat or bash install_linux.sh. The setup wizard executes in the Docker container; end users do not need Python or a venv on the host.

Setup offers account login or a single-user local profile, CPU or remote-HF inference, public model presets, per-user tokens and remote-data consent. Users can later change their own backend and token in the app. Persistent named volumes store accounts, extracted course text, embeddings and learning history; another volume stores the token encryption key and another caches models.

The default URL is http://localhost:7860. The Compose port is bound to 127.0.0.1, not to the public network. The single-user option has no login protection and is appropriate only on a trusted personal computer.

Inference modes

Component	Hosted demo	Local Docker, remote mode	Local Docker, CPU mode
Parsing and embeddings	Space CPU	Local CPU	Local CPU
Speech-to-text	Space CPU	Local CPU	Local CPU
Question and rubric	Qwen3-4B, ZeroGPU	Target Space API	Qwen3-1.7B default, CPU
Evaluation	Qwen3-14B, ZeroGPU	Target Space API	Qwen3-1.7B default, CPU
Course/history persistence	Temporary browser session	Local Docker volumes	Local Docker volumes

CPU uses a smaller model to limit memory use and is not quality-equivalent to the hosted evaluator. The installer also offers Qwen3-4B for both local tasks or custom public Transformers-compatible IDs. One local LLM is kept resident at a time. FP32 is used for compatibility, not 4-bit quantization. Allow substantial RAM and several minutes per request; there are no measured throughput guarantees.

Remote mode sends selected primary/supporting text excerpts, the question, hidden rubric and transcript to Hugging Face. Original files and audio remain on the local host. Personal tokens are passed as client authentication, never placed in prompts or application packages. Caller quota still applies; there is no automatic paid fallback and no shared developer token.

Learning history

The local edition automatically saves processed courses and completed written or oral answer checks. It shows per-concept gap observations, the latest observed status, prior questions/answers, and a recurring-gap practice action. Repeated clicks on the same unchanged answer do not inflate history. These are descriptive observations, not a validated mastery score or a predicted exam result. Grouping uses normalized concept names and primary source IDs; paraphrases can form separate groups.

Answers can be entered directly in writing or supplied orally through local speech transcription. Transcribed text is inserted into the same answer box and may be reviewed or edited before evaluation. The inference endpoint receives answer text only; it is not an assessment-security or proctoring system.

See README_LOCAL.md, docs/DEPLOY_HF.md, docs/INSTALL_WINDOWS.md, docs/INSTALL_LINUX.md, PRIVACY.md, THIRD_PARTY.md and TEST_REPORT.md.