EdgeTutor

EdgeTutor is an offline Android tutor for low-memory devices. It retrieves from locally imported textbooks and runs Qwen3.5-0.8B through MNN-LLM without an internet connection at runtime.

Current state

android-mnn/ is the only product application. It supports:

• on-device PDF ingestion;
• Arctic ONNX embeddings and cosine-similarity retrieval;
• separate local indexes for multiple textbooks;
• Room-backed chat sessions;
• streamed MNN generation;
• device validation and performance reports.

The Android prompt contract and the fine-tuning pipeline use one teacher_v1 behavior with clean prose and no route markers. A retrieved passage is used silently when relevant and ignored when it is not.

Unified teacher model workflow

Every response gives a short explanation or useful hint, stays on topic, and ends with exactly one thoughtful question. The corpus balances fresh explanations, helpful analogies, misconception corrections, stuck/pushback turns, and topic continuity across four subjects.

Generate and validate a replacement dataset:

# Add the key once to the ignored root .env file:
# DEEPSEEK_API_KEY=your-key
python training/generate_data.py --passage-bank training/socratic_data --replace
python training/validate_data.py
python -m pytest tests/test_tutor_dataset.py -q

The generator checks the selected provider key in the process environment, then the ignored root .env, and securely prompts only when neither contains a key. It checkpoints episode blueprints and individual passage-condition jobs, repairs only failed conversations, and shows resumable progress with tqdm. The dataset is replaced only after all 300 traces pass critic and structural checks.

See training/README.md for training, evaluation, and export instructions.

Android development

Generate the local embedding assets:

python scripts/export_onnx.py

Build and test:

cd android-mnn
.\gradlew.bat testDebugUnitTest
.\gradlew.bat assembleDebug

See android-mnn/README.md for local model requirements, installation, and device validation.

Repository layout

edge-tutor/
├── android-mnn/             # Android product and on-device runtime
├── training/                # Dataset generation, training, evaluation, and export
│   ├── generation/          # Author and critic prompts
│   ├── teacher_data/        # Unified teacher training, validation, and test data
│   └── socratic_data/       # Retained until the teacher-data cutover gates pass
├── scripts/                 # ONNX export, diagnostics, and device capture tools
├── src/                     # Arctic ONNX parity implementation
├── tests/                   # Python tests and retrieval fixtures
├── reports/                 # Historical device and host-side evidence
├── local/                   # Ignored models, vendor sources, and working notes
├── data/                    # Ignored source documents and generated indexes
├── pyproject.toml           # Python project and dependency configuration
├── uv.lock                  # Locked Python dependencies
└── README.md

Python supports data preparation, model work, and Android diagnostics. It is not a second product runtime. Performance and answer-quality claims require Android device evidence.

Repository checks

python -m pytest tests/test_tutor_dataset.py -q
pwsh -File scripts/check_repo_hygiene.ps1

The ONNX tests additionally require the dependencies in the local virtual environment.

License

MIT. See LICENSE.