feat: add linting script to pyproject.toml, enhance error handling in CLI, and improve research plan generation

Author: btfranklin

pyproject.toml

@@ -56,3 +56,4 @@ compendium = "compendiumscribe.cli:cli"
 
 [tool.pdm.scripts]
 test = "pytest"
+lint = "flake8 src tests"

src/compendiumscribe/cli.py

@@ -1,8 +1,6 @@
 import json
-import re
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any, TYPE_CHECKING
 
 import click
 
@@ -24,7 +22,6 @@
 )
 
 
-
 @click.group()
 def cli() -> None:
     """Compendium Scribe: AI Research & Rendering Tool."""
@@ -124,17 +121,22 @@ def handle_progress(update: ResearchProgress) -> None:
         click.echo("\nHard shutdown requested.", err=True)
         raise SystemExit(1)
     except ResearchTimeoutError as exc:
+        compendium_title = getattr(exc, "compendium_title", None)
         timeout_data = {
             "research_id": exc.research_id,
             "topic": topic,
+            "title": compendium_title or topic,
             "no_background": no_background,
             "formats": list(formats),
             "max_tool_calls": max_tool_calls,
             "timestamp": datetime.now(timezone.utc).isoformat(),
         }
         Path("timed_out_research.json").write_text(json.dumps(timeout_data, indent=2))
         click.echo(f"\n[!] Deep research timed out (ID: {exc.research_id}).", err=True)
-        click.echo(f"Stored recovery information in timed_out_research.json", err=True)
+        click.echo(
+            "Stored recovery information in timed_out_research.json",
+            err=True,
+        )
         raise SystemExit(1) from exc
     except MissingAPIKeyError as exc:
         click.echo(f"Configuration error: {exc}", err=True)
@@ -154,7 +156,8 @@ def handle_progress(update: ResearchProgress) -> None:
         # If output_path has a suffix, we use it as the stem to avoid out.md.md
         base_path = output_path.parent / output_path.stem
     else:
-        slug = slugify(topic)
+        name_for_slug = compendium.topic or topic
+        slug = slugify(name_for_slug)
         timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
         base_path = Path(f"{slug}_{timestamp}")
 
@@ -226,14 +229,15 @@ def recover(input_file: Path):
         data = json.loads(input_file.read_text(encoding="utf-8"))
         research_id = data["research_id"]
         topic = data["topic"]
+        title = data.get("title") or topic
         formats = tuple(data["formats"])
         max_tool_calls = data.get("max_tool_calls")
         no_background = data.get("no_background", False)
     except (json.JSONDecodeError, KeyError) as exc:
         click.echo(f"Error: Failed to parse recovery file: {exc}", err=True)
         raise SystemExit(1)
 
