learn-lock 0.1.8

██╗     ███████╗ █████╗ ██████╗ ███╗   ██╗██╗      ██████╗  ██████╗██╗  ██╗
██║     ██╔════╝██╔══██╗██╔══██╗████╗  ██║██║     ██╔═══██╗██╔════╝██║ ██╔╝
██║     █████╗  ███████║██████╔╝██╔██╗ ██║██║     ██║   ██║██║     █████╔╝
██║     ██╔══╝  ██╔══██║██╔══██╗██║╚██╗██║██║     ██║   ██║██║     ██╔═██╗
███████╗███████╗██║  ██║██║  ██║██║ ╚████║███████╗╚██████╔╝╚██████╗██║  ██╗
╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚══════╝ ╚═════╝  ╚═════╝╚═╝  ╚═╝

The app that argues with you.

LearnLock is a CLI learning tool that uses adversarial Socratic dialogue to expose gaps in your understanding. It doesn't quiz you — it interrogates you.

Feed it a YouTube video, article, PDF, or GitHub repo. It extracts concepts, builds falsifiable claims, then duels you — inferring what you believe, finding contradictions, and attacking your weakest points.

Table of Contents

• Installation
• Quick Start
• How It Works
• Architecture
• The Duel Engine
• Claim Pipeline
• CLI Commands
• Configuration
• Development
• Known Limitations
• License

Installation

From PyPI

pip install learn-lock==0.1.8

Requires Python 3.11 or higher.

From Source

git clone https://github.com/MitudruDutta/learnlock.git
cd learnlock
pip install -e ".[dev]"

Optional Dependencies

pip install "learn-lock[ocr]"      # EasyOCR for handwritten answer support
pip install "learn-lock[whisper]"   # Whisper fallback for YouTube without transcripts

Quick Start

1. Set at least one API key:

export GROQ_API_KEY=your_key        # Fast extraction + fallback calls
export GEMINI_API_KEY=your_key      # Better duel evaluation + /visual

Or create a .env file in the project root.

2. Launch:

learnlock

3. Paste a YouTube URL, article link, PDF path, or GitHub repo URL

4. Start studying with /study or just press Enter on an empty prompt

5. Double Enter to send your answer

6. New users start in gentle mode automatically until they reach 5 successful reviews

How It Works

1. You explain a concept in your own words
2. The engine infers what you believe
3. It compares your belief against cached ground truth claims
4. It finds contradictions, weighs their confidence, and attacks the strongest actionable point
5. After 3 turns (or success), it reveals your belief trajectory
6. Your score feeds into SM-2 spaced repetition scheduling

Architecture

Source (YouTube/PDF/Article/GitHub)
    │
    ▼
Content Extraction (tools/)
    │
    ▼
Concept Extraction (llm.py) ──▶ 8-12 concepts with claims
    │
    ▼
Storage (SQLite + WAL) ──▶ sources, concepts, progress, duel_memory, cached_claims
    │
    ▼
Scheduler (SM-2) ──▶ spaced repetition with ease factor + interval
    │
    ▼
Duel Engine (duel.py) ──▶ belief modeling → contradiction detection → interrogation
    │
    ▼
HUD (hud.py) ──▶ Rich TUI with claims, belief state, attack panels

LLM Pipeline

• Groq — fast inference for concept extraction and title generation
• Gemini — quality inference for duel evaluation and vision
• Centralized llm.call() with retry, exponential backoff, and automatic provider fallback
• Per-provider rate limiting (token bucket)
• Input sanitization before prompt interpolation

The Duel Engine

The cognitive core. Located in duel.py.

Philosophy

Traditional learning apps ask: "Do you know X?"

LearnLock asks: "What do you believe about X, and where is it wrong?"

Pipeline

1. Belief Modeling — Infers what the user thinks from their response
2. Contradiction Detection — Compares belief against claims, finds violations
3. Interrogation — Generates attack question targeting highest-severity error
4. Snapshot — Records belief state for trajectory tracking

Behaviors

• Vague answers trigger mechanism probes
• Wrong answers trigger claim-specific attacks
• "I don't know" triggers guiding questions (not punishment)
• Low-confidence errors can be shown without tanking the final score
• Correct answers pass after verification
• 3 turns exhausted triggers reveal with full trajectory

Graded Harshness

