@laitszkin/apollo-toolkit 2.9.0 → 2.10.0

package/katex/scripts/render_katex.py

@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Render TeX formulas with the official KaTeX CLI and wrap the output for reuse."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import pathlib
+import subprocess
+import sys
+import tempfile
+from typing import Iterable
+
+
+DEFAULT_CSS_HREF = "https://cdn.jsdelivr.net/npm/katex@0.16.25/dist/katex.min.css"
+
+
+class KatexRenderError(Exception):
+    """User-facing error for rendering failures."""
+
+
+def parse_args(argv: list[str]) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="render_katex.py",
+        description="Render TeX with KaTeX and emit insertion-ready output.",
+    )
+
+    input_group = parser.add_mutually_exclusive_group(required=True)
+    input_group.add_argument("--tex", help="Raw TeX expression without delimiters.")
+    input_group.add_argument("--input-file", help="Path to a UTF-8 text file containing raw TeX.")
+
+    parser.add_argument(
+        "--output-format",
+        choices=("html-fragment", "html-page", "markdown-inline", "markdown-block", "json"),
+        default="html-fragment",
+        help="How to wrap the rendered KaTeX output.",
+    )
+    parser.add_argument(
+        "--katex-format",
+        choices=("html", "mathml", "htmlAndMathml"),
+        default="htmlAndMathml",
+        help="KaTeX internal output format.",
+    )
+    parser.add_argument("--display-mode", action="store_true", help="Render in display mode.")
+    parser.add_argument("--output-file", help="Write the wrapped output to a file.")
+    parser.add_argument("--css-href", default=DEFAULT_CSS_HREF, help="Stylesheet href for html-page/json output.")
+    parser.add_argument("--title", default="KaTeX Render", help="Document title for html-page output.")
+    parser.add_argument("--lang", default="en", help="HTML lang attribute for html-page output.")
+
+    parser.add_argument("--macro", action="append", default=[], help="Macro definition in NAME:VALUE form.")
+    parser.add_argument("--macro-file", help="Path to a JSON file mapping macro names to expansion strings.")
+    parser.add_argument("--error-color", help="Hex color or CSS color name for parse errors.")
+    parser.add_argument("--strict", help="KaTeX strict mode setting.")
+    parser.add_argument("--trust", help="KaTeX trust mode setting.")
+    parser.add_argument("--max-size", type=float, help="Maximum user-specified size in em.")
+    parser.add_argument("--max-expand", type=int, help="Maximum macro expansion count.")
+    parser.add_argument("--min-rule-thickness", type=float, help="Minimum rule thickness in em.")
+    parser.add_argument("--leqno", action="store_true", help="Render display equations with left equation numbers.")
+    parser.add_argument("--fleqn", action="store_true", help="Render display equations flush left.")
+    parser.add_argument(
+        "--color-is-text-color",
+        action="store_true",
+        help="Interpret \\\\color like legacy text color behavior.",
+    )
+    parser.add_argument(
+        "--no-throw-on-error",
+        action="store_true",
+        help="Render invalid input with colored source text instead of failing.",
+    )
+
+    return parser.parse_args(argv)
+
+
+def normalize_path(raw_path: str) -> pathlib.Path:
+    path = pathlib.Path(raw_path).expanduser()
+    if not path.is_absolute():
+        path = pathlib.Path.cwd() / path
+    return path.resolve()
+
+
+def load_tex(args: argparse.Namespace) -> str:
+    if args.input_file:
+        path = normalize_path(args.input_file)
+        if not path.is_file():
+            raise KatexRenderError(f"Input file not found: {path}")
+        return path.read_text(encoding="utf-8").strip()
+    return (args.tex or "").strip()
+
+
+def load_macro_pairs(values: Iterable[str]) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+    for raw_value in values:
+        if ":" not in raw_value:
+            raise KatexRenderError(f"Invalid --macro value '{raw_value}'. Use NAME:VALUE.")
+        name, expansion = raw_value.split(":", 1)
+        name = name.strip()
+        expansion = expansion.strip()
+        if not name or not expansion:
+            raise KatexRenderError(f"Invalid --macro value '{raw_value}'. Use NAME:VALUE.")
+        pairs.append((name, expansion))
+    return pairs
+
+
+def run_katex_cli(tex: str, args: argparse.Namespace) -> str:
+    command = [
+        "npx",
+        "--yes",
+        "--package",
+        "katex",
+        "katex",
+        "--format",
+        args.katex_format,
+    ]
+
+    if args.display_mode:
+        command.append("--display-mode")
+    if args.leqno:
+        command.append("--leqno")
+    if args.fleqn:
+        command.append("--fleqn")
+    if args.color_is_text_color:
+        command.append("--color-is-text-color")
+    if args.no_throw_on_error:
+        command.append("--no-throw-on-error")
+
+    if args.error_color:
+        command.extend(["--error-color", args.error_color])
+    if args.strict:
+        command.extend(["--strict", args.strict])
+    if args.trust:
+        command.extend(["--trust", args.trust])
+    if args.max_size is not None:
+        command.extend(["--max-size", str(args.max_size)])
+    if args.max_expand is not None:
+        command.extend(["--max-expand", str(args.max_expand)])
+    if args.min_rule_thickness is not None:
+        command.extend(["--min-rule-thickness", str(args.min_rule_thickness)])
+
+    for name, expansion in load_macro_pairs(args.macro):
+        command.extend(["--macro", f"{name}:{expansion}"])
+
+    if args.macro_file:
+        macro_file = normalize_path(args.macro_file)
+        if not macro_file.is_file():
+            raise KatexRenderError(f"Macro file not found: {macro_file}")
+        command.extend(["--macro-file", str(macro_file)])
+
+    with tempfile.NamedTemporaryFile("w", suffix=".tex", encoding="utf-8", delete=False) as handle:
+        handle.write(tex)
+        handle.write("\n")
+        temp_path = pathlib.Path(handle.name)
+
+    try:
+        command.extend(["--input", str(temp_path)])
+        result = subprocess.run(
+            command,
+            check=False,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+        )
+    finally:
+        temp_path.unlink(missing_ok=True)
+
+    if result.returncode != 0:
+        stderr = result.stderr.strip() or "KaTeX CLI failed."
+        raise KatexRenderError(stderr)
+
+    return result.stdout.strip()
+
+
+def build_html_page(rendered_html: str, args: argparse.Namespace) -> str:
+    css_link = ""
+    if args.css_href.strip():
+        css_link = f'  <link rel="stylesheet" href="{args.css_href.strip()}">\n'
+
+    return (
+        "<!DOCTYPE html>\n"
+        f'<html lang="{args.lang}">\n'
+        "<head>\n"
+        '  <meta charset="utf-8">\n'
+        f"  <title>{args.title}</title>\n"
+        f"{css_link}"
+        "</head>\n"
+        "<body>\n"
+        f"{rendered_html}\n"
+        "</body>\n"
+        "</html>\n"
+    )
+
+
+def wrap_output(rendered_html: str, tex: str, args: argparse.Namespace) -> str:
+    if args.output_format == "html-fragment":
+        return f"{rendered_html}\n"
+    if args.output_format == "html-page":
+        return build_html_page(rendered_html, args)
+    if args.output_format == "markdown-inline":
+        return f"{rendered_html}\n"
+    if args.output_format == "markdown-block":
+        return f"\n{rendered_html}\n"
+    if args.output_format == "json":
+        payload = {
+            "tex": tex,
+            "displayMode": args.display_mode,
+            "katexFormat": args.katex_format,
+            "cssHref": args.css_href,
+            "content": rendered_html,
+        }
+        return json.dumps(payload, ensure_ascii=False, indent=2) + "\n"
+    raise KatexRenderError(f"Unsupported output format: {args.output_format}")
+
+
+def write_output(content: str, output_file: str | None) -> None:
+    if not output_file:
+        sys.stdout.write(content)
+        return
+
+    path = normalize_path(output_file)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+    sys.stdout.write(str(path) + "\n")
+
+
+def main(argv: list[str]) -> int:
+    try:
+        args = parse_args(argv)
+        tex = load_tex(args)
+        if not tex:
+            raise KatexRenderError("Input TeX is empty.")
+        rendered_html = run_katex_cli(tex, args)
+        wrapped = wrap_output(rendered_html, tex, args)
+        write_output(wrapped, args.output_file)
+        return 0
+    except KatexRenderError as exc:
+        print(f"[ERROR] {exc}", file=sys.stderr)
+        return 1
+    except FileNotFoundError as exc:
+        missing = exc.filename or "required executable"
+        if os.path.basename(missing) in {"npx", "node"}:
+            print("[ERROR] node and npx are required to render KaTeX.", file=sys.stderr)
+            return 1
+        raise
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/katex/scripts/render_katex.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo "[ERROR] python3 is required." >&2
+  exit 1
+fi
+
+exec python3 "$script_dir/render_katex.py" "$@"

