learnx-cli 0.3.0__tar.gz

learnx_cli-0.3.0/.claude/agents/README.md

@@ -0,0 +1,32 @@
+# Review Agents
+
+Each `.md` file in this directory is a Claude sub-agent invoked during pre-merge review.
+
+## Agents
+
+| File | Role |
+|------|------|
+| quality.md | Bugs, security, logic errors |
+| implementation.md | Does the code match the spec's acceptance criteria? |
+| testing.md | Test coverage and quality |
+| simplification.md | Over-engineering and dead code |
+| product_check.md | Runs the real pipeline, checks output quality with ffprobe/pydub/Playwright |
+
+## How to add an agent
+
+1. Create `.claude/agents/<name>.md`
+2. Add YAML frontmatter with `name` (must match filename) and `description`
+3. Write the review instructions in the body
+4. Add the agent name to the parallel launch list in `REVIEW_PROMPT_TEMPLATE` in `scripts/run_review.py`
+
+## The fixes/ convention
+
+Agents do NOT write to `fixes/`. The `fixes/` directory is human-curated institutional
+memory for surprises that are not derivable from reading the code.
+
+Each agent's output includes a **Suggested Fix Notes** section. If an agent encountered
+a novel env quirk, API edge case, or tool gotcha during review, it flags it there.
+The human reads those flags and decides whether to write a permanent `fixes/fixNNN.md`.
+
+Rule: if removing the fix note would confuse a future agent reading the codebase cold,
+it belongs in `fixes/`. If the code or a test already explains it, it does not.

learnx_cli-0.3.0/.claude/agents/implementation.md

@@ -0,0 +1,17 @@
+---
+name: implementation
+description: Verifies that the implementation matches the spec's acceptance criteria
+---
+
+You will be given a git diff and the acceptance criteria from the spec that drove
+these changes. Check each criterion against the diff.
+
+For each criterion:
+- PASS: the diff clearly satisfies it
+- FAIL: the diff does not satisfy it — explain what is missing
+- PARTIAL: the diff partially satisfies it — explain what remains
+
+List spec criteria in order. End with a one-line summary: "N/M criteria satisfied."
+
+If no spec file is provided, verify that the implementation is internally consistent
+and that all stated goals in commit messages or comments are actually achieved.

learnx_cli-0.3.0/.claude/agents/product_check.md

