[Hackathon] feat: AI workflow documentation tool with history, editing, and diff

[zyratlo]

Demo Video

https://drive.google.com/file/d/1PcP_N_hucajoNYRuUK9bxhqcg7jfvic9/view?usp=sharing

What changes were proposed in this PR?

Adds a new AI Workflow Documentation tool to the workspace, accessible from the existing menu bar via the document-text icon. The tool lives in a right-side nz-drawer that doesn't block the canvas, and supports three main flows: generating documentation with an LLM, writing it manually, and managing a per-workflow history of reports.

Generating a report

• Click Generate Documentation on the intro page. The backend agent-service calls the LLM with a structured context of the current workflow (operator IDs, display names, types, descriptions, properties, UDF source code, compiled output schemas, link graph, and author comment-box notes) and a prompt instructing the model to produce sections for Purpose / Inputs / Pipeline Stages / Outputs / Caveats.
• The prompt requires the LLM to format every operator mention as a markdown link of the form Display Name. Clicking one of these links in the rendered doc pans the canvas to center the operator and highlights it.
• A centered spinner and stopwatch gives feedback during the wait. A Cancel button unsubscribes the request and cleans up the temp agent via the service's finalize handler.

Writing your own

• Write Your Own opens the doc view in edit mode with a blank text area. Saving creates a new history entry tagged written: true.
• An Edit button on any existing entry swaps the rendered markdown for a text area pre-filled with the current content. Saving updates the entry in place, marks it edited: true, refreshes its timestamp, and moves it to the top of the history. Source labels in the timestamp adjust accordingly ("Generated" → blue, "Updated" → blue + orange edited pill, "Written" → purple).
• Both the editor and any in-progress draft are persisted, so closing the drawer mid-edit and reopening it lands the user back in the editor with their unsaved text intact. Navigating away from the entry (Back, viewing another report) pops a "Discard unsaved changes?" confirm.

Per-workflow history

• Every generated/written/edited entry is recorded in a list on the intro page. Rows show the title (or timestamp fallback), a "Latest" badge on the newest, plus icons that mirror the report's origin (blue thunderbolt for AI, purple edit pencil for hand-written).
• Each row supports Rename (inline editable title field, with the rename also exposed inside the doc view's header), Duplicate (carries title with a (copy) suffix), and Delete (with popconfirm). The list scrolls internally so long histories don't blow out the drawer.
• A Compare mode lets the user pick any two entries and opens a side-by-side diff. The diff is line-level via diff.diffLines, but each (removed, added) pair runs through diffWordsWithSpace so only the actually-changed words light up — entirely rewritten lines are still uniformly colored. The compare modal shows entry titles (or "Base"/"Head") plus −N / +M totals.

Persistence

• History, last-viewed-page-per-workflow, and the in-progress editing state are all serialized to localStorage under a single versioned key (texera.workflowDoc.v1). The constructor revives Date fields on load; every mutation writes back. DocEntry gets a stable id (crypto.randomUUID() with a timestamp fallback) so the editing-state restore can match entries across JSON round-trips. Quota / availability failures degrade silently to the previous in-memory behavior.

Files

• New:
  • frontend/src/app/workspace/service/workflow-doc/workflow-doc.service.ts
  • frontend/src/app/workspace/component/workflow-doc-panel/
  • frontend/src/app/workspace/component/workflow-doc-diff/
  • agent-service documentation prompt + endpoint.
• Modified:
  • agent-service/src/agent/texera-agent.ts
  • agent-service/src/server.ts
  • frontend/src/app/workspace/component/menu/{menu.component.ts,menu.component.html}
  • frontend/src/app/workspace/component/workflow-editor/workflow-editor.component.ts
  • frontend/src/app/workspace/service/workflow-graph/model/workflow-graph.ts
  • frontend/src/app/app.module.ts (registers NzDrawerModule)
  • frontend/package.json (adds diff and file-saver types where needed).

Any related issues, documentation, discussions?

See Discussion #5059

Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Code (Anthropic Claude Opus 4.7)

Future Work

• Bidirectional report ↔ workflow editing — keep the report and the canvas in sync as both sides change. Editing an operator's description in the report could propagate back to the operator's properties on the canvas; adding or renaming an operator on the canvas could update the corresponding section in the latest report.
• Include runtime information in the doc — augment the LLM context with execution metadata (per-operator runtime stats, row counts, errors, last execution time) so generated reports describe not just what the pipeline does structurally but how it actually behaves on the current data.
• Richer compare view — collapse unchanged sections with git-style "show N unchanged lines" expanders; make texera:op: links clickable inside the diff to reuse the canvas pan/highlight flow; add per-section change summaries ("Inputs: unchanged, Pipeline Stages: 3 lines changed"); offer a unified-vs-side-by-side toggle and an "ignore whitespace" mode.
• Floating, draggable, resizable panel — replace the right-side drawer with a movable, resizable window, so the tool no longer obscures operator details, the run button, or other right-side UI.