Galaxy Notebooks & Reports: Architecture & Feature Summary

Branch: history_pages Date: 2026-04-01 Status: Feature-complete, pre-merge

1. What Are Galaxy Notebooks?

Galaxy Notebooks are markdown documents tied to Galaxy histories. They let users (and AI agents) document, annotate, and share analysis narratives alongside the data that produced them. A history can have multiple notebooks, and each notebook supports an AI assistant that can read history contents and propose edits.

UI terminology vs backend model: The backend uses the existing Page model for everything — a “Galaxy Notebook” is a Page with history_id set, and a “Report” is a standalone Page. User-facing strings are centralized in Page/constants.ts via PAGE_LABELS, making the terminology easy to change without touching backend code.

This unified model means notebooks and reports share the same editor, revision system, AI chat, and API surface. The difference is contextual: notebooks gain access to history-aware AI tools and are accessed through the history panel rather than the reports grid.

Every save creates an immutable revision, edits from humans and agents are tracked separately via edit_source, and the revision system supports preview and one-click rollback.

2. Reports vs Galaxy Notebooks

The system supports two contexts through a single unified editor (PageEditorView):

Both modes share: editor UI, revision system, AI chat, dirty tracking, diff views, and the same API endpoints.

3. User Stories

Researcher documenting an analysis

“I ran a ChIP-seq pipeline and want to write up what I did and what the results mean, with embedded dataset previews and plots, right next to the history that contains the data.”

• Opens history panel -> clicks “Galaxy Notebooks” button
• System auto-creates a notebook titled after the history
• Types markdown prose; uses the toolbox to insert dataset references (history_dataset_display(...))
• Drags a dataset from the history panel into the editor — directive auto-inserted
• Clicks Preview to see rendered markdown with live dataset embeds
• Saves; revision #1 recorded with edit_source="user"

AI-assisted notebook editing

“I have 50 datasets from a variant-calling run. I want the AI to summarize what’s in my history and draft a methods section.”

• Opens notebook -> toggles chat panel (split view: 60% editor / 40% chat)
• Types: “Summarize the datasets in this history and draft a Methods section”
• Agent calls list_history_datasets -> get_dataset_info -> resolve_hid tools
• Agent returns a section_patch proposal targeting ## Methods
• User sees a per-section diff with checkboxes; accepts the Methods section, rejects the Introduction rewrite
• Applied content creates revision with edit_source="agent"
• Conversation persists across panel close/reopen and page refresh

Sharing and publishing

“My analysis is complete. I want to share the notebook read-only.”

• Shared histories expose their notebooks in read-only display mode to other users
• Reports use the Permissions modal to manage sharing, publishing, and slug assignment

Reviewing past AI conversations

“I had a great chat with the AI last week about my RNA-seq results. I want to pick up where I left off.”

• Opens notebook -> toggles chat panel
• Clicks chat history icon to open PageChatHistoryList
• Browses past conversations with timestamps
• Selects a previous exchange to resume it
• Can also delete old conversations to keep things tidy

Revision history and rollback

“The agent’s last edit broke my formatting. I want to go back to the previous version.”

• Opens revision panel (right sidebar, 300px)
• Sees revision list with timestamps and source badges: “Manual”, “AI”, “Restored”
• Clicks an old revision to preview it read-only
• Can compare revision against current content or previous revision (three view modes)
• Clicks “Restore” -> creates a new revision from old content (edit_source="restore")

4. Architecture Overview

+---------------------------------------------------------------------------+
|                          Frontend (Vue 3)                                  |
|                                                                           |
|  HistoryCounter --> HistoryPageView --> PageEditorView <-- PageEditor      |
|       |                 |    |              |                  |           |
|       |           +-----+    +-----+   MarkdownEditor     (report          |
|       |           |                |    TextEditor          entry)         |
|       |     HistoryPageList        |    (drag-drop)                       |
|       |                      SplitView                                    |
|       |                            |                                      |
|       |   PageRevisionList    PageChatPanel                               |
|       |   PageRevisionView     |         |         |                      |
|       |                  ChatMessageCell  ProposalDiffView                 |
|       |                  ChatInput       SectionPatchView                  |
|       |                  PageChatHistoryList                               |
|       |                                                                   |
|  pageEditorStore (Pinia) <---> API Client (api/pages.ts)                  |
+---------------------------------+-----------------------------------------+
                                  | REST
