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

open_pharma_plugins_campaign_studio/tools/generate_audience_journey.py

@@ -0,0 +1,129 @@
+"""generate_audience_journey — validate and persist an audience journey."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class JourneyStageInput(BaseModel):
+    stage: str = Field(description="unaware | aware | interested | convinced | acting | advocating")
+    objective: str = Field(description="What should happen at this stage")
+    key_messages: list[str] = Field(description="claim_id references")
+    channels: list[str] = Field(description="Channels serving this stage")
+    content_type: str = Field(description="educational | promotional | reminder")
+    kpi: str = Field(description="Measurable outcome for this stage")
+
+
+class GenerateAudienceJourneyArgs(BaseModel):
+    campaign_brief_id: str = Field(description="Links to the campaign brief")
+    journey: list[JourneyStageInput] = Field(description="Ordered list of journey stages")
+
+
+TOOL: dict[str, Any] = {
+    "name": "generate_audience_journey",
+    "description": (
+        "Validate and persist an audience journey for a campaign. Checks that "
+        "every channel referenced exists in the brief's channel list, and "
+        "every claim_id in key_messages exists in the approved claims set. "
+        "The agent generates the journey content; this tool validates and saves."
+    ),
+    "args": GenerateAudienceJourneyArgs,
+}
+
+_VALID_STAGES = {
+    "unaware",
+    "aware",
+    "interested",
+    "convinced",
+    "acting",
+    "advocating",
+}
+_VALID_CONTENT_TYPES = {"educational", "promotional", "reminder"}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    from .._campaign_store import load_artifact, load_brief, save_artifact
+
+    campaign_brief_id = arguments["campaign_brief_id"]
+    stages = arguments["journey"]
+
+    brief = load_brief(campaign_brief_id)
+    if not brief:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(
+                    {"error": f"Campaign brief '{campaign_brief_id}' not found. Run create_campaign_brief first."}
+                ),
+            }
+        ]
+
+    claims_data = load_artifact(campaign_brief_id, "approved-claims.json")
+    valid_claim_ids: set[str] = set()
+    if claims_data and isinstance(claims_data, list):
+        valid_claim_ids = {c["claim_id"] for c in claims_data if "claim_id" in c}
+
+    brief_channels = set(brief.get("channels", []))
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    for i, stage in enumerate(stages):
+        s = stage if isinstance(stage, dict) else stage
+        stage_name = s.get("stage", "")
+        if stage_name not in _VALID_STAGES:
+            errors.append(
+                f"Stage {i + 1}: invalid stage '{stage_name}'. Must be one of: {', '.join(sorted(_VALID_STAGES))}"
+            )
+
+        content_type = s.get("content_type", "")
+        if content_type not in _VALID_CONTENT_TYPES:
+            errors.append(
+                f"Stage {i + 1}: invalid content_type '{content_type}'. "
+                f"Must be one of: {', '.join(sorted(_VALID_CONTENT_TYPES))}"
+            )
+
+        invalid_channels = set(s.get("channels", [])) - brief_channels
+        if invalid_channels:
+            errors.append(
+                f"Stage {i + 1}: channels {sorted(invalid_channels)} not in brief. Available: {sorted(brief_channels)}"
+            )
+
+        if valid_claim_ids:
+            unknown_claims = set(s.get("key_messages", [])) - valid_claim_ids
+            if unknown_claims:
+                errors.append(f"Stage {i + 1}: claim_ids {sorted(unknown_claims)} not found in approved claims.")
+        elif s.get("key_messages"):
+            warnings.append(
+                f"Stage {i + 1}: cannot validate claim_ids — no approved-claims.json found. "
+                "Run retrieve_approved_claims first."
+            )
+
+    if errors:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"errors": errors, "warnings": warnings}),
+            }
+        ]
+
+    journey = {
+        "campaign_brief_id": campaign_brief_id,
+        "target_segment": brief.get("target_segment", ""),
+        "stages": stages if isinstance(stages[0], dict) else [s for s in stages],
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    save_artifact(campaign_brief_id, "audience-journey.json", journey)
+
+    result = {
+        "campaign_brief_id": campaign_brief_id,
+        "total_stages": len(stages),
+        "stages": [s.get("stage", "") if isinstance(s, dict) else s for s in stages],
+        "warnings": warnings,
+    }
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]

open_pharma_plugins_campaign_studio/tools/generate_channel_copy.py

@@ -0,0 +1,199 @@
+"""generate_channel_copy — validate and persist structured copy for a channel."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class GenerateChannelCopyArgs(BaseModel):
+    campaign_brief_id: str = Field(description="Links to the campaign brief")
+    channel: str = Field(description="email | banner | poster")
+    copy_json: str = Field(
+        description=(
+            "JSON string of the channel-specific copy. For email: "
+            '{"subject": {"text": "...", "claim_ids": []}, "preheader": {...}, '
+            '"headline": {...}, "body": [{...}], "cta": {...}}. '
+            "For banner: {headline, sub_headline?, cta}. "
+            "For poster: {headline, subhead?, body, bullet_points?, cta, footnotes?}."
+        )
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "generate_channel_copy",
+    "description": (
+        "Validate and persist structured copy for a specific channel. Accepts "
+        "a JSON string with channel-specific copy blocks (EmailCopy, BannerCopy, "
+        "or PosterCopy). Validates that claim_ids exist in the approved claims "
+        "set, enforces character limits per channel, and checks the CTA matches "
+        "the brief. The agent generates the copy; this tool validates and saves."
+    ),
+    "args": GenerateChannelCopyArgs,
+}
+
+_VALID_CHANNELS = {"email", "banner", "poster"}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    from .._campaign_store import load_artifact, load_brief, save_artifact
+
+    campaign_brief_id = arguments["campaign_brief_id"]
+    channel = arguments["channel"]
+    copy_json_str = arguments["copy_json"]
+
+    if channel not in _VALID_CHANNELS:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(
+                    {"error": f"Invalid channel '{channel}'. Must be one of: {', '.join(sorted(_VALID_CHANNELS))}"}
+                ),
+            }
+        ]
+
+    brief = load_brief(campaign_brief_id)
+    if not brief:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"error": f"Campaign brief '{campaign_brief_id}' not found."}),
+            }
+        ]
+
+    if channel not in brief.get("channels", []):
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(
+                    {"error": f"Channel '{channel}' not in brief's channels: {brief.get('channels', [])}"}
+                ),
+            }
+        ]
+
+    try:
+        copy_data = json.loads(copy_json_str)
+    except json.JSONDecodeError as e:
+        return [{"type": "text", "text": json.dumps({"error": f"Invalid JSON: {e}"})}]
+
+    from pydantic import ValidationError
+
+    from ..models.copy import BannerCopy, EmailCopy, PosterCopy
+
+    copy_models = {"email": EmailCopy, "banner": BannerCopy, "poster": PosterCopy}
+    try:
+        copy_data = copy_models[channel].model_validate(copy_data).model_dump(mode="json", exclude_none=True)
+    except ValidationError as exc:
+        return [{"type": "text", "text": json.dumps({"errors": [f"Invalid {channel} copy: {exc}"]})}]
+
+    claims_data = load_artifact(campaign_brief_id, "approved-claims.json")
+    valid_claim_ids: set[str] = set()
+    if claims_data and isinstance(claims_data, list):
+        valid_claim_ids = {c["claim_id"] for c in claims_data if "claim_id" in c}
+
+    errors: list[str] = []
+    warnings: list[str] = []
+
+    all_blocks = _extract_copy_blocks(copy_data, channel)
+
+    from .._claim_engine import is_claim_citation_exempt
+    from .._renderer import load_brand_kit
+
+    legal = load_brand_kit(campaign_brief_id).get("legal", {})
+    promotional = brief.get("mode") == "promotional"
+    for block_name, block in all_blocks:
+        text = block.get("text", "").strip()
+        claim_ids = block.get("claim_ids", [])
+        unknown = set(claim_ids) - valid_claim_ids
+        if unknown:
+            errors.append(f"{block_name}: claim_ids {sorted(unknown)} not found in approved claims.")
+        if promotional and text and not claim_ids and not is_claim_citation_exempt(block_name, text, brief, legal):
+            errors.append(f"{block_name}: promotional copy must cite at least one approved claim ID.")
+
+    if any(block.get("claim_ids") for _, block in all_blocks) and not claims_data:
+        errors.append("Cannot validate claim_ids — run retrieve_approved_claims first.")
+
+    cta = copy_data.get("cta", {}).get("text", "")
+    if cta.strip().casefold() != brief.get("call_to_action", "").strip().casefold():
+        errors.append("cta: text must exactly match the campaign brief call_to_action.")
+
+    for index, footnote in enumerate(copy_data.get("footnotes", [])):
+        if promotional and footnote.strip() and not is_claim_citation_exempt("footnote", footnote, brief, legal):
+            errors.append(f"footnotes[{index}]: promotional footnotes must be verbatim approved legal text.")
+
+    if channel == "banner":
+        headline = copy_data.get("headline", {})
+        headline_text = headline.get("text", "")
+        word_count = len(headline_text.split())
+        if word_count > 8:
+            warnings.append(f"Banner headline has {word_count} words (recommended max: 8).")
+
+        cta = copy_data.get("cta", {})
+        cta_text = cta.get("text", "")
+        cta_words = len(cta_text.split())
+        if cta_words > 3:
+            warnings.append(f"Banner CTA has {cta_words} words (recommended max: 3).")
+
+    if errors:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"errors": errors, "warnings": warnings}),
+            }
+        ]
+
+    artifact = {
+        "campaign_brief_id": campaign_brief_id,
+        "channel": channel,
+        "copy": copy_data,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    save_artifact(campaign_brief_id, f"copy-{channel}.json", artifact)
+
+    result = {
+        "campaign_brief_id": campaign_brief_id,
+        "channel": channel,
+        "total_blocks": len(all_blocks),
+        "warnings": warnings,
+    }
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]
+
+
+def _extract_copy_blocks(copy_data: dict, channel: str) -> list[tuple[str, dict]]:
+    """Extract named copy blocks from channel-specific copy data."""
+    blocks: list[tuple[str, dict]] = []
+
+    simple_fields = {
+        "email": [
+            "subject",
+            "preheader",
+            "headline",
+            "cta",
+        ],
+        "banner": ["headline", "sub_headline", "cta"],
+        "poster": ["headline", "subhead", "cta"],
+    }
+
+    for field in simple_fields.get(channel, []):
+        val = copy_data.get(field)
+        if val and isinstance(val, dict):
+            blocks.append((field, val))
+
+    list_fields = {
+        "email": ["body"],
+        "poster": ["body", "bullet_points"],
+    }
+
+    for field in list_fields.get(channel, []):
+        items = copy_data.get(field)
+        if items and isinstance(items, list):
+            for i, item in enumerate(items):
+                if isinstance(item, dict):
+                    blocks.append((f"{field}[{i}]", item))
+
+    return blocks

