open-pharma-plugins 2.2.0__py3-none-any.whl

open_pharma_plugins_campaign_studio/_claim_engine.py

@@ -0,0 +1,262 @@
+"""Claim validation engine — fuzzy matching, fair balance, and policy checks."""
+
+from __future__ import annotations
+
+import json
+import re
+from importlib.resources import files
+from pathlib import Path
+
+
+def load_policy_rules(jurisdiction: str) -> dict:
+    """Load jurisdiction-specific policy rules from rules.json."""
+    rules_path = Path(str(files("open_pharma_plugins_campaign_studio") / "policy" / "rules.json"))
+    all_rules = json.loads(rules_path.read_text())
+    return all_rules.get(jurisdiction, all_rules.get("FDA", {}))
+
+
+def fuzzy_match(statement: str, approved_claims: list[dict]) -> dict:
+    """Match a statement against approved claims using token overlap.
+
+    Returns the best match with similarity score, or a not_found result.
+    """
+    statement_tokens = _tokenize(statement)
+    if not statement_tokens:
+        return {
+            "claim_id": None,
+            "status": "not_found",
+            "matched_claim_text": None,
+            "similarity_score": 0.0,
+            "deviation": "Empty statement",
+        }
+
+    best_score = 0.0
+    best_claim: dict | None = None
+
+    for claim in approved_claims:
+        claim_tokens = _tokenize(claim.get("text", ""))
+        if not claim_tokens:
+            continue
+
+        intersection = statement_tokens & claim_tokens
+        union = statement_tokens | claim_tokens
+        score = len(intersection) / len(union) if union else 0.0
+
+        if score > best_score:
+            best_score = score
+            best_claim = claim
+
+    if best_score >= 0.6:
+        deviation = None
+        if best_score < 1.0 and best_claim:
+            claim_tokens = _tokenize(best_claim["text"])
+            missing = claim_tokens - statement_tokens
+            extra = statement_tokens - claim_tokens
+            parts = []
+            if missing:
+                parts.append(f"missing terms: {', '.join(sorted(missing)[:5])}")
+            if extra:
+                parts.append(f"extra terms: {', '.join(sorted(extra)[:5])}")
+            deviation = "; ".join(parts) if parts else None
+
+        return {
+            "claim_id": best_claim["claim_id"] if best_claim else None,
+            "status": "approved" if best_score >= 0.8 else "needs_review",
+            "matched_claim_text": best_claim["text"] if best_claim else None,
+            "similarity_score": round(best_score, 3),
+            "deviation": deviation,
+        }
+
+    return {
+        "claim_id": best_claim["claim_id"] if best_claim else None,
+        "status": "not_found",
+        "matched_claim_text": best_claim["text"] if best_claim else None,
+        "similarity_score": round(best_score, 3),
+        "deviation": "No close match found in approved claims",
+    }
+
+
+def check_fair_balance(copy_blocks: list[dict], approved_claims: list[dict], min_ratio: float) -> dict:
+    """Check that safety content accompanies efficacy claims.
+
+    Returns a policy check result with the efficacy-to-safety ratio.
+    """
+    claim_id_to_category = {c["claim_id"]: c.get("category", "").lower() for c in approved_claims}
+
+    efficacy_count = 0
+    safety_count = 0
+
+    for block in copy_blocks:
+        for cid in block.get("claim_ids", []):
+            cat = claim_id_to_category.get(cid, "")
+            if cat in ("efficacy", "positioning", "moa"):
+                efficacy_count += 1
+            elif cat in ("safety", "tolerability"):
+                safety_count += 1
+
+    total = efficacy_count + safety_count
+    if total == 0:
+        return {
+            "check_name": "fair_balance",
+            "result": "pass",
+            "detail": "No efficacy or safety claims found in copy.",
+        }
+
+    safety_ratio = safety_count / total if total > 0 else 0.0
+
+    if safety_ratio >= min_ratio:
+        return {
+            "check_name": "fair_balance",
+            "result": "pass",
+            "detail": (
+                f"Safety ratio: {safety_ratio:.0%} "
+                f"({safety_count} safety / {total} total). "
+                f"Meets minimum {min_ratio:.0%}."
+            ),
+        }
+
+    return {
+        "check_name": "fair_balance",
+        "result": "fail",
+        "detail": (
+            f"Safety ratio: {safety_ratio:.0%} "
+            f"({safety_count} safety / {total} total). "
+            f"Below minimum {min_ratio:.0%}. "
+            "Add more safety/tolerability content."
+        ),
+    }
+
+
+def check_prohibited_language(text: str, patterns: list[dict]) -> list[dict]:
+    """Check text against prohibited language patterns."""
+    violations: list[dict] = []
+    for rule in patterns:
+        if re.search(rule["pattern"], text, re.IGNORECASE):
+            violations.append(
+                {
+                    "check_name": "prohibited_language",
+                    "result": "fail",
+                    "detail": f'{rule["reason"]}. Found in: "{_excerpt(text, rule["pattern"])}"',
+                }
+            )
+    return violations
+
+
+def check_required_elements(all_text: str, legal_data: dict, required: list[str]) -> list[dict]:
+    """Check that required legal elements are present in the copy."""
+    results: list[dict] = []
+    for element in required:
+        element_text = legal_data.get(element, "")
+        if not element_text:
+            results.append(
+                {
+                    "check_name": f"required_{element}",
+                    "result": "fail",
+                    "detail": f"Required element '{element}' not found in brand kit legal content.",
+                }
+            )
+            continue
+
+        keywords = _tokenize(element_text)
+        text_tokens = _tokenize(all_text)
+        overlap = len(keywords & text_tokens) / len(keywords) if keywords else 0
+
+        if overlap >= 0.3:
+            results.append(
+                {
+                    "check_name": f"required_{element}",
+                    "result": "pass",
+                    "detail": f"Required element '{element}' found in copy.",
+                }
+            )
+        else:
+            results.append(
+                {
+                    "check_name": f"required_{element}",
+                    "result": "fail",
+                    "detail": f"Required element '{element}' not found in copy. This must be included per {element} regulations.",
+                }
+            )
+
+    return results
+
+
+def is_claim_citation_exempt(block_name: str, text: str, brief: dict, legal_data: dict) -> bool:
+    """Only the configured CTA and verbatim approved legal text may be uncited."""
+    normalized = _normalize(text)
+    if not normalized:
+        return True
+    if block_name == "cta" and normalized == _normalize(brief.get("call_to_action", "")):
+        return True
+    approved_legal = {
+        _normalize(value)
+        for key, value in legal_data.items()
+        if key != "jurisdictions" and isinstance(value, str) and value.strip()
+    }
+    return normalized in approved_legal
+
+
+def _normalize(text: str) -> str:
+    return " ".join(str(text).split()).casefold()
+
+
+def _tokenize(text: str) -> set[str]:
+    """Lowercase tokenization with stop-word removal."""
+    stop_words = {
+        "a",
+        "an",
+        "the",
+        "and",
+        "or",
+        "but",
+        "in",
+        "on",
+        "at",
+        "to",
+        "for",
+        "of",
+        "with",
+        "by",
+        "from",
+        "is",
+        "was",
+        "were",
+        "are",
+        "been",
+        "be",
+        "have",
+        "has",
+        "had",
+        "do",
+        "does",
+        "did",
+        "will",
+        "would",
+        "could",
+        "should",
+        "may",
+        "might",
+        "can",
+        "shall",
+        "that",
+        "this",
+        "these",
+        "those",
+        "it",
+        "its",
+        "as",
+        "not",
+        "no",
+    }
+    tokens = set(re.findall(r"\b[a-z0-9][a-z0-9.%<>=-]*\b", text.lower()))
+    return tokens - stop_words
+
+
+def _excerpt(text: str, pattern: str) -> str:
+    """Extract a short excerpt around the first match."""
+    m = re.search(pattern, text, re.IGNORECASE)
+    if not m:
+        return ""
+    start = max(0, m.start() - 20)
+    end = min(len(text), m.end() + 20)
+    return text[start:end].strip()

