AI Agent Substantiation – 4+1 Architecture Document

1. Business Motivation View

Context

Marketing teams often produce creatives that include claims — statements about product performance, price, or features.
In both retail and pharma, such claims must be substantiated before use in market.

Retail Example: "50% off all skincare this week" requires historical pricing evidence.
Pharma Example: "Clinically proven to reduce migraine frequency by 30%" requires clinical trial documentation.

Currently, substantiation workflows are slow, manual, and error-prone, leading to compliance risks and launch delays.

Goals

Automate claim detection in creatives using AI Agents.
Anchor claims precisely within creative assets for review.
Enable a structured substantiation workflow using SubstantiationRequest and SubstantiationResponse as specialized comments.
Support BYOD (Bring Your Own Definition) forms for structured evidence collection.
Support citations to documents using a standard referencing model like BibTeX.

Business Benefits

Faster Time-to-Market — Reduce substantiation cycle times by automating claim detection and evidence collection.
Regulatory Compliance — Ensure all claims are backed by verifiable evidence before release.
Traceability & Auditability — Maintain a clear, anchored chain of requests, responses, and supporting documents.

2. Claim-Substantiation Bounded Context

class diagram and detailed definitions:

@startuml
title Substantiation Claim Domain Model (Retail + Pharma Extension)

' Base Claim classes
class Claim {
  + UUID id
  + claim_text: String
  + claim_type: String
  + asset_reference: String
  + detected_at: DateTime
}

class SubstantiationRequest {
  + UUID id
  + claim_id: UUID
  + required_evidence: String
  + created_by: String
  + created_at: DateTime
}

class SubstantiationResponse {
  + UUID id
  + request_id: UUID
  + form_data: JSONB
  + decision: String  // Approved, Rejected, NeedsRevision
  + reviewed_by: String
  + reviewed_at: DateTime
}

class Citation {
  + UUID id
  + response_id: UUID
  + bibtex_entry: Text
}

' Retail-specific augmentations
class RetailOfferDetail {
  + offer_id: UUID
  + product_list: List<String>
  + previous_price: Decimal
  + current_price: Decimal
  + saving_amount: Decimal
  + saving_percentage: Decimal
  + start_date: Date
  + end_date: Date
  + percentage_rules_info: String
  + online_availability: Boolean
  + minimum_spend: Decimal
  + delivery_terms: String
  + stock_confirmation: String
  + compliance_sign_off: String
}

' Pharma-specific augmentations
class PharmaStudyDetail {
  + study_id: UUID
  + study_type: String  // clinicalTrial, observationalStudy, metaAnalysis
  + endpoints: String
  + population: String
  + outcome: String
  + statistical_significance: String
  + publication_reference: String
  + regulatory_approval_status: String
}

' Relationships
Claim "1" -- "1" SubstantiationRequest
SubstantiationRequest "1" -- "0..1" SubstantiationResponse
SubstantiationResponse "0..*" -- "0..*" Citation
SubstantiationRequest "0..1" -- "0..1" RetailOfferDetail
SubstantiationRequest "0..1" -- "0..1" PharmaStudyDetail

@enduml

Domain Model Breakdown

Core Entities

Claim: Represents a detected claim in a creative asset—captures ID, text, type, asset reference, and detection timestamp.
SubstantiationRequest: Raised when a claim is detected; includes required evidence, who created it, and when.
SubstantiationResponse: Contains form data (structured evidence), reviewer decision, reviewer details, and timestamp.
Citation: Attached to responses, with BibTeX entries for traceability.

Retail Extension: RetailOfferDetail

Derived from the Clearcast form fields:

Offer breakdown (products, prior/current pricing, savings)
Offer validity window (start/end date)
"Percentage Rules" compliance (e.g., at least 10% of products meet the advertised saving)
Online availability, minimum spend, delivery terms
Stock confirmation and legal/compliance sign-offs

Pharma Extension: PharmaStudyDetail

Key fields to substantiate Pharma claims:

Study metadata: clinical trial specifics, endpoints, population
Outcome data: e.g., “30% reduction in migraine frequency”
Statistical significance
Publication/citation reference
Regulatory approval status (e.g., EMA, FDA)

Examples of Model Instantiations

Retail Example:
Claim: “50% off all skincare this week” → RetailOfferDetail might list: specific skincare items, old/new prices, 50% saving, offer dates, confirmation that minimum criteria (10% rule) are met, stock assurance, compliance signature.
Pharma Example:
Claim: “Clinically proven to reduce migraine frequency by 30%” → PharmaStudyDetail would capture: clinical trial ID, sample size, outcome, p‑value, public citation (e.g., DOI in BibTeX), regulatory sign‑off.

