learnx-cli 0.3.0__py3-none-any.whl

tutor/prompts/visual_v3.txt

@@ -0,0 +1,91 @@
+You are generating slide content for an audio tutorial video.
+
+Given the dialogue transcript for one teaching unit, group consecutive lines into
+visual segments. Each segment covers 1–3 lines that share one idea.
+
+For each segment output a JSON object with these exact fields:
+  lines_start  — 0-based index of first line (inclusive)
+  lines_end    — 0-based index of last line (inclusive)
+  visual_type  — one of the 12 types listed below
+  title        — slide header, ≤ 10 words
+  body         — main text content (see per-type notes below); null if unused
+  code         — code string if relevant, else null
+  language     — highlight.js language id (e.g. "java", "python") if code present, else null
+  mermaid      — Mermaid diagram string if visual_type is "diagram", else null
+  left         — left column/panel label for analogy, comparison, decision_guide; else null
+  right        — right column/panel label; else null
+  rows         — list of [left_cell, right_cell] pairs for comparison/analogy/decision_guide; else null
+
+Visual types and when to use them:
+
+  hook_question   — ALEX's opening hook lines (always the first segment).
+                    body: the hook question text. rows: up to 3 learning objectives
+                    as [[objective, ""], ...] (single-column list).
+
+  definition      — ALEX introduces or formally defines a named term or concept.
+                    body: the definition text (1–2 sentences). code: short example
+                    if the definition is illustrated by code.
+
+  analogy         — ALEX uses "like", "think of", "imagine", "similar to", or
+                    "it's as if". body: not used when rows is present.
+                    left/right: the two things being compared (real-world vs code).
+                    rows: [[real_world_description, code_description]].
+
+  comparison      — ALEX contrasts two named concepts side by side.
+                    left/right: the two concept names. rows: property rows
+                    [[left_value, right_value], ...] (3–5 rows).
+
+  code_example    — ALEX demonstrates or references a specific code pattern.
+                    body: one-line description of what the code shows (optional).
+                    code: the code string. language: highlight.js id.
+
+  diagram         — ALEX describes a structural relationship (class hierarchy,
+                    data flow, state machine, dependency graph).
+                    mermaid: a valid Mermaid diagram string.
+                    Use classDiagram for class/interface relationships,
+                    flowchart TD for process flows.
+
+  question_prompt — MAYA or SAM lines only. Do NOT mix with ALEX lines.
+                    body: "SPEAKER: question text" (e.g. "MAYA: But why not just…").
+
+  decision_guide  — ALEX explains when to choose X over Y using if/when/unless
+                    criteria. left: "Use X when". right: "Avoid X when".
+                    rows: [[criterion_for, criterion_against], ...].
+
+  key_insight     — ALEX states a rule, principle, or memorable law.
+                    body: the complete rule statement (one sentence, max 20 words).
+                    Reserve for concise, standalone rules. Use callout for longer
+                    important statements.
+
+  memory_hook     — ALEX's closing memory-hook lines (always the last segment).
+                    body: the mnemonic or summary phrase ALEX uses.
+
+  step_sequence   — ALEX explains a sequential multi-step process ("first…",
+                    "step one…", "then you…", "next…", "finally…").
+                    body: steps separated by \n, one step per line (3–6 steps).
+                    Each line becomes a numbered circle in the slide.
+
+  callout         — A single important statement that stands alone: a prerequisite,
+                    a warning, a key quote, or a tip. Use when the content is too
+                    long or complex for key_insight but is a single highlighted point.
+                    title: the label ("NOTE", "WARNING", "TIP", "PREREQUISITE", "QUOTE").
+                    body: the statement (1–3 sentences).
+
+Assignment rules:
+  1. Cover every line — no gaps; lines_end of segment N + 1 == lines_start of N+1.
+  2. First segment: hook_question. Last segment: memory_hook.
+  3. MAYA or SAM lines alone → question_prompt.
+  4. ALEX using "like", "imagine", "think of", "similar to" → analogy.
+  5. ALEX contrasting two named things → comparison or decision_guide.
+  6. ALEX describing class/flow/dependency structure → diagram (Mermaid required).
+  7. ALEX showing or referencing specific code → code_example.
+  8. ALEX explaining "first… then… finally…" or numbered steps → step_sequence.
+  9. ALEX stating a single short rule (≤ 20 words) → key_insight.
+  10. ALEX making a single important point that's longer than a rule → callout.
+  11. ALEX introducing a named concept with a formal definition → definition.
+  12. Produce 8–15 segments; never fewer than 5.
+  13. Diversity rule: definition must not exceed 35% of total segments.
+      If you would produce more, merge adjacent definitions or reclassify as
+      key_insight, callout, or code_example where appropriate.
+
+Output: a JSON array only. No prose before or after. No markdown code fences.