open_pharma_plugins_campaign_studio/_renderer.py

@@ -0,0 +1,119 @@
+"""Shared rendering utilities — template loading, brand tokens, validation gate."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from importlib.resources import files
+from pathlib import Path
+
+
+def validation_input_fingerprint(campaign_brief_id: str, channels: list[str]) -> str:
+    """Bind a validation decision to the exact brief, claims, and copy inputs."""
+    from ._campaign_store import load_artifact, load_brief
+
+    ordered_channels = sorted(set(channels))
+    payload = {
+        "brief": load_brief(campaign_brief_id),
+        "approved_claims": load_artifact(campaign_brief_id, "approved-claims.json"),
+        "copies": {channel: load_artifact(campaign_brief_id, f"copy-{channel}.json") for channel in ordered_channels},
+    }
+    canonical = json.dumps(payload, sort_keys=True, separators=(",", ":"), ensure_ascii=False, default=str)
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+def check_validation_gate(campaign_brief_id: str, channel: str | None = None) -> str | None:
+    """Return an error message if validation hasn't passed, else None."""
+    from ._campaign_store import load_brief, load_validation_artifact
+
+    report = load_validation_artifact(campaign_brief_id, "policy-checks.json")
+    if not report:
+        return "No validation report found. Run validate_claims_and_fair_balance before rendering."
+    if not report.get("overall_pass"):
+        failures = [c for c in report.get("policy_checks", []) if c.get("result") == "fail"]
+        fail_names = [f.get("check_name", "unknown") for f in failures]
+        return (
+            f"Validation failed ({len(failures)} failures: "
+            f"{', '.join(fail_names)}). Fix and re-validate before rendering."
+        )
+    validated_channels = report.get("channels_validated", [])
+    if channel and channel not in validated_channels:
+        return f"Channel '{channel}' was not included in the passing validation report. Re-validate before rendering."
+    if channel is None:
+        brief_channels = (load_brief(campaign_brief_id) or {}).get("channels", [])
+        if set(validated_channels) != set(brief_channels):
+            return "The passing validation report does not cover every campaign channel. Re-validate before packaging."
+    stored_fingerprint = report.get("input_fingerprint")
+    current_fingerprint = validation_input_fingerprint(campaign_brief_id, validated_channels)
+    if not stored_fingerprint or not hmac.compare_digest(stored_fingerprint, current_fingerprint):
+        return "Campaign inputs changed after validation. Re-run validation before rendering or packaging."
+    return None
+
+
+def load_template(name: str) -> str:
+    """Load a Jinja2 template from the templates directory."""
+    tpl_path = Path(str(files("open_pharma_plugins_campaign_studio") / "templates" / name))
+    return tpl_path.read_text()
+
+
+def load_brand_kit(campaign_brief_id: str) -> dict:
+    """Load full brand kit (palette, typography, legal, paths)."""
+    from ._campaign_store import load_brief
+
+    brief = load_brief(campaign_brief_id)
+    kit_path = None
+    if brief:
+        kit_path = brief.get("brand_kit_path")
+
+    if kit_path and Path(kit_path).is_dir():
+        kit_dir = Path(kit_path)
+    else:
+        kit_dir = Path(str(files("open_pharma_plugins_campaign_studio") / "fixtures" / "brand_kit"))
+
+    return {
+        "palette": _load_json(kit_dir / "palette.json"),
+        "typography": _load_json(kit_dir / "typography.json"),
+        "legal": _load_json(kit_dir / "legal.json"),
+        "logo_path": str(kit_dir / "logo.svg"),
+        "product_image_path": str(kit_dir / "product.png"),
+    }
+
+
+def extract_copy_text(copy_data: dict, channel: str) -> dict:
+    """Extract text fields from channel copy into a flat dict for templates."""
+    result: dict = {}
+
+    if channel == "email":
+        result["subject"] = _block_text(copy_data.get("subject"))
+        result["preheader"] = _block_text(copy_data.get("preheader"))
+        result["headline"] = _block_text(copy_data.get("headline"))
+        result["cta"] = _block_text(copy_data.get("cta"))
+        result["body_paragraphs"] = [_block_text(b) for b in copy_data.get("body", [])]
+    elif channel == "banner":
+        result["headline"] = _block_text(copy_data.get("headline"))
+        result["sub_headline"] = _block_text(copy_data.get("sub_headline"))
+        result["cta"] = _block_text(copy_data.get("cta"))
+    elif channel == "poster":
+        result["headline"] = _block_text(copy_data.get("headline"))
+        result["subhead"] = _block_text(copy_data.get("subhead"))
+        result["cta"] = _block_text(copy_data.get("cta"))
+        result["body_paragraphs"] = [_block_text(b) for b in copy_data.get("body", [])]
+        result["bullet_points"] = [_block_text(b) for b in (copy_data.get("bullet_points") or [])]
+        result["footnotes"] = copy_data.get("footnotes") or []
+
+    return result
+
+
+def _block_text(block: dict | None) -> str:
+    if not block:
+        return ""
+    if isinstance(block, dict):
+        return block.get("text", "")
+    return str(block)
+
+
+def _load_json(path: Path) -> dict:
+    if path.exists():
+        return json.loads(path.read_text())
+    return {}

