[GM Workbench] Generation scratchpad/history (GenerationResult model)

claude-bot commented

2026-07-15 22:01:33 +00:00

Contributor

Motivation / Context

Today, anything generated but not saved is lost when the 2-hour Redis TTL on name-option caching expires or the tab closes (webapp/backend/app/tasks/planning_tasks.py:11-12). There is no persistence of generated-but-unsaved options. GMs generate in bursts during prep and want to come back to results later — pick between three loot parcels, revisit a rumor they didn't use yet, re-open a backstory draft. No generation-history model exists anywhere in the schema today (confirmed: grep for loot/quest_log/generation in webapp/backend/app returns nothing relevant).

This is issue 3 of 3 foundational items, completing the enabling layer before individual Workbench tools ship. It's also the async-status carrier for issue #136's sync/Celery split, and — per the report's hosted-service section (§6) — the natural home for future token-usage metering.

Approach

New model GenerationResult (§5.4), following the campaign-scoped inline-router precedent already used for planning arcs/threads (webapp/backend/app/routers/campaigns.py:3172-3390):
- id, campaign_id (FK CASCADE, indexed), tool_id (Text), params (JSONB), output (JSONB), status (pending/ready/failed — use raw SQL for the enum per this repo's Alembic convention, not op.create_table() with sa.Enum directly, to avoid spurious CREATE TYPE), error, pinned (bool), session_id (nullable FK), created_by, created_at.
- Add a token_usage JSONB column from day one (§6) — provider responses include usage data, and this is the cheapest point to start capturing it for future metering even though quota enforcement itself is out of scope here.
Migration in webapp/backend/alembic/ following existing conventions for JSONB + FK-cascade columns (see the PlotThread/CampaignArc migrations for the inline-router-backed model precedent).
Endpoints, campaign-scoped, GM-only:
- GET /api/campaigns/{campaign_id}/workbench/history — list, filterable by tool_id, pinned.
- Pin/unpin and delete endpoints for individual GenerationResult rows.
Async status lifecycle: the Celery-backed tools registered in issue #136 write pending on enqueue and ready/failed on completion into this table — the same generating → ready/failed shape the existing draft pipeline uses (draft_service.py, reminder_tasks.py:2051-2124). The frontend polls the history/status endpoint, mirroring how WikiDraftReview.jsx already polls draft status.
Retention cleanup: a Celery beat task that deletes unpinned GenerationResult rows older than ~30 days, added alongside the existing beat schedule (find the existing periodic-cleanup task pattern in reminder_tasks.py or the Celery beat config and follow it).
Right-rail UI: minimal scratchpad/history panel — list view filtered by tool, pin/unpin, delete, "re-open into the panel" (loads params/output back into the generation form). This can be a simple list for this issue; the full two-pane workbench layout is issue #153.

Dependencies

#134 (Extract LLM core) — indirect; this model doesn't call the LLM directly.
#136 (Generalized workbench endpoint + tool registry) — direct and required. The POST /workbench/{tool_id}/generate endpoint needs GenerationResult to exist so it has somewhere to write sync results and async status. In practice these two are implemented back-to-back.
Every later Workbench tool issue (#141 and beyond) writes into and reads from this table as its scratchpad.

Out of scope

Per-campaign generation quotas / rate limiting — token_usage is captured here for future metering, but enforcing quotas against it is a separate hosted-service concern (§6), not built in this issue.
The full two-pane workbench UX (tool palette, unified GeneratorPanel, right-rail redesign) — issue #153. This issue only needs a functional, minimal history list.
Per-tool model override / model tiering (§6) — noted as a future registry field, not implemented here.

Acceptance criteria

GenerationResult model + migration exist with all fields above, including token_usage JSONB.
GET /api/campaigns/{campaign_id}/workbench/history returns campaign-scoped results, filterable by tool_id and pinned, GM-only.
Pin/unpin and delete work and are GM-only.
A Celery-backed tool's pending → ready/failed transitions are visible via the history endpoint (verified against at least the names tool once wired through #136, or a stub tool for this issue's own testing).
Retention cleanup task deletes unpinned rows older than the configured threshold and is registered in Celery beat; pinned rows are never auto-deleted.
Minimal frontend list view exists showing history entries with pin/delete/re-open actions.

## Motivation / Context Today, anything generated but not saved is lost when the 2-hour Redis TTL on name-option caching expires or the tab closes (`webapp/backend/app/tasks/planning_tasks.py:11-12`). There is no persistence of generated-but-unsaved options. GMs generate in bursts during prep and want to come back to results later — pick between three loot parcels, revisit a rumor they didn't use yet, re-open a backstory draft. No generation-history model exists anywhere in the schema today (confirmed: grep for loot/quest_log/generation in `webapp/backend/app` returns nothing relevant). This is issue 3 of 3 foundational items, completing the enabling layer before individual Workbench tools ship. It's also the async-status carrier for issue #136's sync/Celery split, and — per the report's hosted-service section (§6) — the natural home for future token-usage metering. ## Approach - **New model `GenerationResult`** (§5.4), following the campaign-scoped inline-router precedent already used for planning arcs/threads (`webapp/backend/app/routers/campaigns.py:3172-3390`): - `id`, `campaign_id` (FK CASCADE, indexed), `tool_id` (Text), `params` (JSONB), `output` (JSONB), `status` (`pending`/`ready`/`failed` — use raw SQL for the enum per this repo's Alembic convention, not `op.create_table()` with `sa.Enum` directly, to avoid spurious `CREATE TYPE`), `error`, `pinned` (bool), `session_id` (nullable FK), `created_by`, `created_at`. - Add a `token_usage` JSONB column from day one (§6) — provider responses include usage data, and this is the cheapest point to start capturing it for future metering even though quota enforcement itself is out of scope here. - **Migration** in `webapp/backend/alembic/` following existing conventions for JSONB + FK-cascade columns (see the `PlotThread`/`CampaignArc` migrations for the inline-router-backed model precedent). - **Endpoints**, campaign-scoped, GM-only: - `GET /api/campaigns/{campaign_id}/workbench/history` — list, filterable by `tool_id`, `pinned`. - Pin/unpin and delete endpoints for individual `GenerationResult` rows. - **Async status lifecycle**: the Celery-backed tools registered in issue #136 write `pending` on enqueue and `ready`/`failed` on completion into this table — the same `generating → ready/failed` shape the existing draft pipeline uses (`draft_service.py`, `reminder_tasks.py:2051-2124`). The frontend polls the history/status endpoint, mirroring how `WikiDraftReview.jsx` already polls draft status. - **Retention cleanup**: a Celery beat task that deletes unpinned `GenerationResult` rows older than ~30 days, added alongside the existing beat schedule (find the existing periodic-cleanup task pattern in `reminder_tasks.py` or the Celery beat config and follow it). - **Right-rail UI**: minimal scratchpad/history panel — list view filtered by tool, pin/unpin, delete, "re-open into the panel" (loads `params`/`output` back into the generation form). This can be a simple list for this issue; the full two-pane workbench layout is issue #153. ## Dependencies - **#134** (Extract LLM core) — indirect; this model doesn't call the LLM directly. - **#136** (Generalized workbench endpoint + tool registry) — direct and required. The `POST /workbench/{tool_id}/generate` endpoint needs `GenerationResult` to exist so it has somewhere to write sync results and async status. In practice these two are implemented back-to-back. - Every later Workbench tool issue (#141 and beyond) writes into and reads from this table as its scratchpad. ## Out of scope - Per-campaign generation quotas / rate limiting — `token_usage` is captured here for future metering, but enforcing quotas against it is a separate hosted-service concern (§6), not built in this issue. - The full two-pane workbench UX (tool palette, unified `GeneratorPanel`, right-rail redesign) — issue #153. This issue only needs a functional, minimal history list. - Per-tool model override / model tiering (§6) — noted as a future registry field, not implemented here. ## Acceptance criteria - `GenerationResult` model + migration exist with all fields above, including `token_usage` JSONB. - `GET /api/campaigns/{campaign_id}/workbench/history` returns campaign-scoped results, filterable by `tool_id` and `pinned`, GM-only. - Pin/unpin and delete work and are GM-only. - A Celery-backed tool's `pending → ready/failed` transitions are visible via the history endpoint (verified against at least the names tool once wired through #136, or a stub tool for this issue's own testing). - Retention cleanup task deletes unpinned rows older than the configured threshold and is registered in Celery beat; pinned rows are never auto-deleted. - Minimal frontend list view exists showing history entries with pin/delete/re-open actions.

claude-bot added this to the v3.10.0 - GM Workbench milestone

2026-07-15 22:01:53 +00:00

claude-bot added the

backend

enhancement

frontend

labels

Rows
Columns

[GM Workbench] Generation scratchpad/history (GenerationResult model) #138

Motivation / Context

Approach

Dependencies

Out of scope

Acceptance criteria