@@ -0,0 +1,111 @@
+---
+name: product_check
+description: Runs the LearnX pipeline on the test fixture and verifies audio, video, and slide output quality
+---
+
+You are checking whether the product works, not whether the code looks right.
+Run the following steps in order and report the result of each.
+
+## Step 1 — Run the pipeline on the test fixture
+
+```bash
+python -m tutor generate tutor/tests/e2e/fixtures/sample.md --output /tmp/learnx_check
+```
+
+Expected: exits 0, output directory contains tutorial.mp3, tutorial.mp4 (or slides).
+If it crashes: paste the traceback. STOP — do not proceed to further steps.
+
+## Step 2 — Verify audio stream in video
+
+```bash
+ffprobe -v error \
+  -select_streams a:0 \
+  -show_entries stream=codec_type,duration,bit_rate \
+  -of json /tmp/learnx_check/tutorial.mp4
+```
+
+Expected: `codec_type` is `audio`, `duration` > 0.
+FAIL if: no audio stream returned, or duration is 0 or null.
+
+## Step 3 — Check audio is not silent
+
+```python
+from pydub import AudioSegment
+audio = AudioSegment.from_mp3("/tmp/learnx_check/tutorial.mp3")
+db_level = audio.dBFS
+print(f"Audio level: {db_level:.1f} dBFS")
+# Anything above -60 dBFS is audible
+assert db_level > -60, f"Audio appears silent: {db_level:.1f} dBFS"
+```
+
+Expected: dBFS above -60.
+FAIL if: dBFS is -inf or below -60 (silent or near-silent track).
+
+## Step 4 — Screenshot HTML slides (if slides were generated)
+
+```python
+from playwright.sync_api import sync_playwright
+import pathlib
+
+slide_dir = pathlib.Path("/tmp/learnx_check/slides")
+if slide_dir.exists():
+    html_files = list(slide_dir.glob("*.html"))
+    with sync_playwright() as p:
+        browser = p.chromium.launch()
+        page = browser.new_page(viewport={"width": 1280, "height": 720})
+        for html in html_files[:3]:   # first 3 slides max
+            page.goto(f"file://{html}")
+            page.wait_for_load_state("networkidle")
+            screenshot = f"/tmp/learnx_check/screenshot_{html.stem}.png"
+            page.screenshot(path=screenshot)
+            print(f"Screenshot saved: {screenshot}")
+        browser.close()
+```
+
+After running: describe what the screenshots look like. Are slides blank? Is text visible?
+Are there any error messages or broken layout?
+
+## Step 5 — Check A/V sync (timing.json vs audio duration)
+
+```python
+import json
+from pydub import AudioSegment
+import pathlib
+
+timing = json.loads(
+    pathlib.Path("/tmp/learnx_check/tutorial.timing.json").read_text()
+)
+audio = AudioSegment.from_mp3("/tmp/learnx_check/tutorial.mp3")
+
+last_unit = max(int(k) for k in timing["units"])
+last_entry = timing["units"][str(last_unit)][-1]
+timing_end_ms = last_entry["end_ms"]
+audio_duration_ms = len(audio)
+drift_ms = abs(audio_duration_ms - timing_end_ms)
+
+print(f"Audio duration: {audio_duration_ms}ms")
+print(f"Timing end:     {timing_end_ms}ms")
+print(f"Drift:          {drift_ms}ms")
+assert drift_ms < 500, f"A/V drift too large: {drift_ms}ms"
+```
+
+Expected: drift < 500ms.
+FAIL if: drift >= 500ms (slides and audio will be noticeably out of sync).
+
+## Report format
+
+```
+PIPELINE RUN: PASS / FAIL
+AUDIO STREAM: PRESENT (Xs) / MISSING
+SILENCE CHECK: {dBFS value} — PASS / FAIL
+SLIDE SCREENSHOTS: [describe what you see for each slide]
+A/V SYNC: {drift}ms — PASS / FAIL
+
+OVERALL: PRODUCT WORKING / PRODUCT BROKEN
+Blocking issues: [list or "none"]
+
+Suggested fix notes:
+[List any novel pipeline surprises — env issues, tool edge cases, encoding quirks —
+that are NOT obvious from reading the code. Write "none" if nothing surprising happened.
+Do NOT write to fixes/ — this is for the human to decide.]
+```

learnx_cli-0.3.0/.claude/agents/quality.md

@@ -0,0 +1,15 @@
+---
+name: quality
+description: Reviews code for bugs, security issues, and logic errors
+---
+
+Review the git diff for the following. Report each finding as:
+  FILE:LINE — severity (critical/major/minor) — description
+
+1. Logic errors: off-by-one, wrong condition, silent failure paths
+2. Security: hardcoded secrets, path traversal, injection vulnerabilities
+3. Resource leaks: unclosed files, unreleased locks, unbounded loops
+4. Error handling: exceptions swallowed silently, wrong exception types caught
+
+Output "NO ISSUES FOUND" if the diff is clean. Do not suggest style improvements
+— that is the simplification agent's job.

learnx_cli-0.3.0/.claude/agents/regression_check.md

@@ -0,0 +1,22 @@
+---
+name: regression_check
+description: Check that phase 1 fix commits did not introduce new problems
+---
+
+You are running Phase 2 of a two-phase review. Examine only the changes introduced
+by the phase 1 fix commits — not the original implementation diff.
+
+Run `git log --oneline main..HEAD` to list all commits. Identify which commits are
+fix commits (typically the most recent ones, added after the original spec work).
+Run `git show <hash>` on each fix commit.
+
+Look for:
+1. New logic errors or off-by-ones introduced by the fix
+2. New security issues or resource leaks
+3. Broken or removed tests
+4. Unrelated changes bundled into the fix commit
+
+End with a single verdict line:
+  CLEAN — no regressions detected
+  or
+  REGRESSION FOUND — <one-sentence description>

learnx_cli-0.3.0/.claude/agents/simplification.md

