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

open_pharma_plugins_campaign_studio/tools/validate_claims_and_fair_balance.py

@@ -0,0 +1,285 @@
+"""validate_claims_and_fair_balance — compliance gate before rendering."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ValidateClaimsArgs(BaseModel):
+    campaign_brief_id: str = Field(description="Links to the campaign brief")
+    channels: list[str] | None = Field(
+        default=None,
+        description="Validate specific channels; all if omitted",
+    )
+
+
+TOOL: dict[str, Any] = {
+    "name": "validate_claims_and_fair_balance",
+    "description": (
+        "Run the compliance gate on generated channel copy. Reads copy and "
+        "approved claims from the campaign directory and performs three checks: "
+        "(1) claim grounding — fuzzy-match each copy statement against approved "
+        "claims; (2) fair balance — ratio of safety to efficacy content; "
+        "(3) policy compliance — jurisdiction-required elements, prohibited "
+        "language patterns. Persists claim-map.json, policy-checks.json, and "
+        "source-evidence.json. ALL checks must pass before rendering."
+    ),
+    "args": ValidateClaimsArgs,
+}
+
+
+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_validation_artifact,
+    )
+    from .._claim_engine import (
+        check_fair_balance,
+        check_prohibited_language,
+        check_required_elements,
+        fuzzy_match,
+        is_claim_citation_exempt,
+        load_policy_rules,
+    )
+    from .._renderer import validation_input_fingerprint
+
+    campaign_brief_id = arguments["campaign_brief_id"]
+    requested_channels = arguments.get("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."}),
+            }
+        ]
+
+    claims_data = load_artifact(campaign_brief_id, "approved-claims.json")
+    if not claims_data:
+        return [
+            {
+                "type": "text",
+                "text": json.dumps({"error": "No approved-claims.json found. Run retrieve_approved_claims first."}),
+            }
+        ]
+
+    channels = requested_channels or brief.get("channels", [])
+    jurisdiction = brief.get("policy_jurisdiction", "FDA")
+    mode = brief.get("mode", "promotional")
+
+    rules = load_policy_rules(jurisdiction)
+
+    all_claim_results: list[dict] = []
+    all_policy_checks: list[dict] = []
+    all_copy_blocks: list[dict] = []
+    all_text_parts: list[str] = []
+    claim_by_id = {claim.get("claim_id"): claim for claim in claims_data}
+    used_claim_ids: set[str] = set()
+    brand_kit = _load_brand_legal(campaign_brief_id)
+
+    for channel in channels:
+        copy_artifact = load_artifact(campaign_brief_id, f"copy-{channel}.json")
+        if not copy_artifact:
+            all_policy_checks.append(
+                {
+                    "check_name": f"copy_{channel}_exists",
+                    "result": "fail",
+                    "detail": f"No copy-{channel}.json found. Run generate_channel_copy first.",
+                }
+            )
+            continue
+
+        copy_data = copy_artifact.get("copy", {})
+        blocks = _extract_all_blocks(copy_data, channel)
+        all_copy_blocks.extend(blocks)
+
+        for block_name, block in blocks:
+            text = block.get("text", "")
+            all_text_parts.append(text)
+
+            claim_ids = block.get("claim_ids", [])
+            if not claim_ids:
+                if mode == "promotional" and text and not is_claim_citation_exempt(block_name, text, brief, brand_kit):
+                    all_policy_checks.append(
+                        {
+                            "check_name": "missing_claim_citation",
+                            "result": "fail",
+                            "detail": f"{channel}.{block_name}: promotional copy has no approved claim ID.",
+                        }
+                    )
+                continue
+
+            for claim_id in claim_ids:
+                claim = claim_by_id.get(claim_id)
+                used_claim_ids.add(claim_id)
+                if claim is None:
+                    all_claim_results.append(
+                        {
+                            "claim_id": claim_id,
+                            "declared_claim_id": claim_id,
+                            "statement": text,
+                            "status": "not_found",
+                            "matched_claim_text": None,
+                            "similarity_score": 0.0,
+                            "deviation": "Declared claim ID is not in the approved claims set",
+                        }
+                    )
+                    continue
+                match_result = fuzzy_match(text, [claim])
+                match_result["declared_claim_id"] = claim_id
+                match_result["statement"] = text
+                all_claim_results.append(match_result)
+
+    combined_text = " ".join(all_text_parts)
+
+    # Fair balance check
+    fb = check_fair_balance(
+        [b for _, b in _extract_flat_blocks(channels, campaign_brief_id)],
+        claims_data,
+        rules.get("min_safety_ratio", 0.3),
+    )
+    all_policy_checks.append(fb)
+
+    # Prohibited language check
+    prohibited = rules.get("prohibited_patterns", [])
+    all_policy_checks.extend(check_prohibited_language(combined_text, prohibited))
+
+    # Non-promotional language check
+    if mode in ("non_promotional", "disease_awareness"):
+        np_prohibited = rules.get("non_promotional_prohibited", [])
+        all_policy_checks.extend(check_prohibited_language(combined_text, np_prohibited))
+
+    # Required elements check
+    required = rules.get("required_elements", [])
+    all_policy_checks.extend(check_required_elements(combined_text, brand_kit, required))
+
+    overall_pass = all(c.get("result") != "fail" for c in all_policy_checks) and all(
+        c.get("status") == "approved" for c in all_claim_results
+    )
+
+    # Build source evidence
+    source_evidence = []
+    seen_sources: set[str] = set()
+    for claim in claims_data:
+        if claim.get("claim_id") not in used_claim_ids:
+            continue
+        key = f"{claim.get('source_document')}:{claim.get('source_reference')}"
+        if key not in seen_sources:
+            seen_sources.add(key)
+            source_evidence.append(
+                {
+                    "document_id": claim.get("claim_id", ""),
+                    "document_name": claim.get("source_document", ""),
+                    "page_number": None,
+                    "excerpt": claim.get("source_reference", ""),
+                }
+            )
+
+    # Build claim map
+    claim_map: dict[str, list[str]] = {}
+    for result in all_claim_results:
+        stmt = result.get("statement", "")[:60]
+        cid = result.get("declared_claim_id")
+        if cid:
+            claim_map.setdefault(stmt, []).append(cid)
+
+    # Persist
+    report = {
+        "campaign_brief_id": campaign_brief_id,
+        "channels_validated": channels,
+        "claims_checked": all_claim_results,
+        "policy_checks": all_policy_checks,
+        "overall_pass": overall_pass,
+        "input_fingerprint": validation_input_fingerprint(campaign_brief_id, channels),
+        "generated_at": datetime.now(timezone.utc).isoformat(),
+    }
+
+    save_validation_artifact(campaign_brief_id, "policy-checks.json", report)
+    save_validation_artifact(campaign_brief_id, "claim-map.json", claim_map)
+    save_validation_artifact(campaign_brief_id, "source-evidence.json", source_evidence)
+
+    summary = {
+        "campaign_brief_id": campaign_brief_id,
+        "overall_pass": overall_pass,
+        "channels_validated": channels,
+        "claims_total": len(all_claim_results),
+        "claims_approved": sum(1 for c in all_claim_results if c.get("status") == "approved"),
+        "claims_needs_review": sum(1 for c in all_claim_results if c.get("status") == "needs_review"),
+        "claims_not_found": sum(1 for c in all_claim_results if c.get("status") == "not_found"),
+        "policy_pass": sum(1 for c in all_policy_checks if c.get("result") == "pass"),
+        "policy_warn": sum(1 for c in all_policy_checks if c.get("result") == "warn"),
+        "policy_fail": sum(1 for c in all_policy_checks if c.get("result") == "fail"),
+        "failures": [c for c in all_policy_checks if c.get("result") == "fail"]
+        + [c for c in all_claim_results if c.get("status") != "approved"],
+    }
+    return [{"type": "text", "text": json.dumps(summary, indent=2)}]
+
+
+def _extract_all_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 = {
+        "email": ["subject", "preheader", "headline", "cta"],
+        "banner": ["headline", "sub_headline", "cta"],
+        "poster": ["headline", "subhead", "cta"],
+    }
+    for field in simple.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
+
+
+def _extract_flat_blocks(channels: list[str], campaign_brief_id: str) -> list[tuple[str, dict]]:
+    """Load and extract blocks from all channel copy files."""
+    from .._campaign_store import load_artifact
+
+    blocks: list[tuple[str, dict]] = []
+    for channel in channels:
+        copy_artifact = load_artifact(campaign_brief_id, f"copy-{channel}.json")
+        if copy_artifact:
+            blocks.extend(_extract_all_blocks(copy_artifact.get("copy", {}), channel))
+    return blocks
+
+
+def _load_brand_legal(campaign_brief_id: str) -> dict:
+    """Load legal content from brand kit."""
+    import json
+    from importlib.resources import files
+    from pathlib import Path
+
+    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():
+        legal_path = Path(kit_path) / "legal.json"
+    else:
+        legal_path = Path(str(files("open_pharma_plugins_campaign_studio") / "fixtures" / "brand_kit" / "legal.json"))
+
+    if legal_path.exists():
+        return json.loads(legal_path.read_text())
+    return {}

open_pharma_plugins_competitive_intelligence/__init__.py

@@ -0,0 +1,13 @@
+from mcp_framework import build_registry
+
+__version__ = "1.1.0"
+
+SPECS, get_handler, list_tools = build_registry(__name__, ["tools"])
+
+USAGE_NOTE = (
+    "Competitive Intelligence tracks competitor trial pipelines, FDA "
+    "regulatory events, label changes, news, and publications. Maintains "
+    "a persistent watchlist and generates shareable briefing reports."
+)
+
+SYSTEM_DEPS = []

open_pharma_plugins_competitive_intelligence/__main__.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+
+from mcp_framework import run_main
+
+
+def main() -> None:
+    run_main(__package__ or Path(__file__).resolve().parent.name)
+
+
+if __name__ == "__main__":
+    main()

open_pharma_plugins_competitive_intelligence/_artifacts.py

@@ -0,0 +1,87 @@
+"""Private, non-overwriting artifact primitives for CI run projections."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import secrets
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from shared.filesystem import (
+    atomic_write_bytes,
+    atomic_write_text,
+    contained_path,
+    ensure_private_dir,
+    validate_component,
+)
+
+from ._watchlist import reports_dir
+from .models import ArtifactManifest, ArtifactRecord
+
+_FORMULA_PREFIXES = ("=", "+", "-", "@", "\t", "\r")
+_MAX_ATTEMPTS = 3
+
+
+def sanitize_display_stem(value: str | None, *, default: str) -> str:
+    clean = re.sub(r"[^A-Za-z0-9_-]", "_", value or "")
+    clean = clean[:100]
+    return clean if clean not in {"", ".", ".."} else default
+
+
+def safe_csv_cell(value: Any) -> str:
+    text = "" if value is None else str(value)
+    candidate = text.lstrip(" \u00a0")
+    return f"'{text}" if candidate.startswith(_FORMULA_PREFIXES) else text
+
+
+def create_artifact_dir(run_id: str, *, now: datetime | None = None) -> Path:
+    validate_component(run_id, label="run id")
+    generated_at = _utc(now)
+    run_root = ensure_private_dir(contained_path(reports_dir(), run_id))
+    for _attempt in range(_MAX_ATTEMPTS):
+        artifact_id = f"artifact_{generated_at.strftime('%Y%m%dT%H%M%SZ')}_{secrets.token_hex(4)}"
+        candidate = contained_path(run_root, artifact_id)
+        try:
+            candidate.mkdir(mode=0o700, exist_ok=False)
+            return candidate
+        except FileExistsError:
+            continue
+    raise FileExistsError("could not allocate a unique artifact directory after three attempts")
+
+
+def write_artifact(
+    output_dir: Path,
+    relative_path: str,
+    content: str | bytes,
+    *,
+    media_type: str,
+) -> ArtifactRecord:
+    validate_component(relative_path, label="artifact path")
+    path = contained_path(output_dir, relative_path)
+    payload = content.encode("utf-8") if isinstance(content, str) else content
+    atomic_write_bytes(path, payload)
+    return ArtifactRecord(
+        relative_path=relative_path,
+        media_type=media_type,
+        byte_size=len(payload),
+        sha256=hashlib.sha256(payload).hexdigest(),
+    )
+
+
+def write_manifest(output_dir: Path, manifest: ArtifactManifest) -> Path:
+    path = contained_path(output_dir, "manifest.json")
+    atomic_write_text(
+        path,
+        json.dumps(manifest.model_dump(mode="json"), indent=2, ensure_ascii=False),
+    )
+    return path
+
+
+def _utc(value: datetime | None) -> datetime:
+    now = value or datetime.now(timezone.utc)
+    if now.tzinfo is None:
+        raise ValueError("now must be timezone-aware")
+    return now.astimezone(timezone.utc)