open_pharma_plugins_campaign_studio/fixtures/brand_kit/legal.json

@@ -0,0 +1,21 @@
+{
+  "isi": "IMPORTANT SAFETY INFORMATION: ONCORIX can cause immune-mediated adverse reactions including pneumonitis, colitis, hepatitis, endocrinopathies, and nephritis. Monitor patients for signs and symptoms. Withhold or permanently discontinue ONCORIX based on severity. See full Prescribing Information for complete boxed warning and additional important safety information.",
+  "pi_ref": "Please see full Prescribing Information, including Boxed WARNING, at www.oncorix-hcp.example.com/pi",
+  "copyright": "© 2026 Example Pharma Inc. All rights reserved.",
+  "reporting_statement": "You are encouraged to report adverse events. Contact Example Pharma at 1-800-XXX-XXXX or FDA at 1-800-FDA-1088 or www.fda.gov/medwatch.",
+  "disclaimer": "ONCORIX is a registered trademark of Example Pharma Inc.",
+  "jurisdictions": {
+    "FDA": {
+      "required_elements": ["isi", "pi_ref", "reporting_statement"],
+      "fair_balance_required": true
+    },
+    "EMA": {
+      "required_elements": ["pi_ref", "reporting_statement"],
+      "fair_balance_required": true
+    },
+    "MHRA": {
+      "required_elements": ["pi_ref", "reporting_statement"],
+      "fair_balance_required": true
+    }
+  }
+}