@@ -0,0 +1,15 @@
+---
+name: simplification
+description: Detects over-engineering, unnecessary abstraction, and dead code
+---
+
+Review the diff for complexity that is not justified by the spec.
+
+1. Abstractions: classes or functions created for a single use case
+2. Premature generalisation: parameters, config, or interfaces for hypothetical callers
+3. Dead code: code that is added but never called
+4. Over-indirection: wrapper functions that just call one other function
+5. Unnecessary comments: comments that restate what the code already says
+
+Rate overall complexity: LOW / MEDIUM / HIGH.
+List specific findings only. Do not suggest refactors not related to over-engineering.

learnx_cli-0.3.0/.claude/agents/testing.md

@@ -0,0 +1,15 @@
+---
+name: testing
+description: Reviews test coverage and test quality for the changed code
+---
+
+Review the test changes in the diff.
+
+1. Coverage: are all new code paths exercised by at least one test?
+2. Assertions: do tests assert specific values, or do they just assert no exception?
+3. Isolation: do tests depend on external state (filesystem, network, other tests)?
+4. Names: do test names describe what they verify (not just "test_function_x")?
+5. Missing tests: list any new public functions or edge cases with no test at all.
+
+Format: FILE — finding description
+Output "TESTS LOOK GOOD" if no issues found.

learnx_cli-0.3.0/.claude/agents/verify_fixes.md

@@ -0,0 +1,20 @@
+---
+name: verify_fixes
+description: Verify that each phase 1 review finding was fully resolved
+---
+
+You are running Phase 2 of a two-phase review. You will be given the phase 1
+findings report and must determine whether each finding was addressed.
+
+Run `git log --oneline main..HEAD` to list all commits, including any fix commits
+added after phase 1. Run `git show <hash>` on any fix commit to see what changed.
+
+For each finding from the phase 1 report, produce one line:
+  RESOLVED   — the fix is present and correct
+  PARTIAL    — something changed but the finding is not fully addressed
+  UNRESOLVED — no change addresses this finding
+
+End with a summary line:
+  VERIFIED (N/N findings resolved)
+  or
+  STILL FAILING (N/M unresolved: <short list>)

learnx_cli-0.3.0/.claude/settings.assisted.json

@@ -0,0 +1,27 @@
+{
+  "_comment": [
+    "Assisted mode reference. NOT loaded directly by Claude Code.",
+    "The wrapper writes this content to .claude/settings.local.json at session start",
+    "and deletes it on exit. settings.local.json is gitignored.",
+    "Deny rules removed — local git ops happen without prompts.",
+    "git push and git merge to main still require approval (no allow rule for them)."
+  ],
+  "permissions": {
+    "allow": [
+      "Bash(py -m pytest*)",
+      "Bash(py -m ruff*)",
+      "Bash(python*)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git add*)",
+      "Bash(git commit*)",
+      "Bash(git checkout*)",
+      "Bash(git branch*)",
+      "Bash(git stash*)",
+      "Read(*)",
+      "Edit(*)",
+      "Write(*)"
+    ]
+  }
+}

learnx_cli-0.3.0/.claude/settings.json

@@ -0,0 +1,26 @@
+{
+  "_comment": [
+    "Supervised mode — the committed host default.",
+    "Use python scripts/learnx_dk.py --mode to select a different mode.",
+    "Container modes (container, yolo) ignore this file entirely."
+  ],
+  "permissions": {
+    "allow": [
+      "Bash(py -m pytest*)",
+      "Bash(py -m ruff check*)",
+      "Bash(py -m ruff format*)",
+      "Bash(git status*)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git checkout main)",
+      "Bash(git checkout -b sandbox/*)",
+      "Bash(git branch*)"
+    ],
+    "deny": [
+      "Bash(git push*)",
+      "Bash(git merge*)",
+      "Bash(git reset*)",
+      "Bash(git branch -D*)"
+    ]
+  }
+}

learnx_cli-0.3.0/.dockerignore

@@ -0,0 +1,19 @@
+# Large generated directories — not needed in build context
+audio/
+__pycache__/
+*.pyc
+*.pyo
+.pytest_cache/
+.ruff_cache/
+
+# Version control
+.git/
+.gitignore
+
+# Dev environment
+.venv/
+*.egg-info/
+
+# OS noise
+.DS_Store
+Thumbs.db

