feat: rewrite report annotation as an interwoven blog post

Replace the overall-story-plus-notes annotation with a StoryAgent that returns ordered prose and view blocks, so the exported report reads like a blog post with narrative woven between the charts and tables. Clicking Annotate now opens a guidance popup (tone presets plus free text) to steer the angle, and a Report/Story toggle keeps the section export checkboxes reachable after a story is generated.

Author: ghostiee-11

lumen/ai/agents/story.py

@@ -3,8 +3,6 @@
 import param
 import yaml
 
-from panel.pane import Markdown
-from panel_material_ui import ChatMessage, Typography
 from pydantic import BaseModel, Field
 
 from ...pipeline import Pipeline
@@ -17,36 +15,47 @@
 _MAX_DATA_CHARS = 2000
 
 
-class Story(BaseModel):
+class StoryBlock(BaseModel):
 
-    chain_of_thought: str = Field(
-        description="In 1-2 sentences, outline the narrative arc across the selected tables and charts."
+    prose: str = Field(
+        default="",
+        description=(
+            "A narrative paragraph in Markdown. Leave empty when this block "
+            "places a chart or table instead."
+        ),
     )
 
-    title: str = Field(
-        description="A short, descriptive title for the report story."
+    view: int | None = Field(
+        default=None,
+        description=(
+            "The number of the chart or table to place here, taken from the "
+            "catalog. Leave null for a prose block."
+        ),
     )
 
-    markdown: str = Field(
-        description="The narrative in Markdown, referencing the selected tables and charts and their key findings."
-    )
 
-
-class SectionNote(BaseModel):
+class Story(BaseModel):
 
     chain_of_thought: str = Field(
-        description="In 1-2 sentences, the key insight for this section."
+        description="In 1-2 sentences, outline the narrative arc that ties the charts and tables together."
     )
 
-    markdown: str = Field(
-        description="A concise Markdown note (2-4 sentences) annotating this section's table(s) and chart(s)."
+    title: str = Field(
+        description="A short, descriptive title for the report story."
+    )
+
+    blocks: list[StoryBlock] = Field(
+        description=(
+            "The report as a flowing blog post: alternating prose blocks and "
+            "chart/table blocks, in reading order."
+        )
     )
 
 
 class StoryAgent(LLMUser):
     """
-    Writes a natural-language "story" annotating the tables and charts a user
-    selected for export: one overall narrative plus per-section notes.
+    Writes a "story" that reads like a blog post: short prose paragraphs
+    interleaved with the charts and tables a user selected for export.
     """
 
     prompts = param.Dict(
@@ -55,33 +64,20 @@ class StoryAgent(LLMUser):
                 "template": PROMPTS_DIR / "StoryAgent" / "main.jinja2",
                 "response_model": Story,
             },
-            "section": {
-                "template": PROMPTS_DIR / "StoryAgent" / "section.jinja2",
-                "response_model": SectionNote,
-            },
         }
     )
 
-    async def write_story(self, report_context: str, title: str = "") -> Story:
-        """Write the overall narrative covering all selected sections."""
+    async def write_story(self, catalog: str, guidance: str = "", title: str = "") -> Story:
+        """Write the blog-post story that weaves prose around the catalogued views."""
         return await self._invoke_prompt(
             "main",
             messages=[{"role": "user", "content": "Write the report story."}],
             context={},
-            report_context=report_context,
+            catalog=catalog,
+            guidance=guidance,
             report_title=title,
         )
 
-    async def write_note(self, section_context: str, title: str = "") -> SectionNote:
-        """Write a short note annotating a single section."""
-        return await self._invoke_prompt(
-            "section",
-            messages=[{"role": "user", "content": "Write the section note."}],
-            context={},
-            section_context=section_context,
-            section_title=title,
-        )
-
 
 async def _describe_editor(view: LumenEditor) -> str:
     """Summarize a chart/table editor as spec + data summary for the prompt."""
@@ -92,7 +88,7 @@ async def _describe_editor(view: LumenEditor) -> str:
         parts.append(f"Specification:\n{spec[:_MAX_SPEC_CHARS]}")
     except (TypeError, ValueError, AttributeError, yaml.YAMLError):
         pass
-    pipeline = component if isinstance(component, Pipeline) else getattr(component, "pipeline", None)
+    pipeline = component if isinstance(component, Pipeline) else component.pipeline
     if pipeline is not None:
         try:
             data = await get_data(pipeline)
@@ -103,30 +99,10 @@ async def _describe_editor(view: LumenEditor) -> str:
     return "\n".join(parts) or (view.title or type(component).__name__)
 
 
-async def build_view_context(view) -> str | None:
-    """Describe a single report view (text, table, or chart) for the story prompt."""
-    if isinstance(view, (Typography, Markdown)):
-        return view.object
-    if isinstance(view, str):
-        return view
-    if isinstance(view, ChatMessage):
-        obj = view.object
-        return obj.object if isinstance(obj, Markdown) else (obj if isinstance(obj, str) else None)
-    if isinstance(view, LumenEditor):
-        return await _describe_editor(view)
-    return None
-
-
-async def build_section_context(section) -> str:
-    """Compact context describing one section's tables, charts, and notes."""
-    described = [await build_view_context(view) for view in section.views]
-    return "\n\n".join(text.strip() for text in described if text and text.strip())
-
-
-async def build_report_context(sections) -> str:
-    """Context describing every selected section for the overall story."""
-    blocks = [
-        f"## {section.title or 'Section'}\n{await build_section_context(section)}"
-        for section in sections
-    ]
+async def build_catalog(views) -> str:
+    """Number each chart/table so the story can reference them by their catalog number."""
+    blocks = []
+    for i, view in enumerate(views, start=1):
+        label = view.title or f"View {i}"
+        blocks.append(f"### View {i}: {label}\n{await _describe_editor(view)}")
     return "\n\n".join(blocks)

lumen/ai/prompts/StoryAgent/main.jinja2

@@ -1,20 +1,28 @@
 {% extends 'Actor/main.jinja2' %}
 
 {%- block instructions -%}
-You are a data storyteller. Write a cohesive narrative about a report made up of the
-selected tables and charts below.
+You are a data storyteller. Turn the catalogued charts and tables below into a
+report that reads like a blog post, weaving prose around the visuals.
 
-- Open with a short overview of what the report covers.
-- Walk through the key findings, referring to the tables and charts by their section titles.
-- Surface notable patterns, comparisons, and takeaways grounded ONLY in the provided data
-  summaries and chart specifications.
-- Do not invent numbers that are not supported by the data summaries.
-- Write in Markdown and keep it tight and readable.
+- Return an ordered list of blocks. Each block is either prose or a chart/table.
+- A prose block has `prose` set to Markdown text and `view` left null.
+- A chart/table block has `view` set to that view's number from the catalog and
+  `prose` left empty.
+- Open with a short prose block introducing what the report covers, then walk
+  through the catalog: a prose lead-in, the chart/table it discusses, and so on,
+  so pictures and text alternate like a blog post.
+- Reference every catalogued view exactly once and only use numbers that appear
+  in the catalog.
+- Ground every claim ONLY in the provided data summaries and specifications; do
+  not invent numbers.
+{%- if guidance %}
+- Follow this guidance on angle and tone: {{ guidance }}
+{%- endif %}
 {%- endblock -%}
 
 {%- block context -%}
 Report title: {{ report_title }}
 
-Selected tables and charts:
-{{ report_context }}
+Catalog of charts and tables:
+{{ catalog }}
 {%- endblock -%}