open_pharma_plugins_campaign_studio/fixtures/brand_kit/logo.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 50" width="200" height="50">
+  <rect width="200" height="50" rx="4" fill="#003B5C"/>
+  <text x="100" y="33" text-anchor="middle" font-family="Arial, sans-serif" font-size="24" font-weight="bold" fill="#FFFFFF">ONCORIX</text>
+</svg>

open_pharma_plugins_campaign_studio/fixtures/brand_kit/palette.json

@@ -0,0 +1,11 @@
+{
+  "primary": "#003B5C",
+  "secondary": "#00A3E0",
+  "accent": "#E8792F",
+  "text": "#1A202C",
+  "text_light": "#FFFFFF",
+  "background": "#FFFFFF",
+  "background_alt": "#F7FAFC",
+  "safety_highlight": "#E53E3E",
+  "success": "#38A169"
+}

open_pharma_plugins_campaign_studio/fixtures/brand_kit/product.png

@@ -0,0 +1 @@
+placeholder — replace with actual product image

open_pharma_plugins_campaign_studio/fixtures/brand_kit/typography.json

@@ -0,0 +1,14 @@
+{
+  "heading_family": "Arial, Helvetica, sans-serif",
+  "body_family": "Arial, Helvetica, sans-serif",
+  "heading_weight": "bold",
+  "body_weight": "normal",
+  "sizes": {
+    "h1": "28px",
+    "h2": "22px",
+    "h3": "18px",
+    "body": "14px",
+    "small": "11px",
+    "legal": "9px"
+  }
+}