• Turn 1: Forgiving — only clear violations flagged
• Turn 2: Moderate — violations plus omissions
• Turn 3: Strict — all violations surfaced

Error Types

Claim Pipeline

Claims are the epistemic foundation. The duel is only as fair as the claims.

Three-Pass Verification

Pass 1: Generation — LLM generates claims with explicit instructions to produce conceptual truths, not transcript parroting. Demands falsifiable statements about WHY and HOW, not just WHAT.

Pass 2: Garbage Filter — Pattern matching rejects stateful claims ("is running", "must remain active"), tautologies ("processes requests", "serves requests"), and vague claims ("is useful", "is important").

Pass 3: Sharpness Filter — Rejects blurry truths that are technically correct but unfalsifiable ("handles security", "manages data", "deals with").

Claim Types

Claim Caching

Claims are generated lazily on first duel or the first /claims request, then cached in the database (cached_claims table). Subsequent duels and claim reviews load from cache instead of re-parsing, making study sessions faster and more deterministic.

CLI Commands

Flags

Notes:

• New installs automatically start in gentle mode until 5 successful reviews are recorded.
• /claims, /delete, and /visual accept numeric IDs to resolve ambiguous names.
• /visual is opt-in and only applies to YouTube concepts with timestamped transcript matches.

Configuration

All settings via environment variables or .env file.

API Keys

Models

SM-2 Parameters

Extraction

LLM Tuning

Development

Setup

git clone https://github.com/MitudruDutta/learnlock.git
cd learnlock
pip install -e ".[dev]"

Testing

pytest                    # Run all tests
pytest -v                 # Verbose output
pytest tests/test_duel.py # Run specific test file

Linting

ruff check src tests

Building

python -m build
python -m twine check dist/*

Project Structure

src/learnlock/
├── __init__.py      # Version from importlib.metadata
├── cli.py           # CLI interface and command routing
├── config.py        # Environment-based configuration with validation
├── duel.py          # Duel Engine — belief modeling, contradiction, interrogation
├── hud.py           # Rich TUI — claims, belief, attack, reveal panels
├── llm.py           # LLM interface — call(), retry, fallback, sanitization
├── ocr.py           # Image text extraction (EasyOCR/Tesseract)
├── scheduler.py     # SM-2 spaced repetition
├── security.py      # URL validation, filename sanitization, safe redirects
├── storage.py       # SQLite persistence with lazy init and claim caching
├── py.typed         # PEP 561 type marker
└── tools/
    ├── __init__.py
    ├── youtube.py   # YouTube transcript + timestamp extraction
    ├── article.py   # Web article extraction (trafilatura)
    ├── pdf.py       # PDF extraction (pymupdf)
    └── github.py    # GitHub README extraction
tests/
├── conftest.py      # Fixtures: tmp_db, mock_llm, seeded_db
├── test_cli.py      # CLI command routing and input detection
├── test_duel.py     # Duel engine, belief scoring, claim verification
├── test_llm.py      # JSON parsing, sanitization, concept extraction
├── test_scheduler.py # SM-2 algorithm, due queries, intervals
├── test_storage.py  # All CRUD ops, migrations, caching
└── test_tools.py    # YouTube URL normalization, timestamp search

Known Limitations

Claim Quality (Epistemic Risk)

Claims are LLM-generated. Despite three-pass filtering, semantic drift can occur — a source saying "enforces authentication" might become "handles security." Pattern filters reduce but don't eliminate this.

Hallucinated Errors (Moral Risk)

The contradiction detector can still invent violations. A correct answer might be flagged as missing_mechanism due to LLM drift. Graded harshness, claim-index validation, and confidence weighting mitigate but do not eliminate this.

Confidence Is Not Full Verification

The engine can now express low-confidence findings and down-weight them before scoring, but this is still single-pass judgment. It is not the same as multi-pass agreement or formal claim verification.

Import/Export Is Merge-Oriented, Not Multi-Device Sync

/export and /import are safe for backup, restore, and controlled merges. They are not yet a full conflict-free sync protocol for multiple machines writing concurrently.

UI Density

The full HUD shows claims, belief, attack target, and interrogation simultaneously. LearnLock starts new users in gentle mode automatically, and --gentle can keep that softer experience enabled later.

License

MIT

Stop consuming. Start retaining.

LearnLock doesn't teach you.
It finds out what you don't know.