open_pharma_plugins_campaign_studio/tools/generate_message_architecture.py

@@ -0,0 +1,121 @@
+"""generate_message_architecture — validate and persist a message hierarchy."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SourceReferenceInput(BaseModel):
+    document_id: str = Field(description="Source document identifier")
+    document_name: str = Field(description="Original filename")
+    page_number: int | None = Field(default=None)
+    excerpt: str = Field(description="Verbatim passage from the source")
+
+
+class MessageTierInput(BaseModel):
+    tier: str = Field(description="primary | secondary | supporting")
+    message: str = Field(description="The message statement")
+    claim_ids: list[str] = Field(description="Approved claim IDs this message draws from")
+    audience_stage: str | None = Field(default=None, description="Links to a journey stage")
+    rationale: str = Field(description="Why this message matters for the objective")
+
+
+class GenerateMessageArchitectureArgs(BaseModel):
+    campaign_brief_id: str = Field(description="Links to the campaign brief")
+    messages: list[MessageTierInput] = Field(description="Tiered message hierarchy")
+    fair_balance_statement: str = Field(description="Required safety/risk language")
+    fair_balance_sources: list[SourceReferenceInput] = Field(description="Sources for the fair balance statement")
+
+
+TOOL: dict[str, Any] = {
+    "name": "generate_message_architecture",
+    "description": (
+        "Validate and persist a three-tier message architecture (primary, "
+        "secondary, supporting). Checks that claim_ids exist in the approved "
+        "claims set, at least one primary message is present, and fair balance "
+        "is included. The agent generates the messages; this tool validates and saves."
+    ),
+    "args": GenerateMessageArchitectureArgs,
+}
+
+_VALID_TIERS = {"primary", "secondary", "supporting"}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    from .._campaign_store import load_artifact, load_brief, save_artifact
+
+    campaign_brief_id = arguments["campaign_brief_id"]
+    messages = arguments["messages"]
+    fair_balance = arguments["fair_balance_statement"]
+    fair_balance_sources = arguments.get("fair_balance_sources", [])
+
+    brief = load_brief(campaign_brief_id)
+    if not brief:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps(
+                    {"error": f"Campaign brief '{campaign_brief_id}' not found. Run create_campaign_brief first."}
+                ),
+            }
+        ]
+
+    claims_data = load_artifact(campaign_brief_id, "approved-claims.json")
+    valid_claim_ids: set[str] = set()
+    if claims_data and isinstance(claims_data, list):
+        valid_claim_ids = {c["claim_id"] for c in claims_data if "claim_id" in c}
+
+    errors: list[str] = []
+
+    has_primary = False
+    for i, msg in enumerate(messages):
+        m = msg if isinstance(msg, dict) else msg
+        tier = m.get("tier", "")
+        if tier not in _VALID_TIERS:
+            errors.append(f"Message {i + 1}: invalid tier '{tier}'. Must be one of: {', '.join(sorted(_VALID_TIERS))}")
+        if tier == "primary":
+            has_primary = True
+
+        if valid_claim_ids:
+            unknown = set(m.get("claim_ids", [])) - valid_claim_ids
+            if unknown:
+                errors.append(f"Message {i + 1}: claim_ids {sorted(unknown)} not found in approved claims.")
+
+    if not has_primary:
+        errors.append("At least one message must have tier 'primary'.")
+
+    if not fair_balance.strip():
+        errors.append("fair_balance_statement is required.")
+
+    if errors:
+        return [{"type": "text", "text": json.dumps({"errors": errors})}]
+
+    architecture = {
+        "campaign_brief_id": campaign_brief_id,
+        "brand": brief.get("brand", ""),
+        "indication": brief.get("indication", ""),
+        "message_tiers": messages if isinstance(messages[0], dict) else [m for m in messages],
+        "fair_balance_statement": fair_balance,
+        "fair_balance_sources": fair_balance_sources if isinstance(fair_balance_sources, list) else [],
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    save_artifact(campaign_brief_id, "message-architecture.json", architecture)
+
+    tier_counts = {}
+    for m in messages:
+        t = m.get("tier", "") if isinstance(m, dict) else m
+        tier_counts[t] = tier_counts.get(t, 0) + 1
+
+    result = {
+        "campaign_brief_id": campaign_brief_id,
+        "total_messages": len(messages),
+        "tier_counts": tier_counts,
+        "fair_balance_included": True,
+    }
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]

open_pharma_plugins_campaign_studio/tools/package_mlr_submission.py

@@ -0,0 +1,230 @@
+"""package_mlr_submission — assemble the full MLR review package."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class PackageMlrSubmissionArgs(BaseModel):
+    campaign_brief_id: str = Field(description="Links to the campaign")
+    reviewer_notes: str | None = Field(
+        default=None,
+        description="Additional context for reviewers",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "package_mlr_submission",
+    "description": (
+        "Assemble the full MLR (Medical-Legal-Regulatory) review package for "
+        "a campaign. Collects all generated artifacts — brief, claims, journey, "
+        "message architecture, channel copies, validation reports, and rendered "
+        "assets — into the campaign directory and generates a human-readable "
+        "mlr-review-summary.md cover sheet. Requires that validation has passed."
+    ),
+    "args": PackageMlrSubmissionArgs,
+}
+
+
+def handle(arguments: dict[str, Any]) -> list[dict[str, Any]]:
+    import json
+    from datetime import datetime, timezone
+
+    from .._campaign_store import (
+        campaign_dir,
+        load_brief,
+        load_validation_artifact,
+        outputs_dir,
+        save_output,
+    )
+    from .._renderer import check_validation_gate
+
+    campaign_brief_id = arguments["campaign_brief_id"]
+    reviewer_notes = arguments.get("reviewer_notes")
+
+    gate_error = check_validation_gate(campaign_brief_id)
+    if gate_error:
+        return [{"type": "text", "text": json.dumps({"error": gate_error})}]
+
+    brief = load_brief(campaign_brief_id)
+    if not brief:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"error": f"Campaign brief '{campaign_brief_id}' not found."}),
+            }
+        ]
+
+    # Collect all artifacts
+    artifacts: dict[str, str] = {}
+    cdir = campaign_dir(campaign_brief_id)
+    odir = outputs_dir(campaign_brief_id)
+
+    artifact_files = [
+        "campaign-brief.json",
+        "approved-claims.json",
+        "audience-journey.json",
+        "message-architecture.json",
+    ]
+    for channel in brief.get("channels", []):
+        artifact_files.append(f"copy-{channel}.json")
+
+    for fname in artifact_files:
+        path = cdir / fname
+        if path.exists():
+            artifacts[fname] = "present"
+        else:
+            artifacts[fname] = "MISSING"
+
+    validation_files = [
+        "claim-map.json",
+        "policy-checks.json",
+        "source-evidence.json",
+    ]
+    vdir = cdir / "validation"
+    for fname in validation_files:
+        path = vdir / fname
+        if path.exists():
+            artifacts[f"validation/{fname}"] = "present"
+        else:
+            artifacts[f"validation/{fname}"] = "MISSING"
+
+    output_files = []
+    for channel in brief.get("channels", []):
+        ext_map = {"email": "html", "banner": "svg", "poster": "pdf"}
+        ext = ext_map.get(channel, "html")
+        fname = f"{channel}.{ext}"
+        path = odir / fname
+        if path.exists():
+            output_files.append(fname)
+            artifacts[f"outputs/{fname}"] = "present"
+        else:
+            artifacts[f"outputs/{fname}"] = "MISSING"
+
+    # Load validation report for summary
+    validation = load_validation_artifact(campaign_brief_id, "policy-checks.json")
+    source_evidence = load_validation_artifact(campaign_brief_id, "source-evidence.json")
+    claim_map = load_validation_artifact(campaign_brief_id, "claim-map.json")
+
+    # Generate MLR review summary markdown
+    md = _build_summary_md(
+        brief,
+        validation,
+        source_evidence,
+        claim_map,
+        output_files,
+        artifacts,
+        reviewer_notes,
+    )
+
+    summary_path = save_output(campaign_brief_id, "mlr-review-summary.md", md)
+
+    missing = [k for k, v in artifacts.items() if v == "MISSING"]
+
+    result = {
+        "campaign_brief_id": campaign_brief_id,
+        "package_directory": str(cdir),
+        "mlr_summary_path": str(summary_path),
+        "total_artifacts": len(artifacts),
+        "present": sum(1 for v in artifacts.values() if v == "present"),
+        "missing": missing,
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+    }
+    return [{"type": "text", "text": json.dumps(result, indent=2)}]
+
+
+def _build_summary_md(
+    brief: dict,
+    validation: dict | None,
+    source_evidence: list | None,
+    claim_map: dict | None,
+    output_files: list[str],
+    artifacts: dict[str, str],
+    reviewer_notes: str | None,
+) -> str:
+    lines: list[str] = []
+    lines.append(f"# MLR Review Summary — {brief.get('campaign_name', 'Campaign')}")
+    lines.append("")
+    lines.append(f"**Campaign ID:** {brief.get('campaign_brief_id', '')}")
+    lines.append(f"**Brand:** {brief.get('brand', '')}")
+    lines.append(f"**Indication:** {brief.get('indication', '')}")
+    lines.append(f"**Mode:** {brief.get('mode', '')}")
+    lines.append(f"**Jurisdiction:** {brief.get('policy_jurisdiction', '')}")
+    lines.append(f"**Target Segment:** {brief.get('target_segment', '')}")
+    lines.append(f"**Objective:** {brief.get('behavioral_objective', '')}")
+    lines.append(f"**Channels:** {', '.join(brief.get('channels', []))}")
+    lines.append(f"**Approval Workflow:** {brief.get('approval_workflow', '')}")
+    lines.append("")
+
+    # Claim-to-source traceability
+    lines.append("## Claim-to-Source Traceability")
+    lines.append("")
+    if claim_map:
+        lines.append("| Copy Statement | Claim IDs |")
+        lines.append("|---|---|")
+        for stmt, cids in claim_map.items():
+            lines.append(f"| {stmt} | {', '.join(cids)} |")
+    else:
+        lines.append("_No claim map available._")
+    lines.append("")
+
+    # Source evidence
+    lines.append("## Source Evidence")
+    lines.append("")
+    if source_evidence and isinstance(source_evidence, list):
+        lines.append("| Document | Reference |")
+        lines.append("|---|---|")
+        for src in source_evidence:
+            lines.append(f"| {src.get('document_name', '')} | {src.get('excerpt', '')} |")
+    else:
+        lines.append("_No source evidence available._")
+    lines.append("")
+
+    # Validation summary
+    lines.append("## Validation Summary")
+    lines.append("")
+    if validation:
+        overall = "PASS" if validation.get("overall_pass") else "FAIL"
+        lines.append(f"**Overall:** {overall}")
+        lines.append("")
+        checks = validation.get("policy_checks", [])
+        if checks:
+            lines.append("| Check | Result | Detail |")
+            lines.append("|---|---|---|")
+            for c in checks:
+                lines.append(f"| {c.get('check_name', '')} | {c.get('result', '')} | {c.get('detail', '')} |")
+        lines.append("")
+    else:
+        lines.append("_No validation report available._")
+        lines.append("")
+
+    # Assets
+    lines.append("## Rendered Assets")
+    lines.append("")
+    if output_files:
+        for f in output_files:
+            lines.append(f"- `{f}`")
+    else:
+        lines.append("_No rendered assets._")
+    lines.append("")
+
+    # Package completeness
+    lines.append("## Package Completeness")
+    lines.append("")
+    lines.append("| Artifact | Status |")
+    lines.append("|---|---|")
+    for name, status in sorted(artifacts.items()):
+        icon = "present" if status == "present" else "**MISSING**"
+        lines.append(f"| {name} | {icon} |")
+    lines.append("")
+
+    # Reviewer notes
+    if reviewer_notes:
+        lines.append("## Reviewer Notes")
+        lines.append("")
+        lines.append(reviewer_notes)
+        lines.append("")
+
+    return "\n".join(lines)