open_pharma_plugins_competitive_intelligence/_cache.py

@@ -0,0 +1,144 @@
+"""Schema-versioned, credential-free response cache for CI provider calls."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping
+
+from shared.filesystem import atomic_write_json, contained_path, ensure_private_dir, sanitize_mapping, sanitize_url
+
+from .models import CacheStatus
+
+_SCHEMA_VERSION = 2
+_DEFAULT_TTL_HOURS = 24
+
+
+@dataclass(frozen=True)
+class CacheLookup:
+    status: CacheStatus
+    payload: Any | None
+    cached_at: datetime | None
+
+
+def _cache_dir() -> Path:
+    from shared.env import get_env
+
+    root = ensure_private_dir(
+        get_env(
+            "OPEN_PHARMA_CI_DATA_DIR",
+            str(Path.home() / ".open-pharma-plugins" / "competitive-intelligence"),
+        )
+    )
+    return ensure_private_dir(contained_path(root, "cache"))
+
+
+def _ttl_hours() -> int:
+    try:
+        from shared.env import get_env
+
+        value = get_env("CI_CACHE_TTL_HOURS", str(_DEFAULT_TTL_HOURS))
+        parsed = int(value) if value else _DEFAULT_TTL_HOURS
+        return parsed if parsed >= 0 else _DEFAULT_TTL_HOURS
+    except (TypeError, ValueError):
+        return _DEFAULT_TTL_HOURS
+
+
+def _cache_key(namespace: str, params: Mapping[str, Any] | None = None) -> str:
+    clean_namespace = _sanitize_namespace(namespace)
+    clean_params = _sanitize_value(params or {})
+    raw = clean_namespace + "|" + json.dumps(clean_params, sort_keys=True, default=str)
+    return hashlib.sha256(raw.encode()).hexdigest()[:24]
+
+
+def cache_lookup(namespace: str, params: Mapping[str, Any] | None = None) -> CacheLookup:
+    ttl_hours = _ttl_hours()
+    if ttl_hours == 0:
+        return CacheLookup(status=CacheStatus.DISABLED, payload=None, cached_at=None)
+    key = _cache_key(namespace, params)
+    path = contained_path(_cache_dir(), f"{key}.json")
+    if not path.exists():
+        return CacheLookup(status=CacheStatus.MISS, payload=None, cached_at=None)
+    try:
+        data = json.loads(path.read_text())
+        if data.get("schema_version") != _SCHEMA_VERSION:
+            return CacheLookup(status=CacheStatus.MISS, payload=None, cached_at=None)
+        cached_at = datetime.fromisoformat(str(data["cached_at"]).replace("Z", "+00:00"))
+        if cached_at.tzinfo is None:
+            raise ValueError("cache timestamp must include a timezone")
+        cached_at = cached_at.astimezone(timezone.utc)
+        age_hours = (datetime.now(timezone.utc) - cached_at).total_seconds() / 3600
+        if age_hours > ttl_hours:
+            return CacheLookup(status=CacheStatus.MISS, payload=None, cached_at=None)
+        return CacheLookup(status=CacheStatus.HIT, payload=data.get("payload"), cached_at=cached_at)
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError, OSError):
+        return CacheLookup(status=CacheStatus.MISS, payload=None, cached_at=None)
+
+
+def cache_store(namespace: str, params: Mapping[str, Any] | None, payload: Any) -> None:
+    if _ttl_hours() == 0:
+        return
+    clean_namespace = _sanitize_namespace(namespace)
+    clean_params = _sanitize_value(params or {})
+    key = _cache_key(clean_namespace, clean_params)
+    path = contained_path(_cache_dir(), f"{key}.json")
+    data = {
+        "schema_version": _SCHEMA_VERSION,
+        "cached_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "namespace": clean_namespace,
+        "params": clean_params,
+        "payload": _sanitize_value(payload),
+    }
+    atomic_write_json(path, data)
+
+
+def cache_stats() -> dict[str, Any]:
+    d = _cache_dir()
+    files = list(d.glob("*.json"))
+    total_bytes = sum(f.stat().st_size for f in files)
+    recognized = 0
+    for path in files:
+        try:
+            if json.loads(path.read_text()).get("schema_version") == _SCHEMA_VERSION:
+                recognized += 1
+        except (json.JSONDecodeError, OSError, AttributeError):
+            pass
+    return {
+        "cache_dir": str(d),
+        "schema_version": _SCHEMA_VERSION,
+        "entry_count": recognized,
+        "ignored_entry_count": len(files) - recognized,
+        "total_bytes": total_bytes,
+    }
+
+
+def cache_clear() -> int:
+    d = _cache_dir()
+    removed = 0
+    for path in d.glob("*.json"):
+        try:
+            if json.loads(path.read_text()).get("schema_version") != _SCHEMA_VERSION:
+                continue
+        except (json.JSONDecodeError, OSError, AttributeError):
+            continue
+        path.unlink(missing_ok=True)
+        removed += 1
+    return removed
+
+
+def _sanitize_namespace(namespace: str) -> str:
+    return sanitize_url(namespace) if "://" in namespace else namespace
+
+
+def _sanitize_value(value: Any) -> Any:
+    sanitized = sanitize_mapping(value)
+    if isinstance(sanitized, dict):
+        return {key: _sanitize_value(item) for key, item in sanitized.items()}
+    if isinstance(sanitized, list):
+        return [_sanitize_value(item) for item in sanitized]
+    if isinstance(sanitized, str) and "://" in sanitized:
+        return sanitize_url(sanitized)
+    return sanitized