package/learning-error-book/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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).
+description: A learning-focused error-book workflow. When the user asks to summarize mistakes, the agent summarizes mistakes made while solving questions, writes structured reference data, and renders polished PDFs directly without Markdown as an intermediate.
 ---
 
 # Learning Error Book Skill
@@ -15,23 +15,27 @@ description: A learning-focused error-book workflow. When the user asks to summa
 ## 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.
+- Execution: Build an evidence table first, write structured reference data, then render polished PDFs directly 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.
+- Output: Deliver separate MC and long-question error books, each backed by its own reference file and rendered PDF.
 
-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).
+Goal: when the user asks to "summarize mistakes / summarize errors / compile an error book", summarize mistakes with evidence and generate or update structured error-book data plus polished PDFs directly from that data.
 
 ## 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:
+GIVEN the user asks to summarize mistakes/errors
+THEN the agent summarizes the user's mistakes made while solving questions
+AND generates or updates two error-book tracks when relevant:
+- one for multiple-choice questions
+- one for long-answer questions
+AND each track 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**.
+  - For MC questions: explain why each option is wrong/right, and why the correct option is correct
+  - For long-answer questions: compare the expected solution steps against the user's steps, show exactly where the divergence starts, and identify the key concepts involved
+AND the delivered error books must be polished PDFs rendered directly from structured data, without Markdown as an intermediate.
 
 ## Trigger Conditions
 
