🦊 Kalvin App — Offline AI 3D Visual Learning Companion

🌟 ▶ Click Here to Watch the Full Kalvin App Demonstration Video

"Education for all is our Mission. Trusted by Parents. Loved by Students."
100% Offline • 3D Anaglyph Stereoscopic Visualizations • Edge LLM Tutoring • Zero Internet & Zero Distractions

---

🧭 Table of Contents

• ✨ What Makes Kalvin Special?
• 🕶️ 3D Stereoscopic Visual Engine
• 🧠 Autonomous Offline AI Tutoring Stack
• 🧩 Application Architecture
• 🎮 Key Modules & Learning Modes
• 🛠️ Tech Stack & Dependencies
• 🚀 Getting Started & Local Setup
• 📂 Project Directory Tour
• 🤝 Contributing & Mission

---

✨ What Makes Kalvin Special?

Most EdTech solutions require continuous high-speed broadband, exposing children to algorithm rabbit holes, advertisements, and data harvesting. In underserved communities and remote regions, internet access is often intermittent or completely nonexistent.

Kalvin is engineered from the ground up as a sovereign, local-first learning companion:

1. 🚫 100% Offline by Design: Runs cutting-edge quantized LLMs (GGUF via llama.cpp and llama_cpp_dart) locally on-device. No data ever leaves the student's hardware.
2. 🕶️ 3D Anaglyph Stereoscopic Visual Engine: Students put on simple red-cyan 3D glasses and watch volcanic eruptions, planetary orbits, and water cycles pop off the screen in realistic depth.
3. 🦊 Empathetic AI Tutor Persona: Kalvin adapts his tone, pacing, vocabulary, and emotional encouragement to match the learner's comprehension level.
4. 🎙️ Natural Voice Conversations: Hands-free multi-turn dialogues combining local Speech-to-Text (STT) with expressive Text-to-Speech (TTS).
5. 🛡️ Safe & Distraction-Free: No web browsing, no sponsored content, and no external trackers. Pure focus on science, exploration, and curiosity.

---

🕶️ 3D Stereoscopic Visual Engine

Kalvin bridges textbook theory and spatial intuition using an embedded Three.js visual engine configured with Anaglyph Stereoscopy:

Interactive 3D Scene	Scientific Concepts Taught	Interactive Controls
🪐 Solar System	Heliocentric orbits, celestial scale, planetary rotation, orbital velocity	360° orbital camera, zoom to Earth/Mars/Jupiter, speed dials
🌋 Volcanic Eruption	Magma chambers, crust pressure, pyroclastic ash dispersion, tectonic plates	Cross-section dissection view, eruption pressure trigger
💧 The Water Cycle	Evaporation, atmospheric condensation, precipitation, groundwater infiltration	Particle flow paths, thermal sliders, phase transition toggles

Students can switch between Monoscopic 2D mode and Red-Cyan Anaglyph 3D mode on any standard screen with zero specialized hardware.

---

🧠 Autonomous Offline AI Tutoring Stack

Kalvin includes an on-device cognitive architecture that ensures child-safe, curriculum-aligned, and encouraging pedagogical dialogues:

flowchart LR
    Mic["🎙️ Student Voice Input"] --> STT["Local STT Engine"]
    STT --> Pipeline["Cognitive AI Pipeline"]

    subgraph CognitiveCore ["lib/ai/ - Local Intelligence Layer"]
        Pipeline --> Discovery["Context Discovery Engine"]
        Discovery --> Profile["Learner Profile & History (Hive)"]
        Profile --> Personality["Personality & Emotion Engine"]
        Personality --> LLM["Local llama.cpp Engine (GGUF)"]
        LLM --> Sanitizer["Response Sanitizer & Quality Filter"]
        Sanitizer --> Trigger["3D Visual Trigger Engine"]
    end

    Trigger -->|Visual Actions| Engine3D["🕶️ Three.js Stereoscopic Stage"]
    Sanitizer -->|Spoken Response| TTS["🔊 Expressive Local TTS"]
    Sanitizer -->|Animated Feedback| Avatar["🦊 Rive & WebM Avatar States"]

Loading

The AI Pipeline in Action

• Context Discovery Engine: Dissects user questions to detect subject matter, difficulty level, and emotional frustration.
• Personality Engine: Injects Kalvin's signature friendly, curiosity-sparking mentor voice.
• Visual Trigger Engine: Recognizes when an explanation would benefit from visual immersion and automatically commands the Three.js stage to load corresponding 3D models and animations.
• Quality & Safety Filter: Filters hallucinations, ensures age-appropriate guidance, and formats bite-sized learning cards.

---

🧩 Application Architecture

flowchart TD
    subgraph UI ["Flutter Presentation Layer (lib/screens)"]
        Home["Home Dashboard (home_screen.dart)"]
        Learn["Interactive Learn & Chat (learn_screen.dart)"]
        Visual["3D Immersion Studio (studio_screen.dart)"]
        Library["Saved Knowledge Library (library_screen.dart)"]
        ModelSetup["Model Setup & Quantization Manager"]
    end

    subgraph State ["Core Services & State (lib/services)"]
        Nav["Main Navigation Hub"]
        Theme["Theme & Accessible Color System"]
        HiveDB[("Hive NoSQL Local Storage")]
    end

    subgraph AI_Bridge ["Edge Inference & Hardware Bridge"]
        LlamaService["llama_cpp_dart Bridge"]
        AudioBridge["Audio & TTS/STT Controller"]
        InAppWebView["InAppWebView (Three.js WebGL Host)"]
    end

    subgraph AssetsStore ["Local Offline Bundle (assets/)"]
        GGUF["Quantized AI Model Files"]
        ThreeScenes["Three.js 3D Scenes & Textures"]
        RiveAnim["Rive Fox Avatars & Lottie Assets"]
    end

    UI --> State
    State --> AI_Bridge
    AI_Bridge --> AssetsStore