open_pharma_plugins_campaign_studio/fixtures/sample_approved_claims.json

@@ -0,0 +1,119 @@
+[
+  {
+    "claim_id": "c-001",
+    "text": "ONCORIX demonstrated a median overall survival of 24.1 months versus 13.6 months with standard of care (HR 0.68; 95% CI 0.55-0.84; p<0.001).",
+    "category": "efficacy",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 1 (Primary Endpoint)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-002",
+    "text": "Overall response rate was 42.3% with ONCORIX versus 16.2% with control (p<0.001).",
+    "category": "efficacy",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 2 (Secondary Endpoints)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-003",
+    "text": "Median progression-free survival was 11.2 months with ONCORIX versus 5.8 months with control (HR 0.58; 95% CI 0.47-0.72; p<0.001).",
+    "category": "efficacy",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 2 (Secondary Endpoints)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-004",
+    "text": "Among responders, 68% maintained response at 12 months.",
+    "category": "efficacy",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Figure 3 (Duration of Response)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-005",
+    "text": "Consistent overall survival benefit was observed across pre-specified subgroups including PD-L1 status, BRAF mutation status, and prior lines of therapy.",
+    "category": "efficacy",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Figure 4 (Forest Plot)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-006",
+    "text": "Treatment-related adverse events of any grade occurred in 72.4% of patients receiving ONCORIX versus 64.8% with control.",
+    "category": "safety",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 3 (Safety Summary)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-007",
+    "text": "The most common adverse events (>=15%) with ONCORIX were fatigue (28.1%), rash (19.4%), and diarrhoea (16.7%).",
+    "category": "safety",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 3 (Safety Summary)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-008",
+    "text": "Immune-mediated adverse events occurred in 18.3% of patients, most commonly thyroid disorders (6.2%) and hepatitis (3.1%).",
+    "category": "safety",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 4 (Immune-Mediated AEs)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-009",
+    "text": "Grade 3-4 treatment-related adverse events occurred in 18.2% of ONCORIX patients versus 12.1% with control.",
+    "category": "safety",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 3 (Safety Summary)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-010",
+    "text": "Treatment discontinuation due to adverse events occurred in 8.4% of patients receiving ONCORIX.",
+    "category": "safety",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "MERIDIAN-301, Table 3 (Safety Summary)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-011",
+    "text": "ONCORIX (rivolumab) is a humanised monoclonal antibody that selectively blocks the interaction between PD-1 and its ligands PD-L1 and PD-L2, restoring T-cell-mediated anti-tumour immunity.",
+    "category": "MOA",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "SmPC Section 5.1 (Mechanism of Action)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-012",
+    "text": "The recommended dose of ONCORIX is 240 mg administered as an intravenous infusion over 30 minutes every 2 weeks.",
+    "category": "dosing",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "SmPC Section 4.2 (Posology)",
+    "expiry": null,
+    "restrictions": null
+  },
+  {
+    "claim_id": "c-013",
+    "text": "Treatment with ONCORIX should be continued until disease progression or unacceptable toxicity, for a maximum of 24 months.",
+    "category": "dosing",
+    "source_document": "ONCORIX Approved Product Messages 2026",
+    "source_reference": "SmPC Section 4.2 (Posology)",
+    "expiry": null,
+    "restrictions": null
+  }
+]

open_pharma_plugins_campaign_studio/models/__init__.py

