feat: Display research blueprint section titles, enhance JSON parsing error messages with content snippets, and correct prompt template application.

Author: btfranklin

pdm.lock

@@ -9,7 +9,7 @@ dependencies = [
     "openai>=2.11.0",
     "python-dotenv>=1.2.1",
     "click>=8.3.1",
-    "promptdown>=1.0.1",
+    "promptdown>=1.1.0",
     "mistune>=3.2.0",
     "fpdf2>=2.8.5",
 ]

pyproject.toml

@@ -89,6 +89,11 @@ def handle_progress(update: ResearchProgress) -> None:
             **stream_kwargs,
         )
 
+        # Display blueprint section titles when available
+        if "section_titles" in meta and meta["section_titles"]:
+            for title in meta["section_titles"]:
+                click.echo(f"           - {title}")
+
     try:
         config = ResearchConfig(
             background=not no_background,

src/compendiumscribe/cli.py

@@ -67,7 +67,7 @@ def await_completion(
             config,
             phase="deep_research",
             status="update",
-            message="Deep research still running; awaiting updated status.",
+            message="In progress...",
             metadata={
                 "status": status,
                 "poll_attempt": attempts,

src/compendiumscribe/research/execution/polling.py

@@ -70,16 +70,20 @@ def build_compendium(
             )
             plan = default_research_plan(normalized_topic)
         else:
+            key_sections = plan.get("key_sections", []) or []
             emit_progress(
                 config,
                 phase="planning",
                 status="completed",
                 message="Received refined research blueprint.",
                 metadata={
-                    "sections": len(plan.get("key_sections", []) or []),
+                    "sections": len(key_sections),
                     "questions": len(
                         plan.get("research_questions", []) or []
                     ),
+                    "section_titles": [
+                        s.get("title") for s in key_sections if s.get("title")
+                    ],
                 },
             )
 

src/compendiumscribe/research/orchestrator.py

@@ -84,6 +84,12 @@ def collect_response_text(response: Any) -> str:
 def decode_json_payload(text: str) -> dict[str, Any]:
     candidate = text.strip()
 
+    # Helper to create a preview snippet for error messages
+    def _snippet(s: str, max_len: int = 200) -> str:
+        if len(s) <= max_len:
+            return s
+        return s[:max_len] + "..."
+
     if candidate.startswith("```"):
         candidate = candidate.strip("`").strip()
         if candidate.startswith("json"):
@@ -94,20 +100,24 @@ def decode_json_payload(text: str) -> dict[str, Any]:
         end = candidate.rfind("}")
         if start == -1 or end == -1:
             raise DeepResearchError(
-                "Unable to locate JSON object in response."
+                f"Unable to locate JSON object in response. "
+                f"Received: {_snippet(text)!r}"
             )
         candidate = candidate[start:end + 1]
 
     try:
         payload = json.loads(candidate)
     except json.JSONDecodeError as exc:
         raise DeepResearchError(
-            "Deep research response was not valid JSON."
+            f"Deep research response was not valid JSON. "
+            f"Parse error at position {exc.pos}: {exc.msg}. "
+            f"Content: {_snippet(candidate)!r}"
         ) from exc
 
     if not isinstance(payload, dict):
         raise DeepResearchError(
-            "Expected JSON object at top level of response."
+            f"Expected JSON object at top level of response, "
+            f"got {type(payload).__name__}: {_snippet(str(payload))!r}"
         )
 
     return payload

src/compendiumscribe/research/parsing.py

@@ -17,7 +17,7 @@ def generate_research_plan(
 ) -> dict[str, Any] | None:
     prompt_obj = load_prompt_template("topic_blueprint.prompt.md")
     # Apply template values
-    prompt_obj.apply_template_values({"topic": topic})
+    prompt_obj = prompt_obj.apply_template_values({"topic": topic})
 
     # Convert to Responses API input
     responses_input = prompt_obj.to_responses_input()
@@ -122,7 +122,7 @@ def compose_deep_research_prompt(topic: str, plan: dict[str, Any]) -> Any:
         indent=2,
     )
 
-    prompt_obj.apply_template_values(
+    prompt_obj = prompt_obj.apply_template_values(
         {
             "topic": topic,
             "primary_objective": plan.get(