+---------------------------------v-----------------------------------------+
|                       Backend (FastAPI)                                    |
|                                                                           |
|  /api/pages (history_id filter) --> PageManager                           |
|  /api/pages/{id}/revisions      --> PageManager (revisions)               |
|  /api/chat (page_id)            --> ChatManager + AgentService            |
|                                          |                                |
|                                  PageAssistantAgent                       |
|                                    +- list_history_datasets               |
|                                    +- get_dataset_info                    |
|                                    +- get_dataset_peek                    |
|                                    +- get_collection_structure            |
|                                    +- resolve_hid                         |
|                                                                           |
|  Models: Page (+ history_id), PageRevision (+ edit_source), ChatExchange  |
|  markdown_util.py: ready_galaxy_markdown_for_export()                     |
+---------------------------------------------------------------------------+

5. Data Model

Page (extended)

Relationships: user, history (optional), revisions (cascade delete), latest_revision (eager), source_invocation, tags, annotations, ratings, users_shared_with

PageRevision (extended)

ChatExchange (extended)

The page_id FK scopes chat exchanges to a page.

Migration

6. Content Pipeline

Page content has three representations across the boundary, not two. The DB-internal form is distinct from both API fields — a distinction the earlier draft of this doc collapsed (see correction note below).

INBOUND (create/update):
  client markdown (ENCODED ids) --ready_galaxy_markdown_for_import--> decode_id --> DB
  e.g. history_dataset_id=f2db41e1fa331b3e  ----------------------->  history_dataset_id=42

DB-internal (page_revision.content):
  RAW integer ids, directives un-expanded     history_dataset_id=42   (never returned to clients)

OUTBOUND (show/update response) -- rewrite_content_for_export():
        DB-internal ---ready_galaxy_markdown_for_export--> two forms, BOTH with ENCODED ids:
           |
           +--> content_editor = export_markdown
           |      ENCODED ids, directives intact, NOT embed-expanded   (editor reads/writes this)
           |
           +--> content = export_markdown_embed_expanded
                  ENCODED ids + embedded dataset content               (Markdown renderer uses this)

The API returns both fields in PageDetails:

• content_editor: what the text editor displays and saves back — encoded ids, un-expanded directives
• content: what the Markdown renderer uses — encoded ids, embeds expanded

Correction (2026-06-12): An earlier revision of this section described content_editor as “raw, same as DB content” with history_dataset_id=42. That is wrong. The raw integer form exists only in the page_revision.content DB column; the service always runs rewrite_content_for_export before returning, so both API fields carry encoded ids. The real difference between content_editor and content is embed expansion (un-expanded directives vs. inlined dataset content), not raw-vs-encoded ids. Verified against managers/pages.py:457 (rewrite_content_for_export), services/pages.py:89 (_page_to_details), and managers/markdown_util.py:111,655 (import decode_id / export encode_id). This matters: any consumer reading content_editor (the editor, and any MCP page tool) stays in encoded-id space — no raw DB ids leak across the API boundary.

7. Agent Architecture

PageAssistantAgent

Registered as AgentType.PAGE_ASSISTANT in the Galaxy agent framework. Uses pydantic-ai with structured output.

Tools (5):

When editing a report (no history_id), history tools are unavailable — the agent can still do full-replacement and section-patch edits on the content.

Output types (3, discriminated by mode literal):

System prompt is dynamically assembled:

1. Static instructions from prompts/page_assistant.md
2. Auto-generated directive reference table (reads markdown_parse.VALID_ARGUMENTS at runtime)
3. Current page content injected as context
4. History name and item count summary (when history_id is set)

The agent works in HID-space (matching what users see in the history panel) and uses resolve_hid to translate to the history_dataset_id=N directive arguments that Galaxy’s markdown renderer expects.

Chat Persistence

Conversations are scoped per-page via ChatExchange.page_id. The flow:

1. User sends message -> POST /api/chat with page_id and agent_type="page_assistant"
2. API looks up page, extracts history_id and current content from the page record
3. Agent processes with history tools (if notebook) and current document context
4. Response stored as ChatExchange + ChatExchangeMessage with full agent_response JSON
5. Frontend persists exchange_id in userLocalStorage per-page for session continuity