learnx_cli-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,80 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["main", "v*-*"]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install ruff
+        run: pip install "ruff>=0.4"
+
+      - name: Check style
+        run: ruff check tutor/
+
+      - name: Check formatting
+        run: ruff format --check tutor/
+
+  unit-tests:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    needs: lint
+    if: false  # change to false to skip unit tests
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: |
+          grep -v 'audioop-lts' tutor/requirements.txt > /tmp/requirements-filtered.txt
+          pip install -r /tmp/requirements-filtered.txt
+          pip install -r tutor/requirements-dev.txt
+
+      - name: Run unit tests
+        run: python -m pytest tutor/tests/ --ignore=tutor/tests/e2e/ -m "not slow" -v
+
+  e2e-tests:
+    name: E2E Smoke Tests
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    if: false  # change to false to skip e2e tests
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y ffmpeg
+
+      - name: Install Python dependencies
+        run: |
+          grep -v 'audioop-lts' tutor/requirements.txt > /tmp/requirements-filtered.txt
+          pip install -r /tmp/requirements-filtered.txt
+          pip install -r tutor/requirements-dev.txt
+
+      - name: Install Playwright browsers
+        run: python -m playwright install chromium --with-deps
+
+      - name: Run E2E smoke tests
+        run: python -m pytest tutor/tests/e2e/ -v
+        env:
+          # LLM calls are mocked in conftest.py — no real key needed
+          ANTHROPIC_API_KEY: "test-key-not-used"

learnx_cli-0.3.0/.gitignore

