mirror of
https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git
synced 2026-06-18 07:19:35 +00:00
feat(growth-operator): Arabic Growth Operator — 10 modules + 16 endpoints + 50 tests
Builds the full Saudi Autonomous Revenue OS surface as 10 deterministic
modules + a 16-endpoint router under /api/v1/growth-operator/.
Approval-first: every outbound is draft. No live send / charge / calendar
insert from this layer.
MODULES (auto_client_acquisition/growth_operator/)
1. client_profile.py — ClientGrowthProfile + Saudi-default approval
+ compliance rules (no cold WhatsApp, blocked keywords, weekly cap,
quiet_hours_riyadh)
2. contact_importer.py — normalize_phone (Saudi E.164),
dedupe_contacts (richer-record-wins), classify_contact_source
(existing/inbound/event/referral/old_lead/cold/unknown), detect_opt_out
(Arabic + English markers), summarize_import (dashboard report)
3. contactability.py — score_contactability returns
safe/needs_review/blocked with Arabic reasons; default policy:
no cold WhatsApp without lawful basis (PDPL Art.5)
4. targeting.py — segment_contacts, rank_targets (filters unsafe),
recommend_top_10, why_now_stub (deterministic, sector-aware)
5. message_planner.py — draft_arabic_message (Saudi tone, 4-sector
opener bank, no overhyped phrases, always pending_approval),
draft_followup (4 outcome modes), draft_objection_response
(6 indexed Saudi B2B objections with score_delta + next_action)
6. partnership_planner.py — 6 partner types catalog
(agency / consultant / integrator / crm / community / influencer)
+ suggest_partner_types (size/sector aware) + draft_partner_outreach
+ partner_scorecard (platinum/gold/silver/bronze)
7. meeting_planner.py — build_meeting_agenda (15/20-30/45+ min slot
plans), build_calendar_draft (Google Calendar shape, live_inserted=False,
conferenceData for Meet, Asia/Riyadh timezone), build_post_meeting_followup
8. payment_offer.py — sar_to_halalas, build_moyasar_payment_link_draft
(full payload + in-chat message + 4-plan catalog, live_charged=False)
9. proof_pack.py — build_weekly_proof_pack with grade A+/A/B/C/D,
activity/money/quality/best-of sections, dynamic next_week_plan_ar,
markdown export
10. mission_planner.py — 6 GROWTH_MISSIONS (first_10_opportunities ⭐
kill feature, recover_stalled_deals, partnership_sprint,
safe_whatsapp_campaign, meeting_booking_sprint, list_cleanup);
list_missions() + run_mission()
ROUTER (api/routers/growth_operator.py) — 16 endpoints
POST /contacts/import-preview · POST /contactability/score
POST /targets/top-10 · POST /messages/draft · POST /messages/followup
POST /messages/objection-response · POST /partners/suggest
POST /partners/outreach · POST /partners/scorecard
POST /meetings/draft · POST /meetings/post-followup
POST /payment-offer/draft · GET /missions · POST /missions/{id}/run
GET /proof-pack/demo · POST /profile
WIRING: api/main.py adds growth_operator import + router include
(positioned after personal_operator, before public).
DOCS
- docs/ARABIC_GROWTH_OPERATOR_FULL_SPEC.md (NEW): 20-section vision +
customer-type table + upload flow + contactability rules +
WhatsApp/Gmail/Calendar/Moyasar drafts + 6 missions + 16-endpoint
catalog + competitive comparison + beta readiness checklist
TESTS — 50 passing on Python 3.10 venv
tests/unit/test_growth_operator.py covers:
- Phone normalization across 5 input formats including invalid
- Dedupe richer-record invariant
- Source classification (existing/inbound/event/cold/unknown)
- Opt-out detection (Arabic + English notes + status)
- Import summary aggregation
- Contactability: opt-out blocked, cold WhatsApp blocked,
unknown→needs_review, existing→safe, inbound→safe
- Bulk contactability summary
- Top-10 filtering (unsafe excluded), max-cap enforcement
- Segment buckets
- Arabic message: pending_approval invariant + Arabic content
+ no overhyped phrases (banned list)
- Followup approval invariant
- Objection response: known + unknown→diagnostic
- Partner suggestions size-aware (SMB→agency/consultant/community)
- Partner outreach approval invariant
- Partner unknown type returns error
- Partner scorecard tier ordering
- Meeting agenda + calendar draft (live_inserted=False) +
Asia/Riyadh timezone + post-followup pending
- Payment: halalas conversion (1 SAR=100), negative raises,
draft NEVER charges (live_charged=False), unknown plan→error
- Proof pack: grade range + structure + markdown export
- Missions: first_10_opportunities present + kill feature ID
+ run mission known/unknown
- Profile: demo specialized + partial not specialized
+ default compliance blocks 'ضمان 100' + no_cold_whatsapp_without_lawful_basis
VERIFICATION
- 527 unit tests pass (was 477; +50 growth_operator)
- 2 skipped (provider smoke needs API keys)
- AST green on all 13 new files
- Approval invariant holds across every drafting function
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Dealix Builder
parent
80e1fc3533
commit
8942c6e84c
@ -27,6 +27,7 @@ from api.routers import (
|
||||
ecosystem,
|
||||
email_send,
|
||||
full_os,
|
||||
growth_operator,
|
||||
health,
|
||||
innovation,
|
||||
leads,
|
||||
@ -146,6 +147,7 @@ def create_app() -> FastAPI:
|
||||
app.include_router(innovation.router)
|
||||
app.include_router(business.router)
|
||||
app.include_router(personal_operator.router)
|
||||
app.include_router(growth_operator.router)
|
||||
app.include_router(public.router)
|
||||
app.include_router(admin.router)
|
||||
|
||||
|
||||
260
dealix/api/routers/growth_operator.py
Normal file
260
dealix/api/routers/growth_operator.py
Normal file
@ -0,0 +1,260 @@
|
||||
"""
|
||||
Growth Operator router — Arabic Growth Operator endpoints.
|
||||
|
||||
Approval-first: every outbound is draft. Nothing is sent / charged /
|
||||
scheduled live from this router; that happens in dedicated send / billing
|
||||
/ calendar services after explicit user approval.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from typing import Any
|
||||
|
||||
from fastapi import APIRouter, Body, Query
|
||||
|
||||
from auto_client_acquisition.growth_operator import (
|
||||
build_calendar_draft,
|
||||
build_meeting_agenda,
|
||||
build_moyasar_payment_link_draft,
|
||||
build_post_meeting_followup,
|
||||
build_weekly_proof_pack,
|
||||
contactability_summary,
|
||||
dedupe_contacts,
|
||||
draft_arabic_message,
|
||||
draft_followup,
|
||||
draft_objection_response,
|
||||
draft_partner_outreach,
|
||||
list_missions,
|
||||
partner_scorecard,
|
||||
profile_from_dict,
|
||||
recommend_top_10,
|
||||
run_mission,
|
||||
score_contactability,
|
||||
suggest_partner_types,
|
||||
summarize_import,
|
||||
)
|
||||
|
||||
router = APIRouter(prefix="/api/v1/growth-operator", tags=["growth-operator"])
|
||||
log = logging.getLogger(__name__)
|
||||
|
||||
|
||||
# ── 1. Contacts: import preview ─────────────────────────────────
|
||||
@router.post("/contacts/import-preview")
|
||||
async def contacts_import_preview(
|
||||
contacts: list[dict[str, Any]] = Body(default_factory=list, embed=True),
|
||||
channel: str = Body(default="whatsapp", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
"""Preview import: dedupe + source classify + contactability summary."""
|
||||
deduped = dedupe_contacts(contacts)
|
||||
return {
|
||||
"import_summary": summarize_import(contacts),
|
||||
"contactability": contactability_summary(deduped, channel=channel),
|
||||
"policy_note_ar": (
|
||||
"العميل يرفع أرقام مملوكة/مصرح بها. لا cold WhatsApp بدون lawful basis."
|
||||
),
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
|
||||
|
||||
# ── 2. Targeting: top-10 ────────────────────────────────────────
|
||||
@router.post("/targets/top-10")
|
||||
async def targets_top_10(
|
||||
contacts: list[dict[str, Any]] = Body(default_factory=list, embed=True),
|
||||
sector_hint: str = Body(default="", embed=True),
|
||||
channel: str = Body(default="whatsapp", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
"""Rank uploaded contacts → top-10 safe + Why-Now."""
|
||||
return recommend_top_10(contacts, sector_hint=sector_hint, channel=channel)
|
||||
|
||||
|
||||
# ── 3. Messages: draft / followup / objection ──────────────────
|
||||
@router.post("/messages/draft")
|
||||
async def messages_draft(
|
||||
contact: dict[str, Any] = Body(..., embed=True),
|
||||
profile: dict[str, Any] | None = Body(default=None, embed=True),
|
||||
goal_ar: str = Body(default="تشغيل نمو B2B بلا إرسال عشوائي", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
"""Saudi-tone Arabic outreach draft (always pending_approval)."""
|
||||
return draft_arabic_message(contact, profile=profile, goal_ar=goal_ar)
|
||||
|
||||
|
||||
@router.post("/messages/followup")
|
||||
async def messages_followup(
|
||||
contact: dict[str, Any] = Body(..., embed=True),
|
||||
days_since_last: int = Body(default=3, embed=True),
|
||||
last_outcome: str = Body(default="no_reply", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
return draft_followup(
|
||||
contact, days_since_last=days_since_last, last_outcome=last_outcome,
|
||||
)
|
||||
|
||||
|
||||
@router.post("/messages/objection-response")
|
||||
async def messages_objection_response(
|
||||
objection_id: str = Body(..., embed=True),
|
||||
contact: dict[str, Any] | None = Body(default=None, embed=True),
|
||||
) -> dict[str, Any]:
|
||||
return draft_objection_response(objection_id, contact=contact)
|
||||
|
||||
|
||||
# ── 4. Partners: suggest / outreach / scorecard ────────────────
|
||||
@router.post("/partners/suggest")
|
||||
async def partners_suggest(
|
||||
sector: str = Body(default="", embed=True),
|
||||
customer_size: str = Body(default="smb", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
return suggest_partner_types(sector=sector, customer_size=customer_size)
|
||||
|
||||
|
||||
@router.post("/partners/outreach")
|
||||
async def partners_outreach(
|
||||
partner_type_key: str = Body(..., embed=True),
|
||||
partner_name: str = Body(default="", embed=True),
|
||||
customer_name: str = Body(default="Dealix", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
return draft_partner_outreach(
|
||||
partner_type_key=partner_type_key,
|
||||
partner_name=partner_name,
|
||||
customer_name=customer_name,
|
||||
)
|
||||
|
||||
|
||||
@router.post("/partners/scorecard")
|
||||
async def partners_scorecard(payload: dict[str, Any] = Body(...)) -> dict[str, Any]:
|
||||
return partner_scorecard(
|
||||
partner_id=payload.get("partner_id", "unknown"),
|
||||
intros_made=int(payload.get("intros_made", 0)),
|
||||
deals_influenced=int(payload.get("deals_influenced", 0)),
|
||||
revenue_share_paid_sar=float(payload.get("revenue_share_paid_sar", 0)),
|
||||
relationship_age_months=int(payload.get("relationship_age_months", 0)),
|
||||
)
|
||||
|
||||
|
||||
# ── 5. Meetings: agenda / calendar draft / followup ────────────
|
||||
@router.post("/meetings/draft")
|
||||
async def meetings_draft(
|
||||
contact_name: str = Body(..., embed=True),
|
||||
company: str = Body(..., embed=True),
|
||||
contact_email: str | None = Body(default=None, embed=True),
|
||||
purpose_ar: str = Body(default="اكتشاف وتأهيل أولي", embed=True),
|
||||
duration_minutes: int = Body(default=20, embed=True),
|
||||
proposed_start_iso: str | None = Body(default=None, embed=True),
|
||||
) -> dict[str, Any]:
|
||||
"""Build agenda + calendar draft (NOT created live)."""
|
||||
agenda = build_meeting_agenda(
|
||||
contact_name=contact_name,
|
||||
company=company,
|
||||
purpose_ar=purpose_ar,
|
||||
duration_minutes=duration_minutes,
|
||||
)
|
||||
cal_draft = build_calendar_draft(
|
||||
contact_email=contact_email,
|
||||
contact_name=contact_name,
|
||||
company=company,
|
||||
proposed_start_iso=proposed_start_iso,
|
||||
duration_minutes=duration_minutes,
|
||||
)
|
||||
return {"agenda": agenda, "calendar_draft": cal_draft}
|
||||
|
||||
|
||||
@router.post("/meetings/post-followup")
|
||||
async def meetings_post_followup(
|
||||
contact_name: str = Body(..., embed=True),
|
||||
company: str = Body(..., embed=True),
|
||||
summary_ar: str = Body(..., embed=True),
|
||||
next_step_ar: str = Body(default="أرسل recap + pilot offer", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
return build_post_meeting_followup(
|
||||
contact_name=contact_name,
|
||||
company=company,
|
||||
summary_ar=summary_ar,
|
||||
next_step_ar=next_step_ar,
|
||||
)
|
||||
|
||||
|
||||
# ── 6. Payment offer (Moyasar payment-link draft) ─────────────
|
||||
@router.post("/payment-offer/draft")
|
||||
async def payment_offer_draft(
|
||||
plan_key: str = Body(..., embed=True),
|
||||
customer_id: str = Body(..., embed=True),
|
||||
contact_email: str | None = Body(default=None, embed=True),
|
||||
custom_amount_sar: float | None = Body(default=None, embed=True),
|
||||
) -> dict[str, Any]:
|
||||
return build_moyasar_payment_link_draft(
|
||||
plan_key=plan_key,
|
||||
customer_id=customer_id,
|
||||
contact_email=contact_email,
|
||||
custom_amount_sar=custom_amount_sar,
|
||||
)
|
||||
|
||||
|
||||
# ── 7. Missions ────────────────────────────────────────────────
|
||||
@router.get("/missions")
|
||||
async def missions_list() -> dict[str, Any]:
|
||||
return list_missions()
|
||||
|
||||
|
||||
@router.post("/missions/{mission_id}/run")
|
||||
async def missions_run(
|
||||
mission_id: str,
|
||||
payload: dict[str, Any] = Body(default_factory=dict),
|
||||
) -> dict[str, Any]:
|
||||
return run_mission(mission_id, payload=payload)
|
||||
|
||||
|
||||
# ── 8. Proof Pack demo ─────────────────────────────────────────
|
||||
@router.get("/proof-pack/demo")
|
||||
async def proof_pack_demo(
|
||||
customer_id: str = Query(default="demo"),
|
||||
customer_name: str = Query(default="Demo Saudi B2B Co."),
|
||||
) -> dict[str, Any]:
|
||||
return build_weekly_proof_pack(
|
||||
customer_id=customer_id,
|
||||
customer_name=customer_name,
|
||||
week_label="W18-2026",
|
||||
plan_cost_weekly_sar=750,
|
||||
opportunities_discovered=42,
|
||||
messages_drafted=38,
|
||||
messages_approved=33,
|
||||
messages_sent=33,
|
||||
replies_received=11,
|
||||
positive_replies=4,
|
||||
meetings_booked=3,
|
||||
meetings_held=2,
|
||||
proposals_sent=1,
|
||||
deals_won=0,
|
||||
pipeline_added_sar=185_000,
|
||||
revenue_won_sar=0,
|
||||
risky_drafts_blocked=5,
|
||||
revenue_leaks_recovered=2,
|
||||
avg_response_minutes=42,
|
||||
best_message_subject="ملاحظة على توسعكم في الرياض",
|
||||
best_message_reply_rate=0.18,
|
||||
)
|
||||
|
||||
|
||||
# ── 9. Single-contact contactability ─────────────────────────
|
||||
@router.post("/contactability/score")
|
||||
async def contactability_score_single(
|
||||
contact: dict[str, Any] = Body(..., embed=True),
|
||||
channel: str = Body(default="whatsapp", embed=True),
|
||||
) -> dict[str, Any]:
|
||||
return score_contactability(contact, channel=channel)
|
||||
|
||||
|
||||
# ── 10. Profile ────────────────────────────────────────────────
|
||||
@router.post("/profile")
|
||||
async def profile_set(
|
||||
profile: dict[str, Any] = Body(..., embed=True),
|
||||
) -> dict[str, Any]:
|
||||
p = profile_from_dict(profile)
|
||||
return {
|
||||
"profile": p.to_dict(),
|
||||
"is_specialized": p.is_specialized(),
|
||||
"missing_fields_ar": (
|
||||
[] if p.is_specialized() else
|
||||
["sector", "city", "offer_one_liner", "ideal_customer"]
|
||||
),
|
||||
}
|
||||
96
dealix/auto_client_acquisition/growth_operator/__init__.py
Normal file
96
dealix/auto_client_acquisition/growth_operator/__init__.py
Normal file
@ -0,0 +1,96 @@
|
||||
"""
|
||||
Arabic Growth Operator — Dealix's customer-facing growth-execution layer.
|
||||
|
||||
This package bundles the building blocks for the operator experience:
|
||||
- client_profile : Saudi B2B Growth Profile per customer
|
||||
- contact_importer : safe upload + normalize + classify uploaded numbers
|
||||
- contactability : per-contact "can we contact?" decision
|
||||
- targeting : segmenting + ranking + Top-10 with Why-Now stub
|
||||
- message_planner : Arabic drafts + follow-ups + objection responses
|
||||
- partnership_planner : partner suggestions + outreach drafts + scorecard
|
||||
- meeting_planner : agenda + calendar draft + post-meeting follow-up
|
||||
- payment_offer : Moyasar payment-link draft (no charge)
|
||||
- proof_pack : weekly evidence pack with revenue + risk metrics
|
||||
- mission_planner : Growth Missions (10-in-10, recover-stalled, etc.)
|
||||
|
||||
DESIGN INVARIANTS
|
||||
- draft-only by default; nothing is sent / charged / scheduled live
|
||||
- every outbound has approval_required=True
|
||||
- PDPL: no cold WhatsApp without lawful basis; uploads classified safely
|
||||
- deterministic: same input → same output (testable without external APIs)
|
||||
"""
|
||||
|
||||
from auto_client_acquisition.growth_operator.client_profile import (
|
||||
ClientGrowthProfile,
|
||||
build_demo_profile,
|
||||
profile_from_dict,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.contact_importer import (
|
||||
classify_contact_source,
|
||||
dedupe_contacts,
|
||||
detect_opt_out,
|
||||
normalize_phone,
|
||||
summarize_import,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.contactability import (
|
||||
CONTACTABILITY_LABELS,
|
||||
contactability_summary,
|
||||
score_contactability,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.message_planner import (
|
||||
draft_arabic_message,
|
||||
draft_followup,
|
||||
draft_objection_response,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.meeting_planner import (
|
||||
build_calendar_draft,
|
||||
build_meeting_agenda,
|
||||
build_post_meeting_followup,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.mission_planner import (
|
||||
GROWTH_MISSIONS,
|
||||
list_missions,
|
||||
run_mission,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.partnership_planner import (
|
||||
draft_partner_outreach,
|
||||
partner_scorecard,
|
||||
suggest_partner_types,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.payment_offer import (
|
||||
build_moyasar_payment_link_draft,
|
||||
sar_to_halalas,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.proof_pack import (
|
||||
build_weekly_proof_pack,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.targeting import (
|
||||
rank_targets,
|
||||
recommend_top_10,
|
||||
segment_contacts,
|
||||
why_now_stub,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
# client_profile
|
||||
"ClientGrowthProfile", "build_demo_profile", "profile_from_dict",
|
||||
# contact_importer
|
||||
"normalize_phone", "dedupe_contacts", "classify_contact_source",
|
||||
"detect_opt_out", "summarize_import",
|
||||
# contactability
|
||||
"CONTACTABILITY_LABELS", "score_contactability", "contactability_summary",
|
||||
# targeting
|
||||
"segment_contacts", "rank_targets", "recommend_top_10", "why_now_stub",
|
||||
# message_planner
|
||||
"draft_arabic_message", "draft_followup", "draft_objection_response",
|
||||
# partnership_planner
|
||||
"suggest_partner_types", "draft_partner_outreach", "partner_scorecard",
|
||||
# meeting_planner
|
||||
"build_meeting_agenda", "build_calendar_draft", "build_post_meeting_followup",
|
||||
# payment_offer
|
||||
"build_moyasar_payment_link_draft", "sar_to_halalas",
|
||||
# proof_pack
|
||||
"build_weekly_proof_pack",
|
||||
# mission_planner
|
||||
"GROWTH_MISSIONS", "list_missions", "run_mission",
|
||||
]
|
||||
116
dealix/auto_client_acquisition/growth_operator/client_profile.py
Normal file
116
dealix/auto_client_acquisition/growth_operator/client_profile.py
Normal file
@ -0,0 +1,116 @@
|
||||
"""
|
||||
Client Growth Profile — the per-customer config that turns Dealix from a
|
||||
generic operator into a specialized one.
|
||||
|
||||
Without this profile every agent works on a generic prompt; with it,
|
||||
every draft, every Why-Now, and every recommendation is grounded in:
|
||||
the customer's offer, ICP, sales cycle, channels, objection history,
|
||||
approval rules, and compliance constraints.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import Any
|
||||
|
||||
|
||||
@dataclass
|
||||
class ClientGrowthProfile:
|
||||
"""Per-customer growth context fed to every agent decision."""
|
||||
|
||||
customer_id: str
|
||||
company_name: str
|
||||
sector: str
|
||||
city: str
|
||||
offer_one_liner: str
|
||||
ideal_customer: str
|
||||
average_deal_size_sar: float = 0.0
|
||||
current_channels: tuple[str, ...] = () # e.g. ("whatsapp", "email")
|
||||
sales_cycle_days: int = 30
|
||||
common_objections: tuple[str, ...] = ()
|
||||
approval_rules: dict[str, Any] = field(default_factory=dict)
|
||||
compliance_rules: dict[str, Any] = field(default_factory=dict)
|
||||
|
||||
def to_dict(self) -> dict[str, Any]:
|
||||
return {
|
||||
"customer_id": self.customer_id,
|
||||
"company_name": self.company_name,
|
||||
"sector": self.sector,
|
||||
"city": self.city,
|
||||
"offer_one_liner": self.offer_one_liner,
|
||||
"ideal_customer": self.ideal_customer,
|
||||
"average_deal_size_sar": self.average_deal_size_sar,
|
||||
"current_channels": list(self.current_channels),
|
||||
"sales_cycle_days": self.sales_cycle_days,
|
||||
"common_objections": list(self.common_objections),
|
||||
"approval_rules": self.approval_rules,
|
||||
"compliance_rules": self.compliance_rules,
|
||||
}
|
||||
|
||||
def is_specialized(self) -> bool:
|
||||
"""A profile becomes 'specialized' once the minimum context is set."""
|
||||
return all([
|
||||
self.sector,
|
||||
self.city,
|
||||
self.offer_one_liner,
|
||||
self.ideal_customer,
|
||||
])
|
||||
|
||||
|
||||
# Sane defaults reflecting Saudi B2B norms — used until customer overrides.
|
||||
_DEFAULT_APPROVAL_RULES: dict[str, Any] = {
|
||||
"require_human_for_first_send": True,
|
||||
"require_human_for_high_value_deals_above_sar": 100_000,
|
||||
"max_consecutive_followups": 3,
|
||||
"quiet_hours_riyadh": [21, 8], # no outbound 9pm-8am Riyadh
|
||||
"blocked_dates": [],
|
||||
}
|
||||
_DEFAULT_COMPLIANCE_RULES: dict[str, Any] = {
|
||||
"no_cold_whatsapp_without_lawful_basis": True,
|
||||
"require_unsubscribe_in_email": True,
|
||||
"blocked_keywords": ["ضمان 100", "نتائج مضمونة", "رقم الهوية", "iban"],
|
||||
"weekly_message_cap_per_contact": 2,
|
||||
"min_cohort_for_benchmarks": 5,
|
||||
}
|
||||
|
||||
|
||||
def profile_from_dict(data: dict[str, Any]) -> ClientGrowthProfile:
|
||||
"""Build a profile from a dict; missing optional fields fall back to defaults."""
|
||||
return ClientGrowthProfile(
|
||||
customer_id=str(data.get("customer_id") or ""),
|
||||
company_name=str(data.get("company_name") or ""),
|
||||
sector=str(data.get("sector") or "").lower().strip(),
|
||||
city=str(data.get("city") or "").strip(),
|
||||
offer_one_liner=str(data.get("offer_one_liner") or "").strip(),
|
||||
ideal_customer=str(data.get("ideal_customer") or "").strip(),
|
||||
average_deal_size_sar=float(data.get("average_deal_size_sar") or 0),
|
||||
current_channels=tuple(data.get("current_channels") or ()),
|
||||
sales_cycle_days=int(data.get("sales_cycle_days") or 30),
|
||||
common_objections=tuple(data.get("common_objections") or ()),
|
||||
approval_rules=data.get("approval_rules") or dict(_DEFAULT_APPROVAL_RULES),
|
||||
compliance_rules=data.get("compliance_rules") or dict(_DEFAULT_COMPLIANCE_RULES),
|
||||
)
|
||||
|
||||
|
||||
def build_demo_profile(*, customer_id: str = "demo") -> ClientGrowthProfile:
|
||||
"""Deterministic demo profile — used in /docs and test fixtures."""
|
||||
return ClientGrowthProfile(
|
||||
customer_id=customer_id,
|
||||
company_name="Demo Saudi B2B Co.",
|
||||
sector="real_estate",
|
||||
city="الرياض",
|
||||
offer_one_liner="منصة سعودية لتشغيل الإيرادات + اكتشاف فرص B2B",
|
||||
ideal_customer="شركات تطوير عقاري متوسطة، 50-200 موظف، مهتمة بـ pre-sales pipeline",
|
||||
average_deal_size_sar=85_000,
|
||||
current_channels=("whatsapp", "email"),
|
||||
sales_cycle_days=45,
|
||||
common_objections=(
|
||||
"السعر عالي",
|
||||
"كلم الشريك",
|
||||
"بعد العيد",
|
||||
"وش يضمن النتائج؟",
|
||||
"أرسل العرض واتساب",
|
||||
),
|
||||
approval_rules=dict(_DEFAULT_APPROVAL_RULES),
|
||||
compliance_rules=dict(_DEFAULT_COMPLIANCE_RULES),
|
||||
)
|
||||
@ -0,0 +1,162 @@
|
||||
"""
|
||||
Contact Importer — safely intake uploaded customer phone/email lists.
|
||||
|
||||
Steps:
|
||||
1. normalize_phone — Saudi-friendly E.164 normalizer
|
||||
2. dedupe_contacts — drop exact phone duplicates (keep richest record)
|
||||
3. classify_contact_source — existing / lead / inbound / event / cold / unknown
|
||||
4. detect_opt_out — flags contacts marked as opted-out / blocked
|
||||
5. summarize_import — top-level report ready for the dashboard
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
from typing import Any
|
||||
|
||||
# ── Phone normalization ──────────────────────────────────────────
|
||||
_DIGITS_RE = re.compile(r"\D+")
|
||||
|
||||
|
||||
def normalize_phone(raw: str | None) -> str:
|
||||
"""
|
||||
Normalize Saudi phone numbers to E.164-like form starting with 966.
|
||||
|
||||
Accepts: +966500000001, 0500000001, 500000001, 00966500000001,
|
||||
+966 (50) 000-0001, etc.
|
||||
Returns: bare digits (e.g. "966500000001") or "" if invalid.
|
||||
"""
|
||||
if not raw:
|
||||
return ""
|
||||
s = _DIGITS_RE.sub("", str(raw))
|
||||
if not s:
|
||||
return ""
|
||||
# Strip leading 00 (international prefix)
|
||||
if s.startswith("00"):
|
||||
s = s[2:]
|
||||
# Already starts with 966
|
||||
if s.startswith("966") and len(s) == 12:
|
||||
return s
|
||||
# Local 0-prefixed (e.g. 0512345678)
|
||||
if s.startswith("0") and len(s) == 10:
|
||||
return "966" + s[1:]
|
||||
# Bare 9-digit local mobile (e.g. 512345678)
|
||||
if len(s) == 9 and s.startswith("5"):
|
||||
return "966" + s
|
||||
# Already bare with country code but no leading +
|
||||
if len(s) == 12 and s.startswith("966"):
|
||||
return s
|
||||
return s if 10 <= len(s) <= 15 else ""
|
||||
|
||||
|
||||
# ── Dedup ────────────────────────────────────────────────────────
|
||||
def dedupe_contacts(contacts: list[dict[str, Any]]) -> list[dict[str, Any]]:
|
||||
"""
|
||||
Drop exact phone duplicates. When two records share a phone, keep the one
|
||||
with more non-empty fields (richer record).
|
||||
"""
|
||||
seen: dict[str, dict[str, Any]] = {}
|
||||
for c in contacts:
|
||||
phone = normalize_phone(c.get("phone", ""))
|
||||
if not phone:
|
||||
# Records with no phone are kept as-is, keyed by name+email
|
||||
key = f"name:{c.get('name','').strip().lower()}|email:{c.get('email','').strip().lower()}"
|
||||
if key not in seen:
|
||||
seen[key] = c
|
||||
continue
|
||||
c_norm = dict(c)
|
||||
c_norm["phone"] = phone
|
||||
existing = seen.get(phone)
|
||||
if existing is None:
|
||||
seen[phone] = c_norm
|
||||
else:
|
||||
existing_filled = sum(1 for v in existing.values() if v)
|
||||
new_filled = sum(1 for v in c_norm.values() if v)
|
||||
if new_filled > existing_filled:
|
||||
seen[phone] = c_norm
|
||||
return list(seen.values())
|
||||
|
||||
|
||||
# ── Source classification ────────────────────────────────────────
|
||||
SOURCE_LABELS: tuple[str, ...] = (
|
||||
"existing_customer",
|
||||
"old_lead",
|
||||
"inbound_lead",
|
||||
"event_lead",
|
||||
"cold_list",
|
||||
"referral",
|
||||
"unknown",
|
||||
)
|
||||
|
||||
|
||||
def classify_contact_source(contact: dict[str, Any]) -> str:
|
||||
"""Classify a contact's source. Conservative: unknown by default."""
|
||||
src = str(contact.get("source", "")).lower().strip()
|
||||
rel = str(contact.get("relationship_status", "")).lower().strip()
|
||||
last = contact.get("last_contacted_at")
|
||||
|
||||
if rel in ("existing", "customer", "client", "active") or src in (
|
||||
"existing_customer", "customer", "active_customer",
|
||||
):
|
||||
return "existing_customer"
|
||||
if rel in ("inbound", "form_submission") or src in (
|
||||
"inbound", "website_form", "form_submission",
|
||||
):
|
||||
return "inbound_lead"
|
||||
if src in ("event", "exhibition", "conference", "trade_show"):
|
||||
return "event_lead"
|
||||
if src in ("referral", "introduction"):
|
||||
return "referral"
|
||||
if rel in ("lead", "prospect") or last:
|
||||
return "old_lead"
|
||||
if src in ("cold", "scraped", "purchased_list"):
|
||||
return "cold_list"
|
||||
return "unknown"
|
||||
|
||||
|
||||
# ── Opt-out detection ────────────────────────────────────────────
|
||||
_OPT_OUT_TOKENS = {
|
||||
"opt_out", "opted_out", "unsubscribed", "blocked", "do_not_contact",
|
||||
"stop", "remove", "إلغاء", "اشتراك", "ايقاف", "إيقاف",
|
||||
}
|
||||
|
||||
|
||||
def detect_opt_out(contact: dict[str, Any]) -> bool:
|
||||
"""Return True if the record is flagged as opted-out / blocked."""
|
||||
flag = str(contact.get("opt_in_status", "")).lower().strip()
|
||||
if flag in _OPT_OUT_TOKENS:
|
||||
return True
|
||||
if str(contact.get("status", "")).lower() in _OPT_OUT_TOKENS:
|
||||
return True
|
||||
notes = str(contact.get("notes", "")).lower()
|
||||
if any(tok in notes for tok in _OPT_OUT_TOKENS):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
# ── Summary ──────────────────────────────────────────────────────
|
||||
def summarize_import(contacts: list[dict[str, Any]]) -> dict[str, Any]:
|
||||
"""Top-level report for the upload dashboard. Pure function."""
|
||||
total = len(contacts)
|
||||
deduped = dedupe_contacts(contacts)
|
||||
by_source: dict[str, int] = {label: 0 for label in SOURCE_LABELS}
|
||||
opt_out_count = 0
|
||||
invalid_phone = 0
|
||||
|
||||
for c in deduped:
|
||||
if detect_opt_out(c):
|
||||
opt_out_count += 1
|
||||
if not c.get("phone") or len(str(c.get("phone"))) < 9:
|
||||
invalid_phone += 1
|
||||
src = classify_contact_source(c)
|
||||
by_source[src] = by_source.get(src, 0) + 1
|
||||
|
||||
return {
|
||||
"raw_total": total,
|
||||
"after_dedupe": len(deduped),
|
||||
"duplicates_removed": total - len(deduped),
|
||||
"invalid_phone": invalid_phone,
|
||||
"opt_out_count": opt_out_count,
|
||||
"by_source": by_source,
|
||||
"ready_to_review": len(deduped) - opt_out_count - invalid_phone,
|
||||
}
|
||||
186
dealix/auto_client_acquisition/growth_operator/contactability.py
Normal file
186
dealix/auto_client_acquisition/growth_operator/contactability.py
Normal file
@ -0,0 +1,186 @@
|
||||
"""
|
||||
Contactability — per-contact "can we contact?" decision with PDPL reasons.
|
||||
|
||||
Default policy: **no cold WhatsApp** without lawful basis.
|
||||
PDPL Art.5 emphasizes lawful basis, consent, and purpose limitation.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
from auto_client_acquisition.growth_operator.contact_importer import (
|
||||
classify_contact_source,
|
||||
detect_opt_out,
|
||||
normalize_phone,
|
||||
)
|
||||
|
||||
# ── Decision labels ──────────────────────────────────────────────
|
||||
CONTACTABILITY_LABELS: tuple[str, ...] = (
|
||||
"safe", # consent + lawful basis verified
|
||||
"needs_review", # source unclear; pending operator confirmation
|
||||
"blocked", # opt-out / banned / invalid / breaches policy
|
||||
)
|
||||
|
||||
|
||||
def score_contactability(
|
||||
contact: dict[str, Any],
|
||||
*,
|
||||
channel: str = "whatsapp",
|
||||
require_consent_for_cold_whatsapp: bool = True,
|
||||
) -> dict[str, Any]:
|
||||
"""
|
||||
Decide whether this contact can be approached on this channel today.
|
||||
|
||||
Returns:
|
||||
{
|
||||
"label": "safe"|"needs_review"|"blocked",
|
||||
"channel": "...",
|
||||
"reasons": [...], # human-readable Arabic reasons
|
||||
"next_action": "...", # what the operator should do
|
||||
}
|
||||
"""
|
||||
reasons: list[str] = []
|
||||
label: str = "safe"
|
||||
|
||||
# 1) Opt-out / banned wins everything
|
||||
if detect_opt_out(contact):
|
||||
return {
|
||||
"label": "blocked",
|
||||
"channel": channel,
|
||||
"reasons": ["العميل سجل opt-out أو محظور — لا تواصل بأي شكل."],
|
||||
"next_action": "remove_from_lists",
|
||||
}
|
||||
|
||||
# 2) Phone validity
|
||||
phone = normalize_phone(contact.get("phone"))
|
||||
if channel == "whatsapp" and not phone:
|
||||
return {
|
||||
"label": "blocked",
|
||||
"channel": channel,
|
||||
"reasons": ["لا يوجد رقم صالح — WhatsApp مستحيل."],
|
||||
"next_action": "remove_or_collect_phone",
|
||||
}
|
||||
|
||||
# 3) Source classification
|
||||
src = classify_contact_source(contact)
|
||||
|
||||
# Cold WhatsApp without consent → blocked
|
||||
if channel == "whatsapp" and require_consent_for_cold_whatsapp:
|
||||
if src == "cold_list":
|
||||
return {
|
||||
"label": "blocked",
|
||||
"channel": channel,
|
||||
"reasons": [
|
||||
"WhatsApp البارد ممنوع بدون lawful basis (PDPL م.5).",
|
||||
"السياسة: لا cold WhatsApp افتراضياً.",
|
||||
],
|
||||
"next_action": "switch_to_email_or_get_consent",
|
||||
}
|
||||
if src == "unknown":
|
||||
return {
|
||||
"label": "needs_review",
|
||||
"channel": channel,
|
||||
"reasons": [
|
||||
"مصدر الرقم غير محدد — يحتاج توثيق lawful basis.",
|
||||
"ارجع للمشغّل لإقرار العلاقة قبل الإرسال.",
|
||||
],
|
||||
"next_action": "operator_confirms_source",
|
||||
}
|
||||
|
||||
# 4) Healthy paths
|
||||
if src in ("existing_customer", "inbound_lead", "referral"):
|
||||
return {
|
||||
"label": "safe",
|
||||
"channel": channel,
|
||||
"reasons": [
|
||||
f"علاقة قائمة ({src}) — أساس قانوني قائم لـ business contact.",
|
||||
],
|
||||
"next_action": "draft_message_with_approval",
|
||||
}
|
||||
if src == "old_lead":
|
||||
last = contact.get("last_contacted_at")
|
||||
if last:
|
||||
reasons.append("lead سابق — تواصل ضمن نافذة شهور قابلة للتبرير.")
|
||||
label = "safe"
|
||||
else:
|
||||
reasons.append("lead سابق بدون تاريخ تواصل — يحتاج warm-up قصير.")
|
||||
label = "needs_review"
|
||||
return {
|
||||
"label": label,
|
||||
"channel": channel,
|
||||
"reasons": reasons,
|
||||
"next_action": (
|
||||
"draft_short_followup_with_approval" if label == "safe"
|
||||
else "operator_confirms_continuity"
|
||||
),
|
||||
}
|
||||
if src == "event_lead":
|
||||
return {
|
||||
"label": "safe",
|
||||
"channel": channel,
|
||||
"reasons": ["lead من فعالية مع موافقة ضمنية على المتابعة بـ 30 يوم."],
|
||||
"next_action": "draft_event_followup_with_approval",
|
||||
}
|
||||
|
||||
# 5) Email channel — more permissive (List-Unsubscribe header makes it safer)
|
||||
if channel == "email":
|
||||
if src == "unknown":
|
||||
return {
|
||||
"label": "needs_review",
|
||||
"channel": "email",
|
||||
"reasons": ["مصدر غير محدد — أرسل عبر إيميل مع List-Unsubscribe إن قبلت."],
|
||||
"next_action": "operator_confirms_source",
|
||||
}
|
||||
return {
|
||||
"label": "safe",
|
||||
"channel": "email",
|
||||
"reasons": [f"مصدر مقبول للإيميل B2B ({src})."],
|
||||
"next_action": "draft_email_with_approval",
|
||||
}
|
||||
|
||||
# Fallback (defensive)
|
||||
return {
|
||||
"label": "needs_review",
|
||||
"channel": channel,
|
||||
"reasons": ["لا تطابق سياسة معروفة — يحتاج مراجعة المشغّل."],
|
||||
"next_action": "operator_review_required",
|
||||
}
|
||||
|
||||
|
||||
def contactability_summary(
|
||||
contacts: list[dict[str, Any]],
|
||||
*,
|
||||
channel: str = "whatsapp",
|
||||
) -> dict[str, Any]:
|
||||
"""Bulk classification report for the upload dashboard."""
|
||||
counts: dict[str, int] = {label: 0 for label in CONTACTABILITY_LABELS}
|
||||
next_actions: dict[str, int] = {}
|
||||
sample_blocked: list[dict[str, Any]] = []
|
||||
sample_review: list[dict[str, Any]] = []
|
||||
sample_safe: list[dict[str, Any]] = []
|
||||
|
||||
for c in contacts:
|
||||
decision = score_contactability(c, channel=channel)
|
||||
counts[decision["label"]] += 1
|
||||
next_actions[decision["next_action"]] = next_actions.get(decision["next_action"], 0) + 1
|
||||
if decision["label"] == "blocked" and len(sample_blocked) < 5:
|
||||
sample_blocked.append({**c, **decision})
|
||||
elif decision["label"] == "needs_review" and len(sample_review) < 5:
|
||||
sample_review.append({**c, **decision})
|
||||
elif decision["label"] == "safe" and len(sample_safe) < 5:
|
||||
sample_safe.append({**c, **decision})
|
||||
|
||||
return {
|
||||
"channel": channel,
|
||||
"total": len(contacts),
|
||||
"by_label": counts,
|
||||
"by_next_action": next_actions,
|
||||
"sample_safe": sample_safe,
|
||||
"sample_review": sample_review,
|
||||
"sample_blocked": sample_blocked,
|
||||
"policy_note": (
|
||||
"لا cold WhatsApp بدون lawful basis — السياسة الافتراضية. "
|
||||
"العميل يقدر يعدل القاعدة لكل قائمة بعد توثيق المصدر."
|
||||
),
|
||||
}
|
||||
@ -0,0 +1,149 @@
|
||||
"""
|
||||
Meeting Operator — agenda + calendar draft + post-meeting follow-up.
|
||||
|
||||
Pure drafting only. No live Google Calendar event creation here —
|
||||
the actual `events.insert` happens elsewhere (and only after explicit
|
||||
user authorization via OAuth).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from datetime import datetime, timedelta, timezone
|
||||
from typing import Any
|
||||
|
||||
|
||||
def build_meeting_agenda(
|
||||
*,
|
||||
contact_name: str,
|
||||
company: str,
|
||||
purpose_ar: str = "اكتشاف وتأهيل أولي",
|
||||
duration_minutes: int = 20,
|
||||
) -> dict[str, Any]:
|
||||
"""Generate a deterministic Saudi-friendly agenda."""
|
||||
if duration_minutes <= 15:
|
||||
slots_ar = [
|
||||
"تعارف سريع (٢ دقائق)",
|
||||
"فهم وضع الشركة الحالي (٥ دقائق)",
|
||||
"عرض موجز لـ Dealix (٥ دقائق)",
|
||||
"تحديد الخطوة التالية (٣ دقائق)",
|
||||
]
|
||||
elif duration_minutes <= 30:
|
||||
slots_ar = [
|
||||
"تعارف وأهداف الاجتماع (٣ دقائق)",
|
||||
f"الوضع الحالي لدى {company} (٧ دقائق)",
|
||||
"كيف يدعم Dealix هدفكم (١٠ دقائق)",
|
||||
"أسئلة مفتوحة (٥ دقائق)",
|
||||
"الخطوات التالية + توقيت المتابعة (٥ دقائق)",
|
||||
]
|
||||
else:
|
||||
slots_ar = [
|
||||
"تعارف وأهداف الاجتماع (٥ دقائق)",
|
||||
f"التشخيص العميق لـ {company} (١٥ دقيقة)",
|
||||
"عرض demo حي مع سيناريو فعلي (١٥ دقيقة)",
|
||||
"ROI breakdown (٥ دقائق)",
|
||||
"أسئلة + تحديات تنفيذية (١٠ دقائق)",
|
||||
"الخطة المقترحة + الموافقات المطلوبة (١٠ دقائق)",
|
||||
]
|
||||
return {
|
||||
"title_ar": f"اجتماع Dealix × {company}",
|
||||
"purpose_ar": purpose_ar,
|
||||
"duration_minutes": duration_minutes,
|
||||
"agenda_ar": slots_ar,
|
||||
"attendees_suggested_ar": [contact_name, "مؤسس / مدير مبيعات Dealix"],
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
|
||||
|
||||
def build_calendar_draft(
|
||||
*,
|
||||
contact_email: str | None,
|
||||
contact_name: str,
|
||||
company: str,
|
||||
proposed_start_iso: str | None = None,
|
||||
duration_minutes: int = 20,
|
||||
) -> dict[str, Any]:
|
||||
"""
|
||||
Build a Google-Calendar-shaped draft (NOT inserted live).
|
||||
|
||||
Suggests the next business hour slot if no start is provided.
|
||||
Real `events.insert` happens only after the operator approves AND
|
||||
has authorized Calendar OAuth.
|
||||
"""
|
||||
if proposed_start_iso:
|
||||
try:
|
||||
start_dt = datetime.fromisoformat(proposed_start_iso.replace("Z", "+00:00")).replace(tzinfo=None)
|
||||
except ValueError:
|
||||
start_dt = _next_business_hour()
|
||||
else:
|
||||
start_dt = _next_business_hour()
|
||||
end_dt = start_dt + timedelta(minutes=duration_minutes)
|
||||
|
||||
summary_ar = f"اجتماع Dealix × {company}"
|
||||
description_ar = (
|
||||
f"اجتماع مع {contact_name} من {company} لاستكشاف فرصة استخدام "
|
||||
f"Dealix لتشغيل النمو. مدة الاجتماع: {duration_minutes} دقيقة."
|
||||
)
|
||||
return {
|
||||
"summary": summary_ar,
|
||||
"description": description_ar,
|
||||
"start": {
|
||||
"dateTime": start_dt.isoformat(),
|
||||
"timeZone": "Asia/Riyadh",
|
||||
},
|
||||
"end": {
|
||||
"dateTime": end_dt.isoformat(),
|
||||
"timeZone": "Asia/Riyadh",
|
||||
},
|
||||
"attendees": [
|
||||
{"email": contact_email} for contact_email in [contact_email] if contact_email
|
||||
],
|
||||
"conference_data_request": {
|
||||
"createRequest": {
|
||||
"requestId": f"dealix-meet-{int(start_dt.timestamp())}",
|
||||
"conferenceSolutionKey": {"type": "hangoutsMeet"},
|
||||
}
|
||||
},
|
||||
"live_inserted": False,
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
"compliance_note_ar": (
|
||||
"draft فقط — لا يُنشأ event حي في Google Calendar حتى موافقة "
|
||||
"OAuth صريحة + ضغطة المستخدم 'أنشئ الاجتماع'."
|
||||
),
|
||||
}
|
||||
|
||||
|
||||
def build_post_meeting_followup(
|
||||
*,
|
||||
contact_name: str,
|
||||
company: str,
|
||||
summary_ar: str,
|
||||
next_step_ar: str = "أرسل recap + pilot offer",
|
||||
) -> dict[str, Any]:
|
||||
"""Generate the post-meeting follow-up draft."""
|
||||
body_ar = (
|
||||
f"شكراً أستاذ {contact_name} على وقتكم الصباحي.\n\n"
|
||||
f"خلاصة الاجتماع:\n{summary_ar}\n\n"
|
||||
f"الخطوة التالية: {next_step_ar}\n\n"
|
||||
f"نسعد بمتابعة الموضوع متى ناسبكم."
|
||||
)
|
||||
return {
|
||||
"channel_recommendation": "email",
|
||||
"subject_ar": f"شكراً {contact_name} — متابعة اجتماع {company}",
|
||||
"body_ar": body_ar,
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
|
||||
|
||||
# ── Internal helpers ────────────────────────────────────────────
|
||||
def _next_business_hour(*, now: datetime | None = None) -> datetime:
|
||||
"""Next 09:00-17:00 Riyadh slot (demo helper; not timezone-perfect)."""
|
||||
n = now or datetime.now(timezone.utc).replace(tzinfo=None)
|
||||
# Push to next day 10am UTC ~ 1pm Riyadh — safe demo slot
|
||||
candidate = (n + timedelta(days=1)).replace(hour=10, minute=0, second=0, microsecond=0)
|
||||
# Skip Friday (Saudi weekend = Fri-Sat)
|
||||
while candidate.weekday() in (4, 5):
|
||||
candidate += timedelta(days=1)
|
||||
return candidate
|
||||
@ -0,0 +1,265 @@
|
||||
"""
|
||||
Saudi Message Engine — Arabic drafts that don't sound like spam.
|
||||
|
||||
Style rules (encoded in templates):
|
||||
- short (≤4 sentences for first message)
|
||||
- non-exaggerated (no "ضمان 100%", no "نتائج مضمونة")
|
||||
- explicit reason for outreach (not generic)
|
||||
- simple ask (one CTA, low-commitment)
|
||||
- sector-aware tone
|
||||
- approval_required = True ALWAYS
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
from typing import Any
|
||||
|
||||
|
||||
# ── Saudi B2B opening line bank — sector-aware ──────────────────
|
||||
_OPENERS_BY_SECTOR_AR: dict[str, list[str]] = {
|
||||
"real_estate": [
|
||||
"السلام عليكم أستاذ {name}،\nلاحظت أنكم تتوسعون في {city}.",
|
||||
"مرحباً أستاذ {name}،\nمتابع نشاطكم في تطوير العقار في {city}.",
|
||||
],
|
||||
"clinics": [
|
||||
"السلام عليكم دكتور {name}،\nشاهدت تطور خدمات العيادة في {city}.",
|
||||
"مرحباً دكتور {name}،\nأقدر اهتمامكم بتجربة المرضى في {city}.",
|
||||
],
|
||||
"logistics": [
|
||||
"السلام عليكم أستاذ {name}،\nلاحظت توسعكم في خدمات الشحن في {city}.",
|
||||
"مرحباً أستاذ {name}،\nقطاع اللوجستيات في {city} يتحرك بسرعة.",
|
||||
],
|
||||
"training": [
|
||||
"السلام عليكم أستاذ {name}،\nمتابع أثر برامجكم التدريبية في {city}.",
|
||||
"مرحباً أستاذ {name}،\nالطلب على التدريب الـ B2B يتزايد في {city}.",
|
||||
],
|
||||
"default": [
|
||||
"السلام عليكم أستاذ {name}،\nمتابع نشاطكم في {city}.",
|
||||
"مرحباً أستاذ {name}،\nلاحظت تطوركم في {city}.",
|
||||
],
|
||||
}
|
||||
|
||||
# A single short reason + ask combo. Keep under 4 sentences total.
|
||||
_REASON_TEMPLATES_AR: dict[str, str] = {
|
||||
"existing_customer": "باعتبار العلاقة القائمة معكم، عندي اقتراح سريع يخدم {goal}.",
|
||||
"inbound_lead": "بناءً على اهتمامكم الأخير، عندي خطوة واضحة لتسريع {goal}.",
|
||||
"referral": "وصلتني توصية مهنية للتواصل معكم بخصوص {goal}.",
|
||||
"event_lead": "بعد لقائنا الأخير، حضّرت اقتراح صغير يخدم {goal}.",
|
||||
"old_lead": "بمناسبة الموسم الجديد، عندي تحديث يهم {goal}.",
|
||||
"unknown": "بعد البحث في خدماتكم، عندي فرضية صغيرة تخدم {goal}.",
|
||||
"cold_list": "بعد البحث في خدماتكم، عندي فرضية صغيرة تخدم {goal}.",
|
||||
}
|
||||
|
||||
_ASK_TEMPLATES_AR: list[str] = [
|
||||
"يناسبك أرسل لك مثال سريع؟",
|
||||
"هل ١٥ دقيقة الأسبوع الجاي مناسبة لمشاركة الفكرة؟",
|
||||
"تفضّل أرسل ملخص بصفحة واحدة أو نتفق على مكالمة قصيرة؟",
|
||||
]
|
||||
|
||||
|
||||
def _pick(seq: list[str], seed: str) -> str:
|
||||
"""Deterministic choice — same seed → same pick."""
|
||||
if not seq:
|
||||
return ""
|
||||
h = hashlib.md5(seed.encode("utf-8")).digest()
|
||||
return seq[h[0] % len(seq)]
|
||||
|
||||
|
||||
def _resolve_name(contact: dict[str, Any]) -> str:
|
||||
n = (contact.get("name") or "").strip()
|
||||
if not n:
|
||||
return "الفاضل"
|
||||
parts = n.split()
|
||||
return parts[0] if parts else n
|
||||
|
||||
|
||||
def _resolve_city(contact: dict[str, Any], default: str = "السعودية") -> str:
|
||||
return (contact.get("city") or default).strip()
|
||||
|
||||
|
||||
def _resolve_sector(contact: dict[str, Any], default: str = "default") -> str:
|
||||
s = (contact.get("sector") or default).lower().strip()
|
||||
return s if s in _OPENERS_BY_SECTOR_AR else "default"
|
||||
|
||||
|
||||
# ── Public API ──────────────────────────────────────────────────
|
||||
def draft_arabic_message(
|
||||
contact: dict[str, Any],
|
||||
*,
|
||||
profile: dict[str, Any] | None = None,
|
||||
source: str | None = None,
|
||||
goal_ar: str = "تشغيل نمو B2B بلا إرسال عشوائي",
|
||||
) -> dict[str, Any]:
|
||||
"""
|
||||
Build a Saudi-tone Arabic outreach draft.
|
||||
|
||||
- profile: optional ClientGrowthProfile.to_dict() for offer context
|
||||
- source: classify_contact_source override; auto-derived if None
|
||||
"""
|
||||
from auto_client_acquisition.growth_operator.contact_importer import (
|
||||
classify_contact_source,
|
||||
)
|
||||
|
||||
src = source or classify_contact_source(contact)
|
||||
name = _resolve_name(contact)
|
||||
city = _resolve_city(contact)
|
||||
sector = _resolve_sector(contact)
|
||||
seed = f"{contact.get('phone','')}{contact.get('name','')}{src}"
|
||||
opener = _pick(_OPENERS_BY_SECTOR_AR[sector], seed).format(name=name, city=city)
|
||||
reason = _REASON_TEMPLATES_AR.get(src, _REASON_TEMPLATES_AR["unknown"]).format(goal=goal_ar)
|
||||
ask = _pick(_ASK_TEMPLATES_AR, seed + "ask")
|
||||
|
||||
offer_line = ""
|
||||
if profile and profile.get("offer_one_liner"):
|
||||
offer_line = f"\n\nنحن: {profile['offer_one_liner']}."
|
||||
|
||||
body_ar = f"{opener}\n\n{reason}{offer_line}\n\n{ask}"
|
||||
return {
|
||||
"channel_recommendation": "whatsapp" if contact.get("phone") else "email",
|
||||
"subject_ar": None,
|
||||
"body_ar": body_ar,
|
||||
"source_classification": src,
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
"guardrails_ar": [
|
||||
"لا تُرسل قبل موافقة المشغّل.",
|
||||
"لا تستخدم في WhatsApp البارد بدون lawful basis.",
|
||||
"احذف أي مبالغة قبل الإرسال.",
|
||||
],
|
||||
"estimated_length_chars": len(body_ar),
|
||||
}
|
||||
|
||||
|
||||
def draft_followup(
|
||||
contact: dict[str, Any],
|
||||
*,
|
||||
days_since_last: int,
|
||||
last_outcome: str = "no_reply",
|
||||
) -> dict[str, Any]:
|
||||
"""Short follow-up draft based on last outcome."""
|
||||
name = _resolve_name(contact)
|
||||
seed = f"f{contact.get('phone','')}{last_outcome}{days_since_last}"
|
||||
|
||||
if last_outcome == "no_reply" and days_since_last <= 3:
|
||||
body = (
|
||||
f"السلام عليكم أستاذ {name}،\n\n"
|
||||
"أعرف أن جدولكم مزدحم. لو الفكرة لا تناسب الآن، أقدر أرسل ملخص "
|
||||
"بصفحة واحدة تراجعونه على راحتكم. هل أرسل؟"
|
||||
)
|
||||
elif last_outcome == "no_reply":
|
||||
body = (
|
||||
f"السلام عليكم أستاذ {name}،\n\n"
|
||||
f"مر {days_since_last} يوم على رسالتي السابقة. لو لا يناسب الآن، "
|
||||
"أقدر أعود في التوقيت الأنسب لكم — متى يناسب؟"
|
||||
)
|
||||
elif last_outcome == "objection":
|
||||
body = (
|
||||
f"شكراً أستاذ {name} على وضوحكم. "
|
||||
"بناءً على ما ذكرتم، حضّرت توضيح مختصر يجاوب على نقطتكم تحديداً. "
|
||||
"هل أرسل؟"
|
||||
)
|
||||
elif last_outcome == "positive":
|
||||
body = (
|
||||
f"شكراً أستاذ {name}. "
|
||||
"أحجز ١٥ دقيقة هذا الأسبوع لمناقشة الخطوة التالية — متى يناسبك؟"
|
||||
)
|
||||
else:
|
||||
body = (
|
||||
f"السلام عليكم أستاذ {name}،\n\n"
|
||||
f"تابعت معكم سابقاً. لو فيه تحديث، يسعدني أعرف."
|
||||
)
|
||||
|
||||
return {
|
||||
"body_ar": body,
|
||||
"purpose": f"followup_{last_outcome}_d{days_since_last}",
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
|
||||
|
||||
# ── Objection-to-Action library ─────────────────────────────────
|
||||
_OBJECTION_RESPONSES_AR: dict[str, dict[str, Any]] = {
|
||||
"send_offer_whatsapp": {
|
||||
"interpretation_ar": "اهتمام متوسط — ليس إغلاق، لكن مفتوح للمعلومات.",
|
||||
"response_ar": (
|
||||
"تمام، أرسل خلال دقائق ملف صفحتين بالعربي + voice note قصير "
|
||||
"يشرح أهم ٣ نقاط. ثم نتفق على متابعة بعد يومين."
|
||||
),
|
||||
"next_action": "send_pdf_then_followup_in_2d",
|
||||
"score_delta": +5,
|
||||
},
|
||||
"after_eid": {
|
||||
"interpretation_ar": "تأجيل ثقافي مفهوم — احترم التوقيت السعودي.",
|
||||
"response_ar": (
|
||||
"إن شاء الله. أسجل تذكير لـ بعد العيد بأسبوع، وأرسل لكم Pulse "
|
||||
"الشهري حتى ذلك الحين. كل عام وأنتم بخير."
|
||||
),
|
||||
"next_action": "schedule_post_eid_followup",
|
||||
"score_delta": +1,
|
||||
},
|
||||
"talk_to_partner": {
|
||||
"interpretation_ar": "stakeholder جديد — يحتاج intro + ملف موجز.",
|
||||
"response_ar": (
|
||||
"محترم — أحضّر لكم ملف من صفحتين بالعربي مهيأ للعرض على الشريك. "
|
||||
"هل أرسله مباشرة لكم أو نعمل اجتماع ثلاثي قصير؟"
|
||||
),
|
||||
"next_action": "arm_champion_with_2page_brief",
|
||||
"score_delta": +3,
|
||||
},
|
||||
"price_high": {
|
||||
"interpretation_ar": "اعتراض قيمة — يحتاج ROI breakdown، ليس خصم.",
|
||||
"response_ar": (
|
||||
"حقكم تركّزون على القيمة. أرسل ROI breakdown يوضح تكلفة الـ lead "
|
||||
"المؤهل لدينا مقارنة بالبدائل. توافقون؟"
|
||||
),
|
||||
"next_action": "send_roi_breakdown",
|
||||
"score_delta": +5,
|
||||
},
|
||||
"have_vendor": {
|
||||
"interpretation_ar": "منافس قائم — اسأل عن الفجوة الفعلية.",
|
||||
"response_ar": (
|
||||
"ممتاز — مع مَن؟ والسؤال المهم: هل الـ leads مؤهلة فعلاً أم form fills؟ "
|
||||
"إن فيه فجوة، نقدر نكمل وليس نستبدل. مجاناً نعمل audit."
|
||||
),
|
||||
"next_action": "offer_free_audit_position_as_complement",
|
||||
"score_delta": +2,
|
||||
},
|
||||
"no_need": {
|
||||
"interpretation_ar": "رفض/توقيت — الأنسب nurture بدون ضغط.",
|
||||
"response_ar": (
|
||||
"متفهم تماماً. نسجلكم في Pulse الشهري المجاني، ونعود حين تتغير "
|
||||
"الأولويات. شاكرين وقتكم."
|
||||
),
|
||||
"next_action": "nurture_via_monthly_pulse",
|
||||
"score_delta": -2,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def draft_objection_response(
|
||||
objection_id: str,
|
||||
*,
|
||||
contact: dict[str, Any] | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Look up an objection and return a Saudi-toned response draft."""
|
||||
obj = _OBJECTION_RESPONSES_AR.get(objection_id)
|
||||
if obj is None:
|
||||
return {
|
||||
"objection_id": objection_id,
|
||||
"interpretation_ar": "اعتراض غير مصنّف — يحتاج تشخيص يدوي.",
|
||||
"response_ar": (
|
||||
"شكراً على وضوحكم. ممكن تشاركوني السبب الرئيسي حتى أعطيكم "
|
||||
"إجابة مناسبة؟"
|
||||
),
|
||||
"next_action": "diagnostic_question",
|
||||
"score_delta": 0,
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
return {
|
||||
"objection_id": objection_id,
|
||||
**obj,
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
@ -0,0 +1,154 @@
|
||||
"""
|
||||
Growth Missions — outcome-shaped tasks instead of features.
|
||||
|
||||
Each mission has: id, title_ar, goal_ar, steps (ordered, approval-gated),
|
||||
expected_duration_days, kill_metric (the ONE number that proves success).
|
||||
|
||||
Pure deterministic. Production wires each step to the relevant agent.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from typing import Any
|
||||
|
||||
|
||||
GROWTH_MISSIONS: tuple[dict[str, Any], ...] = (
|
||||
{
|
||||
"id": "first_10_opportunities",
|
||||
"title_ar": "اطلع لي 10 فرص",
|
||||
"goal_ar": "اكتشاف 10 شركات سعودية مناسبة + رسائل عربية + موافقة + متابعة أسبوع.",
|
||||
"expected_duration_days": 7,
|
||||
"kill_metric": "ten_drafts_approved",
|
||||
"steps_ar": [
|
||||
"تحديد القطاع والمدينة + المعايير الأساسية.",
|
||||
"اكتشاف 30 شركة مرشحة من المصادر المسموحة.",
|
||||
"فلترة لـ 10 بأعلى Why-Now score.",
|
||||
"كتابة 10 رسائل عربية بحالة pending_approval.",
|
||||
"موافقة المشغّل على عينة → إرسال آمن.",
|
||||
"تصنيف الردود + اقتراح متابعة لكل واحدة.",
|
||||
"Proof Pack أسبوعي عند الإغلاق.",
|
||||
],
|
||||
"primary_endpoint": "/api/v1/innovation/opportunities/ten-in-ten",
|
||||
"approval_required": True,
|
||||
},
|
||||
{
|
||||
"id": "recover_stalled_deals",
|
||||
"title_ar": "أنقذ الصفقات المتوقفة",
|
||||
"goal_ar": "اكتشف الصفقات بدون نشاط 14+ يوم + اقترح متابعات multi-thread.",
|
||||
"expected_duration_days": 5,
|
||||
"kill_metric": "stalled_deals_revived",
|
||||
"steps_ar": [
|
||||
"قراءة pipeline الحالي + revenue_graph.leak_detector.",
|
||||
"تصنيف الصفقات: stalled / single-threaded / no-proposal.",
|
||||
"اقتراح multi-thread (DM إضافي داخل الحساب).",
|
||||
"كتابة drafts متابعة pending_approval لكل صفقة.",
|
||||
"موافقة المشغّل → إرسال + جدولة re-check بعد 7 أيام.",
|
||||
],
|
||||
"primary_endpoint": "/api/v1/revenue-os/leaks",
|
||||
"approval_required": True,
|
||||
},
|
||||
{
|
||||
"id": "partnership_sprint",
|
||||
"title_ar": "ابدأ شراكات",
|
||||
"goal_ar": "تحديد + التواصل مع 5 شركاء محتملين خلال أسبوعين.",
|
||||
"expected_duration_days": 14,
|
||||
"kill_metric": "partner_intros_replied",
|
||||
"steps_ar": [
|
||||
"تحديد قطاع العميل + حجمه → اقتراح أنواع شركاء مناسبة.",
|
||||
"ترشيح 5 شركاء محتملين بأعلى strategic_value.",
|
||||
"كتابة outreach warm لكل واحد.",
|
||||
"موافقة المشغّل → إرسال على email.",
|
||||
"متابعة الردود + جدولة 20 دقيقة لكل ردّ إيجابي.",
|
||||
"Partner scorecard أولي بعد المكالمات.",
|
||||
],
|
||||
"primary_endpoint": "/api/v1/growth-operator/partners/suggest",
|
||||
"approval_required": True,
|
||||
},
|
||||
{
|
||||
"id": "safe_whatsapp_campaign",
|
||||
"title_ar": "جهز حملة واتساب آمنة",
|
||||
"goal_ar": "تحويل قائمة العميل إلى حملة WhatsApp يحترم PDPL + opt-in.",
|
||||
"expected_duration_days": 3,
|
||||
"kill_metric": "safe_messages_drafted",
|
||||
"steps_ar": [
|
||||
"رفع قائمة الأرقام عبر contact_importer.",
|
||||
"تنظيف + dedupe + classify_source.",
|
||||
"فحص contactability — إخراج blocked/needs_review.",
|
||||
"كتابة رسائل عربية لكل segment آمن.",
|
||||
"موافقة المشغّل لكل segment على حدة.",
|
||||
"إرسال آمن مع opt-out في كل رسالة.",
|
||||
],
|
||||
"primary_endpoint": "/api/v1/growth-operator/contacts/import-preview",
|
||||
"approval_required": True,
|
||||
},
|
||||
{
|
||||
"id": "meeting_booking_sprint",
|
||||
"title_ar": "احجز لي 3 اجتماعات",
|
||||
"goal_ar": "حجز 3 اجتماعات مع leads أعلى Why-Now خلال 5 أيام عمل.",
|
||||
"expected_duration_days": 5,
|
||||
"kill_metric": "meetings_confirmed",
|
||||
"steps_ar": [
|
||||
"اختيار أعلى 10 leads من Top-10 السابق.",
|
||||
"إعداد agenda + calendar draft لكل واحد.",
|
||||
"كتابة intro + ask مكالمة 15 دقيقة.",
|
||||
"موافقة + إرسال WhatsApp/email.",
|
||||
"تأكيد الحضور قبل الاجتماع بـ 24 ساعة.",
|
||||
"post-meeting follow-up draft.",
|
||||
],
|
||||
"primary_endpoint": "/api/v1/growth-operator/meetings/draft",
|
||||
"approval_required": True,
|
||||
},
|
||||
{
|
||||
"id": "list_cleanup",
|
||||
"title_ar": "ارفع قائمتي ونظفها",
|
||||
"goal_ar": "تحويل ملف غير منظم إلى قائمة contactability-classified جاهزة.",
|
||||
"expected_duration_days": 1,
|
||||
"kill_metric": "safe_contacts_extracted",
|
||||
"steps_ar": [
|
||||
"رفع CSV/Excel.",
|
||||
"normalize_phone + dedupe.",
|
||||
"classify_contact_source لكل سطر.",
|
||||
"score_contactability لكل سطر.",
|
||||
"تقرير: safe / needs_review / blocked + عدد + عينة.",
|
||||
"اقتراح: ابدأ بالـ safe فقط، مع plan لـ needs_review.",
|
||||
],
|
||||
"primary_endpoint": "/api/v1/growth-operator/contacts/import-preview",
|
||||
"approval_required": True,
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
def list_missions() -> dict[str, Any]:
|
||||
"""Return the canonical mission catalog."""
|
||||
return {
|
||||
"count": len(GROWTH_MISSIONS),
|
||||
"missions": list(GROWTH_MISSIONS),
|
||||
"kill_feature_id": "first_10_opportunities",
|
||||
}
|
||||
|
||||
|
||||
def run_mission(mission_id: str, *, payload: dict[str, Any] | None = None) -> dict[str, Any]:
|
||||
"""
|
||||
Plan a mission run — returns the execution outline + first-step
|
||||
prompt for the operator. Does NOT actually execute steps; that's
|
||||
done by routing each step to its primary endpoint.
|
||||
"""
|
||||
mission = next((m for m in GROWTH_MISSIONS if m["id"] == mission_id), None)
|
||||
if mission is None:
|
||||
return {
|
||||
"error": f"unknown_mission: {mission_id}",
|
||||
"available_ids": [m["id"] for m in GROWTH_MISSIONS],
|
||||
}
|
||||
return {
|
||||
"mission_id": mission_id,
|
||||
"title_ar": mission["title_ar"],
|
||||
"goal_ar": mission["goal_ar"],
|
||||
"kill_metric": mission["kill_metric"],
|
||||
"expected_duration_days": mission["expected_duration_days"],
|
||||
"current_step_index": 0,
|
||||
"next_step_ar": mission["steps_ar"][0],
|
||||
"primary_endpoint": mission["primary_endpoint"],
|
||||
"payload_received": payload or {},
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
@ -0,0 +1,163 @@
|
||||
"""
|
||||
Partnership Operator — propose partner types + outreach drafts + scorecard.
|
||||
|
||||
Keep deterministic; partner suggestions come from a curated catalog
|
||||
tuned for Saudi B2B (agencies, consultants, integrators, CRM vendors,
|
||||
founder communities, sector influencers).
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
from typing import Any
|
||||
|
||||
|
||||
PARTNER_TYPES: tuple[dict[str, Any], ...] = (
|
||||
{
|
||||
"key": "marketing_agency",
|
||||
"label_ar": "وكالة تسويق B2B",
|
||||
"rationale_ar": "لديها عملاء يحتاجون lead-gen — Dealix يكمل خدماتها (لا يستبدلها).",
|
||||
"model_ar": "Reseller / Revenue share 20-30%",
|
||||
"ideal_size": "10-50 موظف",
|
||||
},
|
||||
{
|
||||
"key": "sales_consultant",
|
||||
"label_ar": "مستشار مبيعات / مدرب",
|
||||
"rationale_ar": "يحتاج أداة عملية تثبت توصياته للعملاء.",
|
||||
"model_ar": "Affiliate fixed fee + ongoing commission",
|
||||
"ideal_size": "1-5 موظف",
|
||||
},
|
||||
{
|
||||
"key": "tech_integrator",
|
||||
"label_ar": "تكامل تقني / شريك Supabase أو Make.com",
|
||||
"rationale_ar": "ينفّذ التكاملات للعملاء الكبار.",
|
||||
"model_ar": "Implementation revenue share",
|
||||
"ideal_size": "5-20 موظف",
|
||||
},
|
||||
{
|
||||
"key": "crm_vendor",
|
||||
"label_ar": "مزود CRM (Zoho/Salla/Odoo سعودي)",
|
||||
"rationale_ar": "Dealix طبقة نمو فوق الـ CRM، لا منافس مباشر.",
|
||||
"model_ar": "Co-sell + technical alliance",
|
||||
"ideal_size": "30+ موظف",
|
||||
},
|
||||
{
|
||||
"key": "founder_community",
|
||||
"label_ar": "مجتمع مؤسسين سعوديين",
|
||||
"rationale_ar": "الوصول لـ early adopters السعوديين عبر referrals.",
|
||||
"model_ar": "Community partnership + free seats",
|
||||
"ideal_size": "50+ عضو",
|
||||
},
|
||||
{
|
||||
"key": "sector_influencer",
|
||||
"label_ar": "خبير قطاعي (عقار / صحة / لوجستيات)",
|
||||
"rationale_ar": "ثقة جاهزة في القطاع تختصر دورة البيع.",
|
||||
"model_ar": "Equity / advisory + revenue referral",
|
||||
"ideal_size": "1-3 موظف",
|
||||
},
|
||||
)
|
||||
|
||||
|
||||
def suggest_partner_types(
|
||||
*,
|
||||
sector: str = "",
|
||||
customer_size: str = "smb",
|
||||
) -> dict[str, Any]:
|
||||
"""Recommend ranked partner types for the given customer profile."""
|
||||
suggestions = []
|
||||
for p in PARTNER_TYPES:
|
||||
priority = 50
|
||||
if customer_size == "smb" and p["key"] in ("marketing_agency", "sales_consultant", "founder_community"):
|
||||
priority += 25
|
||||
if customer_size == "enterprise" and p["key"] in ("crm_vendor", "tech_integrator"):
|
||||
priority += 25
|
||||
if sector and sector.lower() in ("real_estate", "clinics", "logistics"):
|
||||
if p["key"] == "sector_influencer":
|
||||
priority += 20
|
||||
suggestions.append({**p, "priority": priority})
|
||||
|
||||
suggestions.sort(key=lambda x: x["priority"], reverse=True)
|
||||
return {
|
||||
"sector": sector,
|
||||
"customer_size": customer_size,
|
||||
"suggestions": suggestions[:5],
|
||||
"next_action": "draft_outreach_for_top_3",
|
||||
}
|
||||
|
||||
|
||||
def draft_partner_outreach(
|
||||
*,
|
||||
partner_type_key: str,
|
||||
partner_name: str = "",
|
||||
customer_name: str = "Dealix",
|
||||
) -> dict[str, Any]:
|
||||
"""Generate a warm partnership outreach draft."""
|
||||
pt = next((p for p in PARTNER_TYPES if p["key"] == partner_type_key), None)
|
||||
if pt is None:
|
||||
return {
|
||||
"error": "unknown_partner_type",
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
}
|
||||
|
||||
target = partner_name or pt["label_ar"]
|
||||
seed = hashlib.md5(f"{partner_type_key}{partner_name}".encode()).digest()
|
||||
angle_idx = seed[0] % 2
|
||||
angles_ar = [
|
||||
"تكامل خدماتنا يخدم نفس عملائكم بأقل احتكاك.",
|
||||
"نموذج revenue share واضح + pilot على عميل واحد قبل الالتزام.",
|
||||
]
|
||||
body_ar = (
|
||||
f"السلام عليكم،\n\n"
|
||||
f"أنا من فريق {customer_name}. تابعنا عملكم ووجدناه قريب جداً من جمهورنا.\n\n"
|
||||
f"الفكرة باختصار: {angles_ar[angle_idx]}\n\n"
|
||||
f"هل ١٥-٢٠ دقيقة الأسبوع الجاي مناسبة لاستكشاف فرصة شراكة؟"
|
||||
)
|
||||
return {
|
||||
"partner_type": pt,
|
||||
"channel_recommendation": "email",
|
||||
"body_ar": body_ar,
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
"suggested_next_steps": [
|
||||
"1. رسالة warm",
|
||||
"2. مكالمة 20 دقيقة",
|
||||
"3. عرض partner revenue share",
|
||||
"4. pilot على عميل واحد",
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def partner_scorecard(
|
||||
*,
|
||||
partner_id: str,
|
||||
intros_made: int = 0,
|
||||
deals_influenced: int = 0,
|
||||
revenue_share_paid_sar: float = 0.0,
|
||||
relationship_age_months: int = 0,
|
||||
) -> dict[str, Any]:
|
||||
"""Compute a simple partner-health scorecard."""
|
||||
activity_score = min(100, intros_made * 8 + deals_influenced * 15)
|
||||
longevity_bonus = min(20, relationship_age_months * 2)
|
||||
overall = min(100, activity_score + longevity_bonus)
|
||||
if overall >= 75:
|
||||
tier = "platinum"
|
||||
elif overall >= 50:
|
||||
tier = "gold"
|
||||
elif overall >= 25:
|
||||
tier = "silver"
|
||||
else:
|
||||
tier = "bronze"
|
||||
return {
|
||||
"partner_id": partner_id,
|
||||
"overall_score": overall,
|
||||
"tier": tier,
|
||||
"intros_made": intros_made,
|
||||
"deals_influenced": deals_influenced,
|
||||
"revenue_share_paid_sar": round(revenue_share_paid_sar, 2),
|
||||
"relationship_age_months": relationship_age_months,
|
||||
"next_action_ar": (
|
||||
"احتفظ بالعلاقة بنشاط ثابت — ربع سنوي." if tier in ("platinum", "gold")
|
||||
else "حفّز التفاعل — اقتراح pilot جديد أو إحالة محتملة."
|
||||
),
|
||||
}
|
||||
@ -0,0 +1,97 @@
|
||||
"""
|
||||
Payment-in-Chat — Moyasar payment-link drafts (NO live charge).
|
||||
|
||||
In production: link goes to a Moyasar hosted checkout. The user enters
|
||||
their card on Moyasar's domain (PCI-safe), not inside WhatsApp.
|
||||
|
||||
This module produces a STRUCTURED draft only — the actual
|
||||
`POST /v1/payments` call to Moyasar happens elsewhere with the
|
||||
customer's secret key.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import uuid
|
||||
from typing import Any
|
||||
|
||||
|
||||
# ── Pricing (mirrors landing/pricing.html + business/pricing_strategy.py) ──
|
||||
PLAN_CATALOG_SAR: dict[str, dict[str, Any]] = {
|
||||
"founder_operator": {"label_ar": "مشغّل المؤسس", "amount_sar": 499.0},
|
||||
"growth_os": {"label_ar": "نظام النمو (Growth OS)", "amount_sar": 2999.0},
|
||||
"scale_os": {"label_ar": "نظام التوسّع (Scale OS)", "amount_sar": 7999.0},
|
||||
"performance_pilot": {"label_ar": "Pay-per-Result pilot 30 يوم", "amount_sar": 1.0}, # placeholder
|
||||
}
|
||||
|
||||
|
||||
def sar_to_halalas(amount_sar: float) -> int:
|
||||
"""Convert SAR to halalas (Moyasar's smallest unit). 1 SAR = 100 halalas."""
|
||||
if amount_sar < 0:
|
||||
raise ValueError("amount_sar must be non-negative")
|
||||
return int(round(amount_sar * 100))
|
||||
|
||||
|
||||
def build_moyasar_payment_link_draft(
|
||||
*,
|
||||
plan_key: str,
|
||||
customer_id: str,
|
||||
contact_email: str | None = None,
|
||||
locale: str = "ar",
|
||||
callback_url: str = "https://dealix.sa/payment-success.html",
|
||||
cancel_url: str = "https://dealix.sa/payment-cancelled.html",
|
||||
custom_amount_sar: float | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""
|
||||
Build a Moyasar payment payload (NOT yet sent to Moyasar API).
|
||||
|
||||
Returns a dict the operator can review + approve. The actual
|
||||
`POST /v1/payments` is fired elsewhere by the billing service.
|
||||
"""
|
||||
plan = PLAN_CATALOG_SAR.get(plan_key)
|
||||
if plan is None and custom_amount_sar is None:
|
||||
return {
|
||||
"error": f"unknown_plan: {plan_key}",
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
"live_charged": False,
|
||||
}
|
||||
amount_sar = custom_amount_sar if custom_amount_sar is not None else plan["amount_sar"]
|
||||
label_ar = (plan["label_ar"] if plan else "خطة مخصصة")
|
||||
|
||||
description_ar = (
|
||||
f"اشتراك Dealix — {label_ar}. "
|
||||
f"المبلغ {amount_sar:,.2f} ريال شامل ضريبة القيمة المضافة 15%."
|
||||
)
|
||||
|
||||
return {
|
||||
"moyasar_request_draft": {
|
||||
"amount": sar_to_halalas(amount_sar),
|
||||
"currency": "SAR",
|
||||
"description": description_ar,
|
||||
"callback_url": callback_url,
|
||||
"cancel_url": cancel_url,
|
||||
"metadata": {
|
||||
"customer_id": customer_id,
|
||||
"plan_key": plan_key,
|
||||
"locale": locale,
|
||||
"draft_id": f"draft_pay_{uuid.uuid4().hex[:16]}",
|
||||
},
|
||||
},
|
||||
"amount_sar": amount_sar,
|
||||
"amount_halalas": sar_to_halalas(amount_sar),
|
||||
"label_ar": label_ar,
|
||||
"channel_recommendation": "whatsapp_with_link",
|
||||
"in_chat_message_ar": (
|
||||
f"الباقة المقترحة:\n{label_ar} — {amount_sar:,.0f} ريال\n\n"
|
||||
"[ادفع الآن] [أرسل فاتورة] [كلم المبيعات]\n\n"
|
||||
"ملاحظة: الدفع آمن عبر Moyasar (سعودي مرخّص). فاتورة ZATCA "
|
||||
"تصلكم تلقائياً بعد التأكيد."
|
||||
),
|
||||
"approval_required": True,
|
||||
"approval_status": "pending_approval",
|
||||
"live_charged": False,
|
||||
"compliance_note_ar": (
|
||||
"draft فقط — لا يتم خصم أي مبلغ حتى يضغط العميل 'ادفع' "
|
||||
"على Moyasar وتصلنا webhook 'paid'."
|
||||
),
|
||||
}
|
||||
162
dealix/auto_client_acquisition/growth_operator/proof_pack.py
Normal file
162
dealix/auto_client_acquisition/growth_operator/proof_pack.py
Normal file
@ -0,0 +1,162 @@
|
||||
"""
|
||||
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 "
|
||||
"خارج هوية الشركة المشتركة."
|
||||
),
|
||||
}
|
||||
146
dealix/auto_client_acquisition/growth_operator/targeting.py
Normal file
146
dealix/auto_client_acquisition/growth_operator/targeting.py
Normal file
@ -0,0 +1,146 @@
|
||||
"""
|
||||
Targeting — turn a list of safe contacts into a ranked Top-N with Why-Now.
|
||||
|
||||
Pure functions; no LLM calls. Heuristic ranking:
|
||||
- existing customer / inbound lead: highest base score
|
||||
- event lead: strong recency boost
|
||||
- old lead with last_contacted_at: medium
|
||||
- referral: high trust
|
||||
- unknown / cold: filtered out unless explicitly allowed
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import hashlib
|
||||
from typing import Any
|
||||
|
||||
from auto_client_acquisition.growth_operator.contact_importer import (
|
||||
classify_contact_source,
|
||||
detect_opt_out,
|
||||
normalize_phone,
|
||||
)
|
||||
from auto_client_acquisition.growth_operator.contactability import (
|
||||
score_contactability,
|
||||
)
|
||||
|
||||
|
||||
# ── Segments ─────────────────────────────────────────────────────
|
||||
_SEGMENT_BASE_SCORE: dict[str, float] = {
|
||||
"existing_customer": 90.0,
|
||||
"inbound_lead": 85.0,
|
||||
"referral": 80.0,
|
||||
"event_lead": 75.0,
|
||||
"old_lead": 60.0,
|
||||
"unknown": 35.0,
|
||||
"cold_list": 20.0,
|
||||
}
|
||||
|
||||
|
||||
def segment_contacts(contacts: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
|
||||
"""Group contacts into segments using classify_contact_source."""
|
||||
segs: dict[str, list[dict[str, Any]]] = {
|
||||
"existing_customer": [],
|
||||
"inbound_lead": [],
|
||||
"referral": [],
|
||||
"event_lead": [],
|
||||
"old_lead": [],
|
||||
"unknown": [],
|
||||
"cold_list": [],
|
||||
"blocked_or_invalid": [],
|
||||
}
|
||||
for c in contacts:
|
||||
if detect_opt_out(c) or not normalize_phone(c.get("phone")):
|
||||
segs["blocked_or_invalid"].append(c)
|
||||
continue
|
||||
src = classify_contact_source(c)
|
||||
segs.setdefault(src, []).append(c)
|
||||
return segs
|
||||
|
||||
|
||||
# ── Why-Now stub (deterministic; placeholder until live signals) ──
|
||||
_WHY_NOW_TEMPLATES_AR: dict[str, str] = {
|
||||
"existing_customer": "علاقة قائمة — توقيت ممتاز لعرض expansion / upsell.",
|
||||
"inbound_lead": "أبدى اهتماماً مؤخراً — السرعة (≤24 ساعة) ترفع التحويل.",
|
||||
"referral": "قادم بإحالة موثوقة — احترام السياق المهني.",
|
||||
"event_lead": "تواصل من فعالية مؤخراً — نافذة 30 يوم ذهبية.",
|
||||
"old_lead": "lead سابق — انتهز موسم/حدث جديد للعودة.",
|
||||
"unknown": "مصدر غير محدد — يحتاج warm-up + توثيق lawful basis.",
|
||||
"cold_list": "قائمة باردة — لا تواصل قبل توثيق العلاقة.",
|
||||
}
|
||||
|
||||
|
||||
def why_now_stub(contact: dict[str, Any], *, sector_hint: str = "") -> dict[str, Any]:
|
||||
"""
|
||||
Deterministic Why-Now stub.
|
||||
|
||||
In production, this is replaced by a live signal-driven explainer
|
||||
that reads market_intelligence + company website diff + jobs.
|
||||
"""
|
||||
src = classify_contact_source(contact)
|
||||
company = contact.get("company") or contact.get("name") or "—"
|
||||
rationale = _WHY_NOW_TEMPLATES_AR.get(src, "تواصل قياسي — راجع المصدر قبل الإرسال.")
|
||||
if sector_hint and src in ("event_lead", "inbound_lead", "old_lead"):
|
||||
rationale += f" · مرتبط بقطاع {sector_hint}."
|
||||
# Synthetic stable score (testable, no entropy)
|
||||
seed = hashlib.md5(f"{company}|{src}|{sector_hint}".encode()).digest()
|
||||
bonus = (seed[0] % 21) - 10 # -10..+10
|
||||
return {
|
||||
"rationale_ar": rationale,
|
||||
"score_modifier": bonus,
|
||||
"source": src,
|
||||
}
|
||||
|
||||
|
||||
# ── Ranking ──────────────────────────────────────────────────────
|
||||
def rank_targets(
|
||||
contacts: list[dict[str, Any]],
|
||||
*,
|
||||
sector_hint: str = "",
|
||||
channel: str = "whatsapp",
|
||||
require_safe: bool = True,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""
|
||||
Score every contact, optionally filter to safe-only, return sorted desc.
|
||||
|
||||
Each item in the result is the original contact + score + why_now + decision.
|
||||
"""
|
||||
out: list[dict[str, Any]] = []
|
||||
for c in contacts:
|
||||
decision = score_contactability(c, channel=channel)
|
||||
if require_safe and decision["label"] != "safe":
|
||||
continue
|
||||
why = why_now_stub(c, sector_hint=sector_hint)
|
||||
base = _SEGMENT_BASE_SCORE.get(why["source"], 30.0)
|
||||
score = max(0.0, min(100.0, base + why["score_modifier"]))
|
||||
out.append({
|
||||
**c,
|
||||
"fit_score": round(score, 1),
|
||||
"why_now": why,
|
||||
"contactability": decision,
|
||||
})
|
||||
out.sort(key=lambda x: x["fit_score"], reverse=True)
|
||||
return out
|
||||
|
||||
|
||||
def recommend_top_10(
|
||||
contacts: list[dict[str, Any]],
|
||||
*,
|
||||
sector_hint: str = "",
|
||||
channel: str = "whatsapp",
|
||||
) -> dict[str, Any]:
|
||||
"""The Top-10 view consumed by the dashboard's Growth Radar tile."""
|
||||
ranked = rank_targets(
|
||||
contacts, sector_hint=sector_hint, channel=channel, require_safe=True,
|
||||
)
|
||||
top = ranked[:10]
|
||||
return {
|
||||
"channel": channel,
|
||||
"sector_hint": sector_hint,
|
||||
"candidates_evaluated": len(contacts),
|
||||
"candidates_safe": len(ranked),
|
||||
"top": top,
|
||||
"recommendation_ar": (
|
||||
f"اخترنا أعلى {len(top)} فرصة آمنة من قائمة {len(contacts)} "
|
||||
f"بعد فلترة المخاطرة. كل واحدة بحالة pending_approval."
|
||||
),
|
||||
}
|
||||
351
dealix/docs/ARABIC_GROWTH_OPERATOR_FULL_SPEC.md
Normal file
351
dealix/docs/ARABIC_GROWTH_OPERATOR_FULL_SPEC.md
Normal file
@ -0,0 +1,351 @@
|
||||
# Arabic Growth Operator — Full Spec
|
||||
|
||||
> **الرؤية:** Dealix ليس CRM ولا أداة WhatsApp ولا بوت رسائل. هو **Saudi Autonomous Revenue OS**: بوت عربي ذكي داخل WhatsApp/الداشبورد يفهم الشركة، السوق السعودي، الأرقام المرفوعة من العميل، الشراكات، الاجتماعات، المتابعة، الدفع، والامتثال — ويقترح وينفذ بموافقة واضحة.
|
||||
> **آخر تحديث:** 2026-05-01
|
||||
> **حالة الكود:** ✅ مبني، 50/50 unit tests خضراء على Python 3.10 venv
|
||||
|
||||
---
|
||||
|
||||
## 1. الجملة المحورية
|
||||
|
||||
> **Dealix هو مدير نمو عربي ذكي للشركات السعودية:
|
||||
> يعرف من تستهدف، ماذا تقول، متى تتابع، من تشارك، وكيف تثبت أن كل هذا جاب نتيجة.**
|
||||
|
||||
---
|
||||
|
||||
## 2. تجربة WhatsApp مثل Boardy لكن أقوى
|
||||
|
||||
**Boardy** يقترح علاقات.
|
||||
**Dealix** يقترح علاقات + leads + رسائل + اجتماعات + مدفوعات + proof + revenue.
|
||||
|
||||
كل بطاقة في الـ feed:
|
||||
- **Why now** ولماذا الآن تحديداً
|
||||
- **Recommended action** بعربي طبيعي
|
||||
- **3 buttons فقط** (حد WhatsApp Reply Buttons): قبول / تخطي / رسالة
|
||||
- لو ضغط "رسالة" → يدخل draft mode: اعتماد / تعديل / إلغاء
|
||||
|
||||
---
|
||||
|
||||
## 3. أنواع العملاء التي تخدمهم
|
||||
|
||||
| النوع | كيف يخدمه Dealix |
|
||||
|---|---|
|
||||
| **صاحب الشركة** | daily brief 3 قرارات صباحاً، قرار مطلوب feed، Proof Pack أسبوعي |
|
||||
| **مدير المبيعات** | deals at risk، reps slow follow-up، messages to approve، forecast، coaching |
|
||||
| **متجر / SMB** | تصنيف العملاء VIP/inactive/repeat/leads، حملات استرجاع، payment links، عروض موسمية |
|
||||
| **مؤسس فردي** | First 10 Customers Autopilot، Personal Operator، Strategic Board Brief |
|
||||
| **وكالة تسويق** | reseller / revenue share + سياسة موافقات لكل عميل |
|
||||
|
||||
---
|
||||
|
||||
## 4. استخدام الأرقام المرفوعة من العميل
|
||||
|
||||
> **القاعدة الذهبية:** الأرقام لازم تكون مملوكة/مصرّح بها أو عندها علاقة مناسبة. لا cold WhatsApp بدون lawful basis.
|
||||
|
||||
العميل يرفع ملف:
|
||||
|
||||
```text
|
||||
name, phone, company, city, sector, source, relationship_status,
|
||||
opt_in_status, last_contacted_at, notes
|
||||
```
|
||||
|
||||
ثم Dealix يعمل تلقائياً:
|
||||
|
||||
1. **normalize_phone** — تطبيع للأرقام السعودية (E.164)
|
||||
2. **dedupe_contacts** — إزالة التكرار، الإبقاء على السجل الأغنى
|
||||
3. **classify_contact_source** — existing / inbound / event / referral / old_lead / cold / unknown
|
||||
4. **detect_opt_out** — إشارات الـ opt-out بالعربي + الإنجليزي
|
||||
5. **score_contactability** — `safe / needs_review / blocked` مع أسباب عربية واضحة
|
||||
6. **summarize_import** — ملخص مرئي يطلع للعميل
|
||||
|
||||
### المخرج للعميل
|
||||
```text
|
||||
رفعت 1,000 رقم.
|
||||
- 420 آمن للتواصل
|
||||
- 180 يحتاج مراجعة
|
||||
- 90 opt-out أو ممنوع
|
||||
- 310 غير واضح المصدر
|
||||
أقترح نبدأ فقط بـ 420 رقم الآمنة.
|
||||
[اعرض العينة] [جهز الرسائل] [احذف غير الآمن]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Contactability + opt-in
|
||||
|
||||
### القرارات الـ 3
|
||||
- **safe**: علاقة قائمة (existing/inbound/referral) + رقم صالح + ليس opt-out
|
||||
- **needs_review**: مصدر غير واضح / lead قديم بدون last_contacted_at
|
||||
- **blocked**: opt-out / cold WhatsApp بدون lawful basis / رقم غير صالح
|
||||
|
||||
### قاعدة WhatsApp الافتراضية
|
||||
```text
|
||||
لا cold WhatsApp بدون lawful basis (PDPL م.5).
|
||||
السياسة: لا cold WhatsApp افتراضياً.
|
||||
```
|
||||
|
||||
العميل يقدر يعدل القاعدة لكل قائمة بعد توثيق المصدر، لكن الأمر الافتراضي هو **الحماية**.
|
||||
|
||||
---
|
||||
|
||||
## 6. WhatsApp Approvals
|
||||
|
||||
WhatsApp Reply Buttons محدودة بـ 3:
|
||||
|
||||
```text
|
||||
[قبول] [تخطي] [رسالة]
|
||||
```
|
||||
|
||||
لو ضغط "رسالة":
|
||||
|
||||
```text
|
||||
[اعتماد] [تعديل] [إلغاء]
|
||||
```
|
||||
|
||||
كل draft يخرج بـ:
|
||||
- `approval_required: True`
|
||||
- `approval_status: "pending_approval"`
|
||||
- `guardrails_ar`: قائمة قواعد عربية واضحة
|
||||
|
||||
---
|
||||
|
||||
## 7. Gmail Drafts (لا إرسال مباشر)
|
||||
|
||||
- Endpoint يستخدم `gmail.compose` scope فقط
|
||||
- ينشئ مسودة في صندوق المستخدم بـ label `DRAFT`
|
||||
- المستخدم يضغط "Send" بنفسه من Gmail
|
||||
|
||||
---
|
||||
|
||||
## 8. Calendar Drafts (لا إنشاء مباشر)
|
||||
|
||||
- `build_calendar_draft()` يرجع dict مطابق لـ Google Calendar `events.insert` body
|
||||
- `live_inserted: False` دائماً
|
||||
- `conferenceDataVersion: 1` للحصول على Google Meet
|
||||
- الـ insert الفعلي يحدث في خدمة منفصلة، فقط بعد:
|
||||
- موافقة OAuth صريحة من المستخدم
|
||||
- ضغط زر "أنشئ الاجتماع"
|
||||
|
||||
---
|
||||
|
||||
## 9. Payment Links (Moyasar)
|
||||
|
||||
- `build_moyasar_payment_link_draft()` يبني payload بصيغة Moyasar
|
||||
- المبلغ بالـ halalas (1 SAR = 100)
|
||||
- `live_charged: False` دائماً
|
||||
- `POST /v1/payments` الفعلي يحدث في billing service
|
||||
|
||||
داخل المحادثة:
|
||||
|
||||
```text
|
||||
الباقة المقترحة:
|
||||
نظام النمو (Growth OS) — 2,999 ريال
|
||||
[ادفع الآن] [أرسل فاتورة] [كلم المبيعات]
|
||||
```
|
||||
|
||||
ضغط "ادفع الآن" → ينقل لـ Moyasar Hosted Checkout (PCI-safe)، **ليس** إدخال بطاقة داخل WhatsApp.
|
||||
|
||||
---
|
||||
|
||||
## 10. الشراكات
|
||||
|
||||
`suggest_partner_types()` يرجع 6 أنواع شركاء جاهزة:
|
||||
- marketing_agency
|
||||
- sales_consultant
|
||||
- tech_integrator (Supabase / Make.com)
|
||||
- crm_vendor (Zoho / Salla / Odoo سعودي)
|
||||
- founder_community
|
||||
- sector_influencer (عقار / صحة / لوجستيات)
|
||||
|
||||
كل نوع له: rationale_ar، model_ar (Reseller / Revenue share / Affiliate / Equity)، ideal_size.
|
||||
|
||||
`partner_scorecard()` يحسب: tier (platinum / gold / silver / bronze) من intros + deals + revenue share + age.
|
||||
|
||||
---
|
||||
|
||||
## 11. الاجتماعات
|
||||
|
||||
`build_meeting_agenda()` يخلق agenda سعودي مناسب:
|
||||
- 15min → 4 فقرات
|
||||
- 20-30min → 5 فقرات
|
||||
- 45min+ → 6 فقرات (يشمل demo حي + ROI breakdown)
|
||||
|
||||
`build_post_meeting_followup()` ينتج draft شكر + ملخص + خطوة تالية.
|
||||
|
||||
---
|
||||
|
||||
## 12. Proof Pack
|
||||
|
||||
`build_weekly_proof_pack()` يولد تقرير أسبوعي:
|
||||
- **Activity:** 10 أرقام (opportunities, drafts, sent, replies, meetings, proposals, deals)
|
||||
- **Money:** Pipeline + Revenue + Multiple
|
||||
- **Quality:** drafts خطرة محبوطة (PDPL gates) + leaks recovered + avg response
|
||||
- **Best of:** أفضل subject + reply rate
|
||||
- **Next week plan:** قائمة عربية ديناميكية بناءً على الأرقام
|
||||
|
||||
التقدير: A+ / A / B / C / D حسب pipeline / cost multiple + deals.
|
||||
|
||||
تصدير Markdown جاهز للإرسال للإدارة.
|
||||
|
||||
---
|
||||
|
||||
## 13. Growth Missions (6 مهمات outcome-shaped)
|
||||
|
||||
| ID | Title AR | Kill Metric | Endpoint |
|
||||
|---|---|---|---|
|
||||
| **first_10_opportunities** ⭐ | اطلع لي 10 فرص | ten_drafts_approved | `/api/v1/innovation/opportunities/ten-in-ten` |
|
||||
| recover_stalled_deals | أنقذ الصفقات المتوقفة | stalled_deals_revived | `/api/v1/revenue-os/leaks` |
|
||||
| partnership_sprint | ابدأ شراكات | partner_intros_replied | `/api/v1/growth-operator/partners/suggest` |
|
||||
| safe_whatsapp_campaign | جهز حملة واتساب آمنة | safe_messages_drafted | `/api/v1/growth-operator/contacts/import-preview` |
|
||||
| meeting_booking_sprint | احجز لي 3 اجتماعات | meetings_confirmed | `/api/v1/growth-operator/meetings/draft` |
|
||||
| list_cleanup | ارفع قائمتي ونظفها | safe_contacts_extracted | `/api/v1/growth-operator/contacts/import-preview` |
|
||||
|
||||
**Kill feature:** `first_10_opportunities` — الميزة التي تبيع.
|
||||
|
||||
---
|
||||
|
||||
## 14. حدود البحث في السوق والسوشال
|
||||
|
||||
### المصادر المسموحة
|
||||
- موقع الشركة + صفحات عامة
|
||||
- Google Search / Maps (API مع keys)
|
||||
- LinkedIn (API / يدوي مصرّح)
|
||||
- X / Instagram / Facebook Graph API (بإذن العميل)
|
||||
- Job boards / event pages / tender feeds
|
||||
- CRM العميل + ملفاته + Google Sheets / Gmail / Calendar (بإذن)
|
||||
- WhatsApp opt-in / inbound
|
||||
|
||||
### ما لا يُبنى أبداً
|
||||
- Scraping مخالف
|
||||
- تجاوز login
|
||||
- DM تلقائي بدون موافقة
|
||||
- جمع أرقام عشوائية
|
||||
- تخزين PII غير ضرورية
|
||||
- إرسال جماعي غير مصرح
|
||||
|
||||
> **اللغة الصحيحة في المنتج:**
|
||||
> "Dealix يبحث في المصادر المصرح بها والمتاحة، ويحوّلها إلى فرص قابلة للمراجعة، ولا يرسل بدون موافقة."
|
||||
|
||||
---
|
||||
|
||||
## 15. القواعد الـ 12 الأساسية (Compliance)
|
||||
|
||||
1. **Client Growth Profile** — كل عميل له ملف، بدونه البوت عام
|
||||
2. **Contactability Engine** — كل رقم/lead له decision
|
||||
3. **WhatsApp Approval OS** — 3 buttons فقط، draft-first
|
||||
4. **Lead Intelligence** — fit_score, intent_score, why_now, best_angle, risk
|
||||
5. **Saudi Message Engine** — قصير، غير مبالغ، سبب واضح، طلب بسيط
|
||||
6. **Objection-to-Action** — كل رد → action مع interpretation
|
||||
7. **Meeting Operator** — agenda + draft + followup، بدون live insert
|
||||
8. **Gmail Draft Operator** — `gmail.compose` فقط، draft مع label DRAFT
|
||||
9. **Payment-in-Chat** — Moyasar payment link، لا بطاقات في WhatsApp
|
||||
10. **Partnership Operator** — 6 أنواع + outreach + scorecard
|
||||
11. **Proof Pack** — weekly evidence ضد churn
|
||||
12. **Growth Missions** — outcome-shaped tasks (لا dashboard معقد)
|
||||
|
||||
---
|
||||
|
||||
## 16. ما يُنفَّذ الآن (في الكود)
|
||||
|
||||
✅ **مبني وعليه 50 unit test ناجحة:**
|
||||
|
||||
```
|
||||
auto_client_acquisition/growth_operator/
|
||||
├── __init__.py # exports
|
||||
├── client_profile.py # ClientGrowthProfile + defaults
|
||||
├── contact_importer.py # normalize/dedupe/classify/opt_out/summarize
|
||||
├── contactability.py # safe/needs_review/blocked + reasons
|
||||
├── targeting.py # segment + rank + top-10 + why_now stub
|
||||
├── message_planner.py # Arabic drafts + followups + objections
|
||||
├── partnership_planner.py # types + outreach + scorecard
|
||||
├── meeting_planner.py # agenda + calendar draft + followup
|
||||
├── payment_offer.py # Moyasar payment link draft
|
||||
├── proof_pack.py # weekly proof pack
|
||||
└── mission_planner.py # 6 growth missions
|
||||
|
||||
api/routers/growth_operator.py # 16 endpoints under /api/v1/growth-operator/
|
||||
tests/unit/test_growth_operator.py # 50 passing
|
||||
```
|
||||
|
||||
### Endpoints الـ 16
|
||||
|
||||
```
|
||||
POST /api/v1/growth-operator/contacts/import-preview
|
||||
POST /api/v1/growth-operator/contactability/score
|
||||
POST /api/v1/growth-operator/targets/top-10
|
||||
POST /api/v1/growth-operator/messages/draft
|
||||
POST /api/v1/growth-operator/messages/followup
|
||||
POST /api/v1/growth-operator/messages/objection-response
|
||||
POST /api/v1/growth-operator/partners/suggest
|
||||
POST /api/v1/growth-operator/partners/outreach
|
||||
POST /api/v1/growth-operator/partners/scorecard
|
||||
POST /api/v1/growth-operator/meetings/draft
|
||||
POST /api/v1/growth-operator/meetings/post-followup
|
||||
POST /api/v1/growth-operator/payment-offer/draft
|
||||
GET /api/v1/growth-operator/missions
|
||||
POST /api/v1/growth-operator/missions/{id}/run
|
||||
GET /api/v1/growth-operator/proof-pack/demo
|
||||
POST /api/v1/growth-operator/profile
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 17. ما يُؤجَّل (بعد أول 10 عملاء)
|
||||
|
||||
❌ **لا تنفذ الآن:**
|
||||
- Live WhatsApp send (نظل draft-first)
|
||||
- Live Calendar `events.insert` (يحتاج OAuth + UI confirm)
|
||||
- Live Moyasar charges (يحتاج billing service منفصل)
|
||||
- Live LinkedIn / X / Instagram scraping
|
||||
- Multi-tenant SSO
|
||||
- Mobile app
|
||||
- MCP gateway مفتوح
|
||||
- Marketplace خارجي
|
||||
- Local LLM infra
|
||||
|
||||
---
|
||||
|
||||
## 18. الجاهزية للتجربة (Beta)
|
||||
|
||||
| المعيار | الحالة |
|
||||
|---|---|
|
||||
| Unit tests | ✅ 527 passed (50 منها growth_operator + 477 موجودة) |
|
||||
| AST + import sanity | ✅ كل الـ 13 ملف |
|
||||
| Approval invariant | ✅ كل draft عنده `approval_required: True` |
|
||||
| لا live charge / send | ✅ كل drafts فقط |
|
||||
| PDPL guardrails | ✅ no cold WhatsApp by default |
|
||||
| Arabic body content | ✅ كل القوالب عربية طبيعية |
|
||||
| Endpoint coverage | ✅ 16 endpoint + 6 missions + Top-10 + Proof Pack |
|
||||
|
||||
**جاهز للـ private beta** بمجرد:
|
||||
1. ربط Railway env vars
|
||||
2. ربط Moyasar live keys
|
||||
3. ربط WhatsApp Cloud / Green API
|
||||
4. 10 شركات pilot
|
||||
|
||||
---
|
||||
|
||||
## 19. المقارنة الموجزة
|
||||
|
||||
| ضد | قوته | تميزنا |
|
||||
|---|---|---|
|
||||
| **Boardy** | اقتراح علاقات | علاقات + leads + رسائل + اجتماعات + payments + proof |
|
||||
| **HubSpot** | عام، شامل | عربي، سعودي، WhatsApp-first، outcome-first |
|
||||
| **Gong** | conversation intelligence | نبدأ من market signal → action، لا فقط analytics |
|
||||
| **أدوات WhatsApp** | إرسال bulk | نقرر هل ترسل، ماذا، لمن، متى، آمن أم لا |
|
||||
| **الوكالات** | تنفيذ يدوي | system قابل للقياس + شفاف + scalable |
|
||||
|
||||
---
|
||||
|
||||
## 20. الخطوة التالية المباشرة
|
||||
|
||||
1. **Beta-recruit 10 شركات سعودية** (real_estate / clinics / training / agencies — لكل قطاع 2-3)
|
||||
2. **شغّل `first_10_opportunities` mission** لكل شركة في أول 24 ساعة
|
||||
3. **اقصد 50% approval rate + 5+ replies** في أول أسبوع
|
||||
4. **أرسل Proof Pack الأسبوع الأول** لكل عميل
|
||||
5. **اجمع feedback** وحدّث القوالب
|
||||
|
||||
> هذا النهج (kill feature → 10 عملاء → proof) أقوى من إطلاق عام بدون validation.
|
||||
> Boardy للعلاقات + Dealix للنمو والإيرادات.
|
||||
|
||||
— Dealix · Saudi Autonomous Revenue Platform · 🇸🇦
|
||||
401
dealix/tests/unit/test_growth_operator.py
Normal file
401
dealix/tests/unit/test_growth_operator.py
Normal file
@ -0,0 +1,401 @@
|
||||
"""Unit tests for the Arabic Growth Operator layer."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import pytest
|
||||
|
||||
from auto_client_acquisition.growth_operator import (
|
||||
build_calendar_draft,
|
||||
build_demo_profile,
|
||||
build_meeting_agenda,
|
||||
build_moyasar_payment_link_draft,
|
||||
build_post_meeting_followup,
|
||||
build_weekly_proof_pack,
|
||||
classify_contact_source,
|
||||
contactability_summary,
|
||||
dedupe_contacts,
|
||||
detect_opt_out,
|
||||
draft_arabic_message,
|
||||
draft_followup,
|
||||
draft_objection_response,
|
||||
draft_partner_outreach,
|
||||
list_missions,
|
||||
normalize_phone,
|
||||
partner_scorecard,
|
||||
profile_from_dict,
|
||||
rank_targets,
|
||||
recommend_top_10,
|
||||
run_mission,
|
||||
sar_to_halalas,
|
||||
score_contactability,
|
||||
segment_contacts,
|
||||
suggest_partner_types,
|
||||
summarize_import,
|
||||
)
|
||||
|
||||
|
||||
# ── 1. Phone normalization ───────────────────────────────────────
|
||||
def test_normalize_phone_country_prefix_kept():
|
||||
assert normalize_phone("+966500000001") == "966500000001"
|
||||
|
||||
|
||||
def test_normalize_phone_local_zero_to_country():
|
||||
assert normalize_phone("0500000001") == "966500000001"
|
||||
|
||||
|
||||
def test_normalize_phone_bare_9_digits():
|
||||
assert normalize_phone("500000001") == "966500000001"
|
||||
|
||||
|
||||
def test_normalize_phone_double_zero():
|
||||
assert normalize_phone("00966500000001") == "966500000001"
|
||||
|
||||
|
||||
def test_normalize_phone_strips_punctuation():
|
||||
assert normalize_phone("+966 (50) 000-0001") == "966500000001"
|
||||
|
||||
|
||||
def test_normalize_phone_invalid_returns_empty():
|
||||
assert normalize_phone("") == ""
|
||||
assert normalize_phone("abc") == ""
|
||||
|
||||
|
||||
# ── 2. Dedupe ────────────────────────────────────────────────────
|
||||
def test_dedupe_drops_exact_phone_duplicates():
|
||||
out = dedupe_contacts([
|
||||
{"name": "X", "phone": "0500000001"},
|
||||
{"name": "X duplicate", "phone": "+966 50 000 0001"},
|
||||
])
|
||||
assert len(out) == 1
|
||||
|
||||
|
||||
def test_dedupe_keeps_richer_record():
|
||||
out = dedupe_contacts([
|
||||
{"name": "X", "phone": "0500000001"},
|
||||
{"name": "X full", "phone": "0500000001", "email": "x@example.sa", "company": "Co"},
|
||||
])
|
||||
assert len(out) == 1
|
||||
assert out[0].get("email") == "x@example.sa"
|
||||
|
||||
|
||||
# ── 3. Source classification ─────────────────────────────────────
|
||||
def test_classify_existing_customer():
|
||||
assert classify_contact_source({"relationship_status": "customer"}) == "existing_customer"
|
||||
|
||||
|
||||
def test_classify_inbound():
|
||||
assert classify_contact_source({"source": "website_form"}) == "inbound_lead"
|
||||
|
||||
|
||||
def test_classify_event():
|
||||
assert classify_contact_source({"source": "exhibition"}) == "event_lead"
|
||||
|
||||
|
||||
def test_classify_cold():
|
||||
assert classify_contact_source({"source": "cold"}) == "cold_list"
|
||||
|
||||
|
||||
def test_classify_unknown_default():
|
||||
assert classify_contact_source({}) == "unknown"
|
||||
|
||||
|
||||
# ── 4. Opt-out detection ─────────────────────────────────────────
|
||||
def test_detect_opt_out_via_status():
|
||||
assert detect_opt_out({"opt_in_status": "opted_out"}) is True
|
||||
|
||||
|
||||
def test_detect_opt_out_via_arabic_notes():
|
||||
assert detect_opt_out({"notes": "العميل طلب إيقاف الرسائل"}) is True
|
||||
|
||||
|
||||
def test_detect_opt_out_clean():
|
||||
assert detect_opt_out({"name": "X"}) is False
|
||||
|
||||
|
||||
# ── 5. Summarize import ──────────────────────────────────────────
|
||||
def test_summarize_import_aggregates():
|
||||
contacts = [
|
||||
{"name": "A", "phone": "0500000001", "source": "customer"},
|
||||
{"name": "A dup", "phone": "0500000001", "source": "customer"}, # dup
|
||||
{"name": "B", "phone": "0500000002", "source": "cold"},
|
||||
{"name": "C", "phone": "0500000003", "opt_in_status": "opted_out"},
|
||||
]
|
||||
s = summarize_import(contacts)
|
||||
assert s["raw_total"] == 4
|
||||
assert s["after_dedupe"] == 3
|
||||
assert s["duplicates_removed"] == 1
|
||||
assert s["opt_out_count"] == 1
|
||||
|
||||
|
||||
# ── 6. Contactability — core safety rules ───────────────────────
|
||||
def test_contactability_blocks_opt_out():
|
||||
out = score_contactability({"opt_in_status": "opted_out", "phone": "0500000001"})
|
||||
assert out["label"] == "blocked"
|
||||
|
||||
|
||||
def test_contactability_blocks_cold_whatsapp_by_default():
|
||||
"""No cold WhatsApp without lawful basis — that's the policy."""
|
||||
out = score_contactability(
|
||||
{"phone": "0500000001", "source": "cold", "name": "X"},
|
||||
channel="whatsapp",
|
||||
)
|
||||
assert out["label"] == "blocked"
|
||||
assert any("PDPL" in r or "lawful" in r or "بدون" in r for r in out["reasons"])
|
||||
|
||||
|
||||
def test_contactability_unknown_source_needs_review():
|
||||
out = score_contactability(
|
||||
{"phone": "0500000001", "name": "X"},
|
||||
channel="whatsapp",
|
||||
)
|
||||
assert out["label"] == "needs_review"
|
||||
|
||||
|
||||
def test_contactability_existing_customer_safe():
|
||||
out = score_contactability(
|
||||
{"phone": "0500000001", "name": "X", "relationship_status": "customer"},
|
||||
channel="whatsapp",
|
||||
)
|
||||
assert out["label"] == "safe"
|
||||
|
||||
|
||||
def test_contactability_inbound_lead_safe():
|
||||
out = score_contactability(
|
||||
{"phone": "0500000001", "name": "X", "source": "website_form"},
|
||||
channel="whatsapp",
|
||||
)
|
||||
assert out["label"] == "safe"
|
||||
|
||||
|
||||
def test_contactability_summary_aggregates():
|
||||
s = contactability_summary(
|
||||
[
|
||||
{"phone": "0500000001", "relationship_status": "customer"},
|
||||
{"phone": "0500000002", "source": "cold"},
|
||||
{"phone": "0500000003", "opt_in_status": "opted_out"},
|
||||
],
|
||||
channel="whatsapp",
|
||||
)
|
||||
assert s["by_label"]["safe"] >= 1
|
||||
assert s["by_label"]["blocked"] >= 2 # cold + opt-out
|
||||
|
||||
|
||||
# ── 7. Targeting + ranking ──────────────────────────────────────
|
||||
def test_rank_targets_filters_unsafe():
|
||||
contacts = [
|
||||
{"phone": "0500000001", "relationship_status": "customer"},
|
||||
{"phone": "0500000002", "source": "cold"},
|
||||
]
|
||||
ranked = rank_targets(contacts, sector_hint="real_estate", channel="whatsapp")
|
||||
assert len(ranked) == 1 # only the safe customer survives
|
||||
|
||||
|
||||
def test_recommend_top_10_returns_at_most_10():
|
||||
contacts = [
|
||||
{"phone": f"05000000{i:02d}", "relationship_status": "customer", "name": f"X{i}"}
|
||||
for i in range(15)
|
||||
]
|
||||
out = recommend_top_10(contacts, sector_hint="real_estate")
|
||||
assert out["candidates_evaluated"] == 15
|
||||
assert len(out["top"]) == 10
|
||||
|
||||
|
||||
def test_segment_contacts_buckets():
|
||||
segs = segment_contacts([
|
||||
{"phone": "0500000001", "relationship_status": "customer"},
|
||||
{"phone": "0500000002", "source": "exhibition"},
|
||||
{"phone": "0500000003", "source": "cold"},
|
||||
{"phone": "0500000004", "opt_in_status": "opted_out"},
|
||||
])
|
||||
assert len(segs["existing_customer"]) == 1
|
||||
assert len(segs["event_lead"]) == 1
|
||||
assert len(segs["cold_list"]) == 1
|
||||
assert len(segs["blocked_or_invalid"]) == 1
|
||||
|
||||
|
||||
# ── 8. Message planner — Arabic + approval invariant ────────────
|
||||
def test_arabic_message_always_pending_approval():
|
||||
out = draft_arabic_message(
|
||||
{"phone": "0500000001", "name": "سامي", "city": "الرياض", "sector": "real_estate"},
|
||||
)
|
||||
assert out["approval_required"] is True
|
||||
assert out["approval_status"] == "pending_approval"
|
||||
|
||||
|
||||
def test_arabic_message_contains_arabic():
|
||||
out = draft_arabic_message({"phone": "0500000001", "name": "X", "sector": "clinics"})
|
||||
assert any("" <= ch <= "ۿ" for ch in out["body_ar"]), "body must contain Arabic"
|
||||
|
||||
|
||||
def test_arabic_message_no_overhyped_phrases():
|
||||
"""The default templates must not contain 'ضمان 100%' / 'مضمونة' etc."""
|
||||
out = draft_arabic_message({"phone": "0500000001", "name": "X"})
|
||||
body = out["body_ar"]
|
||||
for banned in ("ضمان 100", "نتائج مضمونة", "آخر فرصة", "اضغط هنا فوراً"):
|
||||
assert banned not in body
|
||||
|
||||
|
||||
def test_followup_returns_pending_approval():
|
||||
out = draft_followup({"phone": "0500000001", "name": "X"}, days_since_last=3)
|
||||
assert out["approval_required"] is True
|
||||
|
||||
|
||||
def test_objection_response_known():
|
||||
out = draft_objection_response("send_offer_whatsapp")
|
||||
assert "next_action" in out
|
||||
assert out["approval_required"] is True
|
||||
|
||||
|
||||
def test_objection_response_unknown_diagnostic():
|
||||
out = draft_objection_response("totally_unknown_objection")
|
||||
assert out["next_action"] == "diagnostic_question"
|
||||
|
||||
|
||||
# ── 9. Partnership planner ──────────────────────────────────────
|
||||
def test_partnership_suggestions_smb_emphasizes_agencies():
|
||||
out = suggest_partner_types(customer_size="smb")
|
||||
top_keys = [s["key"] for s in out["suggestions"][:3]]
|
||||
# SMB should prioritize agency / consultant / community
|
||||
assert any(k in ("marketing_agency", "sales_consultant", "founder_community") for k in top_keys)
|
||||
|
||||
|
||||
def test_partnership_outreach_pending():
|
||||
out = draft_partner_outreach(partner_type_key="marketing_agency", partner_name="Test Agency")
|
||||
assert out["approval_required"] is True
|
||||
|
||||
|
||||
def test_partnership_outreach_unknown_type():
|
||||
out = draft_partner_outreach(partner_type_key="bogus_type")
|
||||
assert "error" in out
|
||||
|
||||
|
||||
def test_partner_scorecard_grading():
|
||||
high = partner_scorecard(
|
||||
partner_id="p1", intros_made=10, deals_influenced=4,
|
||||
revenue_share_paid_sar=50_000, relationship_age_months=6,
|
||||
)
|
||||
low = partner_scorecard(partner_id="p2")
|
||||
assert high["overall_score"] > low["overall_score"]
|
||||
assert high["tier"] in ("platinum", "gold")
|
||||
assert low["tier"] == "bronze"
|
||||
|
||||
|
||||
# ── 10. Meeting planner — no live event ─────────────────────────
|
||||
def test_meeting_agenda_returns_slots():
|
||||
out = build_meeting_agenda(
|
||||
contact_name="سامي", company="Test Co.",
|
||||
purpose_ar="تأهيل أولي", duration_minutes=20,
|
||||
)
|
||||
assert out["agenda_ar"]
|
||||
assert out["approval_required"] is True
|
||||
|
||||
|
||||
def test_meeting_calendar_draft_not_inserted():
|
||||
out = build_calendar_draft(
|
||||
contact_email="x@test.sa", contact_name="X", company="Test Co.",
|
||||
duration_minutes=30,
|
||||
)
|
||||
assert out["live_inserted"] is False
|
||||
assert out["approval_required"] is True
|
||||
# Required Google Calendar shape
|
||||
assert "summary" in out and "start" in out and "end" in out
|
||||
assert out["start"]["timeZone"] == "Asia/Riyadh"
|
||||
|
||||
|
||||
def test_post_meeting_followup_pending():
|
||||
out = build_post_meeting_followup(
|
||||
contact_name="X", company="Test", summary_ar="مهتم في pilot.",
|
||||
)
|
||||
assert out["approval_required"] is True
|
||||
|
||||
|
||||
# ── 11. Payment offer — no live charge ──────────────────────────
|
||||
def test_sar_to_halalas_basic():
|
||||
assert sar_to_halalas(1) == 100
|
||||
assert sar_to_halalas(2999) == 299_900
|
||||
|
||||
|
||||
def test_sar_to_halalas_negative_raises():
|
||||
with pytest.raises(ValueError):
|
||||
sar_to_halalas(-5)
|
||||
|
||||
|
||||
def test_payment_draft_does_not_charge():
|
||||
out = build_moyasar_payment_link_draft(
|
||||
plan_key="growth_os", customer_id="c1", contact_email="x@test.sa",
|
||||
)
|
||||
assert out["live_charged"] is False
|
||||
assert out["approval_required"] is True
|
||||
# Moyasar payload uses halalas
|
||||
assert out["moyasar_request_draft"]["amount"] == 299_900
|
||||
assert out["moyasar_request_draft"]["currency"] == "SAR"
|
||||
|
||||
|
||||
def test_payment_draft_unknown_plan():
|
||||
out = build_moyasar_payment_link_draft(plan_key="bogus", customer_id="c1")
|
||||
assert "error" in out
|
||||
assert out["live_charged"] is False
|
||||
|
||||
|
||||
# ── 12. Proof pack ──────────────────────────────────────────────
|
||||
def test_proof_pack_structure():
|
||||
out = build_weekly_proof_pack(
|
||||
customer_id="c1", customer_name="Test Co.", week_label="W18-2026",
|
||||
plan_cost_weekly_sar=750,
|
||||
opportunities_discovered=42, messages_drafted=38,
|
||||
messages_approved=33, messages_sent=33,
|
||||
replies_received=11, positive_replies=4,
|
||||
meetings_booked=3, meetings_held=2,
|
||||
proposals_sent=1, deals_won=0,
|
||||
pipeline_added_sar=185_000, revenue_won_sar=0,
|
||||
risky_drafts_blocked=5, revenue_leaks_recovered=2,
|
||||
avg_response_minutes=42,
|
||||
)
|
||||
assert out["grade"] in ("A+", "A", "B", "C", "D")
|
||||
assert "activity" in out and "money" in out and "quality" in out
|
||||
assert out["next_week_plan_ar"]
|
||||
assert "Dealix Proof Pack" in out["markdown_export"]
|
||||
|
||||
|
||||
# ── 13. Missions ────────────────────────────────────────────────
|
||||
def test_missions_include_first_10_opportunities():
|
||||
out = list_missions()
|
||||
ids = {m["id"] for m in out["missions"]}
|
||||
assert "first_10_opportunities" in ids
|
||||
assert "recover_stalled_deals" in ids
|
||||
assert "partnership_sprint" in ids
|
||||
assert "safe_whatsapp_campaign" in ids
|
||||
assert out["kill_feature_id"] == "first_10_opportunities"
|
||||
|
||||
|
||||
def test_run_mission_known():
|
||||
out = run_mission("first_10_opportunities", payload={"sector": "real_estate"})
|
||||
assert out["mission_id"] == "first_10_opportunities"
|
||||
assert out["next_step_ar"]
|
||||
assert out["primary_endpoint"]
|
||||
assert out["approval_required"] is True
|
||||
|
||||
|
||||
def test_run_mission_unknown():
|
||||
out = run_mission("bogus_mission")
|
||||
assert "error" in out
|
||||
|
||||
|
||||
# ── 14. Profile ─────────────────────────────────────────────────
|
||||
def test_demo_profile_specialized():
|
||||
p = build_demo_profile()
|
||||
assert p.is_specialized()
|
||||
assert "compliance_rules" in p.to_dict()
|
||||
|
||||
|
||||
def test_profile_from_dict_partial_not_specialized():
|
||||
p = profile_from_dict({"customer_id": "c1", "company_name": "X"})
|
||||
assert not p.is_specialized()
|
||||
|
||||
|
||||
def test_profile_default_compliance_blocks_keywords():
|
||||
p = profile_from_dict({"customer_id": "c1"})
|
||||
rules = p.compliance_rules
|
||||
assert "blocked_keywords" in rules
|
||||
assert "ضمان 100" in rules["blocked_keywords"]
|
||||
assert rules["no_cold_whatsapp_without_lawful_basis"] is True
|
||||
Loading…
Reference in New Issue
Block a user