@laitszkin/apollo-toolkit 2.0.0

package/learn-skill-from-conversations/tests/test_extract_recent_conversations.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""Edge-case tests for extract_recent_conversations.py."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parents[1] / "scripts" / "extract_recent_conversations.py"
+)
+
+
+def write_session(path: Path, timestamp: datetime) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    entries = [
+        {
+            "type": "session_meta",
+            "payload": {"timestamp": timestamp.isoformat()},
+        },
+        {
+            "type": "event_msg",
+            "payload": {"type": "user_message", "message": f"user:{path.stem}"},
+        },
+        {
+            "type": "event_msg",
+            "payload": {"type": "agent_message", "message": f"assistant:{path.stem}"},
+        },
+    ]
+    with path.open("w", encoding="utf-8") as handle:
+        for entry in entries:
+            handle.write(json.dumps(entry) + "\n")
+
+
+def run_extractor(
+    sessions_dir: Path,
+    archived_dir: Path | None = None,
+    *extra_args: str,
+) -> str:
+    cmd = [
+        sys.executable,
+        str(SCRIPT_PATH),
+        "--sessions-dir",
+        str(sessions_dir),
+    ]
+    if archived_dir is not None:
+        cmd.extend(["--archived-sessions-dir", str(archived_dir)])
+    cmd.extend(extra_args)
+    result = subprocess.run(cmd, capture_output=True, text=True, check=True)
+    return result.stdout
+
+
+class ExtractRecentConversationsTests(unittest.TestCase):
+    def test_default_lookback_covers_last_24_hours(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            write_session(sessions_root / "recent.jsonl", now - timedelta(hours=3))
+
+            output = run_extractor(sessions_root)
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("LOOKBACK_MINUTES=1440", output)
+
+    def test_limit_zero_is_treated_as_unlimited(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            write_session(sessions_root / "a.jsonl", now - timedelta(minutes=5))
+            write_session(sessions_root / "b.jsonl", now - timedelta(minutes=10))
+            write_session(sessions_root / "c.jsonl", now - timedelta(minutes=15))
+
+            output = run_extractor(
+                sessions_root,
+                None,
+                "--lookback-minutes",
+                "60",
+                "--limit",
+                "0",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=3", output)
+
+    def test_archived_sessions_are_read_before_cleanup(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            archived_root = Path(tmp) / "archived_sessions"
+            now = datetime.now(timezone.utc)
+            archived_file = archived_root / "archived.jsonl"
+            write_session(archived_file, now - timedelta(minutes=30))
+
+            output = run_extractor(
+                sessions_root,
+                archived_root,
+                "--lookback-minutes",
+                "60",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("ARCHIVED_SESSIONS_INCLUDED=true", output)
+            self.assertIn("user:archived", output)
+            self.assertIn("assistant:archived", output)
+            self.assertIn("CLEANUP_REMOVED_ARCHIVED_SESSIONS=1", output)
+            self.assertFalse(archived_file.exists())
+
+    def test_cleanup_removes_only_old_sessions_from_sessions_dir(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            recent_file = sessions_root / "recent.jsonl"
+            old_file = sessions_root / "old.jsonl"
+            write_session(recent_file, now - timedelta(hours=6))
+            write_session(old_file, now - timedelta(days=8))
+
+            output = run_extractor(
+                sessions_root,
+                None,
+                "--lookback-minutes",
+                "1440",
+                "--retention-days",
+                "7",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("CLEANUP_REMOVED_OLD_SESSIONS=1", output)
+            self.assertTrue(recent_file.exists())
+            self.assertFalse(old_file.exists())
+
+    def test_archived_cleanup_skips_active_sessions_when_paths_overlap(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            now = datetime.now(timezone.utc)
+            recent_file = sessions_root / "recent.jsonl"
+            write_session(recent_file, now - timedelta(minutes=5))
+
+            output = run_extractor(
+                sessions_root,
+                sessions_root,
+                "--lookback-minutes",
+                "60",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("CLEANUP_REMOVED_ARCHIVED_SESSIONS=0", output)
+            self.assertTrue(recent_file.exists())
+
+    def test_limit_one_only_returns_latest_session_across_sources(self) -> None:
+        with tempfile.TemporaryDirectory() as tmp:
+            sessions_root = Path(tmp) / "sessions"
+            archived_root = Path(tmp) / "archived_sessions"
+            now = datetime.now(timezone.utc)
+            write_session(sessions_root / "older.jsonl", now - timedelta(minutes=20))
+            newest = archived_root / "newest.jsonl"
+            write_session(newest, now - timedelta(minutes=5))
+
+            output = run_extractor(
+                sessions_root,
+                archived_root,
+                "--lookback-minutes",
+                "60",
+                "--limit",
+                "1",
+            )
+
+            self.assertIn("RECENT_CONVERSATIONS_FOUND=1", output)
+            self.assertIn("newest.jsonl", output)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/learning-error-book/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: learning-error-book
+description: A learning-focused error-book workflow. When the user asks to summarize mistakes, the agent summarizes mistakes made while solving questions and generates/updates an error book in Markdown, rendered to PDF (depends on the pdf skill).
+---
+
+# Learning Error Book Skill
+
+## Dependencies
+
+- Required: `pdf` whenever question sources or the final deliverable involve PDF handling.
+- Conditional: none.
+- Optional: none.
+- Fallback: If PDF extraction fails, escalate to OCR through `pdf`; if OCR still cannot recover the content, ask the user for the minimum needed text or screenshots.
+
+## Standards
+
+- Evidence: Summarize mistakes only from traceable question sources, user attempts, and correct-answer evidence.
+- Execution: Build an evidence table first, update `error_book/error-book.md`, then render `error_book/error-book.pdf` with Chinese-safe fonts.
+- Quality: Explain mistake types, concept misunderstandings, and per-question solutions in a way that is specific, complete, and non-speculative.
+- Output: Deliver the standardized error-book structure in Markdown and PDF with consistent section coverage.
+
+Goal: when the user asks to "summarize mistakes / summarize errors / compile an error book", **summarize mistakes with evidence** and **generate or update** an error book (Markdown -> PDF).
+
+## Behavior Contract (GIVEN/THEN)
+
+GIVEN the user asks to **summarize mistakes/errors**  
+THEN the agent summarizes the user's mistakes made while solving questions  
+AND generates or updates an **error book** that includes:
+- Coverage scope (which question files / sources are included)
+- Common mistake types overview
+- Conceptual mistake highlights (definition, user's common misjudgment, cautions)
+- Mistake-by-mistake analysis and solutions
+  - For MC questions: explain why **each option** is wrong/right, and why the correct option is correct
+AND the delivered error book must be a **PDF rendered from Markdown**, using fonts that properly render **Chinese text and Markdown symbols**.
+
+## Trigger Conditions
+
+Use this skill when the user intent matches:
+- "summarize mistakes", "what did I do wrong", "compile error book", "review wrong answers"
+- user provides question files (often PDFs) and asks to summarize mistakes
+
+## Inputs (Facts You Must Collect)
+
+Before writing anything, ensure you have enough facts (do not guess):
+- Question source: file paths (PDF), or pasted text/screenshots, or question id/page number
+- User's attempt: chosen option / written answer, and their reasoning (if available)
+- Correct answer and explanation: extract from the PDF if present; otherwise ask the user to provide it
+
+If the PDF is scanned/image-based and text extraction fails:
+- Use the `pdf` skill to attempt OCR (if available)
+- If OCR is not possible, request pasted text or screenshots (minimum: stem + options/sub-questions)
+
+## Output Spec (Required Sections)
+
+The error book must contain:
+1) **Coverage Scope**: which question files/sources are included (with paths; include page/question ids when available)
+2) **Common Mistake Types Overview**: 3-8 categories (concept misunderstanding, misreading conditions, derivation/calculation error, option traps, etc.), with representative questions
+3) **Conceptual Mistake Highlights** (per concept):
+   - Definition (precise and actionable)
+   - User's common misjudgment (mapped to concrete mistakes)
+   - Cautions / checklists to avoid repeating the mistake
+4) **Per-Question Mistake & Solution**:
+   - Traceable locator: file + page/question id
+   - User answer vs correct answer
+   - Why it's wrong (link back to mistake type + concept)
+   - Correct solution (step-by-step)
+   - For **MC**: explain why **each option** is wrong/right, and why the correct option is correct
+
+Formats:
+- Editable source: `error_book/error-book.md` (Markdown)
+- Deliverable: `error_book/error-book.pdf` (PDF rendered from Markdown)
+
+## Recommended File Layout (Keep It Consistent)
+
+```text
+error_book/
+  error-book.md
+  error-book.pdf
+  sources/          # optional: shortcuts/copies/list of source PDFs
+```
+
+## Workflow (Required)
+
+1) **Determine coverage**
+   - If the user provided files/question ids: add them to Coverage Scope
+   - If not: search the workspace for relevant PDFs and confirm with the user
+
+2) **Extract question text + answers/explanations (extract when possible)**
+   - Use the `pdf` skill (pypdf/pdfplumber/OCR as available)
+   - If extraction fails, request user-provided text/screenshots
+
+3) **Build an evidence table before writing**
+   - For each question: locator, user answer, correct answer, mistake type, concept(s), explanation
+   - Then map it into the required four sections
+
+4) **Generate/update `error_book/error-book.md`**
+   - If missing: start from `assets/error_book_template.md`
+   - If exists: preserve existing content; append new mistakes; update Overview + Concepts sections
+
+5) **Render Markdown -> PDF (CJK font support)**
+   - Run:
+     - `python3 learning-error-book/scripts/render_markdown_to_pdf.py error_book/error-book.md error_book/error-book.pdf`
+   - If paper size/font needs change: adjust script flags (`--help`)
+
+## Built-in Template
+
+- `assets/error_book_template.md`: template for first-time creation
+
+## Rendering Notes (Avoid Pitfalls)
+
+- Supported Markdown subset: headings, lists, **bold**/**italic**, inline `code`, fenced code blocks
+- For complex tables/math: prefer bullet lists + step-by-step derivations, or paste original content into the question section

package/learning-error-book/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Learning Error Book"
+  short_description: "Summarize mistakes into a Markdown-to-PDF error book"
+  default_prompt: "Use $learning-error-book to gather evidence about the user's mistakes, use $pdf whenever PDF extraction or OCR is needed, generate or update error_book/error-book.md from the skill template, and render the final deliverable to error_book/error-book.pdf."

package/learning-error-book/assets/error_book_template.md

@@ -0,0 +1,66 @@
+# Error Book
+
+Last updated: {{DATE}}
+
+## 1. Coverage Scope
+
+This error book includes the following question sources (with traceable locators):
+
+- (Question file/source):
+  - Path: `...`
+  - Included questions: Q... / Page ... (optional)
+
+## 2. Common Mistake Types Overview
+
+> Goal: classify mistake patterns first, then use questions as evidence later.
+
+- Concept misunderstanding:
+  - Representative questions: ...
+- Misreading / missing conditions:
+  - Representative questions: ...
+- Incomplete reasoning steps:
+  - Representative questions: ...
+- Calculation / sign / algebra errors (if any):
+  - Representative questions: ...
+- Option traps / intuitive misjudgment (common in MC):
+  - Representative questions: ...
+
+## 3. Conceptual Mistake Highlights
+
+### Concept: {{CONCEPT_NAME}}
+
+- Definition (precise and actionable):
+  - ...
+- User's common misjudgment (mapped to this mistake):
+  - ...
+- Cautions / checklists:
+  - ...
+- Minimal example (optional):
+  - ...
+
+## 4. Mistake-by-Mistake Analysis & Solutions
+
+### Question: {{QUESTION_ID}}
+
+- Source locator:
+  - File: `...`
+  - Page / Question id: ...
+- Stem:
+  - ...
+- (If MC) Options:
+  - A. ...
+  - B. ...
+  - C. ...
+  - D. ...
+- User answer: ...
+- Correct answer: ...
+- Why it was wrong (link to mistake type + concept):
+  - ...
+- Correct solution (step-by-step):
+  1. ...
+  2. ...
+- (If MC) Option-by-option reasoning:
+  - Why A is wrong/right: ...
+  - Why B is wrong/right: ...
+  - Why C is wrong/right: ...
+  - Why D is wrong/right: ...