@@ -0,0 +1,71 @@
+# Folders excluded from this repo
+week1/
+week2/
+systemDesign/
+
+# Generated output directories (root-level only — not tutor/audio/ source)
+/audio/
+/video/
+
+# Generated audio output
+*.mp3
+*.script.txt
+*.units.json
+*.session.json
+*.chunks.json
+*.meta.json
+*.visuals.json
+tutorial_units/
+
+# TTS temp files
+.tts_tmp/
+
+# LLM cache (regenerated on demand)
+.tutor_cache/
+
+# Secrets — never commit
+tutor/.env
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+.mypy_cache/
+.ruff_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Logs
+tutor.log
+*.log
+
+# Editor / OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+
+# Reference repos — cloned locally for reading, not part of this project
+ralphex/
+
+# Docker build artifacts
+.docker/
+*.dockerignore.bak
+
+# Dev workflow scripts output
+scripts/__pycache__/
+
+# Assisted mode runtime settings override — written and deleted by learnx_dk.py
+.claude/settings.local.json
+
+# sandbox/ prototype scripts — tracked selectively; outputs are not
+sandbox/*.log
+sandbox/*.json
+sandbox/*.mp3
+
+problems/
+week3/

learnx_cli-0.3.0/.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.10
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format

learnx_cli-0.3.0/CLAUDE.md

@@ -0,0 +1,144 @@
+# LearnX CLI — Product Context
+
+> For DevLoop workflow instructions (spec days, implementation loop, commands) see **DEVLOOP.md**.
+
+---
+
+## What This Project Is
+
+LearnX is a Python CLI that converts a Markdown document into an audio-first tutorial
+with optional video. The pipeline is:
+
+```
+Document → chunk → LLM summarise → LLM curriculum → LLM dialogue
+        → TTS render → assemble audio (+ timing.json)
+        → (optional) LLM visual plan → render slides → subtitle → mp4
+```
+
+Entry point: `tutor/__main__.py`. CLI commands live in `tutor/cli/`.
+Primary platform: Windows / PowerShell. Python 3.12+.
+
+---
+
+## Two Layers in This Repo
+
+```
+tutor/     LearnX CLI — the product. Audio tutorial generator.
+scripts/   DevLoop — the build system. Runs Claude in Docker, manages review pipeline.
+```
+
+These are independent concerns that share one repository. `scripts/` is never imported
+by `tutor/`. A user of LearnX CLI never touches `scripts/`.
+
+---
+
+## Product Layout
+
+```
+tutor/              the Python package
+  __main__.py         CLI entry point
+  models.py           all dataclasses — start here to understand data shapes
+  constants.py        silence gap constants, limits
+  config.py           LLM provider / model config
+  audio/              audio pipeline (audio_builder.py, tts_renderer.py)
+  generation/         LLM pipeline (curriculum, dialogue, narrator, visual_planner)
+  ingestion/          document processing (chunker, doc_analyzer)
+  visual/             video pipeline (beat_timer, slide_compositor, subtitle_writer…)
+  player/             interactive playback
+  cli/                CLI commands and shell
+  tests/              pytest unit suite — mirrors tutor/ structure
+  tests/e2e/          E2E smoke tests — run real pipeline, check output quality
+  infra/              LLM client wrapper
+
+specs/              versioned spec files — source of truth for all tutor/ code
+  v0/ … v3/          completed versions (regression reference)
+  v4-workflow/        DevLoop upgrade specs (archived)
+  v5/ … v11/         active versions
+
+plan/               version-level design and architecture docs
+  v0_plan.md … v11_plan.md
+  v4_update_plan.md  DevLoop v4 upgrade rationale
+  v4_architecture.md DevLoop component map
+
+fixes/              post-mortem notes (fix001.md … )
+                    read these before starting — they contain env/API gotchas
+
+dev_setup/          developer process documentation
+  spec-driven_plan.md      what SDD means and how to write specs
+  context_hygiene_plan.md  how to manage session context
+  sandbox_plan.md          git branch + test isolation strategy
+  autonomy_plan.md         how to run the implement→test→fix loop (Level 1–4)
+  handoff_template.md      copy-paste prompt for starting each spec day
+  container_plan.md        how to run Claude inside Docker (Level 4 workflow)
+
+scripts/            DevLoop tooling (NOT imported by tutor/)
+  devloop.py          launcher — runs Claude inside Docker
+  run_review.py       triggers 5-agent code + product review
+  dk/                 devloop submodules (config, docker, dashboard, runners…)
+  tests/              pytest tests for scripts/
+
+sandbox/            throwaway prototype scripts — NOT imported by tutor/
+
+.claude/
+  settings.json       allow list only (deny rules removed — Docker is the sandbox)
+  agents/             review + product check agent definitions
+```
+
+---
+
+## Code Quality Rules
+
+These rules apply to every file touched during a spec day or refactoring session.
+
+```
+MAX 400 LOC PER FILE — if a file exceeds 400 lines, split it before committing.
+  Extract by cohesion: group things that change together and depend on each other.
+  Keep the public interface in the original file; move implementation to submodules.
+
+CLEAN CODE
+  Functions do one thing. Name them for what they do, not how.
+  No functions longer than 40 lines. No nesting deeper than 3 levels.
+  No magic numbers — use named constants.
+  No dead code, no commented-out blocks, no TODO left in committed code.
+  Never hardcode a parameter value inside a function body when the caller
+    passed that value as an argument — always forward the parameter.
+
+MAINTAINABILITY
+  Every module has a single clear responsibility (SRP).
+  Avoid deep coupling: pass what a function needs, don't let it reach into globals.
+  Prefer explicit imports over star imports.
+  Update imports everywhere when you move code.
+
+SCALABILITY
+  New behaviour should be addable without modifying existing logic (OCP).
+  Favour composition over inheritance for extending behaviour.
+  Config goes in devloop.toml / llm_config.toml, not hardcoded in source.
+
+REUSABILITY
+  Pure functions (no side effects) are easier to test and reuse — prefer them.
+  Separate I/O (file reads, subprocess calls, network) from logic.
+  If two files share a helper, extract it to a shared module; never duplicate.
+```
+
+---
+
+## Where to Find Things
+
+| Question | Where to look |
+|---|---|
+| What does this feature do? | `specs/vN/dayN.md` |
+| Why was this approach chosen? | `plan/vN_plan.md` |
+| Why does this edge case exist? | `fixes/fix0NN.md` |
+| What dataclasses exist? | `tutor/models.py` |
+| What silence constants are used? | `tutor/constants.py` |
+| How is the LLM called? | `tutor/infra/llm.py` |
+| How to start a new spec day? | `dev_setup/handoff_template.md` |
+
+---
+
+## Read Before Starting Any v3 Day
+
+1. `fixes/fix001.md` — ffmpeg is not always on PATH on Windows; pydub needs the binary patched in at startup.
+2. `fixes/fix013.md` — timing inflation root cause: `compute_slide_timings()` was using estimated beat offsets instead of actual MP3 durations.
+3. `fixes/fix009.md` — per-unit loudnorm breaks audio duration with image-based concat video; volume boost is applied at encode time instead.
+4. `plan/v3_plan.md` — the architectural rationale for the whole v3 approach.