@@ -0,0 +1,34 @@
+"""Campaign-studio models — re-exports for convenient imports."""
+
+from ._common import SourceReference
+from .brief import CampaignBrief
+from .claims import ApprovedClaim
+from .copy import BannerCopy, ChannelCopy, CopyBlock, EmailCopy, PosterCopy
+from .journey import AudienceJourney, JourneyStage
+from .message import MessageArchitecture, MessageTier
+from .mlr import MlrPackage, RenderedAsset
+from .validation import (
+    ClaimValidationReport,
+    ClaimValidationResult,
+    PolicyCheck,
+)
+
+__all__ = [
+    "ApprovedClaim",
+    "AudienceJourney",
+    "BannerCopy",
+    "CampaignBrief",
+    "ChannelCopy",
+    "ClaimValidationReport",
+    "ClaimValidationResult",
+    "CopyBlock",
+    "EmailCopy",
+    "JourneyStage",
+    "MessageArchitecture",
+    "MessageTier",
+    "MlrPackage",
+    "PolicyCheck",
+    "PosterCopy",
+    "RenderedAsset",
+    "SourceReference",
+]

open_pharma_plugins_campaign_studio/models/_common.py

@@ -0,0 +1,12 @@
+"""Shared types used across campaign-studio models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class SourceReference(BaseModel):
+    document_id: str = Field(description="Identifier of the approved source document")
+    document_name: str = Field(description="Original filename")
+    page_number: int | None = Field(default=None, description="1-indexed page or slide number, if applicable")
+    excerpt: str = Field(description="Verbatim passage from the source")

open_pharma_plugins_campaign_studio/models/brief.py

@@ -0,0 +1,72 @@
+"""Campaign brief models."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class CampaignBrief(BaseModel):
+    campaign_brief_id: str = Field(description="Unique reusable identifier")
+    campaign_name: str = Field(description="Short campaign name")
+
+    # Jurisdiction & mode
+    country: str = Field(description="ISO 3166-1 alpha-2 country code")
+    policy_jurisdiction: str = Field(description="Regulatory jurisdiction: FDA | EMA | MHRA | HSA | PMDA | TGA")
+    mode: str = Field(description="promotional | non_promotional | disease_awareness")
+
+    # Product
+    brand: str = Field(description="Brand name")
+    indication: str = Field(description="Approved indication")
+    lifecycle_stage: str = Field(
+        default="growth",
+        description="pre_launch | launch | growth | mature | LOE",
+    )
+
+    # Audience & objectives
+    target_segment: str = Field(description="e.g. oncologists, PCPs, nurses, patients")
+    behavioral_objective: str = Field(description="What the audience should DO after exposure")
+    educational_objective: str | None = Field(default=None)
+    desired_kpi: list[str] = Field(description="e.g. ['open_rate>25%', 'HCP_reach_500']")
+
+    # Content sources
+    approved_claims_path: str | None = Field(
+        default=None,
+        description="Path to claims JSON or PDF",
+    )
+    call_to_action: str = Field(description="Primary CTA text")
+
+    # Channels
+    channels: list[str] = Field(description="['email', 'banner', 'poster']")
+    asset_dimensions: dict | None = Field(
+        default=None,
+        description='{"banner": "728x90", "poster": "A4"}',
+    )
+
+    # Brand
+    brand_kit_path: str | None = Field(
+        default=None,
+        description="Path to brand kit directory; uses fixture if omitted",
+    )
+
+    # Localisation
+    language: str = Field(default="en")
+    localisation_notes: str | None = Field(default=None)
+
+    # Compliance
+    required_safety_content: list[str] = Field(
+        default_factory=list,
+        description="ISI, boxed warning, PI reference",
+    )
+    required_legal_content: list[str] = Field(
+        default_factory=list,
+        description="Copyright, disclaimer, reporting statement",
+    )
+
+    # Delivery
+    delivery_constraints: str | None = Field(default=None)
+    approval_workflow: str = Field(
+        default="mlr_standard",
+        description="mlr_standard | mlr_expedited | medical_only",
+    )
+
+    generated_at: str = Field(description="ISO 8601 timestamp")