@@ -52,61 +56,72 @@ If the PDF is scanned/image-based and text extraction fails:
 
 ## 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):
+The error books 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**:
+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
+   - For MC: explain why each option is wrong/right, and why the correct option is correct
+   - For Long Question: compare each expected step with the user's corresponding step, explain the gap at each step, state the first incorrect step clearly, and list the key concepts that question depends on
 
 Formats:
-- Editable source: `error_book/error-book.md` (Markdown)
-- Deliverable: `error_book/error-book.pdf` (PDF rendered from Markdown)
+- MC reference: `error_book/references/mc-question-reference.json`
+- Long-question reference: `error_book/references/long-question-reference.json`
+- MC deliverable: `error_book/mc-question-error-book.pdf`
+- Long-question deliverable: `error_book/long-question-error-book.pdf`
 
 ## Recommended File Layout (Keep It Consistent)
 
 ```text
 error_book/
-  error-book.md
-  error-book.pdf
+  mc-question-error-book.pdf
+  long-question-error-book.pdf
+  references/
+    mc-question-reference.json
+    long-question-reference.json
   sources/          # optional: shortcuts/copies/list of source PDFs
 ```
 
 ## Workflow (Required)
 
-1) **Determine coverage**
+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)**
+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**
+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
+   - For long-answer questions, also collect expected steps, user steps, step-by-step gaps, first wrong step, and key concepts
+   - Then map it into the required sections for the relevant track
 