tutor/qa/qa.py

@@ -0,0 +1,105 @@
+import json
+import logging
+from datetime import datetime
+from pathlib import Path
+
+from tutor.exceptions import LLMError
+from tutor.infra.llm import LLMFn
+from tutor.models import Chunk, QAExchange, SessionLog, TeachingUnit
+
+log = logging.getLogger(__name__)
+
+QA_PROMPT_PATH = Path(__file__).parent.parent / "prompts" / "qa.txt"
+
+
+def answer(
+    question: str,
+    current_unit: TeachingUnit,
+    all_chunks: list[Chunk],
+    session: SessionLog,
+    llm_fn: LLMFn,
+    position_seconds: int = 0,
+) -> str:
+    context = _build_context(current_unit, all_chunks, session)
+    log.debug("Q&A context length: %d chars", len(context))
+    prompt = _load_qa_prompt(current_unit.concept)
+    messages = [
+        {"role": "system", "content": prompt},
+        {"role": "user", "content": f"{context}\n\nStudent's question: {question}"},
+    ]
+
+    try:
+        raw = llm_fn(messages, call_type="qa")
+    except LLMError as e:
+        log.error("Q&A LLM call failed: %s", e)
+        return f"Sorry — could not generate an answer right now. ({e})"
+
+    answer_text = raw.strip()
+    _append_exchange(session, current_unit, question, answer_text, position_seconds)
+    return answer_text
+
+
+def _build_context(
+    current_unit: TeachingUnit,
+    all_chunks: list[Chunk],
+    session: SessionLog,
+) -> str:
+    chunk_map = {c.chunk_id: c for c in all_chunks}
+
+    current_chunks = [chunk_map[s] for s in current_unit.source_sections if s in chunk_map]
+
+    recent = session.exchanges[-3:] if session.exchanges else []
+
+    parts: list[str] = []
+
+    if current_chunks:
+        parts.append("=== Source Content ===")
+        for chunk in current_chunks:
+            parts.append(f"[{chunk.breadcrumb}]\n{chunk.text}")
+
+    if recent:
+        parts.append("\n=== Prior Questions This Session ===")
+        for ex in recent:
+            parts.append(f"Q: {ex.question}\nA: {ex.answer}")
+
+    return "\n\n".join(parts) if parts else "No source content available."
+
+
+def _append_exchange(
+    session: SessionLog,
+    unit: TeachingUnit,
+    question: str,
+    answer: str,
+    position_seconds: int,
+) -> None:
+    exchange = QAExchange(
+        id=len(session.exchanges) + 1,
+        unit_number=unit.unit,
+        unit_concept=unit.concept,
+        position_seconds=position_seconds,
+        question=question,
+        answer=answer,
+        source_sections=unit.source_sections,
+        timestamp=datetime.utcnow().isoformat(),
+    )
+    session.exchanges.append(exchange)
+    _save_session(session)
+
+
+def _save_session(session: SessionLog) -> None:
+    from dataclasses import asdict
+
+    path = Path("tutorial.session.json")
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(asdict(session), f, indent=2, ensure_ascii=False)
+
+
+def _load_qa_prompt(concept: str) -> str:
+    try:
+        template = QA_PROMPT_PATH.read_text(encoding="utf-8")
+        return template.replace("{concept}", concept)
+    except FileNotFoundError:
+        return (
+            f"Answer the student's question about: {concept}. "
+            "Be concise, cite sources, end with a follow-up question."
+        )

tutor/requirements-dev.txt

@@ -0,0 +1,2 @@
+pytest>=7.0.0
+pytest-asyncio>=0.21.0

tutor/requirements.txt

@@ -0,0 +1,12 @@
+openai>=1.0.0
+groq>=0.9.0
+edge-tts>=6.1.9
+pydub>=0.25.1
+pygame>=2.5.0
+tqdm>=4.66.0
+readchar>=4.0.0
+python-dotenv>=1.0.0
+markdown-it-py>=3.0.0
+audioop-lts>=0.2.1  # pydub compatibility for Python 3.13+
+jinja2>=3.1
+playwright>=1.44