Archangel

Posted on Oct 25 Edited on Oct 25

🦥 Sloth Study: Maximum Retention, Zero Scramble

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady Submission 🦥

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

October 20 is International Sloth Day, and sloths have mastered energy conservation: they move slowly, stay calm, avoid unnecessary motion, and let the world come to them.

Studying for college exams, medical certifications, professional licenses, or technical interviews is usually the exact opposite—an exhausting, high-friction ordeal:

Passive Reading Paralysis: Staring at a 40-page technical PDF or 80-slide lecture deck yields poor retention without active recall and self-testing.
The Exhausting Note-Making Grind: Distilling notes, writing flashcards, and formulating multiple-choice test questions takes 2 to 3 hours of grueling administrative effort before actual learning even begins.
Hallucination Anxiety: Pasting confidential research or textbook chapters into commercial cloud chatbots often leads to hallucinations—inventing plausible-sounding historical dates, inaccurate equations, or subtly flawed formulas.
Privacy & Compliance Risks: Students, legal scholars, and corporate researchers cannot legally or ethically paste proprietary curriculum, draft manuscripts, or internal whitepapers into third-party cloud AI servers.
Subscription & Token Fatigue: Monthly fees ($20–$30/month) and pay-per-token API tiers place high-quality study assistants out of reach for students on tight budgets.

The Solution: Sloth Study 🦥

Sloth Study channels the sloth mindset: maximum outcome with minimal energy expenditure. It turns dense PDFs and lecture notes into a verified revision kit in seconds—running entirely on your laptop with zero data ever leaving your machine.

You drag and drop any lecture note, paper, or handbook. Sloth Study automatically creates:

Concise Grounded Takeaways: High-yield bullet points summarizing the core concepts.
Verifiable Active Recall Flashcards: Question-and-answer flip cards with progress tracking ("Got it" counter) and a "Show source" toggle that displays the exact raw text chunk from your original notes to guarantee zero hallucination.
Interactive Scored Quiz: 4-option multiple-choice testing with instant visual feedback (calming green for correct, subtle highlight for incorrect), grounded explanations, and backing quote citations.
Spoken Audio Brief: A conversational spoken revision script formatted for listening while resting, walking, or lying down.