-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
+4) Generate/update structured reference files
+   - For MC questions: start from `assets/mc_question_reference_template.json`
+   - For long-answer questions: start from `assets/long_question_reference_template.json`
+   - If a reference file already exists: preserve existing entries, append new evidence, and refresh overview/concept sections
 
-5) **Render Markdown -> PDF (CJK font support)**
+5) Render structured data -> 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`
+     - `python3 learning-error-book/scripts/render_error_book_json_to_pdf.py error_book/references/mc-question-reference.json error_book/mc-question-error-book.pdf`
+     - `python3 learning-error-book/scripts/render_error_book_json_to_pdf.py error_book/references/long-question-reference.json error_book/long-question-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
+- `assets/mc_question_reference_template.json`: MC error-book structured template
+- `assets/long_question_reference_template.json`: long-answer error-book structured template
 
 ## 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
+- Avoid lossy Markdown conversion. Keep symbols, formulas, and option text in the structured reference payload.
+- For long-answer questions, preserve the original step granularity instead of merging multiple reasoning steps into one.
+- Keep key-concept labels stable across questions so the concept summary can aggregate them cleanly.

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

@@ -1,4 +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."
+  short_description: "Summarize mistakes into structured MC and long-question error books"
+  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/references/mc-question-reference.json and error_book/references/long-question-reference.json as applicable, then render polished PDFs directly to error_book/mc-question-error-book.pdf and error_book/long-question-error-book.pdf without using Markdown as an intermediate."

package/learning-error-book/assets/long_question_reference_template.json

@@ -0,0 +1,57 @@
+{
+  "book_type": "long-question",
+  "title": "Long Question Error Book",
+  "last_updated": "YYYY-MM-DD",
+  "coverage_scope": [
+    {
+      "source_path": "",
+      "included_questions": [],
+      "notes": ""
+    }
+  ],
+  "mistake_overview": [
+    {
+      "type": "Incomplete derivation",
+      "summary": "",
+      "representative_questions": []
+    }
+  ],
+  "concept_highlights": [
+    {
+      "name": "",
+      "definition": "",
+      "common_misjudgment": "",
+      "checklist": []
+    }
+  ],
+  "questions": [
+    {
+      "question_id": "",
+      "source_path": "",
+      "page_or_locator": "",
+      "stem": "",
+      "user_answer": "",
+      "correct_answer": "",
+      "mistake_type": "",
+      "concepts": [],
+      "why_wrong": "",
+      "first_incorrect_step": "",
+      "key_concepts": [
+        {
+          "name": "",
+          "why_it_matters": ""
+        }
+      ],
+      "correct_solution_steps": [],
+      "step_comparison": [
+        {
+          "step_no": 1,
+          "expected_step": "",
+          "user_step": "",
+          "gap": "",
+          "fix": ""
+        }
+      ]
+    }
+  ]
+}

package/learning-error-book/assets/mc_question_reference_template.json

@@ -0,0 +1,49 @@
+{
+  "book_type": "mc-question",
+  "title": "MC Question Error Book",
+  "last_updated": "YYYY-MM-DD",
+  "coverage_scope": [
+    {
+      "source_path": "",
+      "included_questions": [],
+      "notes": ""
+    }
+  ],
+  "mistake_overview": [
+    {
+      "type": "Concept misunderstanding",
+      "summary": "",
+      "representative_questions": []
+    }
+  ],
+  "concept_highlights": [
+    {
+      "name": "",
+      "definition": "",
+      "common_misjudgment": "",
+      "checklist": []
+    }
+  ],
+  "questions": [
+    {
+      "question_id": "",
+      "source_path": "",
+      "page_or_locator": "",
+      "stem": "",
+      "user_answer": "",
+      "correct_answer": "",
+      "mistake_type": "",
+      "concepts": [],
+      "why_wrong": "",
+      "correct_solution_steps": [],
+      "options": [
+        {
+          "label": "A",
+          "text": "",
+          "verdict": "wrong",
+          "reason": ""
+        }
+      ]
+    }
+  ]
+}