eule

Eule is a privacy-first, local-first learning assistant for children with adult oversight built in. The alpha focuses on safe local operation: child chat, audit visibility for parents and teachers, and curriculum-grounded responses through a local retrieval pipeline.

The long-term vision is a trustworthy family and school companion where learning support stays on-device by default, safety decisions are auditable, and adults remain in control. Today, the repository ships a practical backend-first alpha with working APIs, local storage, local model hooks, and UI slices for both child and oversight experiences.

Alpha Quick Start (Developer)

These steps are designed to get a new developer from clone to local run in about 10 minutes.

1. Clone and enter the repository.

git clone https://github.com/isartor-ai/euleki.git
cd euleki

2. Build and run tests.

cargo build --workspace
cargo test --workspace

3. Start the backend.

cargo run -p eule-core

4. Verify health and open UIs.

curl http://localhost:8080/health
open http://localhost:8080/
open http://localhost:8080/dashboard

5. Optional: load demo curriculum data for RAG grounding.

bash curriculum/download-samples.sh
bash curriculum/ingest-samples.sh
cargo run -p eule-cli -- search-curriculum --query "Was ist Fotosynthese?" --subject biologie --limit 5

Project Structure

• eule-core: Rust backend service (Axum), storage, inference integration, embedding and RAG pipelines, child/dashboard routes
• eule-cli: maintenance CLI for ingestion, retrieval checks, benchmarking, and model status
• eule-ui: child-facing UI assets
• eule-dashboard: oversight dashboard UI assets
• docs: architecture, changelog, infrastructure notes, evaluation docs, and user manuals

Voice Backend Configuration

The voice synth endpoints (/api/child/voice/synthesize, /api/dashboard/voice/synthesize) now run through a pluggable TTS service. The voice upload endpoint (/api/child/voice/ask-upload) runs through a pluggable STT strategy.

Default behavior:

• If EULE_TTS_MODEL_PATH is not set, Euleki prefers native macOS voice synthesis when available (say + afconvert) and falls back to the internal tone backend only when native tools are unavailable.
• If EULE_TTS_MODEL_PATH is set, Euleki attempts to run a command-backed TTS backend (default command: piper).

Supported environment variables:

• EULE_TTS_VOICE default voice profile (euli, neutral, teacher)
• EULE_TTS_MODE TTS runtime (native, tone; default remains fallback behavior)
• EULE_TTS_MODEL_PATH model path for command backend
• EULE_TTS_COMMAND command binary (default: piper)
• EULE_TTS_SPEAKER_EULI optional speaker id for euli
• EULE_TTS_SPEAKER_NEUTRAL optional speaker id for neutral
• EULE_TTS_SPEAKER_TEACHER optional speaker id for teacher
• EULE_TTS_NATIVE_VOICE_EULI optional macOS say voice for euli profile (default: Anna)
• EULE_TTS_NATIVE_VOICE_NEUTRAL optional macOS say voice for neutral profile (default: Anna)
• EULE_TTS_NATIVE_VOICE_TEACHER optional macOS say voice for teacher profile (default: Markus)
• EULE_TTS_NATIVE_RATE_WPM optional macOS say speech rate in words per minute (default: 165, allowed: 110-240)
• EULE_TTS_NATIVE_SAMPLE_RATE optional output WAV sample rate (22050, 24000, 32000, 44100, 48000; default: 44100)
• EULE_STT_MODE STT strategy mode (auto, voxtral_single_pass, stt_fallback)
• EULE_STT_MODEL_PATH model path for whisper-cli fallback backend
• EULE_STT_COMMAND command binary for fallback STT (default: whisper-cli)
• EULE_STT_FFMPEG_COMMAND conversion command for WebM uploads (default: ffmpeg)
• EULE_STT_LANGUAGE transcription language for fallback backend (default: de)
• EULE_STT_THREADS optional thread count for fallback STT backend

Health/status:

• GET /api/status now includes tts (boolean readiness) and tts_backend (active backend name).
• GET /api/inference/status now includes voice mode and capability fields (voice_mode, voice_available_modes, voice_startup_alerts, voice_capabilities).
• Current runtime behavior: voxtral_single_pass is reported as unsupported and the active mode falls back to stt_fallback.

Desktop App (macOS / Windows) — Early Scaffold

A cross-platform desktop shell is being built with Tauri v2. See desktop-app/README.md for full setup instructions.

Quick start:

# prerequisite: install Rust and Xcode CLT (macOS)
cargo install tauri-cli --version "^2"

# launch desktop window
cd desktop-app
cargo tauri dev

Rust-only compile check (no window, no Node.js needed):

cargo build -p eule-desktop

Sidecar lifecycle is integrated in issue #31:

• starts eule-core on desktop app launch
• uses a dynamic free localhost port (no hardcoded :8080)
• waits for /health before enabling UI links
• surfaces crash/retry state in the desktop shell

Security hardening from issue #34 adds:

• OS secure storage for desktop session token (with in-memory fallback)
• localhost-only backend request validation in desktop shell
• constrained model/audio env paths before sidecar launch

Architecture Overview

See the detailed architecture document:

• docs/ARCHITECTURE.md

Additional design context:

• docs/whitepaper.md
• design/child-ui/README.md
• design/oversight-dashboard/README.md

Documentation Index

• Changelog: docs/CHANGELOG.md
• Alpha release notes: docs/RELEASE_NOTES_v0.1.0-alpha.1.md
• Alpha2 release notes: docs/RELEASE_NOTES_v0.1.0-alpha.2.md
• Alpha3 release notes: docs/RELEASE_NOTES_v0.1.0-alpha.3.md
• User Manual (English): docs/USER_MANUAL.md
• Benutzerhandbuch (Deutsch): docs/USER_MANUAL.de.md
• Voice UI manual checklist: docs/VOICE_UI_CHECKLIST.md
• Dashboard voice audit checklist: docs/DASHBOARD_VOICE_CHECKLIST.md
• DMG cold-start voice checklist: docs/DMG_COLD_START_VOICE_CHECKLIST.md
• Desktop beta QA gate checklist: docs/DESKTOP_BETA_QA_GATE.md
• Voice quality acceptance samples: docs/VOICE_QUALITY_ACCEPTANCE.md
• Infrastructure notes: docs/INFRASTRUCTURE.md
• macOS app bundle guide: docs/MACOS_APP_BUNDLE.md
• macOS DMG installer guide: docs/MACOS_DMG.md
• Windows signing and installer release guide: docs/WINDOWS_RELEASE.md

Alpha Release v0.1.0-alpha.3

• GitHub release: https://github.com/isartor-ai/euleki/releases/tag/v0.1.0-alpha.3
• Bug reports: alpha bug report template

Alpha Quick Start (Testers)

1. Download the DMG from the release page.
2. Drag Euleki.app into Applications.
3. Launch Euleki from Applications.
4. If setup is prompted, choose Install core + voice (recommended), Install core only, or Skip for now.
5. Keep internet connection active until selected downloads finish.
6. Euleki opens child chat automatically at http://127.0.0.1:8080/.
7. Open oversight dashboard at http://127.0.0.1:8080/dashboard.

No terminal commands are needed for the tester flow.

How to Contribute

Please read:

• CONTRIBUTING.md

At minimum before opening a PR:

cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo test --workspace

License

This project is licensed under EUPL-1.2.