All wrapped in a calm editorial interface (warm cream canvas #E7EBE2, rich ink #2B2622, and deep forest accent #2F5D50) designed to minimize visual stress and keep your focus undisturbed.

Demo

💻 Step-by-Step Local Walkthrough

Running Sloth Study locally takes under two minutes:

Upload Your Notes: Open http://localhost:3000/upload and drop in any PDF (e.g. samples/01_finance_money_basics.pdf or your own course notes).
Live Streaming Progress: Watch the real-time Server-Sent Events (SSE) pipeline extract text, slice token windows, and draft flashcards with live percentage updates.
Study with Confidence:
- Flip through cards with keyboard or mouse.
- Click "Got it" to track mastered cards.
- Click "Show source" on any card or quiz question to reveal the verbatim paragraph from your original notes.
- Take the scored quiz and receive instant visual color feedback (.opt.right / .opt.wrong) with grounded rationales.
- Read or listen to the ~700-word spoken audio summary script.

Code

Check out the complete open-source codebase on GitHub:

🔗 Repository: https://github.com/Uxie7/sloth-study

How I Built It

Sloth Study is built around a clean, modular architecture. The core Domain has zero I/O and zero external dependencies, while all interactions with models, parsers, and databases are encapsulated in clean Adapters.

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#EFE7DB', 'edgeColor': '#2F5D50', 'primaryTextColor': '#2B2622'}}}%%
flowchart LR
    PDF["📄 User PDF / Notes"] --> EXTRACT["PyMuPDF Native Parser"]
    EXTRACT --> CHUNK["Token-Aware Chunker (1500 tokens)"]
    CHUNK --> LLM["Google Gemma 2 2B (via Ollama)"]
    LLM --> STORE[("SQLite DB (data/sloth.db)")]
    STORE --> UI["🖥️ Next.js 16 Web App"]

    subgraph Output ["Your Revision Kit"]
        UI --> FC["🃏 Grounded Flashcards + Source Toggle"]
        UI --> QZ["🎯 Scored Quiz + Distractor Feedback"]
        UI --> AB["🎧 Spoken Audio Revision Brief"]
    end

    style PDF fill:#EFE7DB,stroke:#B08D57,stroke-width:2px;
    style EXTRACT fill:#E4ECE7,stroke:#2F5D50,stroke-width:2px;
    style CHUNK fill:#E4ECE7,stroke:#2F5D50,stroke-width:2px;
    style LLM fill:#DCE6DF,stroke:#2F5D50,stroke-width:2px;
    style STORE fill:#EFE7DB,stroke:#B08D57,stroke-width:2px;
    style UI fill:#F3F6F0,stroke:#2F5D50,stroke-width:2px;
    style Output fill:#FAFBF8,stroke:#2F5D50,stroke-width:1px;

The Open Model Stack

Google Gemma 2 2B (via Ollama): Google's compact 1.6 GB open-weight model is the brain of the project. It runs at high token speeds on standard laptop CPUs without needing discrete GPUs. We instruct it using strict Pydantic JSON schemas to extract flashcards, key takeaways, and quiz questions with 100% adherence.
PyMuPDF (pymupdf): Fast, local C-based text extraction from raw PDF byte streams without sending files to third-party OCR or cloud parsers.
Next.js 16 (JavaScript): A zero-bloat web frontend styled with native CSS custom properties. It delivers smooth card-flip animations, accessible tabs, and instant answer verification without heavy UI libraries.
FastAPI & Server-Sent Events: An async Python server orchestrating extraction, token chunking, and model inference with real-time SSE progress streaming.
SQLite Persistence: Stores completed study kits, structured flashcards, quizzes, and the raw text chunks locally in data/sloth.db.
Piper Neural TTS: Lightweight, local text-to-speech running on ONNX for air-gapped spoken brief generation.

Grounding & Verifiable Facts

The biggest problem with AI study tools is trusting the output. Sloth Study solves this by storing the original text chunks directly alongside the kit in SQLite.

Every flashcard and quiz question retains a source_chunk index. Clicking "Show source" opens a neat, indented quote block containing the exact passage from your original notes, so you can verify facts in context.

Why Does Open Innovation Matter?

Open innovation is what made Sloth Study possible:

True Intellectual Sovereignty: Educational research, confidential manuscripts, legal briefs, and proprietary business documents should not be used as training fodder for commercial cloud models. Open-weight models running on consumer hardware guarantee that sensitive text never leaves your laptop.
Zero Ongoing Costs ($0/month): Commercial AI platforms lock high-yield learning behind expensive monthly tiers or usage-based token meters. With Google's Gemma 2 running locally, students and lifelong learners can generate thousands of revision kits without spending a single dollar.
Resilient & Air-Gapped: Whether you are studying on an airplane, in a rural school with unstable connectivity, or during internet disruptions, open-source AI operates unconditionally.
Democratization on Everyday Hardware: Heavy 70B models require multi-GPU cloud clusters. Google's Gemma 2 2B demonstrates that compact, highly capable open-weight models can run directly on consumer laptops, making cutting-edge AI truly accessible to everyone.

The Lazy Payoff

How much effort does Sloth Study actually save?

The Old Manual Way:
- Reading a 30-page lecture PDF or chapter: 45–60 minutes
- Extracting core concepts and writing flashcards: 30 minutes
- Formulating multiple-choice test questions: 20 minutes
- Writing a spoken summary script: 15 minutes
- Total Administrative Grind: $\sim$110 to 125 minutes of manual effort per topic.
The Sloth Study Way:
- Drag and drop PDF $\rightarrow$ lean back like a sloth for 35 seconds $\rightarrow$ your complete interactive revision kit is ready.
The Payoff:
- 98% time and energy savings on note creation, allowing you to spend 100% of your cognitive energy on active recall, understanding, and rest.

Prize Categories

We are entering the following partner categories for the Hacktoberfest Open-Source AI Challenge: Week 3:

Best Use of Gemma: Google's gemma2:2b runs 100% locally via Ollama to generate grounded flashcards, multiple-choice quizzes with distractor repair, grounded summary bullet points, and ~700-word conversational spoken audio brief scripts in strict Pydantic JSON schemas.
Best Use of ElevenLabs: Adapter built in src/adapters/tts_elevenlabs.py providing cloud-enhanced expressive voice audio generation for the study kit audio briefs (with Piper as local offline fallback).
Best Use of Sentry Agent Tracing: Distributed tracing with custom span() wrappers in src/observability.py tracking PDF extraction, Ollama chunk inference, and SQLite/TTS spans with complete client-side PII scrubbing and zero network calls when disabled.
Best Use of GitHub Copilot: Agent pairing and tracking during the project development recorded into DevRelay session 1201.
Best Use of DevRelay: Full agent pair-programming lifecycle and debugging milestones captured and embedded via interactive session {% agent_session 1201 %}.

DEV Community