-    click.echo(f"Checking status for research ID: {research_id} ('{topic}')...")
+    click.echo(f"Checking status for research ID: {research_id} ('{title}')...")
 
     config = ResearchConfig(
         background=not no_background,
@@ -243,13 +247,13 @@ def recover(input_file: Path):
     try:
         compendium = recover_compendium(
             research_id=research_id,
-            topic=topic,
+            topic=title,
             config=config,
         )
 
         click.echo("Research completed! Writing outputs.")
 
-        slug = slugify(topic)
+        slug = slugify(title)
         timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
         base_path = Path(f"{slug}_{timestamp}")
 

src/compendiumscribe/compendium/entities.py

@@ -4,8 +4,6 @@
 import xml.etree.ElementTree as ET
 
 
-
-
 @dataclass
 class Citation:
     """Represents a single cited source returned by deep research."""

src/compendiumscribe/compendium/html_site_renderer.py

@@ -9,7 +9,7 @@
 
 if TYPE_CHECKING:  # pragma: no cover - hints only
     from .compendium import Compendium
-    from .entities import Citation, Section
+    from .entities import Section
 
 
 def _html_head(title: str, depth: int = 0) -> list[str]:
@@ -297,9 +297,6 @@ def _render_open_questions_page(compendium: "Compendium") -> str:
     return "\n".join(parts) + "\n"
 
 
-
-
-
 def render_html_site(compendium: "Compendium") -> dict[str, str]:
     """Render the compendium as a navigable multi-file HTML site.
 

src/compendiumscribe/compendium/pdf.py

@@ -25,11 +25,11 @@ def render_pdf(compendium: Compendium) -> bytes:
     pdf = CompendiumPDF()
     pdf.alias_nb_pages()
     pdf.add_page()
-    
+
     # Title
     pdf.set_font("helvetica", "B", 24)
     pdf.cell(0, 20, compendium.topic, new_x=XPos.LMARGIN, new_y=YPos.NEXT, align="C")
-    
+
     pdf.set_font("helvetica", "I", 10)
     generated_at = compendium.generated_at.strftime("%Y-%m-%d %H:%M:%S")
     pdf.cell(0, 10, f"Generated at: {generated_at} UTC", new_x=XPos.LMARGIN, new_y=YPos.NEXT, align="C")
@@ -58,18 +58,18 @@ def render_pdf(compendium: Compendium) -> bytes:
         pdf.set_font("helvetica", "B", 16)
         pdf.cell(0, 10, "Sections", new_x=XPos.LMARGIN, new_y=YPos.NEXT)
         pdf.ln(2)
-        
+
         for section in compendium.sections:
             # Check for page break if near bottom
             if pdf.get_y() > 250:
                 pdf.add_page()
-                
+
             pdf.set_font("helvetica", "B", 14)
             title = section.title
             if section.identifier:
                 title = f"{section.identifier}: {title}"
             pdf.cell(0, 10, title, new_x=XPos.LMARGIN, new_y=YPos.NEXT)
-            
+
             pdf.set_font("helvetica", "", 11)
             pdf.multi_cell(0, 6, section.summary)
             pdf.ln(2)
@@ -79,7 +79,7 @@ def render_pdf(compendium: Compendium) -> bytes:
                 pdf.cell(0, 6, "Key Terms: ", ln=False)
                 pdf.set_font("helvetica", "", 10)
                 pdf.multi_cell(0, 6, ", ".join(section.key_terms))
-            
+
             if section.insights:
                 pdf.ln(2)
                 for insight in section.insights:

src/compendiumscribe/compendium/text_utils.py

@@ -1,12 +1,11 @@
 from __future__ import annotations
 
-from typing import Iterator
 import mistune
 
 
 def slugify(text: str, max_length: int | None = 100) -> str:
     """Convert text to a URL-friendly slug.
-    
+
     Args:
         text: The text to convert to a slug.
         max_length: Maximum length of the resulting slug. If None, no truncation.
@@ -16,14 +15,12 @@ def slugify(text: str, max_length: int | None = 100) -> str:
 
     slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
     slug = slug or "page"
-    
+
     if max_length is not None and len(slug) > max_length:
         # Truncate and remove any trailing hyphen from the cut
         slug = slug[:max_length].rstrip("-")
-    
-    return slug
-
 
+    return slug
 
 
 def format_html_text(text: str | None) -> str:
@@ -33,18 +30,18 @@ def format_html_text(text: str | None) -> str:
         return ""
 
     # Create a markdown parser with escaping enabled in the renderer
-    # This prevents raw HTML tags from being passed through while 
+    # This prevents raw HTML tags from being passed through while
     # ensuring that markdown-generated HTML (like <code>) is NOT double-escaped.
     renderer = mistune.HTMLRenderer(escape=True)
     markdown = mistune.create_markdown(renderer=renderer)
-    
+
     result = markdown(text).strip()
-    
-    # If mistune wrapped it in <p>...</p> and it's a single paragraph, 
+
+    # If mistune wrapped it in <p>...</p> and it's a single paragraph,
     # we might want to strip it for inline use.
     if result.startswith("<p>") and result.endswith("</p>") and result.count("<p>") == 1:
         result = result[3:-4]
-        
+
     return result
 
 

src/compendiumscribe/compendium/xml_parser.py

@@ -85,7 +85,7 @@ def _parse_root(root: ET.Element) -> Compendium:
         citations=citations,
         open_questions=open_questions,
     )
-    
+
     if generated_at:
         compendium.generated_at = generated_at
 

src/compendiumscribe/create_llm_clients.py

@@ -25,7 +25,7 @@ def create_openai_client(*, timeout: int | None = None) -> OpenAI:
     actual_timeout = timeout if timeout is not None else DEFAULT_TIMEOUT_SECONDS
 
     client = OpenAI(api_key=api_key, timeout=actual_timeout)
-    
+
     # Quick sanity check for the required API capability
     if not hasattr(client, "responses"):
         raise RuntimeError(

src/compendiumscribe/prompts/topic_blueprint.prompt.md

@@ -4,6 +4,7 @@
 
 You are a research planning assistant preparing inputs for a deep research model. Given the topic below, output a concise JSON object that captures:
 
+- `title`: a clear, engaging title for the research compendium.
 - `primary_objective`: a single sentence describing the overarching research goal.
 - `audience`: the intended audience in one sentence.
 - `key_sections`: 3-5 objects each with `title` and `focus` outlining recommended sections of the final compendium.

src/compendiumscribe/research/__init__.py

@@ -60,4 +60,3 @@
     "coerce_optional_string",
     "get_field",
 ]
-