Combo Suggestions

Overview

Generate candidate creative combos as Suggestion Content Entities (IAO) — ICEs with measurement_confidence (ratio-scale Measurement Datum) — using internal performance Measurement Data, Tag ICE, and Agent signals. Staff can accept suggestions into Creative Act Reports.

Goal: Execute a ProcedureExecution that produces suggestion_content_entity rows with confidence scoring and supports an acceptance workflow that realizes suggestions into Reports.

Participants

Actor	Ontological type	Role
Staff user	Person (CCO) bearing Role	Requests generation with constraints
Dashboard API Worker	EngineeredSystem (IOF)	Validates, enqueues
Ingest Worker	EngineeredSystem (IOF)	ProcedureExecution: queries signals, generates Suggestion ICEs
PlanetScale	EngineeredSystem (IOF)	IBE store for Measurement Data + Suggestion ICEs

Main success scenario

[PKO: ProcedureExecution producing IAO Information Content Entities with measurement_confidence]

1. Person bearing Role calls POST /api/combo-suggestions/generate with combo_size and constraints
2. API validates Access, enqueues SUGGESTION_ICE_GENERATE
3. Ingest Worker executes ProcedureExecution:
   • Step: Query signals — reads creative_act_report (avoid duplicates), performance_measurement_dataset for winners/risers, tag_content_entity and agent_role_assignment (if relevant)
   • Step: Generate — produces suggested_combos JSON, computes measurement_confidence (ratio scale 0.00–1.00)
   • Step: Persist — writes suggestion_content_entity(status='pending', measurement_confidence, performance_context)
4. Person reviews via GET /api/combo-suggestions
5. Person accepts suggestion → POST /api/combo-suggestions/:id/accept creates a creative_act_report entry (suggestion realizes into Report)

Exception flows

IssueOccurrence	FallbackStep
Not enough candidate MaterialArtifacts	Write Suggestion ICE with empty list + explanation
Computation exceeds Worker CPU limit	Break into multiple queue messages

Queue contract

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

API endpoints

• POST /api/combo-suggestions/generate — enqueue ProcedureExecution
• GET /api/combo-suggestions — list Suggestion ICEs
• POST /api/combo-suggestions/:id/accept — promote Suggestion ICE to Creative Act Report

Acceptance criteria

• PASS: Suggestion ICEs produced with valid measurement_confidence; accepting creates corresponding creative_act_report row with correct Plan Specification Identifier convention
• FAIL: Duplicates; invalid artifact_identifiers; inability to accept due to missing fields