system-prompts-and-models-of-ai-tools/dealix/auto_client_acquisition/growth_operator/proof_pack.py

"""
Weekly Proof Pack — evidence the customer can show their CEO/board.

Tracks: opportunities discovered, messages approved, replies, meetings,
deals, pipeline, blocked risks (PDPL gates that fired), revenue leaks
recovered, next week plan.

Pure function. No I/O.
"""

from __future__ import annotations

from datetime import datetime, timezone
from typing import Any


def _grade_week(*, pipeline_sar: float, plan_cost_sar: float, deals_won: int) -> str:
    """Quick A+/A/B/C/D grade for the week."""
    if plan_cost_sar <= 0:
        return "B"
    multiple = pipeline_sar / plan_cost_sar
    if multiple >= 5 and deals_won >= 1:
        return "A+"
    if multiple >= 3:
        return "A"
    if multiple >= 1.5:
        return "B"
    if multiple >= 0.5:
        return "C"
    return "D"


def build_weekly_proof_pack(
    *,
    customer_id: str,
    customer_name: str,
    week_label: str,
    plan_cost_weekly_sar: float = 750,
    # Activity
    opportunities_discovered: int = 0,
    messages_drafted: int = 0,
    messages_approved: int = 0,
    messages_sent: int = 0,
    replies_received: int = 0,
    positive_replies: int = 0,
    meetings_booked: int = 0,
    meetings_held: int = 0,
    proposals_sent: int = 0,
    deals_won: int = 0,
    # Money
    pipeline_added_sar: float = 0.0,
    revenue_won_sar: float = 0.0,
    # Risk / quality
    risky_drafts_blocked: int = 0,
    revenue_leaks_recovered: int = 0,
    avg_response_minutes: int = 0,
    # Best of
    best_message_subject: str | None = None,
    best_message_reply_rate: float | None = None,
) -> dict[str, Any]:
    """Build the weekly proof pack (Markdown + structured)."""
    approve_rate = (
        round(messages_approved / messages_drafted, 4) if messages_drafted else 0.0
    )
    reply_rate = (
        round(replies_received / messages_sent, 4) if messages_sent else 0.0
    )
    grade = _grade_week(
        pipeline_sar=pipeline_added_sar,
        plan_cost_sar=plan_cost_weekly_sar,
        deals_won=deals_won,
    )
    multiple = round(pipeline_added_sar / plan_cost_weekly_sar, 2) if plan_cost_weekly_sar else 0.0
    headline_ar = (
        f"{pipeline_added_sar:,.0f} ريال pipeline + "
        f"{meetings_booked} اجتماع + {risky_drafts_blocked} مخاطرة محبوطة "
        f"خلال {week_label}"
    )

    activity = {
        "فرص مكتشفة": opportunities_discovered,
        "مسودات": messages_drafted,
        f"موافقات ({approve_rate*100:.0f}%)": messages_approved,
        "مُرسلة": messages_sent,
        f"ردود ({reply_rate*100:.1f}%)": replies_received,
        "ردود إيجابية": positive_replies,
        "اجتماعات محجوزة": meetings_booked,
        "اجتماعات منعقدة": meetings_held,
        "عروض مرسلة": proposals_sent,
        "صفقات مكسوبة": deals_won,
    }
    money = {
        "Pipeline مضاف": f"{pipeline_added_sar:,.0f} ريال",
        "إيراد محسوم": f"{revenue_won_sar:,.0f} ريال",
        "Multiple على تكلفة الأسبوع": f"{multiple}×",
    }
    quality = {
        "drafts خطرة محبوطة (PDPL gates)": risky_drafts_blocked,
        "تسريبات إيراد منقذة": revenue_leaks_recovered,
        "متوسط زمن الرد (دقيقة)": avg_response_minutes,
    }

    next_week_plan_ar = []
    if reply_rate < 0.05:
        next_week_plan_ar.append("اختبر صياغة مختلفة للسطر الأول — معدل الرد منخفض.")
    if avg_response_minutes > 60:
        next_week_plan_ar.append(f"قلل زمن الرد من {avg_response_minutes} إلى أقل من 60 دقيقة.")
    if meetings_booked == 0 and replies_received >= 5:
        next_week_plan_ar.append("ركّز على qualifying — ردود كثيرة بدون اجتماع.")
    if deals_won == 0 and proposals_sent >= 2:
        next_week_plan_ar.append("مراجعة العروض المرسلة + جلسة Deal Coach.")
    if not next_week_plan_ar:
        next_week_plan_ar.append("ركّز على الـ scale — زد عدد الـ leads بنسبة 30%.")

    md_lines = [
        f"# Dealix Proof Pack — {customer_name}",
        f"**الفترة:** {week_label}",
        f"**التقييم:** {grade}",
        "",
        "## TL;DR",
        headline_ar,
        "",
        "## النشاط",
        *(f"- {k}: {v}" for k, v in activity.items()),
        "",
        "## المال",
        *(f"- {k}: {v}" for k, v in money.items()),
        "",
        "## الجودة + الأمان",
        *(f"- {k}: {v}" for k, v in quality.items()),
        "",
        "## أفضل أداء",
        f"- subject الأنجح: {best_message_subject or '—'}",
        f"- معدل ردها: {(best_message_reply_rate or 0)*100:.1f}%",
        "",
        "## خطة الأسبوع القادم",
        *(f"- {x}" for x in next_week_plan_ar),
        "",
        f"_Generated by Dealix at {datetime.now(timezone.utc).isoformat()}_",
    ]

    return {
        "customer_id": customer_id,
        "customer_name": customer_name,
        "week_label": week_label,
        "grade": grade,
        "headline_ar": headline_ar,
        "activity": activity,
        "money": money,
        "quality": quality,
        "best_message": {
            "subject": best_message_subject,
            "reply_rate": best_message_reply_rate,
        },
        "next_week_plan_ar": next_week_plan_ar,
        "markdown_export": "\n".join(md_lines),
        "approval_required": False,
        "compliance_note_ar": (
            "هذا تقرير قراءة فقط — يُولَّد من سجلات حقيقية ولا يحوي أي PII "
            "خارج هوية الشركة المشتركة."
        ),
    }