Combo Suggestions

Overview

Generate candidate creative combos as combo suggestions stored in macrodata_artifact rows with kind=combo_suggestion. Each suggestion carries a measurement_confidence score (0.00-1.00) computed from internal performance data, product tags, and agent signals. Staff can accept suggestions to promote them into combo reports.

Goal: Run a generation workflow (ontology: ProcedureExecution) that produces combo suggestions with confidence scoring, and support an acceptance workflow that converts suggestions into combo reports.

API endpoints

Method	Path	Spec	Description
GET	/creative-ops/combo-suggestions	creative-ops.yaml	List combo suggestions
POST	/creative-ops/combo-suggestions/{suggestion_id}/accept	creative-ops.yaml	Accept suggestion (converts to combo report)
POST	/creative-ops/combo-suggestions/{suggestion_id}/dismiss	creative-ops.yaml	Dismiss suggestion
POST	/creative-ops/combo-tests/{test_id}/finalize	creative-ops.yaml	Finalize combo test and trigger suggestion generation
GET	/macrodata-catalogs/{catalog_id}/artifacts?kind=combo_suggestion	macrodata.yaml	List suggestions in a catalog (low-level)
GET	/macrodata-artifacts?kind=combo_suggestion	macrodata.yaml	List suggestions across catalogs (low-level)

Schema tables

Table	Role
macrodata_artifact	Stores combo suggestions (kind=combo_suggestion), combo reports, and templates
macrodata_catalog	Catalog/namespace grouping artifacts
link_product_macrodata_artifact	Links products to suggestion artifacts
product	Product reference data
product_tag	Product tags used as generation signals

Infrastructure

Resource	Purpose
Internal Worker (CF Worker)	Validates requests, enqueues generation jobs
Ingest Worker (CF Worker)	Executes the suggestion generation workflow
CF Queue	SUGGESTION_GENERATE job queue for async generation
PlanetScale (Postgres via Hyperdrive)	Primary data store for all artifacts
R2 (measurement.performance)	Performance data used as generation signals

Participants

Actor	Role
Staff user	Requests generation with constraints, reviews and accepts/dismisses suggestions
Dashboard API Worker	Validates, enqueues generation jobs
Ingest Worker	Executes generation workflow: queries signals, produces suggestions
PlanetScale	Data store for performance data and suggestions

Main success scenario

1. Staff user calls POST /creative-ops/combo-tests/{test_id}/finalize with constraints (or triggers generation via the finalize workflow)
2. API validates Access, enqueues SUGGESTION_GENERATE
3. Ingest Worker executes the generation workflow:
   • Step: Query signals — reads combo reports (macrodata_artifact, kind=combo_report) to avoid duplicates, measurement.performance on R2 for winners/risers, product_tag and agent assignments (kind=agent_assignment) if relevant
   • Step: Generate — produces suggested_combos JSON, computes measurement_confidence (ratio scale 0.00-1.00)
   • Step: Persist — writes combo suggestions (macrodata_artifact, kind=combo_suggestion, status=pending, with measurement_confidence and performance_context)
4. Staff reviews via GET /creative-ops/combo-suggestions
5. Staff accepts suggestion via POST /creative-ops/combo-suggestions/{suggestion_id}/accept, which creates a combo report entry (suggestion converts into combo report)

Exception flows

Condition	Fallback
Not enough candidate products	Write suggestion with empty list + explanation
Computation exceeds Worker CPU limit	Break into multiple queue messages

Queue contract

{
  "job_type": "SUGGESTION_GENERATE",
  "job_id": "uuid",
  "combo_size": 3,
  "constraints": { "audience": "WOMEN" }
}

Acceptance criteria

• PASS: Combo suggestions produced with valid measurement_confidence; accepting creates corresponding combo report with correct combo template identifier
• FAIL: Duplicates; invalid artifact_identifiers; inability to accept due to missing fields