3. Logical View (Broader Domain Model)

@startuml

class Board {
  + UUID id
  + name: String
}

class Lane {
  + UUID id
  + name: String
}

class Card {
  + UUID id
  + title: String
  + description: String
}

class Specialism {
  + UUID id
  + type: String
}

class AnchorableEntity {
  + UUID id
  + anchor_type: String
  + location_reference: String
}

class Comment {
  + UUID id
  + text: String
  + type: String
}

class SubstantiationRequest {
  + claim_text: String
  + claim_type: String
  + required_evidence: String
}

class SubstantiationResponse {
  + form_data: JSONB
  + decision: String
}

class Citation {
  + UUID id
  + bibtex_entry: Text
}

Board "1" -- "many" Lane
Lane "1" -- "many" Card
Card "1" -- "many" Specialism
Specialism "1" -- "many" AnchorableEntity
AnchorableEntity "1" -- "many" Comment

Comment <|-- SubstantiationRequest
Comment <|-- SubstantiationResponse
SubstantiationResponse "0..*" -- "0..*" Citation : includes
@enduml

3. Process View (Workflow)

@startuml
start
:Creative Produced;
:AI detects claims;
if (Detected?) then (yes)
  :Classify + Anchor;
  :Create SubstantiationRequest;
  :Assign to Reviewer;
  :Reviewer completes BYOD + citations;
  :Create SubstantiationResponse;
  if (Evidence OK?) then (yes)
    :Approve Claim;
  else
    :Mark Needs Revision;
  endif
else
  :No action;
endif
stop
@enduml

4. Development View (Component Model)

@startuml
package "Frontend" {
  [Upload UI]
  [Review Dashboard]
  [Form Builder]
  [Citation Manager]
}

package "Backend Services" {
  [Claim Detector]
  [Anchor Service]
  [Substantiation Service]
  [Comment Service]
  [Citation Service]
}

package "Storage" {
  [Creative Store]
  [Metadata DB]
  [Evidence Library]
}

[Upload UI] --> [Claim Detector]
[Claim Detector] --> [Anchor Service]
[Anchor Service] --> [Metadata DB]
[Claim Detector] --> [Substantiation Service]
[Substantiation Service] --> [Comment Service]
[Comment Service] --> [Metadata DB]

[Review Dashboard] --> [Substantiation Service]
[Form Builder] --> [Substantiation Service]
[Citation Manager] --> [Citation Service]
[Citation Service] --> [Evidence Library]
@enduml

5. Physical View (Deployment Model)

@startuml
node "User Device" {
  [Browser UI]
}

node "Cloud Platform" {
  node "App Cluster" {
    [Frontend SPA]
    [Backend API]
    [AI Service]
    [Form Processor]
    [Citation Service]
  }

  node "Databases" {
    [Metadata DB]
    [Evidence DB]
    [Asset Store]
  }
}

[Browser UI] --> [Frontend SPA]
[Frontend SPA] --> [Backend API]
[Backend API] --> [AI Service]
[Backend API] --> [Form Processor]
[Backend API] --> [Citation Service]
[Backend API] --> [Metadata DB]
[Citation Service] --> [Evidence DB]
[Backend API] --> [Asset Store]
@enduml

6. Scenarios (Use Cases)

Scenario 1 – Retail

Banner "50% off all skincare" uploaded.
AI classifies it as price claim.
Anchors text.
Creates SubstantiationRequest needing price logs.
Reviewer attaches data, marks approved.
Response logged with BibTeX.

Scenario 2 – Pharma

Video with "clinically proven..." uploaded.
AI anchors via timestamp.
SubstantiationRequest created needing trial proof.
Reviewer fills BYOD form, attaches journal articles.
SubstantiationResponse marked approved.

Architecture Style: Hexagonal (Ports & Adapters)

Core Domain

Implemented in Python using Pydantic.
Includes domain entities: Comment, SubstantiationRequest, SubstantiationResponse, Citation, AnchorableEntity.
Encapsulates business logic.

Ports

Driving Ports: for_claim_detection, for_reviewing_requests, for_submitting_responses
Driven Ports: for_storing_metadata, for_attaching_citations, for_anchoring_creatives

Adapters

Driving Adapters: UI components, API clients.
Driven Adapters: PostgreSQL adapter, S3 asset handler, BibTeX citation manager.

# Example Pydantic Domain Model
from pydantic import BaseModel
from typing import List, Optional

class Citation(BaseModel):
    id: str
    bibtex_entry: str

class SubstantiationResponse(BaseModel):
    id: str
    form_data: dict
    decision: str
    citations: Optional[List[Citation]] = []