Chat History Browsing

Users can browse, resume, and delete past conversations for a page via PageChatHistoryList. The store tracks pageChatHistory, isLoadingChatHistory, showChatHistory, and chatHistoryError state. Chat history is fetched from GET /api/chat/page/{page_id}/history and displayed in a sidebar list with timestamps. Selecting a past exchange resumes it; deletion is also supported.

8. Frontend Components

Component Tree

Galaxy Notebook entry:
  HistoryCounter (button in history panel)
    +- HistoryPageView (list + display routing -- 177 lines)
         +- HistoryPageList (notebook picker -- 91 lines)
         +- Markdown (display-only render)
         +- PageEditorView (edit mode delegation)

Report entry:
  PageEditor (thin wrapper -- 12 lines)
    +- PageEditorView

PageEditorView (unified editor -- 372 lines)
  +- ClickToEdit (inline title editing)
  +- MarkdownEditor
  |    +- TextEditor (drag-and-drop for history items)
  +- PageRevisionList (sidebar panel -- 87 lines)
  +- PageRevisionView (revision preview + diff -- 194 lines)
  +- SplitView (resizable 60/40 split -- 92 lines, shared in Common/)
  |    +- PageChatPanel (agent chat -- 570 lines)
  |         +- ChatMessageCell (shared from ChatGXY)
  |         +- ChatInput (shared from ChatGXY)
  |         +- ProposalDiffView (full-doc diff -- 122 lines)
  |         +- SectionPatchView (per-section diff -- 206 lines)
  |         +- PageChatHistoryList (chat history browser -- 234 lines)
  +- ObjectPermissionsModal (reports only -- 17 lines)
  |    +- ObjectPermissions (363 lines)
  |    +- PermissionObjectType (31 lines)
  |    +- SharingIndicator (72 lines)

PageEditorView (unified editor)

The core editor component. Adapts based on context:

View states (template branching):

1. Loading spinner (no current page yet)
2. Error alert (dismissible)
3. Display-only mode (read-only Markdown render + toolbar with Edit button)
4. Revision view (revision preview/diff with Restore button — supports three view modes)
5. Edit mode (toolbar + editor + optional chat/revision sidepanels)

Revision view modes (revisionViewMode):

• "preview" — read-only render of revision content
• "changes_current" — diff against current page content
• "changes_previous" — diff against previous revision

HistoryPageView (notebook context router)

Routes between three states for Galaxy Notebooks:

1. List mode (no pageId) -> HistoryPageList
2. Display mode (displayOnly=true) -> Markdown renderer with toolbar
3. Edit mode (pageId set, no displayOnly) -> delegates to PageEditorView

Handles Window Manager integration: when WM is active, clicking a notebook in the list opens it in a WinBox window via displayOnly=true with router.push(url, { title, preventWindowManager: false }).

Pinia Store (pageEditorStore)

Mode: mode: "history" | "standalone" — "history" = Galaxy Notebook, "standalone" = Report.

State management:

• Page list, current page, editor content (raw), title
• Dirty tracking: isDirty = currentContent !== originalContent || currentTitle !== originalTitle
• Revision list, selected revision, and revisionViewMode: "preview" | "changes_current" | "changes_previous"
• UI toggles: showRevisions, showChatPanel (mutually exclusive)
• Chat history: pageChatHistory, isLoadingChatHistory, showChatHistory, chatHistoryError
• Loading/saving flags

Cross-session persistence (userLocalStorage):

• currentPageIds — remembers which page was open per-history
• currentChatExchangeIds — remembers chat exchange per-page
• dismissedChatProposals — remembers dismissed proposals per-page

Smart defaults:

• resolveCurrentPage(historyId) returns stored page, falls back to most recent by update_time, or auto-creates a new one

Mode differentiation is minimal — mostly determines UI labels (via PAGE_LABELS) and available features:

• History mode: guard checks require historyId for load operations
• Report mode: savePage() defaults edit_source to "user" if not specified
• API calls are identical — unified /api/pages endpoints handle both via optional history_id

Diff System (sectionDiffUtils.ts — 218 lines)

Built on jsdiff (diff@^8.0.3).

Stale proposal detection: Uses DJB2 hash of original content. If page content changes after a proposal was generated, Accept buttons are disabled.

