Platform concepts

Whet is organized around two complementary surfaces:

• Pipelines — the recurring contract: Source → Processing → Output, driven by runs.
• Sessions — the scratch-pad surface: snapshot inputs, attach generation variants, iterate, export.

Dashboards observe both.

Pipeline-side entities

Entity	What it is
Pipeline	A re-runnable contract: source + processing + output + tone configuration. Persistent.
Source	Where the content comes from. Three layers: official API, managed ingestion, manual paste. See Pipelines.
Run	An execution of the pipeline. FSM pending → running → succeeded / failed / cancelled.
Artifact	What the run produces. Two concrete types: Riff (single-source, prefix rf_) and Brief (multi-source synthesis, up to 50 source posts, prefix bf_). Both share FSM review → ready → published / discarded.
Riff	An artifact generated by POST /artifacts with kind=riff. The product's verb: to "riff" a pattern is to generate a new draft in your voice over the same structure.
Brief	An aggregate artifact generated by POST /artifacts with kind=brief from an array of source_post_ids.
Decode	Structural analysis of a single post (extracts hook, tone, format, triggers). Emits decode.ready.
Refinement	An action that takes an artifact and produces a child artifact (variant). Available actions: shorter, change_tone, match_voice, more_punchy. Genealogy is preserved (parent_id). Triggered by POST /artifacts/{parent_id}/refine.
Workspace	The configuration singleton per organization. One Whet instance = one workspace.
Operator	The human (or agent) who operates the workbench. See Operators.

Session-side entities

The session surface is independent of pipelines — you can run a session against any combination of upstream items without needing them to belong to the same pipeline. See Sessions for the full model.

Entity	What it is
Session canvas	A drafting workspace scoped to one (organization, user) pair. Holds selected items, variants and exports. Lifecycle is independent of pipelines.
Session item	An immutable snapshot of an upstream item (social post / webpage / RSS / custom) at selection moment. Has its own copy of title/snippet/metrics — changes upstream don't propagate.
Variant	A generation slot: preset + prompt + style + (optional) per-variant LLM credential. Holds one append-only history of rounds.
Round	A single generation output for a variant. Append-only — selecting an older round doesn't delete newer ones.
User preset	A named (prompt, style, typeTag) saved by the user, scoped to the org. Built-in presets are stable slugs (social-thread, blog-with-images, long-form, newsletter-section, tldr-brief).
Export	Recorded event when a round is exported (markdown only today). Backs the EXPORTS 7D KPI.
Activity	Log row written on every session-affecting action (UI clicks + MCP tool calls). Drives /console NowFeed.

Dashboard-side entities

Entity	What it is
Dashboard	A named collection of widgets, scoped to the workspace. Layout is GridLayout-style positions.
Widget	A typed chart (kpi, timeseries, donut, bar, topN, table) backed by a querySpec validated at write time against the dataset catalog.
Dataset	Read-only metric/dimension/filter catalog exposed by the engine. dashboards_list_datasets MCP tool returns it.

End-to-end flow (pipelines)

1. An operator creates a pipeline (UI / CLI / MCP) with an intent: "track @growth_dr and build analytical drafts per post."
2. Whet schedules runs according to the scope (per_post / daily_digest / weekly_digest).
3. Each run ingests from the configured layer, processes with the chosen LLM, and persists one or more artifacts.
4. The operator (or an agent via MCP) reviews the inbox, possibly triggers refinements that produce child variants, and eventually publishes with human confirmation.

End-to-end flow (sessions)

1. The operator opens a fresh session canvas from /console (or via session_create).
2. They snapshot upstream items into the session — these become session items (immutable).
3. They attach variants: each with a preset, a prompt, a style, optionally a per-variant LLM.
4. session_generate_variant (or session_generate_all) queues LLM calls; each call appends a round to the variant.
5. The operator picks the best round (session_select_round) and session_export_variant to ship it as markdown.

Webhook events

The exact event names the backend emits:

Event	When
ingest.completed	An ingest run of an operator (social handle) finished.
post.ready	A new social post was ingested.
webpage.ready	A tracked_webpage (public URL) was refetched with changes.
decode.ready	The decode of a post produced its structural analysis. Carries post_id.
riff.ready	A generated riff moved to status=ready.
riff.refined	A riff refinement produced a child. Carries parent_id.
brief.ready	A multi-source brief moved to status=ready.
brief.refined	A brief refinement produced a child. Carries parent_id.
pattern.detected	The decoder identified a new or recurring pattern.
operator.error	An ingest run of an operator failed with an error that needs attention (e.g. dead credentials).

For the job lifecycle itself (from pending to succeeded/failed/cancelled) there is polling of GET /runs/{id}. Webhooks are the channel for "something useful completed" — not for "this run changed state."

If you are building an agent or an external dashboard, subscribe to these webhooks instead of polling. See Webhooks.

See also

• Pipelines — the core concept explained with the three layers.
• Sessions — the drafting canvas.
• Operators — the human role that operates the workbench.
• Patterns and riffs — how voice is preserved during generation.
• Glossary — all terms in a single table.