Loading

---

🎮 Key Modules & Learning Modes

• 🏫 Learn Studio: Interactive chat interface with Kalvin. Ask science, history, or math questions and watch explanations unfold with text cards, voice narration, and reactive avatar expressions.
• 🪐 3D Visual Sandbox: Direct access to inspect, rotate, and experiment with stereoscopic 3D scientific phenomena.
• 📚 Personal Knowledge Library: Automatically bookmarks learned topics, quiz recaps, and fascinating facts for offline revision.
• ⚙️ Model Setup & Hardware Tuning: Fine-tune CPU thread allocation, context window size, and model temperature to optimize performance on low-end budget tablets and laptops.

---

🛠️ Tech Stack & Dependencies

Layer	Component	Description
Framework	Flutter 3.11+ / Dart	Cross-platform UI toolkit targeting Mobile & Desktop
Edge AI Engine	llama_cpp_dart & llama.cpp	Hardware-accelerated local GGUF model execution
3D Rendering	Three.js + AnaglyphEffect	WebGL 3D stereoscopic rendering embedded via flutter_inappwebview
Interactive Avatar	Rive (rive: ^0.13)	Vector-based state-machine animations for Kalvin's facial emotions
Local Storage	Hive & Hive Flutter	High-performance, lightweight key-value database for chat & learner profiles
Voice Processing	speech_to_text & flutter_tts	Completely on-device audio I/O pipeline
Media Playback	video_player	In-app playback for animations and conceptual explainers

---

🚀 Getting Started & Local Setup

Prerequisites

1. Flutter SDK (Version >=3.11.5): Install Flutter
2. Platform Build Tools:
   • For Windows: Visual Studio 2022 with Desktop development with C++
   • For Android: Android Studio & Android SDK
   • For macOS/iOS: Xcode

---

Step 1: Clone the Repository

git clone https://github.com/AP952005/Kalvin.git
cd Kalvin

Step 2: Install Flutter Dependencies

flutter pub get

Step 3: Set Up Local AI Model (GGUF)

1. Download a compatible quantized model (e.g., Llama-3.2-1B-Instruct-Q4_K_M.gguf or Qwen2.5-1.5B-Instruct-Q4_K_M.gguf).
2. Place the .gguf model in the app's local directory or load it directly through the Model Setup Screen within the app UI.

Step 4: Run the Application

# Launch on Windows Desktop:
flutter run -d windows

# Launch on Android device / emulator:
flutter run -d android

---

📂 Project Directory Tour

Kalvin/
├── assets/
│   ├── thumbnail.jpg              # Official video walkthrough banner
│   ├── avatars/                   # Kalvin fox character states (think, speak, idle)
│   ├── model/                     # Windows llama.cpp native DLLs & CLI tools
│   ├── prompts/                   # Pedagogical prompt templates & safety guards
│   ├── rive/                      # Rive vector animations (rocket, avatar)
│   └── visual_engine/             # Three.js 3D WebGL engine
│       ├── AnaglyphEffect.js      # Red-Cyan stereoscopic 3D camera shader
│       ├── OrbitControls.js       # Touch & mouse 3D camera navigation
│       ├── main.js                # Scene loading & animation dispatcher
│       └── scenes/                # Scientific 3D simulations (solar system, volcano, water cycle)
├── lib/
│   ├── ai/                        # On-device AI brain
│   │   ├── llama_service.dart     # llama_cpp_dart inference bridge
│   │   ├── conversation_manager.dart # Context window management
│   │   ├── personality_engine.dart# Kalvin's pedagogical voice
│   │   └── visual_trigger_engine.dart # Text-to-3D scene triggers
│   ├── core/                      # Global constants, errors, and utils
│   ├── screens/                   # App pages (Home, Learn, Studio, Library, Setup)
│   ├── services/                  # Database (Hive) & Audio/TTS controllers
│   ├── theme/                     # Kid-friendly color palettes & typography
│   └── main.dart                  # App bootstrap & service initializers
├── pubspec.yaml                   # Flutter dependencies & asset registrations
└── README.md                      # Documentation & showcase

---

🤝 Contributing & Mission

Kalvin was built with the belief that high-quality, visual, and intelligent education should belong to every child—regardless of internet connectivity or socioeconomic background.

Contributions of all kinds are warmly welcomed:

• 🪐 New Three.js 3D scientific scenes (e.g., Human Anatomy, Chemistry Molecular Bonding, Plant Photosynthesis)
• 🌍 Translations & multi-language prompts for local dialects
• ⚡ Model quantization and inference speed optimizations

Feel free to fork the repository, open issues, and submit pull requests!

---

📄 License

This project is licensed under the MIT License.

Dedicated to curious minds everywhere. 🚀