Routes

Drag-and-Drop

TextEditor supports drag from the history panel when mode="page":

• Uses Galaxy’s eventStore.getDragItems() infrastructure
• Datasets -> history_dataset_display(history_dataset_id=...) directive
• Collections -> history_dataset_collection_display(history_dataset_collection_id=...) directive
• Visual feedback: green dashed border on valid dragover

Window Manager Integration

When Galaxy’s Window Manager (WinBox) is active:

• Notebooks: Clicking a notebook in HistoryPageList opens it in a WinBox window via displayOnly=true
• Reports: “View in Window” grid action calls Galaxy.frame.add() with embed URL
• HistoryCounter: The notebook button respects WM state — opens in frame when active
• onUnmounted skips store.$reset() in display mode (iframe independence)

9. API Surface

All operations use the unified /api/pages endpoints. Notebooks are pages with history_id set; reports have history_id null.

Page CRUD

Revisions

Sharing & Publishing (reports only)

Chat

Index Query Parameters

10. Test Coverage

Summary

Frontend Test Files

Test Infrastructure

• Selenium helpers: 13 methods on NavigatesGalaxy (navigate, create, edit, save, rename, revisions, chat)
• Navigation YAML: 29+ selectors under pages.history section
• Vitest: Pinia testing utilities, MSW for HTTP mocking, Vue shallowMount
• Agent tests: Mocked pydantic-ai agent + optional live LLM tests (env-gated)

11. ChatGXY Extraction

The existing ChatGXY.vue (982 lines) was refactored into shared sub-components before building the page chat panel:

PageChatPanel reuses all extracted components with no duplication.

12. Design Decisions

Unified Page Model

Both Galaxy Notebooks and Reports reuse the existing Page model rather than introducing a separate table. The distinction is a nullable page.history_id FK — when set, the page is a notebook; when null, it’s a report.

• page.history_id (nullable FK to history) distinguishes notebooks from reports
• page_revision.edit_source tracks revision provenance ("user", "agent", "restore")
• chat_exchange.page_id scopes chat to a page
• All page operations go through the unified /api/pages endpoints with optional history_id filter

Benefit: One model, one API, one editor, one store. No duplication.

HID Syntax (Decided: Not stored)

Pages store history_dataset_id=X (matching existing Page syntax) rather than hid=N. The agent uses resolve_hid as a tool to bridge between user-visible HIDs and directive IDs. This avoids complex resolution machinery while preserving the agent’s ability to work with HIDs naturally.

Trade-off: power users hand-editing markdown see opaque IDs, but the toolbox and drag-and-drop handle insertion — most users never read raw markdown.

UI Convergence

The legacy PageEditorMarkdown.vue (Options API, local state, no revisions/chat) was replaced by a single unified editor:

• PageEditorView.vue adapts via mode: "history" | "standalone" (notebook vs report)
• HistoryPageView.vue handles only list + display routing; edit mode delegates to PageEditorView
• Legacy PageEditorMarkdown.vue and PageEditor/services.js deleted
• Single pageEditorStore handles both modes with minimal branching

Multiple Notebooks Per History

No unique constraint on page.history_id. A history can have multiple notebooks for different analysis perspectives, collaborators, or document types.

Title Not Versioned

Title lives on Page, not on revisions. Renaming doesn’t create a new revision — it’s page identity, not content. (PageRevision does have a title field for snapshot purposes.)

Revision = Append-Only

Every edit (user save, agent apply, restore) creates a new PageRevision. No in-place updates. edit_source tracks provenance.

Section-Level Patching

The agent can propose section-level edits (targeted by heading). The frontend shows per-section diffs with individual checkboxes. Users accept/reject sections independently. This is more practical than all-or-nothing for large documents.

Panel Mutual Exclusion

The revision panel and chat panel are mutually exclusive — toggling one closes the other. This avoids layout complexity and keeps the editor area usable.

13. File Inventory

Backend (Python)

Frontend (TypeScript/Vue)

Tests

14. Remaining Work

Not Yet Implemented

Known Issues

• APPLY_PAGE_EDIT and INSERT_PAGE_SECTION action types defined in agentActions.ts but not fully wired to UI handlers
• MarkdownHelp.vue does not yet have page-specific help text for history context
• No concurrent edit protection (last-write-wins)