Spaces:
Running on Zero
Running on Zero
| title: Document Exam Trainer | |
| emoji: "\U0001F393" | |
| 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`. | |