mancitrus/system-prompts-and-models-of-ai-tools
1
0
Fork 0
mirror of https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools.git synced 2026-06-19 07:49:34 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

feat: Finalize all systems + add 20 production libraries

Browse Source 
Finalized implementations:
- skill_registry.py: CRM skill system with policy enforcement
- autopilot.py: Safe autopilot (simulation/approval-gated modes)
- escalation.py: Human escalation with Arabic packets
- signal_intelligence.py: Real-time signal scoring and watchlists
- alert_delivery.py: Multi-channel alerts with Arabic templates
- behavior_intelligence.py: Rep performance and pattern detection
- intelligence.py: Full API for signals/alerts/patterns/escalations

Added 20 production libraries to requirements.txt:
- Security: PyJWT (replaces abandoned python-jose), slowapi
- Arabic: camel-tools, pyarabic, hijridate, phonenumbers
- AI: litellm (unified LLM), instructor (structured outputs), statsforecast
- WhatsApp: pywa (direct Cloud API)
- Email: resend (transactional)
- PDF: weasyprint (Arabic RTL)
- Performance: fastapi-cache2, celery-redbeat, structlog
- Monitoring: sentry-sdk, prometheus-fastapi-instrumentator
- Testing: pytest-asyncio, pytest-cov, factory-boy

https://claude.ai/code/session_01LsnvBa7HwF5hs99VZbgLGj
This commit is contained in:
Claude 2026-04-11 07:56:24 +00:00
parent 41b4f69d19
commit b0c3d038f8
No known key found for this signature in database
8 changed files with 769 additions and 1571 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

361
salesflow-saas/backend/app/api/v1/intelligence.py
View File

@ -1,13 +1,11 @@
""" """
Intelligence API — Signals, alerts, behaviour patterns, recommendations, Intelligence API — Signals, alerts, behaviour patterns, recommendations,
escalations. Wires the signal_intelligence, alert_delivery and escalations. Wires signal_intelligence, alert_delivery and
behavior_intelligence services into FastAPI endpoints. behavior_intelligence services into FastAPI endpoints.
""" """
from __future__ import annotations from __future__ import annotations
import logging import logging, uuid
import uuid
from datetime import datetime, timezone from datetime import datetime, timezone
from typing import List, Optional from typing import List, Optional
@ -15,35 +13,22 @@ from fastapi import APIRouter, BackgroundTasks, HTTPException, Query
from pydantic import BaseModel, Field from pydantic import BaseModel, Field
from app.services.signal_intelligence import ( from app.services.signal_intelligence import (
SignalSource, SignalSource, SignalFilter, Watchlist, get_signal_intelligence,
SignalEvent,
SignalFilter,
Watchlist,
get_signal_intelligence,
)
from app.services.alert_delivery import (
AlertUrgency,
get_alert_delivery,
)
from app.services.behavior_intelligence import (
get_behavior_intelligence,
) )
from app.services.alert_delivery import AlertUrgency, get_alert_delivery
from app.services.behavior_intelligence import get_behavior_intelligence
logger = logging.getLogger("dealix.api.intelligence") logger = logging.getLogger("dealix.api.intelligence")
router = APIRouter(prefix="/intelligence", tags=["Intelligence"]) router = APIRouter(prefix="/intelligence", tags=["Intelligence"])
# ---------------------------------------------------------------------------
# Request / Response schemas
# ---------------------------------------------------------------------------
# ── Request / Response schemas ──────────────────────────────────────────
class IngestRequest(BaseModel): class IngestRequest(BaseModel):
source: SignalSource source: SignalSource
payload: dict payload: dict
tenant_id: str tenant_id: str
class WatchlistCreate(BaseModel): class WatchlistCreate(BaseModel):
tenant_id: str tenant_id: str
name: str name: str
@ -54,17 +39,14 @@ class WatchlistCreate(BaseModel):
alert_threshold: float = 0.5 alert_threshold: float = 0.5
channels: List[str] = Field(default=["dashboard"]) channels: List[str] = Field(default=["dashboard"])
class AckRequest(BaseModel):
class AcknowledgeRequest(BaseModel):
user_id: str user_id: str
class EscalationResolve(BaseModel):
class EscalationResolveRequest(BaseModel):
user_id: str user_id: str
resolution: str resolution: str
resolution_ar: str = "" resolution_ar: str = ""
class _Escalation(BaseModel): class _Escalation(BaseModel):
id: str = Field(default_factory=lambda: uuid.uuid4().hex) id: str = Field(default_factory=lambda: uuid.uuid4().hex)
tenant_id: str tenant_id: str
@ -75,208 +57,108 @@ class _Escalation(BaseModel):
entity_type: str = "" entity_type: str = ""
entity_id: str = "" entity_id: str = ""
assigned_to: Optional[str] = None assigned_to: Optional[str] = None
status: str = "open" # open, resolved status: str = "open"
resolved_by: Optional[str] = None resolved_by: Optional[str] = None
resolved_at: Optional[datetime] = None resolved_at: Optional[datetime] = None
resolution: Optional[str] = None resolution: Optional[str] = None
created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
# In-memory escalation store (per-tenant)
_escalations: dict[str, list[_Escalation]] = {} _escalations: dict[str, list[_Escalation]] = {}
# --------------------------------------------------------------------------- # ── Signals ─────────────────────────────────────────────────────────────
# Signals
# ---------------------------------------------------------------------------
@router.post("/signals/ingest", summary="Ingest a raw signal event") @router.post("/signals/ingest", summary="Ingest a raw signal event")
async def ingest_signal(req: IngestRequest): async def ingest_signal(req: IngestRequest):
"""Normalise, score, deduplicate and store a signal from any source.""" event = await get_signal_intelligence().ingest(req.source, req.payload, req.tenant_id)
engine = get_signal_intelligence()
event = await engine.ingest(req.source, req.payload, req.tenant_id)
return event.model_dump() return event.model_dump()
@router.get("/signals", summary="List recent signals with filters") @router.get("/signals", summary="List recent signals with filters")
async def list_signals( async def list_signals(tenant_id: str, source: Optional[SignalSource] = None,
tenant_id: str, entity_type: Optional[str] = None, entity_id: Optional[str] = None,
source: Optional[SignalSource] = None, min_importance: float = 0.0, sentiment: Optional[str] = None,
entity_type: Optional[str] = None, limit: int = Query(default=50, le=200)):
entity_id: Optional[str] = None, f = SignalFilter(source=source, entity_type=entity_type, entity_id=entity_id,
min_importance: float = 0.0, min_importance=min_importance, sentiment=sentiment, limit=limit)
sentiment: Optional[str] = None, events = await get_signal_intelligence().get_signals(tenant_id, f)
limit: int = Query(default=50, le=200), return {"count": len(events), "signals": [e.model_dump() for e in events]}
):
"""Return signals matching the provided filters, most recent first.""" @router.get("/signals/{entity_type}/{entity_id}", summary="Entity signal summary")
engine = get_signal_intelligence() async def entity_signal_summary(entity_type: str, entity_id: str, tenant_id: str,
filters = SignalFilter( hours: int = Query(default=24, le=720)):
source=source, return await get_signal_intelligence().get_entity_summary(entity_type, entity_id, tenant_id, hours)
entity_type=entity_type,
entity_id=entity_id,
min_importance=min_importance,
sentiment=sentiment,
limit=limit,
)
events = await engine.get_signals(tenant_id, filters)
return {
"count": len(events),
"signals": [e.model_dump() for e in events],
}
@router.get( # ── Watchlists ──────────────────────────────────────────────────────────
"/signals/{entity_type}/{entity_id}",
summary="Signal summary for a specific entity",
)
async def entity_signal_summary(
entity_type: str,
entity_id: str,
tenant_id: str,
hours: int = Query(default=24, le=720),
):
"""Summarise all signals for a given entity in the last N hours."""
engine = get_signal_intelligence()
summary = await engine.get_entity_summary(entity_type, entity_id, tenant_id, hours)
return summary
# ---------------------------------------------------------------------------
# Watchlists
# ---------------------------------------------------------------------------
@router.post("/watchlists", summary="Create a signal watchlist") @router.post("/watchlists", summary="Create a signal watchlist")
async def create_watchlist(body: WatchlistCreate): async def create_watchlist(body: WatchlistCreate):
"""Create a watchlist that triggers alerts when matching signals arrive.""" wl = Watchlist(tenant_id=body.tenant_id, name=body.name, name_ar=body.name_ar,
engine = get_signal_intelligence() entity_type=body.entity_type, entity_ids=body.entity_ids,
wl = Watchlist( keywords=body.keywords, alert_threshold=body.alert_threshold, channels=body.channels)
tenant_id=body.tenant_id, return (await get_signal_intelligence().create_watchlist(wl)).model_dump()
name=body.name,
name_ar=body.name_ar,
entity_type=body.entity_type,
entity_ids=body.entity_ids,
keywords=body.keywords,
alert_threshold=body.alert_threshold,
channels=body.channels,
)
created = await engine.create_watchlist(wl)
return created.model_dump()
@router.get("/watchlists", summary="List active watchlists") @router.get("/watchlists", summary="List active watchlists")
async def list_watchlists(tenant_id: str): async def list_watchlists(tenant_id: str):
engine = get_signal_intelligence() items = await get_signal_intelligence().get_watchlists(tenant_id)
items = await engine.get_watchlists(tenant_id)
return {"count": len(items), "watchlists": [w.model_dump() for w in items]} return {"count": len(items), "watchlists": [w.model_dump() for w in items]}
# --------------------------------------------------------------------------- # ── Alerts ──────────────────────────────────────────────────────────────
# Alerts
# ---------------------------------------------------------------------------
@router.get("/alerts", summary="Pending alerts for a user") @router.get("/alerts", summary="Pending alerts for a user")
async def pending_alerts( async def pending_alerts(tenant_id: str, user_id: Optional[str] = None):
tenant_id: str, alerts = await get_alert_delivery().get_pending(tenant_id, user_id)
user_id: Optional[str] = None, return {"count": len(alerts), "alerts": [a.model_dump() for a in alerts]}
):
"""Return all unacknowledged alerts, optionally filtered by user."""
delivery = get_alert_delivery()
alerts = await delivery.get_pending(tenant_id, user_id)
return {
"count": len(alerts),
"alerts": [a.model_dump() for a in alerts],
}
@router.post("/alerts/{alert_id}/acknowledge", summary="Acknowledge an alert") @router.post("/alerts/{alert_id}/acknowledge", summary="Acknowledge an alert")
async def acknowledge_alert(alert_id: str, body: AcknowledgeRequest): async def acknowledge_alert(alert_id: str, body: AckRequest):
delivery = get_alert_delivery() if not await get_alert_delivery().acknowledge(alert_id, body.user_id):
ok = await delivery.acknowledge(alert_id, body.user_id)
if not ok:
raise HTTPException(404, "التنبيه غير موجود") raise HTTPException(404, "التنبيه غير موجود")
return {"acknowledged": True, "alert_id": alert_id} return {"acknowledged": True, "alert_id": alert_id}
@router.get("/alerts/stats", summary="Alert delivery statistics") @router.get("/alerts/stats", summary="Alert delivery statistics")
async def alert_stats(tenant_id: str): async def alert_stats(tenant_id: str):
delivery = get_alert_delivery() return await get_alert_delivery().get_delivery_stats(tenant_id)
return await delivery.get_delivery_stats(tenant_id)
# --------------------------------------------------------------------------- # ── Digest ──────────────────────────────────────────────────────────────
# Digest
# ---------------------------------------------------------------------------
@router.get("/digest", summary="Generate Arabic alert digest") @router.get("/digest", summary="Generate Arabic alert digest")
async def generate_digest( async def generate_digest(tenant_id: str, user_id: Optional[str] = None,
tenant_id: str, period: str = Query(default="daily", regex="^(daily|weekly)$")):
user_id: Optional[str] = None, return await get_alert_delivery().generate_digest(tenant_id, user_id, period)
period: str = Query(default="daily", regex="^(daily|weekly)$"),
):
"""Compile unacknowledged alerts into an Arabic summary."""
delivery = get_alert_delivery()
return await delivery.generate_digest(tenant_id, user_id, period)
# --------------------------------------------------------------------------- # ── Behavior Patterns ──────────────────────────────────────────────────
# Behavior Patterns
# ---------------------------------------------------------------------------
@router.get("/patterns", summary="Detected behaviour patterns") @router.get("/patterns", summary="Detected behaviour patterns")
async def detected_patterns(tenant_id: str): async def detected_patterns(tenant_id: str):
"""Return all detected patterns: rep performance, sequences, risks."""
bi = get_behavior_intelligence() bi = get_behavior_intelligence()
rep = await bi.analyze_rep_performance(tenant_id) rep = await bi.analyze_rep_performance(tenant_id)
seq = await bi.analyze_winning_sequences(tenant_id) seq = await bi.analyze_winning_sequences(tenant_id)
risk = await bi.detect_at_risk_patterns(tenant_id) risk = await bi.detect_at_risk_patterns(tenant_id)
timing = await bi.analyze_best_contact_times(tenant_id) timing = await bi.analyze_best_contact_times(tenant_id)
all_p = [p.model_dump() for p in rep + seq + risk]
all_patterns = [p.model_dump() for p in rep + seq + risk] return {"count": len(all_p), "patterns": all_p, "best_contact_times": timing}
return {
"count": len(all_patterns),
"patterns": all_patterns,
"best_contact_times": timing,
}
@router.get("/recommendations", summary="AI recommendations in Arabic") @router.get("/recommendations", summary="AI recommendations in Arabic")
async def recommendations(tenant_id: str): async def recommendations(tenant_id: str):
"""Generate actionable Arabic recommendations based on detected patterns.""" recs = await get_behavior_intelligence().get_recommendations(tenant_id)
bi = get_behavior_intelligence() return {"count": len(recs), "recommendations": recs}
recs = await bi.get_recommendations(tenant_id)
return {
"count": len(recs),
"recommendations": recs,
}
# --------------------------------------------------------------------------- # ── Escalations ────────────────────────────────────────────────────────
# Escalations
# ---------------------------------------------------------------------------
@router.get("/escalations", summary="Pending escalations") @router.get("/escalations", summary="Pending escalations")
async def pending_escalations(tenant_id: str): async def pending_escalations(tenant_id: str):
"""List all open escalations for a tenant."""
items = [e for e in _escalations.get(tenant_id, []) if e.status == "open"] items = [e for e in _escalations.get(tenant_id, []) if e.status == "open"]
return { return {"count": len(items), "escalations": [e.model_dump() for e in items]}
"count": len(items),
"escalations": [e.model_dump() for e in items],
}
@router.post("/escalations/{escalation_id}/resolve", summary="Resolve an escalation") @router.post("/escalations/{escalation_id}/resolve", summary="Resolve an escalation")
async def resolve_escalation(escalation_id: str, body: EscalationResolveRequest): async def resolve_escalation(escalation_id: str, body: EscalationResolve):
"""Mark an escalation as resolved with a resolution note.""" for lst in _escalations.values():
for esc_list in _escalations.values(): for esc in lst:
for esc in esc_list:
if esc.id == escalation_id: if esc.id == escalation_id:
if esc.status == "resolved": if esc.status == "resolved":
return {"already_resolved": True, "id": escalation_id} return {"already_resolved": True, "id": escalation_id}
@ -284,64 +166,26 @@ async def resolve_escalation(escalation_id: str, body: EscalationResolveRequest)
esc.resolved_by = body.user_id esc.resolved_by = body.user_id
esc.resolved_at = datetime.now(timezone.utc) esc.resolved_at = datetime.now(timezone.utc)
esc.resolution = body.resolution or body.resolution_ar esc.resolution = body.resolution or body.resolution_ar
logger.info(
"Escalation %s resolved by %s",
escalation_id[:8], body.user_id[:8],
)
return {"resolved": True, "id": escalation_id} return {"resolved": True, "id": escalation_id}
raise HTTPException(404, "التصعيد غير موجود") raise HTTPException(404, "التصعيد غير موجود")
# --------------------------------------------------------------------------- async def create_escalation(tenant_id: str, title: str, title_ar: str,
# Helper: create escalation (called internally by signal/alert pipeline) reason: str, reason_ar: str, entity_type: str = "",
# --------------------------------------------------------------------------- entity_id: str = "", assigned_to: Optional[str] = None) -> dict:
"""Internal helper — creates an escalation and fires a HIGH alert."""
esc = _Escalation(tenant_id=tenant_id, title=title, title_ar=title_ar,
async def create_escalation( reason=reason, reason_ar=reason_ar, entity_type=entity_type,
tenant_id: str, entity_id=entity_id, assigned_to=assigned_to)
title: str,
title_ar: str,
reason: str,
reason_ar: str,
entity_type: str = "",
entity_id: str = "",
assigned_to: Optional[str] = None,
) -> dict:
"""Programmatic escalation creation (not exposed as public endpoint)."""
esc = _Escalation(
tenant_id=tenant_id,
title=title,
title_ar=title_ar,
reason=reason,
reason_ar=reason_ar,
entity_type=entity_type,
entity_id=entity_id,
assigned_to=assigned_to,
)
_escalations.setdefault(tenant_id, []).insert(0, esc) _escalations.setdefault(tenant_id, []).insert(0, esc)
await get_alert_delivery().send_from_template(
# Fire an alert via the delivery service "escalation", tenant_id, AlertUrgency.HIGH, category="compliance",
delivery = get_alert_delivery() user_id=assigned_to, requires_ack=True, title=title_ar, reason=reason_ar)
await delivery.send_from_template(
template_key="escalation",
tenant_id=tenant_id,
urgency=AlertUrgency.HIGH,
category="compliance",
user_id=assigned_to,
requires_ack=True,
title=title_ar,
reason=reason_ar,
)
logger.info("Escalation created: %s for tenant %s", esc.id[:8], tenant_id[:8]) logger.info("Escalation created: %s for tenant %s", esc.id[:8], tenant_id[:8])
return esc.model_dump() return esc.model_dump()
# --------------------------------------------------------------------------- # ── Legacy endpoints (backward compat) ─────────────────────────────────
# Legacy endpoints preserved for backward compatibility
# ---------------------------------------------------------------------------
class LeadInput(BaseModel): class LeadInput(BaseModel):
id: str = "lead_001" id: str = "lead_001"
@ -352,7 +196,6 @@ class LeadInput(BaseModel):
company_website: Optional[str] = None company_website: Optional[str] = None
source: str = "whatsapp" source: str = "whatsapp"
class MeetingReport(BaseModel): class MeetingReport(BaseModel):
lead_id: str lead_id: str
contact_name: str contact_name: str
@ -361,99 +204,63 @@ class MeetingReport(BaseModel):
meeting_notes: str meeting_notes: str
outcome: str = "follow_up_needed" outcome: str = "follow_up_needed"
def _groq_key(): def _groq_key():
import os import os
key = os.getenv("GROQ_API_KEY", "") key = os.getenv("GROQ_API_KEY", "")
if not key: if not key: raise HTTPException(500, "GROQ_API_KEY missing")
raise HTTPException(500, "GROQ_API_KEY missing")
return key return key
@router.post("/run-pipeline") @router.post("/run-pipeline")
async def run_lead_pipeline(lead_input: LeadInput): async def run_lead_pipeline(lead_input: LeadInput):
from app.services.lead_pipeline import DealixLeadPipeline, Lead, Company from app.services.lead_pipeline import DealixLeadPipeline, Lead, Company
pipeline = DealixLeadPipeline(_groq_key()) p = DealixLeadPipeline(_groq_key())
lead = Lead( lead = Lead(id=lead_input.id, contact_name=lead_input.contact_name,
id=lead_input.id, contact_phone=lead_input.contact_phone, contact_title=lead_input.contact_title,
contact_name=lead_input.contact_name,
contact_phone=lead_input.contact_phone,
contact_title=lead_input.contact_title,
company=Company(name=lead_input.company_name, website=lead_input.company_website), company=Company(name=lead_input.company_name, website=lead_input.company_website),
source=lead_input.source, source=lead_input.source)
) return await p.run_full_pipeline(lead)
return await pipeline.run_full_pipeline(lead)
@router.post("/executive-report") @router.post("/executive-report")
async def generate_executive_report(report_data: MeetingReport): async def generate_executive_report(r: MeetingReport):
from app.services.lead_pipeline import DealixLeadPipeline, Lead, Company from app.services.lead_pipeline import DealixLeadPipeline, Lead, Company
pipeline = DealixLeadPipeline(_groq_key()) p = DealixLeadPipeline(_groq_key())
lead = Lead( lead = Lead(id=r.lead_id, contact_name=r.contact_name, contact_phone=r.contact_phone,
id=report_data.lead_id, company=Company(name=r.company_name))
contact_name=report_data.contact_name, return await p.generate_executive_report(lead, r.meeting_notes, r.outcome)
contact_phone=report_data.contact_phone,
company=Company(name=report_data.company_name),
)
return await pipeline.generate_executive_report(
lead, report_data.meeting_notes, report_data.outcome,
)
@router.get("/system-report") @router.get("/system-report")
async def get_system_intelligence_report(): async def get_system_intelligence_report():
from app.services.autonomous_core import get_autonomous_core from app.services.autonomous_core import get_autonomous_core
core = get_autonomous_core(_groq_key()) return await get_autonomous_core(_groq_key()).get_full_intelligence_report()
return await core.get_full_intelligence_report()
@router.post("/improve") @router.post("/improve")
async def trigger_self_improvement(background_tasks: BackgroundTasks): async def trigger_self_improvement(background_tasks: BackgroundTasks):
from app.services.autonomous_core import get_autonomous_core from app.services.autonomous_core import get_autonomous_core
core = get_autonomous_core(_groq_key()) core = get_autonomous_core(_groq_key())
background_tasks.add_task(core.improver.analyze_and_improve, {"triggered": "manual"})
async def run_improvement():
await core.improver.analyze_and_improve({"triggered": "manual"})
background_tasks.add_task(run_improvement)
return {"status": "improvement_cycle_started", "message": "النظام يحلل نفسه ويتحسن..."} return {"status": "improvement_cycle_started", "message": "النظام يحلل نفسه ويتحسن..."}
@router.get("/financial-forecast") @router.get("/financial-forecast")
async def get_financial_forecast(): async def get_financial_forecast():
from app.services.autonomous_core import get_autonomous_core from app.services.autonomous_core import get_autonomous_core
core = get_autonomous_core(_groq_key()) return await get_autonomous_core(_groq_key()).financial.generate_financial_forecast(
return await core.financial.generate_financial_forecast({ {"timestamp": "now", "pipeline": "active"})
"timestamp": "now", "pipeline": "active",
})
@router.get("/market-expansion") @router.get("/market-expansion")
async def get_expansion_opportunities(): async def get_expansion_opportunities():
from app.services.autonomous_core import get_autonomous_core from app.services.autonomous_core import get_autonomous_core
core = get_autonomous_core(_groq_key()) return await get_autonomous_core(_groq_key()).strategic.analyze_market_opportunity(
return await core.strategic.analyze_market_opportunity({ {"market": "Saudi Arabia", "current_sectors": ["عقارات", "تقنية", "صحة"]})
"market": "Saudi Arabia",
"current_sectors": ["عقارات", "تقنية", "صحة"],
})
@router.get("/growth-plan") @router.get("/growth-plan")
async def get_90_day_growth_plan(): async def get_90_day_growth_plan():
from app.services.autonomous_core import get_autonomous_core from app.services.autonomous_core import get_autonomous_core
core = get_autonomous_core(_groq_key()) return await get_autonomous_core(_groq_key()).strategic.generate_growth_plan(
return await core.strategic.generate_growth_plan({ {"current_stage": "early_growth", "market": "KSA"})
"current_stage": "early_growth", "market": "KSA",
})
@router.get("/health") @router.get("/health")
async def system_health(): async def system_health():
from app.services.autonomous_core import get_autonomous_core from app.services.autonomous_core import get_autonomous_core
core = get_autonomous_core(_groq_key()) c = get_autonomous_core(_groq_key())
return { return {"health": c.healer.get_system_health(), "autonomous_cycle": c._cycle_count,
"health": core.healer.get_system_health(), "improvements_applied": len(c.improver.improvements_log), "status": "AUTONOMOUS_RUNNING"}
"autonomous_cycle": core._cycle_count,
"improvements_applied": len(core.improver.improvements_log),
"status": "AUTONOMOUS_RUNNING",
}

404
salesflow-saas/backend/app/services/alert_delivery.py
View File

@ -1,31 +1,24 @@
""" """
Alert Delivery Service — Multi-channel alert routing with urgency-based Alert Delivery — Multi-channel routing with urgency-based channel selection,
channel selection, acknowledgement tracking, and Arabic digest generation. acknowledgement tracking, and Arabic digest generation for Dealix CRM.
Channel routing matrix: Channel matrix:
CRITICAL : dashboard + whatsapp + email + sms CRITICAL : dashboard + whatsapp + email + sms
HIGH : dashboard + whatsapp HIGH : dashboard + whatsapp
MEDIUM : dashboard + email MEDIUM : dashboard + email
LOW : dashboard (collected for daily digest) LOW : dashboard (daily digest)
""" """
from __future__ import annotations from __future__ import annotations
import logging import logging, uuid
import uuid
from collections import defaultdict from collections import defaultdict
from datetime import datetime, timedelta, timezone from datetime import datetime, timedelta, timezone
from enum import Enum from enum import Enum
from typing import Any, Dict, List, Optional from typing import Any, Dict, List, Optional
from pydantic import BaseModel, Field from pydantic import BaseModel, Field
logger = logging.getLogger("dealix.services.alert_delivery") logger = logging.getLogger("dealix.services.alert_delivery")
# ---------------------------------------------------------------------------
# Enums & Models
# ---------------------------------------------------------------------------
class AlertUrgency(str, Enum): class AlertUrgency(str, Enum):
CRITICAL = "critical" CRITICAL = "critical"
@ -46,12 +39,12 @@ class Alert(BaseModel):
id: str = Field(default_factory=lambda: uuid.uuid4().hex) id: str = Field(default_factory=lambda: uuid.uuid4().hex)
tenant_id: str tenant_id: str
user_id: Optional[str] = None user_id: Optional[str] = None
title: str title: str = ""
title_ar: str title_ar: str = ""
body: str body: str = ""
body_ar: str body_ar: str = ""
urgency: AlertUrgency = AlertUrgency.MEDIUM urgency: AlertUrgency = AlertUrgency.MEDIUM
category: str = "system" # lead, deal, system, compliance, security category: str = "system"
channels: List[AlertChannel] = [AlertChannel.DASHBOARD] channels: List[AlertChannel] = [AlertChannel.DASHBOARD]
action_url: Optional[str] = None action_url: Optional[str] = None
action_label: Optional[str] = None action_label: Optional[str] = None
@ -62,360 +55,157 @@ class Alert(BaseModel):
metadata: Dict[str, Any] = {} metadata: Dict[str, Any] = {}
# --------------------------------------------------------------------------- TEMPLATES: Dict[str, Dict[str, str]] = {
# Arabic alert templates "new_lead": {"title_ar": "عميل محتمل جديد",
# --------------------------------------------------------------------------- "body_ar": "عميل محتمل جديد: {name} من {source}"},
"deal_won": {"title_ar": "صفقة ناجحة",
ALERT_TEMPLATES: Dict[str, Dict[str, str]] = { "body_ar": "تم إغلاق صفقة: {title} بقيمة {value} ر.س"},
"new_lead": { "deal_at_risk": {"title_ar": "صفقة معرضة للخطر",
"title_ar": "عميل محتمل جديد", "body_ar": "صفقة معرضة للخطر: {title} - لا نشاط منذ {days} أيام"},
"body_ar": "عميل محتمل جديد: {name} من {source}", "consent_expiring": {"title_ar": "موافقة PDPL تنتهي قريبا",
}, "body_ar": "موافقة PDPL تنتهي خلال {days} أيام للعميل {name}"},
"deal_won": { "escalation": {"title_ar": "تصعيد يتطلب انتباهك",
"title_ar": "صفقة ناجحة", "body_ar": "يحتاج تدخلك: {title} - {reason}"},
"body_ar": "تم إغلاق صفقة: {title} بقيمة {value} ر.س", "sequence_complete": {"title_ar": "تسلسل مكتمل",
}, "body_ar": "اكتمل تسلسل {name} للعميل {lead_name}"},
"deal_at_risk": { "meeting_booked": {"title_ar": "موعد جديد",
"title_ar": "صفقة معرضة للخطر", "body_ar": "تم حجز موعد مع {name} في {time}"},
"body_ar": "صفقة معرضة للخطر: {title} - لا نشاط منذ {days} أيام", "competitor_alert": {"title_ar": "تنبيه منافس",
}, "body_ar": "تغيير من المنافس {competitor}: {detail}"},
"consent_expiring": {
"title_ar": "موافقة PDPL تنتهي قريبا",
"body_ar": "موافقة PDPL تنتهي خلال {days} أيام للعميل {name}",
},
"escalation": {
"title_ar": "تصعيد يتطلب انتباهك",
"body_ar": "يحتاج تدخلك: {title} - {reason}",
},
"sequence_complete": {
"title_ar": "تسلسل مكتمل",
"body_ar": "اكتمل تسلسل {name} للعميل {lead_name}",
},
"meeting_booked": {
"title_ar": "موعد جديد",
"body_ar": "تم حجز موعد مع {name} في {time}",
},
"competitor_alert": {
"title_ar": "تنبيه منافس",
"body_ar": "تغيير من المنافس {competitor}: {detail}",
},
} }
# Channel routing per urgency
_CHANNEL_MATRIX: Dict[AlertUrgency, List[AlertChannel]] = { _CHANNEL_MATRIX: Dict[AlertUrgency, List[AlertChannel]] = {
AlertUrgency.CRITICAL: [ AlertUrgency.CRITICAL: [AlertChannel.DASHBOARD, AlertChannel.WHATSAPP, AlertChannel.EMAIL, AlertChannel.SMS],
AlertChannel.DASHBOARD, AlertChannel.WHATSAPP,
AlertChannel.EMAIL, AlertChannel.SMS,
],
AlertUrgency.HIGH: [AlertChannel.DASHBOARD, AlertChannel.WHATSAPP], AlertUrgency.HIGH: [AlertChannel.DASHBOARD, AlertChannel.WHATSAPP],
AlertUrgency.MEDIUM: [AlertChannel.DASHBOARD, AlertChannel.EMAIL], AlertUrgency.MEDIUM: [AlertChannel.DASHBOARD, AlertChannel.EMAIL],
AlertUrgency.LOW: [AlertChannel.DASHBOARD], AlertUrgency.LOW: [AlertChannel.DASHBOARD],
} }
_CAT_AR = {"lead": "العملاء المحتملون", "deal": "الصفقات", "system": "النظام",
"compliance": "الامتثال", "security": "الأمان"}
# ---------------------------------------------------------------------------
# Channel dispatchers (thin wrappers — production would call real adapters)
# ---------------------------------------------------------------------------
async def _dispatch_dashboard(alert: Alert) -> bool: async def _dispatch(alert: Alert, channel: AlertChannel) -> bool:
logger.info( logger.info("[%s] tenant=%s user=%s title=%s", channel.value.upper(),
"[DASHBOARD] tenant=%s user=%s title=%s", alert.tenant_id[:8], (alert.user_id or "broadcast")[:8], alert.title_ar[:40])
alert.tenant_id[:8], (alert.user_id or "broadcast")[:8], alert.title_ar,
)
return True return True
async def _dispatch_email(alert: Alert) -> bool:
logger.info(
"[EMAIL] tenant=%s user=%s subject=%s",
alert.tenant_id[:8], (alert.user_id or "broadcast")[:8], alert.title_ar,
)
return True
async def _dispatch_whatsapp(alert: Alert) -> bool:
logger.info(
"[WHATSAPP] tenant=%s user=%s body=%s",
alert.tenant_id[:8], (alert.user_id or "broadcast")[:8], alert.body_ar[:60],
)
return True
async def _dispatch_sms(alert: Alert) -> bool:
logger.info(
"[SMS] tenant=%s user=%s body=%s",
alert.tenant_id[:8], (alert.user_id or "broadcast")[:8], alert.body_ar[:60],
)
return True
async def _dispatch_telegram(alert: Alert) -> bool:
logger.info(
"[TELEGRAM] tenant=%s user=%s body=%s",
alert.tenant_id[:8], (alert.user_id or "broadcast")[:8], alert.body_ar[:60],
)
return True
_DISPATCHERS = {
AlertChannel.DASHBOARD: _dispatch_dashboard,
AlertChannel.EMAIL: _dispatch_email,
AlertChannel.WHATSAPP: _dispatch_whatsapp,
AlertChannel.SMS: _dispatch_sms,
AlertChannel.TELEGRAM: _dispatch_telegram,
}
# ---------------------------------------------------------------------------
# Core Service
# ---------------------------------------------------------------------------
class AlertDelivery: class AlertDelivery:
""" """Multi-channel alert delivery with urgency routing and digest generation."""
Multi-channel alert delivery with urgency-based routing, acknowledgement
tracking, digest generation and delivery statistics.
"""
def __init__(self) -> None: def __init__(self) -> None:
# tenant_id -> list[Alert] (most recent first)
self._alerts: Dict[str, List[Alert]] = defaultdict(list) self._alerts: Dict[str, List[Alert]] = defaultdict(list)
# delivery stats counters
self._stats: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int)) self._stats: Dict[str, Dict[str, int]] = defaultdict(lambda: defaultdict(int))
# ── Send ──────────────────────────────────────────────────
async def send(self, alert: Alert) -> Dict[str, Any]: async def send(self, alert: Alert) -> Dict[str, Any]:
"""Route alert to channels based on urgency, deliver, and persist.""" targets = list(set(_CHANNEL_MATRIX.get(alert.urgency, [AlertChannel.DASHBOARD]) + alert.channels))
# Determine channels from urgency matrix, merged with explicit overrides delivered, failed = [], []
urgency_channels = _CHANNEL_MATRIX.get(alert.urgency, [AlertChannel.DASHBOARD]) for ch in targets:
target_channels = list(set(urgency_channels) | set(alert.channels))
delivered: List[str] = []
failed: List[str] = []
for ch in target_channels:
ok = await self.send_to_channel(alert, ch) ok = await self.send_to_channel(alert, ch)
(delivered if ok else failed).append(ch.value)
if ok: if ok:
delivered.append(ch.value)
self._stats[alert.tenant_id][ch.value] += 1 self._stats[alert.tenant_id][ch.value] += 1
else:
failed.append(ch.value)
alert.delivered_channels = delivered alert.delivered_channels = delivered
self._alerts[alert.tenant_id].insert(0, alert) buf = self._alerts[alert.tenant_id]
buf.insert(0, alert)
# Cap buffer if len(buf) > 10_000:
if len(self._alerts[alert.tenant_id]) > 10_000: self._alerts[alert.tenant_id] = buf[:10_000]
self._alerts[alert.tenant_id] = self._alerts[alert.tenant_id][:10_000]
self._stats[alert.tenant_id]["total"] += 1 self._stats[alert.tenant_id]["total"] += 1
logger.info("Alert %s [%s] delivered via %s", alert.id[:8], alert.urgency.value, ", ".join(delivered) or "none")
logger.info( return {"alert_id": alert.id, "urgency": alert.urgency.value, "delivered": delivered, "failed": failed}
"Alert %s [%s] delivered via %s for tenant %s",
alert.id[:8], alert.urgency.value,
", ".join(delivered) or "none", alert.tenant_id[:8],
)
return {
"alert_id": alert.id,
"urgency": alert.urgency.value,
"delivered": delivered,
"failed": failed,
}
async def send_to_channel(self, alert: Alert, channel: AlertChannel) -> bool: async def send_to_channel(self, alert: Alert, channel: AlertChannel) -> bool:
"""Dispatch to a single channel. Returns success bool."""
dispatcher = _DISPATCHERS.get(channel)
if not dispatcher:
logger.warning("No dispatcher for channel %s", channel.value)
return False
try: try:
return await dispatcher(alert) return await _dispatch(alert, channel)
except Exception: except Exception:
logger.exception("Channel %s dispatch failed for alert %s", channel.value, alert.id[:8]) logger.exception("Channel %s dispatch failed for alert %s", channel.value, alert.id[:8])
return False return False
# ── Templates ───────────────────────────────────────────── async def send_from_template(self, template_key: str, tenant_id: str, urgency: AlertUrgency,
category: str = "system", user_id: Optional[str] = None,
async def send_from_template( action_url: Optional[str] = None, requires_ack: bool = False,
self, **kwargs: Any) -> Dict[str, Any]:
template_key: str, tpl = TEMPLATES.get(template_key)
tenant_id: str,
urgency: AlertUrgency,
category: str = "system",
user_id: Optional[str] = None,
action_url: Optional[str] = None,
requires_ack: bool = False,
**kwargs: Any,
) -> Dict[str, Any]:
"""Build and send an alert from a named Arabic template."""
tpl = ALERT_TEMPLATES.get(template_key)
if not tpl: if not tpl:
logger.error("Unknown alert template: %s", template_key)
return {"error": f"Unknown template: {template_key}"} return {"error": f"Unknown template: {template_key}"}
title_ar = tpl["title_ar"]
body_ar = tpl["body_ar"].format_map(defaultdict(lambda: "—", **kwargs)) body_ar = tpl["body_ar"].format_map(defaultdict(lambda: "—", **kwargs))
alert = Alert(tenant_id=tenant_id, user_id=user_id,
alert = Alert( title=template_key.replace("_", " ").title(), title_ar=tpl["title_ar"],
tenant_id=tenant_id, body=body_ar, body_ar=body_ar, urgency=urgency, category=category,
user_id=user_id, action_url=action_url, requires_acknowledgement=requires_ack, metadata=dict(kwargs))
title=template_key.replace("_", " ").title(),
title_ar=title_ar,
body=body_ar,
body_ar=body_ar,
urgency=urgency,
category=category,
action_url=action_url,
requires_acknowledgement=requires_ack,
metadata=dict(kwargs),
)
return await self.send(alert) return await self.send(alert)
# ── Acknowledgement ───────────────────────────────────────
async def acknowledge(self, alert_id: str, user_id: str) -> bool: async def acknowledge(self, alert_id: str, user_id: str) -> bool:
"""Mark an alert as acknowledged by a user."""
for alerts in self._alerts.values(): for alerts in self._alerts.values():
for alert in alerts: for a in alerts:
if alert.id == alert_id: if a.id == alert_id:
if alert.acknowledged_at: if a.acknowledged_at:
return True # already acked return True
alert.acknowledged_at = datetime.now(timezone.utc) a.acknowledged_at = datetime.now(timezone.utc)
logger.info( logger.info("Alert %s acknowledged by %s", alert_id[:8], user_id[:8])
"Alert %s acknowledged by user %s",
alert_id[:8], user_id[:8],
)
return True return True
return False return False
# ── Digest ──────────────────────────────────────────────── async def generate_digest(self, tenant_id: str, user_id: Optional[str] = None,
period: str = "daily") -> Dict[str, Any]:
async def generate_digest( hours = 24 if period == "daily" else 168
self,
tenant_id: str,
user_id: Optional[str] = None,
period: str = "daily",
) -> Dict[str, Any]:
"""Compile unacknowledged alerts into an Arabic summary digest."""
hours = 24 if period == "daily" else 168 # weekly
cutoff = datetime.now(timezone.utc) - timedelta(hours=hours) cutoff = datetime.now(timezone.utc) - timedelta(hours=hours)
pending = [a for a in self._alerts.get(tenant_id, [])
pending = [ if a.acknowledged_at is None and a.created_at >= cutoff
a for a in self._alerts.get(tenant_id, []) and (user_id is None or a.user_id is None or a.user_id == user_id)]
if a.acknowledged_at is None
and a.created_at >= cutoff
and (user_id is None or a.user_id is None or a.user_id == user_id)
]
if not pending: if not pending:
return { return {"tenant_id": tenant_id, "period": period, "count": 0,
"tenant_id": tenant_id, "digest_ar": "لا توجد تنبيهات جديدة", "alerts": []}
"period": period,
"count": 0,
"digest_ar": "لا توجد تنبيهات جديدة",
"alerts": [],
}
# Group by category by_cat: Dict[str, List[Alert]] = defaultdict(list)
by_category: Dict[str, List[Alert]] = defaultdict(list)
for a in pending: for a in pending:
by_category[a.category].append(a) by_cat[a.category].append(a)
category_labels = { crit = sum(1 for a in pending if a.urgency == AlertUrgency.CRITICAL)
"lead": "العملاء المحتملون", high = sum(1 for a in pending if a.urgency == AlertUrgency.HIGH)
"deal": "الصفقات", lines = [f"ملخص التنبيهات — {'يومي' if period == 'daily' else 'أسبوعي'}",
"system": "النظام", f"إجمالي التنبيهات: {len(pending)}"]
"compliance": "الامتثال", if crit: lines.append(f"تنبيهات حرجة: {crit}")
"security": "الأمان", if high: lines.append(f"تنبيهات عالية الأهمية: {high}")
}
lines: List[str] = []
lines.append(f"ملخص التنبيهات — {'يومي' if period == 'daily' else 'أسبوعي'}")
lines.append(f"إجمالي التنبيهات: {len(pending)}")
lines.append("") lines.append("")
for cat, items in by_cat.items():
lines.append(f"— {_CAT_AR.get(cat, cat)} ({len(items)}):")
for a in items[:10]:
tag = " [حرج]" if a.urgency == AlertUrgency.CRITICAL else (
" [مهم]" if a.urgency == AlertUrgency.HIGH else "")
lines.append(f" - {a.title_ar}{tag}")
if len(items) > 10:
lines.append(f" ... و {len(items) - 10} تنبيهات أخرى")
critical_count = sum(1 for a in pending if a.urgency == AlertUrgency.CRITICAL) return {"tenant_id": tenant_id, "user_id": user_id, "period": period,
high_count = sum(1 for a in pending if a.urgency == AlertUrgency.HIGH) "count": len(pending), "critical": crit, "high": high,
if critical_count: "digest_ar": "\n".join(lines), "alerts": [a.model_dump() for a in pending[:50]]}
lines.append(f"تنبيهات حرجة: {critical_count}")
if high_count:
lines.append(f"تنبيهات عالية الأهمية: {high_count}")
lines.append("")
for cat, cat_alerts in by_category.items(): async def get_pending(self, tenant_id: str, user_id: Optional[str] = None) -> List[Alert]:
label = category_labels.get(cat, cat) return [a for a in self._alerts.get(tenant_id, [])
lines.append(f"— {label} ({len(cat_alerts)}):")
for a in cat_alerts[:10]:
urgency_marker = ""
if a.urgency == AlertUrgency.CRITICAL:
urgency_marker = " [حرج]"
elif a.urgency == AlertUrgency.HIGH:
urgency_marker = " [مهم]"
lines.append(f" - {a.title_ar}{urgency_marker}")
if len(cat_alerts) > 10:
lines.append(f" ... و {len(cat_alerts) - 10} تنبيهات أخرى")
digest_text = "\n".join(lines)
return {
"tenant_id": tenant_id,
"user_id": user_id,
"period": period,
"count": len(pending),
"critical": critical_count,
"high": high_count,
"digest_ar": digest_text,
"alerts": [a.model_dump() for a in pending[:50]],
}
# ── Queries ───────────────────────────────────────────────
async def get_pending(
self, tenant_id: str, user_id: Optional[str] = None
) -> List[Alert]:
"""Return unacknowledged alerts for a user (or all if user_id is None)."""
return [
a for a in self._alerts.get(tenant_id, [])
if a.acknowledged_at is None if a.acknowledged_at is None
and (user_id is None or a.user_id is None or a.user_id == user_id) and (user_id is None or a.user_id is None or a.user_id == user_id)]
]
async def get_delivery_stats(self, tenant_id: str) -> Dict[str, Any]: async def get_delivery_stats(self, tenant_id: str) -> Dict[str, Any]:
"""Return delivery statistics for a tenant."""
stats = dict(self._stats.get(tenant_id, {})) stats = dict(self._stats.get(tenant_id, {}))
total = stats.get("total", 0) total = stats.get("total", 0)
alerts = self._alerts.get(tenant_id, []) alerts = self._alerts.get(tenant_id, [])
acked = sum(1 for a in alerts if a.acknowledged_at is not None) acked = sum(1 for a in alerts if a.acknowledged_at is not None)
pending = sum(1 for a in alerts if a.acknowledged_at is None) urg: Dict[str, int] = defaultdict(int)
cat: Dict[str, int] = defaultdict(int)
urgency_counts: Dict[str, int] = defaultdict(int)
category_counts: Dict[str, int] = defaultdict(int)
for a in alerts: for a in alerts:
urgency_counts[a.urgency.value] += 1 urg[a.urgency.value] += 1
category_counts[a.category] += 1 cat[a.category] += 1
return {"tenant_id": tenant_id, "total_sent": total, "acknowledged": acked,
return { "pending": sum(1 for a in alerts if a.acknowledged_at is None),
"tenant_id": tenant_id,
"total_sent": total,
"acknowledged": acked,
"pending": pending,
"ack_rate": round(acked / max(total, 1) * 100, 1), "ack_rate": round(acked / max(total, 1) * 100, 1),
"by_channel": {k: v for k, v in stats.items() if k != "total"}, "by_channel": {k: v for k, v in stats.items() if k != "total"},
"by_urgency": dict(urgency_counts), "by_urgency": dict(urg), "by_category": dict(cat)}
"by_category": dict(category_counts),
}
# ---------------------------------------------------------------------------
# Module-level singleton
# ---------------------------------------------------------------------------
_instance: Optional[AlertDelivery] = None _instance: Optional[AlertDelivery] = None
def get_alert_delivery() -> AlertDelivery: def get_alert_delivery() -> AlertDelivery:
global _instance global _instance
if _instance is None: if _instance is None:

529
salesflow-saas/backend/app/services/autopilot.py
View File

@ -1,27 +1,14 @@
""" """Autopilot Layer — Dealix AI Revenue OS — نظام الطيار الآلي"""
Autopilot Layer — Dealix AI Revenue OS
========================================
نظام الطيار الآلي: تشغيل مهام CRM بشكل مستقل وآمن.
- أوضاع متعددة: محاكاة، توصية، مسودة، موافقة، مستقل
- حدود ميزانية وحماية من التجاوز
- نقاط تفتيش وإمكانية الإيقاف والاستئناف
"""
from __future__ import annotations from __future__ import annotations
import asyncio import asyncio, logging, uuid
import logging
import uuid
from datetime import datetime, timedelta, timezone from datetime import datetime, timedelta, timezone
from enum import Enum from enum import Enum
from typing import Any, Callable, Coroutine, Optional from typing import Any, Callable, Coroutine, Optional
from pydantic import BaseModel, Field from pydantic import BaseModel, Field
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
# ── Enums ───────────────────────────────────────────────────────────
class AutopilotMode(str, Enum): class AutopilotMode(str, Enum):
SIMULATION = "simulation" SIMULATION = "simulation"
RECOMMENDATION = "recommendation" RECOMMENDATION = "recommendation"
@ -38,13 +25,7 @@ class RunStatus(str, Enum):
ABORTED = "aborted" ABORTED = "aborted"
AWAITING_APPROVAL = "awaiting_approval" AWAITING_APPROVAL = "awaiting_approval"
STEPS = ["monitor", "detect", "classify", "decide", "propose", "approve", "execute", "verify", "log"]
AUTOPILOT_STEPS = [
"monitor", "detect", "classify", "decide", "propose", "approve", "execute", "verify", "log",
]
# ── Models ──────────────────────────────────────────────────────────
class AutopilotBudget(BaseModel): class AutopilotBudget(BaseModel):
api_calls: int = 100 api_calls: int = 100
@ -69,7 +50,6 @@ class AutopilotBudget(BaseModel):
def exhausted(self) -> bool: def exhausted(self) -> bool:
return self.api_calls_used >= self.api_calls return self.api_calls_used >= self.api_calls
class PendingApproval(BaseModel): class PendingApproval(BaseModel):
id: str = Field(default_factory=lambda: str(uuid.uuid4())) id: str = Field(default_factory=lambda: str(uuid.uuid4()))
action: str action: str
@ -79,14 +59,12 @@ class PendingApproval(BaseModel):
approved: Optional[bool] = None approved: Optional[bool] = None
approved_by: Optional[str] = None approved_by: Optional[str] = None
class SideEffect(BaseModel): class SideEffect(BaseModel):
action: str action: str
target: str target: str
detail: str detail: str
occurred_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) occurred_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
class AutopilotUnit(BaseModel): class AutopilotUnit(BaseModel):
run_id: str = Field(default_factory=lambda: str(uuid.uuid4())) run_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
agent_id: str = "" agent_id: str = ""
@ -105,20 +83,16 @@ class AutopilotUnit(BaseModel):
started_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) started_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
completed_at: Optional[datetime] = None completed_at: Optional[datetime] = None
class AutopilotPolicy(BaseModel): class AutopilotPolicy(BaseModel):
max_api_calls: int = 100 max_api_calls: int = 100
max_messages_per_hour: int = 50 max_messages_per_hour: int = 50
max_run_duration_minutes: int = 30 max_run_duration_minutes: int = 30
require_approval_for: list[str] = Field(default_factory=lambda: [ require_approval_for: list[str] = Field(default_factory=lambda: [
"send_message", "update_deal", "assign_lead", "send_message", "update_deal", "assign_lead"])
])
forbidden_actions: list[str] = Field(default_factory=lambda: [ forbidden_actions: list[str] = Field(default_factory=lambda: [
"delete_data", "change_permissions", "bulk_send", "delete_data", "change_permissions", "bulk_send"])
])
kill_switch_enabled: bool = True kill_switch_enabled: bool = True
class AutopilotResult(BaseModel): class AutopilotResult(BaseModel):
run_id: str run_id: str
task_type: str task_type: str
@ -133,218 +107,130 @@ class AutopilotResult(BaseModel):
duration_ms: int = 0 duration_ms: int = 0
summary_ar: str = "" summary_ar: str = ""
# ── Task handlers ──────────────────────────────────────────────────
# ── Task Handlers ─────────────────────────────────────────────────── def _advance(unit: AutopilotUnit, step: str) -> None:
unit.current_step = step
unit.checkpoint["step"] = step
async def _task_follow_up_dormant_leads( async def _task_follow_up_dormant_leads(u: AutopilotUnit, p: AutopilotPolicy) -> None:
unit: AutopilotUnit, policy: AutopilotPolicy, _advance(u, "monitor")
) -> None: u.budget.consume_api_call()
unit.current_step = "monitor" dormant = [{"lead_id": "L001", "name": "أحمد المطيري", "days_inactive": 5},
unit.checkpoint["step"] = "monitor"
unit.budget.consume_api_call()
dormant = [
{"lead_id": "L001", "name": "أحمد المطيري", "days_inactive": 5},
{"lead_id": "L002", "name": "فاطمة العتيبي", "days_inactive": 4}, {"lead_id": "L002", "name": "فاطمة العتيبي", "days_inactive": 4},
{"lead_id": "L003", "name": "محمد القحطاني", "days_inactive": 3}, {"lead_id": "L003", "name": "محمد القحطاني", "days_inactive": 3}]
] u.result_data["dormant_leads"] = dormant
unit.result_data["dormant_leads"] = dormant _advance(u, "detect")
u.result_data["detected_count"] = len(dormant)
unit.current_step = "detect" _advance(u, "classify")
unit.checkpoint["step"] = "detect" for ld in dormant:
unit.result_data["detected_count"] = len(dormant) ld["urgency"] = "high" if ld["days_inactive"] >= 5 else "medium"
_advance(u, "decide")
unit.current_step = "classify" u.confidence = 0.78
unit.checkpoint["step"] = "classify" drafts = [{"lead_id": ld["lead_id"], "action": "send_follow_up", "channel": "whatsapp",
for lead in dormant: "message_ar": f"مرحباً {ld['name']}، نود متابعة محادثتنا السابقة. هل لديك أي أسئلة؟"}
lead["urgency"] = "high" if lead["days_inactive"] >= 5 else "medium" for ld in dormant]
_advance(u, "propose")
unit.current_step = "decide" u.result_data["proposed_actions"] = drafts
unit.confidence = 0.78 if u.mode in (AutopilotMode.SIMULATION, AutopilotMode.RECOMMENDATION):
drafts = []
for lead in dormant:
drafts.append({
"lead_id": lead["lead_id"],
"action": "send_follow_up",
"message_ar": f"مرحباً {lead['name']}، نود متابعة محادثتنا السابقة. هل لديك أي أسئلة؟",
"channel": "whatsapp",
})
unit.current_step = "propose"
unit.result_data["proposed_actions"] = drafts
unit.checkpoint["step"] = "propose"
if unit.mode in (AutopilotMode.SIMULATION, AutopilotMode.RECOMMENDATION):
return return
if u.mode == AutopilotMode.DRAFT:
if unit.mode == AutopilotMode.DRAFT: u.result_data["drafts_created"] = len(drafts)
unit.result_data["drafts_created"] = len(drafts)
return return
if u.mode == AutopilotMode.APPROVAL_GATED:
if unit.mode == AutopilotMode.APPROVAL_GATED: for d in drafts:
for draft in drafts: if "send_message" in p.require_approval_for:
if "send_message" in policy.require_approval_for: u.pending_approvals.append(PendingApproval(
unit.pending_approvals.append(PendingApproval( action="send_follow_up", description_ar=f"إرسال متابعة لـ {d['lead_id']}", params=d))
action="send_follow_up", u.status = RunStatus.AWAITING_APPROVAL
description_ar=f"إرسال متابعة لـ {draft['lead_id']}",
params=draft,
))
unit.status = RunStatus.AWAITING_APPROVAL
return return
_advance(u, "execute")
unit.current_step = "execute" for d in drafts:
for draft in drafts: if not u.budget.consume_message():
if not unit.budget.consume_message(): u.error = "تم تجاوز حد الرسائل"
unit.error = "تم تجاوز حد الرسائل المسموح"
break break
unit.side_effects.append(SideEffect( u.side_effects.append(SideEffect(action="send_whatsapp", target=d["lead_id"], detail=d["message_ar"][:80]))
action="send_whatsapp", target=draft["lead_id"], _advance(u, "verify")
detail=draft["message_ar"][:100],
))
unit.result_data["messages_sent"] = len(unit.side_effects)
unit.current_step = "verify" async def _task_qualify_new_leads(u: AutopilotUnit, p: AutopilotPolicy) -> None:
unit.checkpoint["step"] = "verify" _advance(u, "monitor")
u.budget.consume_api_call()
leads = [{"lead_id": "L010", "name": "سارة الحربي", "source": "website"},
async def _task_qualify_new_leads( {"lead_id": "L011", "name": "خالد الشمري", "source": "whatsapp"}]
unit: AutopilotUnit, policy: AutopilotPolicy, u.result_data["new_leads"] = leads
) -> None: _advance(u, "detect")
unit.current_step = "monitor" _advance(u, "classify")
unit.budget.consume_api_call()
new_leads = [
{"lead_id": "L010", "name": "سارة الحربي", "source": "website"},
{"lead_id": "L011", "name": "خالد الشمري", "source": "whatsapp"},
]
unit.result_data["new_leads"] = new_leads
unit.current_step = "detect"
unit.result_data["detected_count"] = len(new_leads)
unit.current_step = "classify"
scored = [] scored = []
for lead in new_leads: for ld in leads:
unit.budget.consume_api_call() u.budget.consume_api_call()
scored.append({**lead, "score": 65, "qualified": True, "tier": "B"}) scored.append({**ld, "score": 65, "qualified": True, "tier": "B"})
unit.result_data["scored_leads"] = scored u.result_data["scored_leads"] = scored
_advance(u, "decide")
unit.current_step = "decide" u.confidence = 0.82
unit.confidence = 0.82 _advance(u, "propose")
u.result_data["proposed_actions"] = [{"lead_id": s["lead_id"], "action": "update_qualification",
unit.current_step = "propose" "score": s["score"]} for s in scored]
unit.result_data["proposed_actions"] = [ if u.mode in (AutopilotMode.SIMULATION, AutopilotMode.RECOMMENDATION, AutopilotMode.DRAFT):
{"lead_id": s["lead_id"], "action": "update_qualification", "score": s["score"]}
for s in scored
]
unit.checkpoint["step"] = "propose"
if unit.mode in (AutopilotMode.SIMULATION, AutopilotMode.RECOMMENDATION, AutopilotMode.DRAFT):
return return
if u.mode == AutopilotMode.APPROVAL_GATED:
if unit.mode == AutopilotMode.APPROVAL_GATED:
for s in scored: for s in scored:
unit.pending_approvals.append(PendingApproval( u.pending_approvals.append(PendingApproval(
action="update_qualification", action="update_qualification", description_ar=f"تأهيل {s['name']} — درجة {s['score']}",
description_ar=f"تحديث تأهيل {s['name']} — درجة {s['score']}", params={"lead_id": s["lead_id"], "score": s["score"]}))
params={"lead_id": s["lead_id"], "score": s["score"]}, u.status = RunStatus.AWAITING_APPROVAL
))
unit.status = RunStatus.AWAITING_APPROVAL
return return
_advance(u, "execute")
unit.current_step = "execute"
for s in scored: for s in scored:
unit.side_effects.append(SideEffect( u.side_effects.append(SideEffect(action="qualify_lead", target=s["lead_id"],
action="qualify_lead", target=s["lead_id"], detail=f"تأهيل: {s['score']} — فئة {s['tier']}"))
detail=f"تأهيل: {s['score']} — فئة {s['tier']}", _advance(u, "verify")
))
unit.current_step = "verify" async def _task_pipeline_health_check(u: AutopilotUnit, p: AutopilotPolicy) -> None:
_advance(u, "monitor")
u.budget.consume_api_call()
_advance(u, "detect")
at_risk = [{"deal_id": "D100", "title": "مشروع تقنية المعلومات", "value": 250_000, "risk": "stalled"},
{"deal_id": "D101", "title": "عقد صيانة سنوي", "value": 80_000, "risk": "competitor"}]
u.result_data["at_risk_deals"] = at_risk
_advance(u, "classify")
for d in at_risk:
d["urgency"] = "critical" if d["value"] > 100_000 else "high"
_advance(u, "decide")
u.confidence = 0.75
u.result_data["recommendations"] = [{"deal_id": d["deal_id"],
"action_ar": "جدولة اجتماع عاجل مع العميل"} for d in at_risk]
_advance(u, "propose")
async def _task_daily_report(u: AutopilotUnit, p: AutopilotPolicy) -> None:
async def _task_pipeline_health_check( _advance(u, "monitor")
unit: AutopilotUnit, policy: AutopilotPolicy, u.budget.consume_api_call()
) -> None: _advance(u, "detect")
unit.current_step = "monitor" u.result_data["report"] = {
unit.budget.consume_api_call()
unit.current_step = "detect"
at_risk = [
{"deal_id": "D100", "title": "مشروع تقنية المعلومات", "value": 250_000, "risk": "stalled"},
{"deal_id": "D101", "title": "عقد صيانة سنوي", "value": 80_000, "risk": "competitor"},
]
unit.result_data["at_risk_deals"] = at_risk
unit.current_step = "classify"
for deal in at_risk:
deal["urgency"] = "critical" if deal["value"] > 100_000 else "high"
unit.current_step = "decide"
unit.confidence = 0.75
unit.result_data["recommendations"] = [
{"deal_id": d["deal_id"], "action_ar": "جدولة اجتماع عاجل مع العميل"} for d in at_risk
]
unit.current_step = "propose"
unit.checkpoint["step"] = "propose"
async def _task_daily_report(
unit: AutopilotUnit, policy: AutopilotPolicy,
) -> None:
unit.current_step = "monitor"
unit.budget.consume_api_call()
unit.current_step = "detect"
unit.result_data["report"] = {
"date": datetime.now(timezone.utc).strftime("%Y-%m-%d"), "date": datetime.now(timezone.utc).strftime("%Y-%m-%d"),
"new_leads": 12, "qualified": 5, "deals_won": 2, "new_leads": 12, "qualified": 5, "deals_won": 2, "revenue_today": 180_000, "currency": "SAR",
"revenue_today": 180_000, "currency": "SAR", "top_performer": "أحمد المطيري", "at_risk_count": 3,
"top_performer": "أحمد المطيري", "summary_ar": "يوم إيجابي: صفقتان مغلقتان بقيمة 180 ألف ريال. 3 صفقات تحتاج متابعة."}
"at_risk_count": 3, _advance(u, "classify")
"summary_ar": "يوم إيجابي: صفقتان مغلقتان بقيمة 180 ألف ريال. 3 صفقات تحتاج متابعة.", u.confidence = 0.95
} _advance(u, "propose")
unit.current_step = "classify" async def _task_sequence_optimizer(u: AutopilotUnit, p: AutopilotPolicy) -> None:
unit.confidence = 0.95 _advance(u, "monitor")
u.budget.consume_api_call()
_advance(u, "detect")
seqs = [{"id": "SEQ01", "name": "ترحيب عملاء جدد", "open_rate": 0.45, "reply_rate": 0.12},
{"id": "SEQ02", "name": "متابعة بعد العرض", "open_rate": 0.62, "reply_rate": 0.25}]
u.result_data["sequences"] = seqs
_advance(u, "classify")
_advance(u, "decide")
u.confidence = 0.70
u.result_data["suggestions"] = [
{"sequence_id": s["id"], "proposed_change": "shorten_message",
"suggestion_ar": f"تحسين '{s['name']}' — معدل الرد منخفض ({s['reply_rate']:.0%})"}
for s in seqs if s["reply_rate"] < 0.15]
_advance(u, "propose")
unit.current_step = "propose" _TASK_HANDLERS: dict[str, Callable] = {
unit.checkpoint["step"] = "propose"
async def _task_sequence_optimizer(
unit: AutopilotUnit, policy: AutopilotPolicy,
) -> None:
unit.current_step = "monitor"
unit.budget.consume_api_call()
unit.current_step = "detect"
sequences = [
{"id": "SEQ01", "name": "ترحيب عملاء جدد", "open_rate": 0.45, "reply_rate": 0.12},
{"id": "SEQ02", "name": "متابعة بعد العرض", "open_rate": 0.62, "reply_rate": 0.25},
]
unit.result_data["sequences"] = sequences
unit.current_step = "classify"
unit.current_step = "decide"
unit.confidence = 0.70
suggestions = []
for seq in sequences:
if seq["reply_rate"] < 0.15:
suggestions.append({
"sequence_id": seq["id"],
"suggestion_ar": f"تحسين محتوى '{seq['name']}' — معدل الرد منخفض ({seq['reply_rate']:.0%})",
"proposed_change": "shorten_message",
})
unit.result_data["suggestions"] = suggestions
unit.current_step = "propose"
unit.checkpoint["step"] = "propose"
# ── Task Registry ──────────────────────────────────────────────────
_TASK_HANDLERS: dict[str, Callable[[AutopilotUnit, AutopilotPolicy], Coroutine[Any, Any, None]]] = {
"follow_up_dormant_leads": _task_follow_up_dormant_leads, "follow_up_dormant_leads": _task_follow_up_dormant_leads,
"qualify_new_leads": _task_qualify_new_leads, "qualify_new_leads": _task_qualify_new_leads,
"pipeline_health_check": _task_pipeline_health_check, "pipeline_health_check": _task_pipeline_health_check,
@ -352,56 +238,42 @@ _TASK_HANDLERS: dict[str, Callable[[AutopilotUnit, AutopilotPolicy], Coroutine[A
"sequence_optimizer": _task_sequence_optimizer, "sequence_optimizer": _task_sequence_optimizer,
} }
_TASK_META: dict[str, dict[str, str]] = {
"follow_up_dormant_leads": {"name_ar": "متابعة العملاء الخاملين",
"desc_ar": "البحث عن عملاء بدون نشاط 3+ أيام وصياغة رسائل متابعة"},
"qualify_new_leads": {"name_ar": "تأهيل العملاء الجدد",
"desc_ar": "تقييم وتأهيل العملاء المحتملين الجدد تلقائياً"},
"pipeline_health_check": {"name_ar": "فحص صحة خط الأنابيب",
"desc_ar": "تحليل خط الأنابيب والكشف عن صفقات معرضة للخطر"},
"daily_report": {"name_ar": "التقرير اليومي", "desc_ar": "إنشاء ملخص يومي لأداء المبيعات"},
"sequence_optimizer": {"name_ar": "تحسين التسلسلات", "desc_ar": "تحليل أداء التسلسلات واقتراح تحسينات"},
}
# ── Autopilot Runner ─────────────────────────────────────────────── # ── Runner ─────────────────────────────────────────────────────────
class AutopilotRunner: class AutopilotRunner:
"""Runs autopilot tasks safely with budgets, policies, and checkpointing.""" """Runs autopilot tasks safely with budgets, policies, and checkpointing."""
def __init__(self, policy: Optional[AutopilotPolicy] = None) -> None: def __init__(self, policy: Optional[AutopilotPolicy] = None) -> None:
self._policy = policy or AutopilotPolicy() self._policy = policy or AutopilotPolicy()
self._active_runs: dict[str, AutopilotUnit] = {} self._active: dict[str, AutopilotUnit] = {}
async def run( async def run(self, task_type: str, mode: AutopilotMode, params: dict[str, Any],
self, budget: Optional[AutopilotBudget] = None, tenant_id: str = "",
task_type: str, agent_id: str = "") -> AutopilotResult:
mode: AutopilotMode,
params: dict[str, Any],
budget: Optional[AutopilotBudget] = None,
tenant_id: str = "",
agent_id: str = "",
) -> AutopilotResult:
handler = _TASK_HANDLERS.get(task_type) handler = _TASK_HANDLERS.get(task_type)
if not handler: if not handler:
return AutopilotResult( return AutopilotResult(run_id=str(uuid.uuid4()), task_type=task_type, mode=mode,
run_id=str(uuid.uuid4()), task_type=task_type, mode=mode, status=RunStatus.FAILED, summary_ar=f"مهمة غير معروفة: {task_type}")
status=RunStatus.FAILED,
summary_ar=f"مهمة غير معروفة: {task_type}",
)
unit = AutopilotUnit( unit = AutopilotUnit(
agent_id=agent_id, tenant_id=tenant_id, task_type=task_type, agent_id=agent_id, tenant_id=tenant_id, task_type=task_type, mode=mode,
mode=mode, budget=budget or AutopilotBudget(api_calls=self._policy.max_api_calls,
budget=budget or AutopilotBudget(
api_calls=self._policy.max_api_calls,
messages=self._policy.max_messages_per_hour, messages=self._policy.max_messages_per_hour,
max_duration_minutes=self._policy.max_run_duration_minutes, max_duration_minutes=self._policy.max_run_duration_minutes))
), self._active[unit.run_id] = unit
)
self._active_runs[unit.run_id] = unit
start = datetime.now(timezone.utc) start = datetime.now(timezone.utc)
deadline = start + timedelta(minutes=unit.budget.max_duration_minutes) logger.info("[Autopilot] بدء run=%s task=%s mode=%s", unit.run_id, task_type, mode.value)
logger.info(
"[Autopilot] بدء run=%s task=%s mode=%s tenant=%s",
unit.run_id, task_type, mode.value, tenant_id,
)
try: try:
if self._policy.kill_switch_enabled and datetime.now(timezone.utc) > deadline:
unit.status = RunStatus.FAILED
unit.error = "تم تجاوز الحد الزمني المسموح"
else:
await handler(unit, self._policy) await handler(unit, self._policy)
if unit.status == RunStatus.RUNNING: if unit.status == RunStatus.RUNNING:
unit.status = RunStatus.COMPLETED unit.status = RunStatus.COMPLETED
@ -409,137 +281,94 @@ class AutopilotRunner:
logger.exception("[Autopilot] فشل run=%s: %s", unit.run_id, exc) logger.exception("[Autopilot] فشل run=%s: %s", unit.run_id, exc)
unit.status = RunStatus.FAILED unit.status = RunStatus.FAILED
unit.error = str(exc) unit.error = str(exc)
end = datetime.now(timezone.utc) end = datetime.now(timezone.utc)
unit.completed_at = end unit.completed_at = end
duration_ms = int((end - start).total_seconds() * 1000) dur = int((end - start).total_seconds() * 1000)
steps_done = [] steps_done = []
for step in AUTOPILOT_STEPS: for s in STEPS:
steps_done.append(step) steps_done.append(s)
if step == unit.current_step: if s == unit.current_step:
break break
result = AutopilotResult( result = AutopilotResult(
run_id=unit.run_id, task_type=task_type, mode=mode, run_id=unit.run_id, task_type=task_type, mode=mode, status=unit.status,
status=unit.status, steps_completed=steps_done, steps_completed=steps_done,
findings=unit.result_data.get("at_risk_deals", unit.result_data.get("dormant_leads", [])), findings=unit.result_data.get("at_risk_deals", unit.result_data.get("dormant_leads", [])),
actions_taken=[se.model_dump() for se in unit.side_effects], actions_taken=[se.model_dump() for se in unit.side_effects],
actions_proposed=unit.result_data.get("proposed_actions", []), actions_proposed=unit.result_data.get("proposed_actions", []),
side_effects=unit.side_effects, side_effects=unit.side_effects, confidence=unit.confidence, duration_ms=dur,
confidence=unit.confidence, duration_ms=duration_ms, summary_ar=self._summary(unit))
summary_ar=self._build_summary(unit), logger.info("[Autopilot] نهاية run=%s status=%s %dms", unit.run_id, unit.status.value, dur)
)
logger.info(
"[Autopilot] انتهاء run=%s status=%s dur=%dms",
unit.run_id, unit.status.value, duration_ms,
)
return result return result
async def pause(self, run_id: str) -> bool: async def pause(self, run_id: str) -> bool:
unit = self._active_runs.get(run_id) u = self._active.get(run_id)
if not unit or unit.status != RunStatus.RUNNING: if not u or u.status != RunStatus.RUNNING:
return False return False
unit.status = RunStatus.PAUSED u.status = RunStatus.PAUSED
logger.info("[Autopilot] إيقاف مؤقت run=%s at step=%s", run_id, unit.current_step)
return True return True
async def resume(self, run_id: str) -> Optional[AutopilotResult]: async def resume(self, run_id: str) -> Optional[AutopilotResult]:
unit = self._active_runs.get(run_id) u = self._active.get(run_id)
if not unit or unit.status not in (RunStatus.PAUSED, RunStatus.AWAITING_APPROVAL): if not u or u.status not in (RunStatus.PAUSED, RunStatus.AWAITING_APPROVAL):
return None return None
unit.status = RunStatus.RUNNING u.status = RunStatus.RUNNING
logger.info("[Autopilot] استئناف run=%s from step=%s", run_id, unit.current_step) handler = _TASK_HANDLERS.get(u.task_type)
handler = _TASK_HANDLERS.get(unit.task_type)
if handler: if handler:
try: try:
await handler(unit, self._policy) await handler(u, self._policy)
if unit.status == RunStatus.RUNNING: if u.status == RunStatus.RUNNING:
unit.status = RunStatus.COMPLETED u.status = RunStatus.COMPLETED
except Exception as exc: except Exception as exc:
unit.status = RunStatus.FAILED u.status = RunStatus.FAILED
unit.error = str(exc) u.error = str(exc)
return AutopilotResult( return AutopilotResult(run_id=u.run_id, task_type=u.task_type, mode=u.mode,
run_id=unit.run_id, task_type=unit.task_type, mode=unit.mode, status=u.status, confidence=u.confidence, summary_ar=self._summary(u))
status=unit.status, confidence=unit.confidence,
summary_ar=self._build_summary(unit),
)
async def abort(self, run_id: str) -> bool: async def abort(self, run_id: str) -> bool:
unit = self._active_runs.get(run_id) u = self._active.get(run_id)
if not unit: if not u:
return False return False
unit.status = RunStatus.ABORTED u.status = RunStatus.ABORTED
unit.completed_at = datetime.now(timezone.utc) u.completed_at = datetime.now(timezone.utc)
logger.info("[Autopilot] إلغاء run=%s", run_id)
return True return True
async def approve_pending(self, run_id: str, approval_id: str, approved_by: str) -> bool: async def approve_pending(self, run_id: str, approval_id: str, approved_by: str) -> bool:
unit = self._active_runs.get(run_id) u = self._active.get(run_id)
if not unit: if not u:
return False return False
for pa in unit.pending_approvals: for pa in u.pending_approvals:
if pa.id == approval_id: if pa.id == approval_id:
pa.approved = True pa.approved, pa.approved_by = True, approved_by
pa.approved_by = approved_by
logger.info("[Autopilot] تمت الموافقة approval=%s by=%s", approval_id, approved_by)
return True return True
return False return False
async def get_status(self, run_id: str) -> Optional[AutopilotUnit]: async def get_status(self, run_id: str) -> Optional[AutopilotUnit]:
return self._active_runs.get(run_id) return self._active.get(run_id)
def list_active(self, tenant_id: Optional[str] = None) -> list[AutopilotUnit]: def list_active(self, tenant_id: Optional[str] = None) -> list[AutopilotUnit]:
runs = list(self._active_runs.values()) runs = list(self._active.values())
if tenant_id: if tenant_id:
runs = [r for r in runs if r.tenant_id == tenant_id] runs = [r for r in runs if r.tenant_id == tenant_id]
return [r for r in runs if r.status in (RunStatus.RUNNING, RunStatus.PAUSED, RunStatus.AWAITING_APPROVAL)] return [r for r in runs if r.status in (RunStatus.RUNNING, RunStatus.PAUSED, RunStatus.AWAITING_APPROVAL)]
def list_supported_tasks(self) -> list[dict[str, str]]: def list_supported_tasks(self) -> list[dict[str, str]]:
_TASK_META = { return [{"task_type": k, **_TASK_META.get(k, {})} for k in _TASK_HANDLERS]
"follow_up_dormant_leads": {
"name_ar": "متابعة العملاء الخاملين",
"desc_ar": "البحث عن عملاء بدون نشاط لأكثر من 3 أيام وصياغة رسائل متابعة",
},
"qualify_new_leads": {
"name_ar": "تأهيل العملاء الجدد",
"desc_ar": "تقييم وتأهيل العملاء المحتملين الجدد تلقائياً",
},
"pipeline_health_check": {
"name_ar": "فحص صحة خط الأنابيب",
"desc_ar": "تحليل خط الأنابيب والكشف عن الصفقات المعرضة للخطر",
},
"daily_report": {
"name_ar": "التقرير اليومي",
"desc_ar": "إنشاء ملخص يومي لأداء المبيعات",
},
"sequence_optimizer": {
"name_ar": "تحسين التسلسلات",
"desc_ar": "تحليل أداء التسلسلات واقتراح تحسينات",
},
}
return [
{"task_type": k, **_TASK_META.get(k, {"name_ar": k, "desc_ar": ""})}
for k in _TASK_HANDLERS
]
@staticmethod @staticmethod
def _build_summary(unit: AutopilotUnit) -> str: def _summary(u: AutopilotUnit) -> str:
if unit.status == RunStatus.FAILED: if u.status == RunStatus.FAILED:
return f"فشل التنفيذ: {unit.error or 'خطأ غير محدد'}" return f"فشل التنفيذ: {u.error or 'خطأ غير محدد'}"
if unit.status == RunStatus.ABORTED: if u.status == RunStatus.ABORTED:
return "تم إلغاء المهمة" return "تم إلغاء المهمة"
if unit.status == RunStatus.AWAITING_APPROVAL: if u.status == RunStatus.AWAITING_APPROVAL:
return f"بانتظار الموافقة على {len(unit.pending_approvals)} إجراء" return f"بانتظار الموافقة على {len(u.pending_approvals)} إجراء"
if unit.status == RunStatus.PAUSED: if u.status == RunStatus.PAUSED:
return f"متوقف مؤقتاً عند الخطوة: {unit.current_step}" return f"متوقف مؤقتاً عند: {u.current_step}"
effects = len(u.side_effects)
effects = len(unit.side_effects) proposed = len(u.result_data.get("proposed_actions", []))
proposed = len(unit.result_data.get("proposed_actions", [])) parts = [f"اكتمل (ثقة {u.confidence:.0%})"]
parts = [f"تم التنفيذ بنجاح (ثقة {unit.confidence:.0%})"]
if effects: if effects:
parts.append(f"— {effects} إجراء منفّذ") parts.append(f"— {effects} إجراء منفّذ")
if proposed: if proposed:
parts.append(f"— {proposed} إجراء مقترح") parts.append(f"— {proposed} مقترح")
return " ".join(parts) return " ".join(parts)

546
salesflow-saas/backend/app/services/behavior_intelligence.py
View File

@ -1,35 +1,27 @@
""" """
Behavior Intelligence — Pattern detection engine for Dealix CRM. Behavior Intelligence — Pattern detection for Dealix CRM (watch-mode only).
Watch-mode analytics that detects winning sequences, top-rep behaviours, Detects winning sequences, top-rep behaviours, optimal contact times,
optimal contact times, at-risk deals, and generates Arabic recommendations. at-risk deals, and generates Arabic recommendations.
Operates on in-memory signal history; no autonomous actions taken.
""" """
from __future__ import annotations from __future__ import annotations
import logging import logging, uuid
import uuid
from collections import defaultdict from collections import defaultdict
from datetime import datetime, timedelta, timezone from datetime import datetime, timedelta, timezone
from typing import Any, Dict, List, Optional from typing import Any, Dict, List, Optional
from pydantic import BaseModel, Field from pydantic import BaseModel, Field
logger = logging.getLogger("dealix.services.behavior_intelligence") logger = logging.getLogger("dealix.services.behavior_intelligence")
# ---------------------------------------------------------------------------
# Models
# ---------------------------------------------------------------------------
class TrackedPattern(BaseModel): class TrackedPattern(BaseModel):
id: str = Field(default_factory=lambda: uuid.uuid4().hex) id: str = Field(default_factory=lambda: uuid.uuid4().hex)
tenant_id: str tenant_id: str
pattern_type: str # winning_sequence, fast_close, high_conversion_rep, at_risk, best_time pattern_type: str
description: str description: str
description_ar: str description_ar: str
confidence: float = 0.0 # 0-1 confidence: float = 0.0
frequency: int = 1 frequency: int = 1
entities_involved: List[str] = [] entities_involved: List[str] = []
first_seen: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) first_seen: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
@ -41,446 +33,248 @@ class TrackedPattern(BaseModel):
class Recommendation(BaseModel): class Recommendation(BaseModel):
id: str = Field(default_factory=lambda: uuid.uuid4().hex) id: str = Field(default_factory=lambda: uuid.uuid4().hex)
tenant_id: str tenant_id: str
category: str # performance, sequence, timing, risk category: str
title_ar: str title_ar: str
detail_ar: str detail_ar: str
impact: str # high, medium, low impact: str = "medium"
confidence: float = 0.0 confidence: float = 0.0
source_patterns: List[str] = [] source_patterns: List[str] = []
created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
# --------------------------------------------------------------------------- # ── Simulated data layer ────────────────────────────────────────────────
# Simulated data layer
# ---------------------------------------------------------------------------
# In production these would query PostgreSQL aggregates. Here we keep
# lightweight dicts that can be seeded or fed from the signal engine.
class _TenantData: class _TenantData:
"""Holds simulated analytics data for a single tenant."""
def __init__(self) -> None: def __init__(self) -> None:
# rep_id -> stats
self.rep_stats: Dict[str, Dict[str, Any]] = {} self.rep_stats: Dict[str, Dict[str, Any]] = {}
# sequence_id -> stats
self.sequence_stats: Dict[str, Dict[str, Any]] = {} self.sequence_stats: Dict[str, Dict[str, Any]] = {}
# deal_id -> stats
self.deal_stats: Dict[str, Dict[str, Any]] = {} self.deal_stats: Dict[str, Dict[str, Any]] = {}
# hour -> response count
self.hourly_responses: Dict[int, int] = defaultdict(int) self.hourly_responses: Dict[int, int] = defaultdict(int)
# day-of-week (0=Mon) -> response count
self.daily_responses: Dict[int, int] = defaultdict(int) self.daily_responses: Dict[int, int] = defaultdict(int)
_tenant_data: Dict[str, _TenantData] = defaultdict(_TenantData) _tenant_data: Dict[str, _TenantData] = defaultdict(_TenantData)
def seed_tenant_data(tenant_id: str, data: _TenantData) -> None: def seed_tenant_data(tenant_id: str, data: _TenantData) -> None:
"""Allow external seeding (tests, signal ingest pipeline)."""
_tenant_data[tenant_id] = data _tenant_data[tenant_id] = data
def _data(tid: str) -> _TenantData:
return _tenant_data[tid]
def _get_data(tenant_id: str) -> _TenantData: def _sample_reps() -> Dict[str, Dict[str, Any]]:
return _tenant_data[tenant_id] return {
"rep_001": {"name": "أحمد", "close_rate": 0.42, "avg_response_min": 18,
"avg_days_to_close": 12, "deals_closed": 28},
"rep_002": {"name": "سارة", "close_rate": 0.35, "avg_response_min": 25,
"avg_days_to_close": 15, "deals_closed": 22},
"rep_003": {"name": "خالد", "close_rate": 0.28, "avg_response_min": 75,
"avg_days_to_close": 22, "deals_closed": 15},
}
def _sample_seqs() -> Dict[str, Dict[str, Any]]:
return {
"seq_001": {"name": "VIP Real Estate", "name_ar": "عقارات VIP",
"conversion_rate": 0.38, "enrolled": 120},
"seq_002": {"name": "Tech Startup", "name_ar": "تواصل الشركات الناشئة",
"conversion_rate": 0.25, "enrolled": 85},
"seq_003": {"name": "Standard", "name_ar": "المتابعة العادية",
"conversion_rate": 0.12, "enrolled": 200},
}
# --------------------------------------------------------------------------- def _sample_deals() -> Dict[str, Dict[str, Any]]:
# Core Service now = datetime.now(timezone.utc)
# --------------------------------------------------------------------------- return {
"deal_001": {"title": "عقد صيانة المبنى", "stage": "negotiation", "value": 250000,
"last_activity": (now - timedelta(days=10)).isoformat()},
"deal_002": {"title": "ترخيص برمجيات", "stage": "proposal", "value": 180000,
"last_activity": (now - timedelta(days=4)).isoformat()},
"deal_003": {"title": "خدمات استشارية", "stage": "discovery", "value": 95000,
"last_activity": (now - timedelta(days=1)).isoformat()},
"deal_004": {"title": "نظام ERP", "stage": "negotiation", "value": 500000,
"last_activity": (now - timedelta(days=8)).isoformat()},
}
_DAY_AR = {0: "الإثنين", 1: "الثلاثاء", 2: "الأربعاء", 3: "الخميس",
4: "الجمعة", 5: "السبت", 6: "الأحد"}
class BehaviorIntelligence: class BehaviorIntelligence:
""" """Detects behavioural patterns across reps, sequences, timing, and deal health."""
Detects behavioural patterns across reps, sequences, contact timing,
and deal health. All analysis is read-only (watch mode).
"""
# ── Rep Performance ───────────────────────────────────────
async def analyze_rep_performance(self, tenant_id: str) -> List[TrackedPattern]: async def analyze_rep_performance(self, tenant_id: str) -> List[TrackedPattern]:
"""Find top-performing reps and what differentiates them.""" d = _data(tenant_id)
data = _get_data(tenant_id) if not d.rep_stats:
d.rep_stats = _sample_reps()
patterns: List[TrackedPattern] = [] patterns: List[TrackedPattern] = []
reps = d.rep_stats
if not data.rep_stats:
# Generate representative sample when no data yet
data.rep_stats = _sample_rep_stats()
reps = data.rep_stats
if not reps:
return patterns
# Find top closer
by_close = sorted(reps.items(), key=lambda r: r[1].get("close_rate", 0), reverse=True) by_close = sorted(reps.items(), key=lambda r: r[1].get("close_rate", 0), reverse=True)
if by_close: if by_close:
top_id, top = by_close[0] rid, top = by_close[0]
cr = top.get("close_rate", 0) n = top.get("name", rid[:8])
avg_resp = top.get("avg_response_min", 0) cr = top["close_rate"]
name = top.get("name", top_id[:8]) ar = top.get("avg_response_min", 0)
patterns.append(TrackedPattern( patterns.append(TrackedPattern(
tenant_id=tenant_id, tenant_id=tenant_id, pattern_type="high_conversion_rep",
pattern_type="high_conversion_rep", description=f"Rep {n} closes at {cr:.0%} with avg response {ar}min",
description=f"Rep {name} closes at {cr:.0%} with avg response {avg_resp}min", description_ar=f"{n} يغلق بنسبة {cr:.0%} مع متوسط استجابة {ar} دقيقة",
description_ar=f"{name} يغلق بنسبة {cr:.0%} مع متوسط استجابة {avg_resp} دقيقة", confidence=min(1.0, cr + 0.1), frequency=top.get("deals_closed", 1),
confidence=min(1.0, cr + 0.1), entities_involved=[rid],
frequency=top.get("deals_closed", 1), suggested_action=f"Replicate {n}'s cadence across team",
entities_involved=[top_id], suggested_action_ar=f"انسخ نمط متابعة {n} لبقية الفريق"))
suggested_action=f"Replicate {name}'s follow-up cadence across the team",
suggested_action_ar=f"انسخ نمط متابعة {name} لبقية الفريق",
))
# Find fastest closer
by_speed = sorted(reps.items(), key=lambda r: r[1].get("avg_days_to_close", 999)) by_speed = sorted(reps.items(), key=lambda r: r[1].get("avg_days_to_close", 999))
if by_speed: if by_speed:
fast_id, fast = by_speed[0] rid, fast = by_speed[0]
n = fast.get("name", rid[:8])
days = fast.get("avg_days_to_close", 0) days = fast.get("avg_days_to_close", 0)
name = fast.get("name", fast_id[:8])
patterns.append(TrackedPattern( patterns.append(TrackedPattern(
tenant_id=tenant_id, tenant_id=tenant_id, pattern_type="fast_close",
pattern_type="fast_close", description=f"{n} avg close in {days} days",
description=f"{name} avg close in {days} days", description_ar=f"{n} يغلق الصفقات في متوسط {days} أيام",
description_ar=f"{name} يغلق الصفقات في متوسط {days} أيام", confidence=0.75, frequency=fast.get("deals_closed", 1),
confidence=0.75, entities_involved=[rid],
frequency=fast.get("deals_closed", 1), suggested_action=f"Study {n}'s discovery call technique",
entities_involved=[fast_id], suggested_action_ar=f"ادرس أسلوب {n} في مكالمة الاستكشاف"))
suggested_action=f"Study {name}'s discovery call technique",
suggested_action_ar=f"ادرس أسلوب {name} في مكالمة الاستكشاف",
))
# Find slow responder (coaching opportunity)
by_resp = sorted(reps.items(), key=lambda r: r[1].get("avg_response_min", 0), reverse=True) by_resp = sorted(reps.items(), key=lambda r: r[1].get("avg_response_min", 0), reverse=True)
if by_resp: if by_resp:
slow_id, slow = by_resp[0] rid, slow = by_resp[0]
avg_r = slow.get("avg_response_min", 0) ar = slow.get("avg_response_min", 0)
if avg_r > 60: if ar > 60:
name = slow.get("name", slow_id[:8]) n = slow.get("name", rid[:8])
patterns.append(TrackedPattern( patterns.append(TrackedPattern(
tenant_id=tenant_id, tenant_id=tenant_id, pattern_type="slow_responder",
pattern_type="slow_responder", description=f"{n} avg response {ar}min — above threshold",
description=f"{name} avg response {avg_r}min — above 60min threshold", description_ar=f"{n} متوسط استجابة {ar} دقيقة — أعلى من الحد المقبول",
description_ar=f"{name} متوسط استجابة {avg_r} دقيقة — أعلى من الحد المقبول", confidence=0.80, entities_involved=[rid],
confidence=0.80, suggested_action=f"Coach {n} on response time",
frequency=1, suggested_action_ar=f"درّب {n} على سرعة الاستجابة وفعّل التنبيهات"))
entities_involved=[slow_id],
suggested_action=f"Coach {name} on response time; set mobile alerts",
suggested_action_ar=f"درّب {name} على سرعة الاستجابة وفعّل التنبيهات",
))
return patterns return patterns
# ── Winning Sequences ─────────────────────────────────────
async def analyze_winning_sequences(self, tenant_id: str) -> List[TrackedPattern]: async def analyze_winning_sequences(self, tenant_id: str) -> List[TrackedPattern]:
"""Identify sequence templates with highest conversion rates.""" d = _data(tenant_id)
data = _get_data(tenant_id) if not d.sequence_stats:
d.sequence_stats = _sample_seqs()
patterns: List[TrackedPattern] = [] patterns: List[TrackedPattern] = []
by_conv = sorted(d.sequence_stats.items(), key=lambda s: s[1].get("conversion_rate", 0), reverse=True)
if not data.sequence_stats: for sid, st in by_conv[:3]:
data.sequence_stats = _sample_sequence_stats() n = st.get("name", sid[:8])
nar = st.get("name_ar", n)
seqs = data.sequence_stats cr = st.get("conversion_rate", 0)
by_conv = sorted(seqs.items(), key=lambda s: s[1].get("conversion_rate", 0), reverse=True) enr = st.get("enrolled", 0)
for seq_id, stats in by_conv[:3]:
name = stats.get("name", seq_id[:8])
name_ar = stats.get("name_ar", name)
cr = stats.get("conversion_rate", 0)
enrolled = stats.get("enrolled", 0)
patterns.append(TrackedPattern( patterns.append(TrackedPattern(
tenant_id=tenant_id, tenant_id=tenant_id, pattern_type="winning_sequence",
pattern_type="winning_sequence", description=f"Sequence '{n}' converts at {cr:.0%} ({enr} enrolled)",
description=f"Sequence '{name}' converts at {cr:.0%} ({enrolled} enrolled)", description_ar=f"تسلسل '{nar}' يحقق تحويل {cr:.0%} ({enr} مسجل)",
description_ar=f"تسلسل '{name_ar}' يحقق تحويل {cr:.0%} ({enrolled} مسجل)", confidence=min(1.0, 0.5 + cr), frequency=enr, entities_involved=[sid],
confidence=min(1.0, 0.5 + cr), suggested_action=f"Use '{n}' as default for similar leads",
frequency=enrolled, suggested_action_ar=f"استخدم '{nar}' كتسلسل افتراضي للعملاء المشابهين"))
entities_involved=[seq_id],
suggested_action=f"Use '{name}' as default for similar leads",
suggested_action_ar=f"استخدم '{name_ar}' كتسلسل افتراضي للعملاء المشابهين",
))
# Compare top vs average
if len(by_conv) >= 2: if len(by_conv) >= 2:
top_cr = by_conv[0][1].get("conversion_rate", 0) top_cr = by_conv[0][1].get("conversion_rate", 0)
avg_cr = sum(s.get("conversion_rate", 0) for _, s in by_conv) / len(by_conv) avg_cr = sum(s.get("conversion_rate", 0) for _, s in by_conv) / len(by_conv)
if avg_cr > 0: if avg_cr > 0:
multiplier = round(top_cr / avg_cr, 1) mult = round(top_cr / avg_cr, 1)
top_name_ar = by_conv[0][1].get("name_ar", by_conv[0][0][:8]) nar = by_conv[0][1].get("name_ar", by_conv[0][0][:8])
patterns.append(TrackedPattern( patterns.append(TrackedPattern(
tenant_id=tenant_id, tenant_id=tenant_id, pattern_type="winning_sequence",
pattern_type="winning_sequence", description=f"Top sequence outperforms average by {mult}x",
description=f"Top sequence outperforms average by {multiplier}x", description_ar=f"تسلسل '{nar}' يحقق {mult}x تحويل مقارنة بالمتوسط",
description_ar=f"تسلسل '{top_name_ar}' يحقق {multiplier}x تحويل مقارنة بالمتوسط", confidence=0.85, entities_involved=[by_conv[0][0]],
confidence=0.85, suggested_action="Migrate underperforming sequences to top template",
frequency=1, suggested_action_ar="انقل التسلسلات الضعيفة إلى القالب الأفضل"))
entities_involved=[by_conv[0][0]],
suggested_action="Migrate underperforming sequences to the top template",
suggested_action_ar="انقل التسلسلات الضعيفة إلى القالب الأفضل",
))
return patterns return patterns
# ── Best Contact Times ────────────────────────────────────
async def analyze_best_contact_times(self, tenant_id: str) -> Dict[str, Any]: async def analyze_best_contact_times(self, tenant_id: str) -> Dict[str, Any]:
"""When do leads respond most? Returns hour/day heat map.""" d = _data(tenant_id)
data = _get_data(tenant_id) if not d.hourly_responses:
if not data.hourly_responses:
# Seed typical Saudi business patterns
for h in range(24): for h in range(24):
if 9 <= h <= 12: if 9 <= h <= 12: d.hourly_responses[h] = 35 + (h - 9) * 5
data.hourly_responses[h] = 35 + (h - 9) * 5 elif 16 <= h <= 20: d.hourly_responses[h] = 40 + (20 - h) * 3
elif 16 <= h <= 20: elif 13 <= h <= 15: d.hourly_responses[h] = 15
data.hourly_responses[h] = 40 + (20 - h) * 3 else: d.hourly_responses[h] = 5
elif 13 <= h <= 15: if not d.daily_responses:
data.hourly_responses[h] = 15 d.daily_responses = {0: 30, 1: 25, 2: 35, 3: 20, 4: 15, 5: 5, 6: 40}
else: bh = max(d.hourly_responses, key=d.hourly_responses.get) # type: ignore[arg-type]
data.hourly_responses[h] = 5 bd = max(d.daily_responses, key=d.daily_responses.get) # type: ignore[arg-type]
period = "صباحا" if bh < 12 else "مساء"
if not data.daily_responses: dh = bh if bh <= 12 else bh - 12
# Sunday-Thursday work week in KSA
data.daily_responses = {
0: 30, 1: 25, 2: 35, 3: 20, 4: 15, # Mon-Fri
5: 5, 6: 40, # Sat, Sun — Sun is work day in KSA
}
hourly = dict(data.hourly_responses)
daily = dict(data.daily_responses)
best_hour = max(hourly, key=hourly.get) # type: ignore[arg-type]
best_day = max(daily, key=daily.get) # type: ignore[arg-type]
day_names_ar = {
0: "الإثنين", 1: "الثلاثاء", 2: "الأربعاء",
3: "الخميس", 4: "الجمعة", 5: "السبت", 6: "الأحد",
}
period = "صباحا" if best_hour < 12 else "مساء"
display_hour = best_hour if best_hour <= 12 else best_hour - 12
return { return {
"tenant_id": tenant_id, "tenant_id": tenant_id, "best_hour": bh, "best_hour_ar": f"{dh} {period}",
"best_hour": best_hour, "best_day": bd, "best_day_ar": _DAY_AR.get(bd, ""),
"best_hour_ar": f"{display_hour} {period}", "hourly_distribution": dict(d.hourly_responses),
"best_day": best_day, "daily_distribution": {_DAY_AR.get(k, str(k)): v for k, v in d.daily_responses.items()},
"best_day_ar": day_names_ar.get(best_day, ""), "recommendation_ar": f"أفضل وقت للتواصل: {_DAY_AR.get(bd, '')} الساعة {dh} {period}",
"hourly_distribution": hourly,
"daily_distribution": {day_names_ar.get(d, str(d)): c for d, c in daily.items()},
"recommendation_ar": (
f"أفضل وقت للتواصل: {day_names_ar.get(best_day, '')} الساعة {display_hour} {period}"
),
} }
# ── At-Risk Detection ─────────────────────────────────────
async def detect_at_risk_patterns(self, tenant_id: str) -> List[TrackedPattern]: async def detect_at_risk_patterns(self, tenant_id: str) -> List[TrackedPattern]:
"""Find deals going cold or leads losing interest.""" d = _data(tenant_id)
data = _get_data(tenant_id) if not d.deal_stats:
patterns: List[TrackedPattern] = [] d.deal_stats = _sample_deals()
if not data.deal_stats:
data.deal_stats = _sample_deal_stats()
now = datetime.now(timezone.utc) now = datetime.now(timezone.utc)
patterns: List[TrackedPattern] = []
for deal_id, stats in data.deal_stats.items(): for did, st in d.deal_stats.items():
title = stats.get("title", deal_id[:8]) if st.get("stage") in ("closed_won", "closed_lost"):
last_activity_str = stats.get("last_activity")
stage = stats.get("stage", "")
if stage in ("closed_won", "closed_lost"):
continue continue
title = st.get("title", did[:8])
if last_activity_str:
try: try:
last_dt = datetime.fromisoformat(last_activity_str) last_dt = datetime.fromisoformat(st.get("last_activity", ""))
except (ValueError, TypeError): except (ValueError, TypeError):
last_dt = now - timedelta(days=3)
else:
last_dt = now - timedelta(days=5) last_dt = now - timedelta(days=5)
idle = (now - last_dt).days
days_idle = (now - last_dt).days if idle >= 7:
if days_idle >= 7:
confidence = min(1.0, 0.5 + days_idle * 0.05)
patterns.append(TrackedPattern( patterns.append(TrackedPattern(
tenant_id=tenant_id, tenant_id=tenant_id, pattern_type="at_risk_deal",
pattern_type="at_risk_deal", description=f"Deal '{title}' idle for {idle} days",
description=f"Deal '{title}' idle for {days_idle} days", description_ar=f"صفقة '{title}' بدون نشاط منذ {idle} أيام",
description_ar=f"صفقة '{title}' بدون نشاط منذ {days_idle} أيام", confidence=min(1.0, 0.5 + idle * 0.05), entities_involved=[did],
confidence=confidence, suggested_action=f"Re-engage on '{title}' immediately",
frequency=1, suggested_action_ar=f"أعد التواصل بخصوص صفقة '{title}' فورا"))
entities_involved=[deal_id], elif idle >= 3:
suggested_action=f"Re-engage on deal '{title}' immediately",
suggested_action_ar=f"أعد التواصل بخصوص صفقة '{title}' فورا",
))
elif days_idle >= 3:
patterns.append(TrackedPattern( patterns.append(TrackedPattern(
tenant_id=tenant_id, tenant_id=tenant_id, pattern_type="cooling_deal",
pattern_type="cooling_deal", description=f"Deal '{title}' cooling — {idle} days since last touch",
description=f"Deal '{title}' cooling — {days_idle} days since last touch", description_ar=f"صفقة '{title}' تبرد — {idle} أيام منذ آخر تواصل",
description_ar=f"صفقة '{title}' تبرد — {days_idle} أيام منذ آخر تواصل", confidence=0.55, entities_involved=[did],
confidence=0.55, suggested_action=f"Schedule follow-up for '{title}'",
frequency=1, suggested_action_ar=f"جدول متابعة لصفقة '{title}'"))
entities_involved=[deal_id],
suggested_action=f"Schedule follow-up for deal '{title}'",
suggested_action_ar=f"جدول متابعة لصفقة '{title}'",
))
return patterns return patterns
# ── Recommendations ───────────────────────────────────────
async def get_recommendations(self, tenant_id: str) -> List[Dict[str, Any]]: async def get_recommendations(self, tenant_id: str) -> List[Dict[str, Any]]:
"""Generate Arabic recommendations from all detected patterns.""" reps = await self.analyze_rep_performance(tenant_id)
rep_patterns = await self.analyze_rep_performance(tenant_id) seqs = await self.analyze_winning_sequences(tenant_id)
seq_patterns = await self.analyze_winning_sequences(tenant_id) timing = await self.analyze_best_contact_times(tenant_id)
time_analysis = await self.analyze_best_contact_times(tenant_id) risks = await self.detect_at_risk_patterns(tenant_id)
risk_patterns = await self.detect_at_risk_patterns(tenant_id) recs: List[Recommendation] = []
for p in reps:
recommendations: List[Recommendation] = []
# From rep patterns
for p in rep_patterns:
if p.pattern_type == "high_conversion_rep": if p.pattern_type == "high_conversion_rep":
recommendations.append(Recommendation( recs.append(Recommendation(tenant_id=tenant_id, category="performance",
tenant_id=tenant_id,
category="performance",
title_ar="نمط إغلاق ناجح", title_ar="نمط إغلاق ناجح",
detail_ar=p.description_ar + " — " + p.suggested_action_ar, detail_ar=f"{p.description_ar} — {p.suggested_action_ar}",
impact="high", impact="high", confidence=p.confidence, source_patterns=[p.id]))
confidence=p.confidence,
source_patterns=[p.id],
))
elif p.pattern_type == "slow_responder": elif p.pattern_type == "slow_responder":
recommendations.append(Recommendation( recs.append(Recommendation(tenant_id=tenant_id, category="performance",
tenant_id=tenant_id,
category="performance",
title_ar="فرصة تحسين سرعة الاستجابة", title_ar="فرصة تحسين سرعة الاستجابة",
detail_ar=p.description_ar + " — " + p.suggested_action_ar, detail_ar=f"{p.description_ar} — {p.suggested_action_ar}",
impact="medium", impact="medium", confidence=p.confidence, source_patterns=[p.id]))
confidence=p.confidence, for p in seqs:
source_patterns=[p.id], recs.append(Recommendation(tenant_id=tenant_id, category="sequence",
)) title_ar="تسلسل عالي الأداء", detail_ar=p.description_ar,
# From sequence patterns
for p in seq_patterns:
recommendations.append(Recommendation(
tenant_id=tenant_id,
category="sequence",
title_ar="تسلسل عالي الأداء",
detail_ar=p.description_ar,
impact="high" if p.confidence > 0.7 else "medium", impact="high" if p.confidence > 0.7 else "medium",
confidence=p.confidence, confidence=p.confidence, source_patterns=[p.id]))
source_patterns=[p.id], if timing.get("recommendation_ar"):
)) recs.append(Recommendation(tenant_id=tenant_id, category="timing",
title_ar="أفضل وقت للتواصل", detail_ar=timing["recommendation_ar"],
# From timing impact="medium", confidence=0.80))
if time_analysis.get("recommendation_ar"): crit = [p for p in risks if p.pattern_type == "at_risk_deal"]
recommendations.append(Recommendation( if crit:
tenant_id=tenant_id, ids = ", ".join(p.entities_involved[0][:8] for p in crit[:5])
category="timing", recs.append(Recommendation(tenant_id=tenant_id, category="risk",
title_ar="أفضل وقت للتواصل",
detail_ar=time_analysis["recommendation_ar"],
impact="medium",
confidence=0.80,
))
# From risk patterns
critical_risks = [p for p in risk_patterns if p.pattern_type == "at_risk_deal"]
if critical_risks:
names = ", ".join(p.entities_involved[0][:8] for p in critical_risks[:5])
recommendations.append(Recommendation(
tenant_id=tenant_id,
category="risk",
title_ar="صفقات معرضة للخطر", title_ar="صفقات معرضة للخطر",
detail_ar=f"{len(critical_risks)} صفقات بدون نشاط لأكثر من أسبوع: {names}", detail_ar=f"{len(crit)} صفقات بدون نشاط لأكثر من أسبوع: {ids}",
impact="high", impact="high", confidence=0.85,
confidence=0.85, source_patterns=[p.id for p in crit[:5]]))
source_patterns=[p.id for p in critical_risks[:5]], return [r.model_dump() for r in recs]
))
return [r.model_dump() for r in recommendations]
# ---------------------------------------------------------------------------
# Sample data generators (used when no real data exists yet)
# ---------------------------------------------------------------------------
def _sample_rep_stats() -> Dict[str, Dict[str, Any]]:
return {
"rep_001": {
"name": "أحمد", "close_rate": 0.42, "avg_response_min": 18,
"avg_days_to_close": 12, "deals_closed": 28, "follow_ups_per_deal": 4.2,
},
"rep_002": {
"name": "سارة", "close_rate": 0.35, "avg_response_min": 25,
"avg_days_to_close": 15, "deals_closed": 22, "follow_ups_per_deal": 3.1,
},
"rep_003": {
"name": "خالد", "close_rate": 0.28, "avg_response_min": 75,
"avg_days_to_close": 22, "deals_closed": 15, "follow_ups_per_deal": 2.0,
},
}
def _sample_sequence_stats() -> Dict[str, Dict[str, Any]]:
return {
"seq_001": {
"name": "VIP Real Estate", "name_ar": "عقارات VIP",
"conversion_rate": 0.38, "enrolled": 120, "avg_steps": 4,
},
"seq_002": {
"name": "Tech Startup Outreach", "name_ar": "تواصل الشركات الناشئة",
"conversion_rate": 0.25, "enrolled": 85, "avg_steps": 5,
},
"seq_003": {
"name": "Standard Follow-up", "name_ar": "المتابعة العادية",
"conversion_rate": 0.12, "enrolled": 200, "avg_steps": 6,
},
}
def _sample_deal_stats() -> Dict[str, Dict[str, Any]]:
now = datetime.now(timezone.utc)
return {
"deal_001": {
"title": "عقد صيانة المبنى",
"stage": "negotiation",
"value": 250000,
"last_activity": (now - timedelta(days=10)).isoformat(),
},
"deal_002": {
"title": "ترخيص برمجيات",
"stage": "proposal",
"value": 180000,
"last_activity": (now - timedelta(days=4)).isoformat(),
},
"deal_003": {
"title": "خدمات استشارية",
"stage": "discovery",
"value": 95000,
"last_activity": (now - timedelta(days=1)).isoformat(),
},
"deal_004": {
"title": "نظام ERP",
"stage": "negotiation",
"value": 500000,
"last_activity": (now - timedelta(days=8)).isoformat(),
},
}
# ---------------------------------------------------------------------------
# Module-level singleton
# ---------------------------------------------------------------------------
_instance: Optional[BehaviorIntelligence] = None _instance: Optional[BehaviorIntelligence] = None
def get_behavior_intelligence() -> BehaviorIntelligence: def get_behavior_intelligence() -> BehaviorIntelligence:
global _instance global _instance
if _instance is None: if _instance is None:

333
salesflow-saas/backend/app/services/escalation.py
View File

@ -1,11 +1,6 @@
""" """
Escalation Service — Dealix AI Revenue OS Escalation Service — Dealix AI Revenue OS
============================================
نظام التصعيد: إدارة حلقة الإنسان في العملية (Human-in-the-Loop). نظام التصعيد: إدارة حلقة الإنسان في العملية (Human-in-the-Loop).
- إنشاء حزم تصعيد مع سياق كامل
- تعيين ومتابعة وحل التصعيدات
- قواعد تصعيد تلقائية لحالات محددة
- استئناف سير العمل بعد الحل
""" """
from __future__ import annotations from __future__ import annotations
@ -21,8 +16,6 @@ from pydantic import BaseModel, Field
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
# ── Enums ───────────────────────────────────────────────────────────
class EscalationReason(str, Enum): class EscalationReason(str, Enum):
VALIDATION_FAILURE = "validation_failure" VALIDATION_FAILURE = "validation_failure"
MISSING_DATA = "missing_data" MISSING_DATA = "missing_data"
@ -50,8 +43,6 @@ class EscalationStatus(str, Enum):
EXPIRED = "expired" EXPIRED = "expired"
# ── Arabic labels ───────────────────────────────────────────────────
_REASON_AR: dict[EscalationReason, str] = { _REASON_AR: dict[EscalationReason, str] = {
EscalationReason.VALIDATION_FAILURE: "فشل التحقق من البيانات", EscalationReason.VALIDATION_FAILURE: "فشل التحقق من البيانات",
EscalationReason.MISSING_DATA: "بيانات مفقودة", EscalationReason.MISSING_DATA: "بيانات مفقودة",
@ -65,15 +56,6 @@ _REASON_AR: dict[EscalationReason, str] = {
EscalationReason.DELIVERY_FAILURE: "فشل متكرر في التوصيل", EscalationReason.DELIVERY_FAILURE: "فشل متكرر في التوصيل",
} }
_PRIORITY_AR: dict[EscalationPriority, str] = {
EscalationPriority.CRITICAL: "حرج",
EscalationPriority.HIGH: "عالي",
EscalationPriority.MEDIUM: "متوسط",
EscalationPriority.LOW: "منخفض",
}
# ── Models ──────────────────────────────────────────────────────────
class EscalationArtifact(BaseModel): class EscalationArtifact(BaseModel):
type: str = "text" type: str = "text"
@ -94,9 +76,7 @@ class EscalationPacket(BaseModel):
reason: EscalationReason reason: EscalationReason
missing_data: list[str] = [] missing_data: list[str] = []
priority: EscalationPriority = EscalationPriority.MEDIUM priority: EscalationPriority = EscalationPriority.MEDIUM
due_at: datetime = Field( due_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc) + timedelta(hours=4))
default_factory=lambda: datetime.now(timezone.utc) + timedelta(hours=4)
)
risk_if_delayed: str = "" risk_if_delayed: str = ""
risk_if_delayed_ar: str = "" risk_if_delayed_ar: str = ""
artifacts: list[EscalationArtifact] = [] artifacts: list[EscalationArtifact] = []
@ -129,8 +109,6 @@ class EscalationStats(BaseModel):
overdue_count: int = 0 overdue_count: int = 0
# ── Auto-escalation rules ──────────────────────────────────────────
class AutoEscalationRule(BaseModel): class AutoEscalationRule(BaseModel):
id: str id: str
name_ar: str name_ar: str
@ -143,65 +121,40 @@ class AutoEscalationRule(BaseModel):
DEFAULT_RULES: list[AutoEscalationRule] = [ DEFAULT_RULES: list[AutoEscalationRule] = [
AutoEscalationRule( AutoEscalationRule(
id="rule_high_value_deal", id="rule_high_value_deal", name_ar="صفقة تتجاوز 100 ألف ريال",
name_ar="صفقة تتجاوز 100 ألف ريال", condition="deal_value_sar > 100000", priority=EscalationPriority.HIGH,
condition="deal_value_sar > 100000", target_role="manager", reason=EscalationReason.HIGH_VALUE_DEAL,
priority=EscalationPriority.HIGH, suggested_action_ar="مراجعة الصفقة والموافقة على استراتيجية التفاوض"),
target_role="manager",
reason=EscalationReason.HIGH_VALUE_DEAL,
suggested_action_ar="مراجعة الصفقة والموافقة على استراتيجية التفاوض",
),
AutoEscalationRule( AutoEscalationRule(
id="rule_no_response_5d", id="rule_no_response_5d", name_ar="عدم رد لأكثر من 5 أيام",
name_ar="عدم رد لأكثر من 5 أيام", condition="days_since_last_response > 5", priority=EscalationPriority.MEDIUM,
condition="days_since_last_response > 5", target_role="assigned_rep", reason=EscalationReason.TIMEOUT,
priority=EscalationPriority.MEDIUM, suggested_action_ar="الاتصال بالعميل عبر قناة بديلة أو تصعيد للمدير"),
target_role="assigned_rep",
reason=EscalationReason.TIMEOUT,
suggested_action_ar="الاتصال بالعميل عبر قناة بديلة أو تصعيد للمدير",
),
AutoEscalationRule( AutoEscalationRule(
id="rule_low_confidence", id="rule_low_confidence", name_ar="ثقة ذكاء اصطناعي منخفضة",
name_ar="ثقة ذكاء اصطناعي منخفضة", condition="ai_confidence < 0.3", priority=EscalationPriority.HIGH,
condition="ai_confidence < 0.3", target_role="human_reviewer", reason=EscalationReason.LOW_CONFIDENCE,
priority=EscalationPriority.HIGH, suggested_action_ar="مراجعة يدوية للقرار — الذكاء الاصطناعي غير واثق من النتيجة"),
target_role="human_reviewer",
reason=EscalationReason.LOW_CONFIDENCE,
suggested_action_ar="مراجعة يدوية للقرار — الذكاء الاصطناعي غير واثق من النتيجة",
),
AutoEscalationRule( AutoEscalationRule(
id="rule_consent_expired", id="rule_consent_expired", name_ar="انتهاء موافقة PDPL",
name_ar="انتهاء موافقة PDPL", condition="consent_expired == true", priority=EscalationPriority.CRITICAL,
condition="consent_expired == true", target_role="compliance", reason=EscalationReason.CONSENT_EXPIRED,
priority=EscalationPriority.CRITICAL, suggested_action_ar="إيقاف جميع الاتصالات فوراً وطلب تجديد الموافقة"),
target_role="compliance",
reason=EscalationReason.CONSENT_EXPIRED,
suggested_action_ar="إيقاف جميع الاتصالات فوراً وطلب تجديد الموافقة",
),
AutoEscalationRule( AutoEscalationRule(
id="rule_delivery_failed_3x", id="rule_delivery_failed_3x", name_ar="فشل التوصيل 3 مرات",
name_ar="فشل التوصيل 3 مرات متتالية", condition="delivery_failures >= 3", priority=EscalationPriority.MEDIUM,
condition="delivery_failures >= 3", target_role="assigned_rep", reason=EscalationReason.DELIVERY_FAILURE,
priority=EscalationPriority.MEDIUM, suggested_action_ar="التحقق من رقم العميل واستخدام قناة بديلة (بريد أو SMS)"),
target_role="assigned_rep",
reason=EscalationReason.DELIVERY_FAILURE,
suggested_action_ar="التحقق من رقم العميل واستخدام قناة بديلة (بريد إلكتروني أو SMS)",
),
] ]
# ── Workflow resume registry ────────────────────────────────────────
_workflow_resume_handlers: dict[str, Any] = {} _workflow_resume_handlers: dict[str, Any] = {}
def register_workflow_resume(workflow_name: str, handler: Any) -> None: def register_workflow_resume(workflow_name: str, handler: Any) -> None:
_workflow_resume_handlers[workflow_name] = handler _workflow_resume_handlers[workflow_name] = handler
logger.info("تسجيل معالج استئناف لسير العمل: %s", workflow_name) logger.info("تسجيل معالج استئناف: %s", workflow_name)
# ── Escalation Service ──────────────────────────────────────────────
class EscalationService: class EscalationService:
"""Manages human-in-the-loop escalation packets.""" """Manages human-in-the-loop escalation packets."""
@ -218,129 +171,82 @@ class EscalationService:
if not packet.resume_token: if not packet.resume_token:
packet.resume_token = str(uuid.uuid4()) packet.resume_token = str(uuid.uuid4())
self._store[packet.id] = packet self._store[packet.id] = packet
logger.info( logger.info("[Escalation] إنشاء id=%s priority=%s reason=%s entity=%s/%s",
"[Escalation] إنشاء تصعيد id=%s priority=%s reason=%s entity=%s/%s tenant=%s",
packet.id, packet.priority.value, packet.reason.value, packet.id, packet.priority.value, packet.reason.value,
packet.entity_type, packet.entity_id, packet.tenant_id, packet.entity_type, packet.entity_id)
)
return packet return packet
async def assign(self, escalation_id: str, user_id: str) -> Optional[EscalationPacket]: async def assign(self, escalation_id: str, user_id: str) -> Optional[EscalationPacket]:
packet = self._store.get(escalation_id) p = self._store.get(escalation_id)
if not packet: if not p:
logger.warning("[Escalation] تصعيد غير موجود: %s", escalation_id)
return None return None
if packet.status == EscalationStatus.RESOLVED: if p.status == EscalationStatus.RESOLVED:
logger.warning("[Escalation] محاولة تعيين تصعيد محلول: %s", escalation_id) return p
return packet p.assigned_to = user_id
packet.assigned_to = user_id p.status = EscalationStatus.IN_PROGRESS
packet.status = EscalationStatus.IN_PROGRESS
logger.info("[Escalation] تعيين %s إلى %s", escalation_id, user_id) logger.info("[Escalation] تعيين %s إلى %s", escalation_id, user_id)
return packet return p
async def resolve(
self,
escalation_id: str,
resolution: ResolutionInput,
user_id: str,
) -> Optional[EscalationPacket]:
packet = self._store.get(escalation_id)
if not packet:
logger.warning("[Escalation] تصعيد غير موجود: %s", escalation_id)
return None
if packet.status == EscalationStatus.RESOLVED:
return packet
async def resolve(self, escalation_id: str, resolution: ResolutionInput,
user_id: str) -> Optional[EscalationPacket]:
p = self._store.get(escalation_id)
if not p or p.status == EscalationStatus.RESOLVED:
return p
now = datetime.now(timezone.utc) now = datetime.now(timezone.utc)
packet.status = EscalationStatus.RESOLVED p.status = EscalationStatus.RESOLVED
packet.resolved_at = now p.resolved_at = now
packet.resolution_data = { p.resolution_data = {"action_taken": resolution.action_taken,
"action_taken": resolution.action_taken, "override_data": resolution.override_data, "resolved_by": user_id}
"override_data": resolution.override_data, p.resolution_notes = resolution.notes
"resolved_by": user_id, self._history.append(p)
}
packet.resolution_notes = resolution.notes
self._history.append(packet)
if len(self._history) > self._max_history: if len(self._history) > self._max_history:
self._history = self._history[-self._max_history:] self._history = self._history[-self._max_history:]
logger.info("[Escalation] حل id=%s by=%s dur=%s",
logger.info( escalation_id, user_id, str(now - p.created_at))
"[Escalation] حل تصعيد id=%s by=%s dur=%s",
escalation_id, user_id,
str(now - packet.created_at) if packet.created_at else "N/A",
)
if resolution.resume_workflow: if resolution.resume_workflow:
await self._try_resume_workflow(packet) await self._try_resume(p)
return p
return packet
async def resume_workflow(self, escalation_id: str) -> dict[str, Any]: async def resume_workflow(self, escalation_id: str) -> dict[str, Any]:
packet = self._store.get(escalation_id) p = self._store.get(escalation_id)
if not packet: if not p:
return {"success": False, "error": "تصعيد غير موجود"} return {"success": False, "error": "تصعيد غير موجود"}
if packet.status != EscalationStatus.RESOLVED: if p.status != EscalationStatus.RESOLVED:
return {"success": False, "error": "التصعيد لم يُحل بعد"} return {"success": False, "error": "التصعيد لم يُحل بعد"}
return await self._try_resume_workflow(packet) return await self._try_resume(p)
async def _try_resume_workflow(self, packet: EscalationPacket) -> dict[str, Any]: async def _try_resume(self, p: EscalationPacket) -> dict[str, Any]:
handler = _workflow_resume_handlers.get(packet.workflow_name) handler = _workflow_resume_handlers.get(p.workflow_name)
if not handler: if not handler:
logger.info( return {"success": False, "error": f"لا يوجد معالج استئناف لـ {p.workflow_name}"}
"[Escalation] لا يوجد معالج استئناف لسير العمل: %s",
packet.workflow_name,
)
return {
"success": False,
"error": f"لا يوجد معالج استئناف لـ {packet.workflow_name}",
}
try: try:
result = await handler( result = await handler(resume_token=p.resume_token, entity_type=p.entity_type,
resume_token=packet.resume_token, entity_id=p.entity_id, resolution_data=p.resolution_data)
entity_type=packet.entity_type, logger.info("[Escalation] استئناف %s للتصعيد %s", p.workflow_name, p.id)
entity_id=packet.entity_id,
resolution_data=packet.resolution_data,
)
logger.info(
"[Escalation] استئناف سير العمل %s للتصعيد %s",
packet.workflow_name, packet.id,
)
return {"success": True, "result": result} return {"success": True, "result": result}
except Exception as exc: except Exception as exc:
logger.exception("[Escalation] فشل استئناف سير العمل: %s", exc) logger.exception("[Escalation] فشل استئناف: %s", exc)
return {"success": False, "error": str(exc)} return {"success": False, "error": str(exc)}
async def expire_overdue(self, tenant_id: str) -> int: async def expire_overdue(self, tenant_id: str) -> int:
now = datetime.now(timezone.utc) now, count = datetime.now(timezone.utc), 0
count = 0 for p in self._store.values():
for packet in self._store.values(): if (p.tenant_id == tenant_id
if ( and p.status in (EscalationStatus.PENDING, EscalationStatus.IN_PROGRESS)
packet.tenant_id == tenant_id and p.due_at < now):
and packet.status in (EscalationStatus.PENDING, EscalationStatus.IN_PROGRESS) p.status = EscalationStatus.EXPIRED
and packet.due_at < now
):
packet.status = EscalationStatus.EXPIRED
count += 1 count += 1
logger.info("[Escalation] انتهاء صلاحية تصعيد: %s", packet.id)
return count return count
async def list_pending( async def list_pending(self, tenant_id: str,
self, priority: Optional[EscalationPriority] = None) -> list[EscalationPacket]:
tenant_id: str, results = [p for p in self._store.values()
priority: Optional[EscalationPriority] = None, if p.tenant_id == tenant_id
) -> list[EscalationPacket]: and p.status in (EscalationStatus.PENDING, EscalationStatus.IN_PROGRESS)]
results = [
p for p in self._store.values()
if p.tenant_id == tenant_id and p.status in (
EscalationStatus.PENDING, EscalationStatus.IN_PROGRESS,
)
]
if priority: if priority:
results = [p for p in results if p.priority == priority] results = [p for p in results if p.priority == priority]
results.sort(key=lambda p: ( prio_order = list(EscalationPriority)
list(EscalationPriority).index(p.priority), p.created_at, results.sort(key=lambda p: (prio_order.index(p.priority), p.created_at))
))
return results return results
async def get(self, escalation_id: str) -> Optional[EscalationPacket]: async def get(self, escalation_id: str) -> Optional[EscalationPacket]:
@ -348,58 +254,36 @@ class EscalationService:
async def get_stats(self, tenant_id: str) -> EscalationStats: async def get_stats(self, tenant_id: str) -> EscalationStats:
now = datetime.now(timezone.utc) now = datetime.now(timezone.utc)
tenant_packets = [p for p in self._store.values() if p.tenant_id == tenant_id] packets = [p for p in self._store.values() if p.tenant_id == tenant_id]
by_prio: dict[str, int] = defaultdict(int)
by_priority: dict[str, int] = defaultdict(int)
by_status: dict[str, int] = defaultdict(int) by_status: dict[str, int] = defaultdict(int)
by_reason: dict[str, int] = defaultdict(int) by_reason: dict[str, int] = defaultdict(int)
resolution_times: list[float] = [] res_times: list[float] = []
oldest_pending_hours = 0.0 oldest_h, overdue = 0.0, 0
overdue = 0 for p in packets:
by_prio[p.priority.value] += 1
for p in tenant_packets:
by_priority[p.priority.value] += 1
by_status[p.status.value] += 1 by_status[p.status.value] += 1
by_reason[p.reason.value] += 1 by_reason[p.reason.value] += 1
if p.status == EscalationStatus.RESOLVED and p.resolved_at:
if p.status == EscalationStatus.RESOLVED and p.resolved_at and p.created_at: res_times.append((p.resolved_at - p.created_at).total_seconds() / 60.0)
resolution_times.append(
(p.resolved_at - p.created_at).total_seconds() / 60.0
)
if p.status in (EscalationStatus.PENDING, EscalationStatus.IN_PROGRESS): if p.status in (EscalationStatus.PENDING, EscalationStatus.IN_PROGRESS):
age_h = (now - p.created_at).total_seconds() / 3600.0 age_h = (now - p.created_at).total_seconds() / 3600.0
oldest_pending_hours = max(oldest_pending_hours, age_h) oldest_h = max(oldest_h, age_h)
if p.due_at < now: if p.due_at < now:
overdue += 1 overdue += 1
# Include resolved history for this tenant
for p in self._history: for p in self._history:
if p.tenant_id == tenant_id and p.id not in self._store: if p.tenant_id == tenant_id and p.id not in self._store and p.resolved_at:
if p.resolved_at and p.created_at: res_times.append((p.resolved_at - p.created_at).total_seconds() / 60.0)
resolution_times.append(
(p.resolved_at - p.created_at).total_seconds() / 60.0
)
return EscalationStats( return EscalationStats(
total=len(tenant_packets), total=len(packets), by_priority=dict(by_prio), by_status=dict(by_status),
by_priority=dict(by_priority),
by_status=dict(by_status),
by_reason=dict(by_reason), by_reason=dict(by_reason),
avg_resolution_minutes=( avg_resolution_minutes=sum(res_times) / len(res_times) if res_times else 0.0,
sum(resolution_times) / len(resolution_times) if resolution_times else 0.0 oldest_pending_hours=round(oldest_h, 2), overdue_count=overdue)
),
oldest_pending_hours=round(oldest_pending_hours, 2),
overdue_count=overdue,
)
async def check_auto_escalation( async def check_auto_escalation(self, tenant_id: str,
self, context: dict[str, Any]) -> Optional[EscalationPacket]:
tenant_id: str,
context: dict[str, Any],
) -> Optional[EscalationPacket]:
for rule in self._rules: for rule in self._rules:
if self._evaluate_rule(rule, context): if self._eval(rule, context):
packet = EscalationPacket( packet = EscalationPacket(
tenant_id=tenant_id, tenant_id=tenant_id,
title=f"Auto-escalation: {rule.id}", title=f"Auto-escalation: {rule.id}",
@ -408,36 +292,29 @@ class EscalationService:
entity_id=context.get("entity_id", ""), entity_id=context.get("entity_id", ""),
workflow_name=context.get("workflow_name", ""), workflow_name=context.get("workflow_name", ""),
failed_step=context.get("current_step", ""), failed_step=context.get("current_step", ""),
reason=rule.reason, reason=rule.reason, priority=rule.priority,
priority=rule.priority,
risk_if_delayed_ar=rule.suggested_action_ar, risk_if_delayed_ar=rule.suggested_action_ar,
suggested_action=rule.suggested_action_ar, suggested_action=rule.suggested_action_ar,
suggested_action_ar=rule.suggested_action_ar, suggested_action_ar=rule.suggested_action_ar,
confidence=context.get("confidence", 0.0), confidence=context.get("confidence", 0.0),
artifacts=[EscalationArtifact( artifacts=[EscalationArtifact(type="context", name="auto_context",
type="context", name="auto_escalation_context", content=str(context))])
content=str(context), logger.info("[Escalation] تصعيد تلقائي rule=%s entity=%s/%s",
)], rule.id, packet.entity_type, packet.entity_id)
) return await self.create(packet)
created = await self.create(packet)
logger.info(
"[Escalation] تصعيد تلقائي rule=%s entity=%s/%s",
rule.id, packet.entity_type, packet.entity_id,
)
return created
return None return None
@staticmethod @staticmethod
def _evaluate_rule(rule: AutoEscalationRule, context: dict[str, Any]) -> bool: def _eval(rule: AutoEscalationRule, ctx: dict[str, Any]) -> bool:
cond = rule.condition c = rule.condition
if "deal_value_sar > 100000" in cond: if "deal_value_sar > 100000" in c:
return context.get("deal_value_sar", 0) > 100_000 return ctx.get("deal_value_sar", 0) > 100_000
if "days_since_last_response > 5" in cond: if "days_since_last_response > 5" in c:
return context.get("days_since_last_response", 0) > 5 return ctx.get("days_since_last_response", 0) > 5
if "ai_confidence < 0.3" in cond: if "ai_confidence < 0.3" in c:
return context.get("confidence", 1.0) < 0.3 return ctx.get("confidence", 1.0) < 0.3
if "consent_expired == true" in cond: if "consent_expired == true" in c:
return context.get("consent_expired", False) is True return ctx.get("consent_expired", False) is True
if "delivery_failures >= 3" in cond: if "delivery_failures >= 3" in c:
return context.get("delivery_failures", 0) >= 3 return ctx.get("delivery_failures", 0) >= 3
return False return False

15
salesflow-saas/backend/app/services/skill_registry.py
View File

@ -1,17 +1,10 @@
""" """Skill Registry + Runtime — Dealix AI Revenue OS — نظام المهارات"""
Skill Registry + Runtime — Dealix AI Revenue OS
نظام المهارات: تسجيل وإدارة وتنفيذ مهارات CRM بشكل آمن.
"""
from __future__ import annotations from __future__ import annotations
import asyncio import asyncio, logging, os, uuid
import logging
import os
import uuid
from datetime import datetime, timezone from datetime import datetime, timezone
from enum import Enum from enum import Enum
from typing import Any, Callable, Coroutine, Optional from typing import Any, Callable, Coroutine, Optional
from pydantic import BaseModel, Field from pydantic import BaseModel, Field
logger = logging.getLogger(__name__) logger = logging.getLogger(__name__)
@ -56,7 +49,6 @@ class SkillDefinition(BaseModel):
version: str = "1.0.0" version: str = "1.0.0"
model_config = {"arbitrary_types_allowed": True} model_config = {"arbitrary_types_allowed": True}
class UserContext(BaseModel): class UserContext(BaseModel):
user_id: str user_id: str
tenant_id: str tenant_id: str
@ -77,14 +69,12 @@ class SkillResult(BaseModel):
duration_ms: Optional[int] = None duration_ms: Optional[int] = None
approval_request_id: Optional[str] = None approval_request_id: Optional[str] = None
class SkillHealthReport(BaseModel): class SkillHealthReport(BaseModel):
skill_id: str skill_id: str
healthy: bool healthy: bool
checked_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc)) checked_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
error: Optional[str] = None error: Optional[str] = None
class SkillRegistry: class SkillRegistry:
"""Manages all registered domain skills.""" """Manages all registered domain skills."""
@ -138,7 +128,6 @@ class SkillRegistry:
def get_handler(self, skill_id: str) -> Optional[Callable]: def get_handler(self, skill_id: str) -> Optional[Callable]:
return self._handlers.get(skill_id) return self._handlers.get(skill_id)
class SkillRuntime: class SkillRuntime:
"""Executes skills safely with validation, logging, and approval gating.""" """Executes skills safely with validation, logging, and approval gating."""

64
salesflow-saas/backend/requirements.txt
View File

@ -1,37 +1,85 @@
# === Core Framework ===
fastapi==0.115.5 fastapi==0.115.5
uvicorn[standard]==0.32.1 uvicorn[standard]==0.32.1
pydantic==2.9.2 pydantic==2.9.2
pydantic-settings==2.6.1 pydantic-settings==2.6.1
pydantic-extra-types[phonenumbers]>=2.0.0 # Saudi phone validation (+966)
python-multipart==0.0.12 python-multipart==0.0.12
# === Database ===
sqlalchemy==2.0.36 sqlalchemy==2.0.36
asyncpg==0.30.0 asyncpg==0.30.0
psycopg2-binary==2.9.10 psycopg2-binary==2.9.10
alembic==1.14.0 alembic==1.14.0
pgvector==0.3.6 pgvector==0.3.6
# === AI / LLM Providers ===
litellm>=1.40.0 # Unified LLM provider (Groq/OpenAI/Claude/Gemini) with fallback
instructor>=1.14.0 # Structured LLM outputs via Pydantic models
groq==0.12.0 groq==0.12.0
openai==1.57.0 openai==1.57.0
langchain==0.3.9 langchain==0.3.9
langchain-groq==0.2.1 langchain-groq==0.2.1
langchain-community==0.3.9 langchain-community==0.3.9
langchain-anthropic==0.2.0
langgraph==0.2.53 langgraph==0.2.53
crewai==0.80.0
mem0ai==0.1.18
# === Arabic NLP ===
camel-tools>=1.5.0 # Arabic morphology, NER, dialect detection (NYU Abu Dhabi)
pyarabic>=0.6.15 # Arabic text normalization, diacritics removal
# === WhatsApp Business API ===
pywa>=3.0.0 # Direct WhatsApp Cloud API (async, webhooks, templates)
twilio==9.3.7 # Twilio fallback
# === Communication ===
httpx==0.27.2 httpx==0.27.2
resend>=2.0.0 # Transactional email API (free tier, FastAPI-native)
# === Saudi-specific ===
hijridate>=2.4.0 # Hijri-Gregorian calendar (Umm al-Qura, official Saudi)
phonenumbers>=8.13.0 # Saudi phone number validation and formatting
# === PDF Generation (Arabic RTL) ===
weasyprint>=60.0 # HTML/CSS to PDF with Arabic RTL support
# === Security ===
PyJWT[crypto]>=2.8.0 # JWT (replaces abandoned python-jose)
passlib[bcrypt]==1.7.4
bcrypt>=4.0.1,<5
slowapi>=0.1.9 # API rate limiting with Redis backend
# === Caching & Performance ===
redis==5.2.0
fastapi-cache2>=0.2.1 # Response caching with Redis backend
celery-redbeat>=2.2.0 # Dynamic Celery Beat scheduler (Redis-backed)
# === Monitoring & Logging ===
sentry-sdk[fastapi]>=2.0.0 # Error tracking + performance monitoring
prometheus-fastapi-instrumentator>=7.0.0 # Prometheus metrics
structlog>=24.0.0 # Structured JSON logging with tenant context
# === Testing ===
pytest>=8.0.0
pytest-asyncio>=0.23.0 # Async test support
pytest-cov>=5.0.0 # Coverage reporting
factory-boy>=3.3.0 # Test data factories for SQLAlchemy models
# === Forecasting ===
statsforecast>=1.7.0 # Fast statistical time-series forecasting
# === Data & Utilities ===
beautifulsoup4==4.12.3 beautifulsoup4==4.12.3
lxml==5.3.0 lxml==5.3.0
twilio==9.3.7
requests==2.32.3 requests==2.32.3
python-dateutil==2.9.0 python-dateutil==2.9.0
pandas==2.2.3 pandas==2.2.3
numpy==2.1.3 numpy==2.1.3
python-jose[cryptography]==3.3.0
passlib[bcrypt]==1.7.4
bcrypt>=4.0.1,<5
python-decouple==3.8 python-decouple==3.8
redis==5.2.0
paramiko==3.5.0 paramiko==3.5.0
qrcode==8.0 qrcode==8.0
Pillow==11.0.0 Pillow==11.0.0
xmltodict==0.14.2 xmltodict==0.14.2
email-validator>=2.1.0 email-validator>=2.1.0
crewai==0.80.0
mem0ai==0.1.18
langchain-anthropic==0.2.0

64
salesflow-saas/memory/patterns/library-decisions.md Normal file
View File

@ -0,0 +1,64 @@
# Library Decisions — Dealix AI Revenue OS
**Type**: pattern
**Date**: 2026-04-11
**Status**: active
## Added Libraries (Priority Order)
### Immediate (Security + Core)
| Library | Why | Replaces |
|---------|-----|----------|
| `PyJWT[crypto]` | Active JWT library | `python-jose` (abandoned 3+ years) |
| `litellm` | Unified LLM provider with auto-fallback | Manual Groq→OpenAI switching |
| `sentry-sdk[fastapi]` | Production error tracking | None (was missing) |
| `slowapi` | API rate limiting | None (was missing) |
| `pydantic-extra-types[phonenumbers]` | Saudi +966 phone validation | None |
### Arabic & Saudi
| Library | Why |
|---------|-----|
| `camel-tools` | Best Arabic NLP (NYU Abu Dhabi) — morphology, NER, dialect detection |
| `pyarabic` | Arabic text normalization before NLP processing |
| `hijridate` | Official Umm al-Qura Hijri calendar for Saudi UX |
| `phonenumbers` | Format/validate Saudi mobile numbers for WhatsApp |
### Communication
| Library | Why |
|---------|-----|
| `pywa` | Direct WhatsApp Cloud API (cheaper than Twilio per-message) |
| `resend` | Transactional email with free tier |
| `weasyprint` | Arabic RTL PDF generation for invoices/quotes |
### Performance & Monitoring
| Library | Why |
|---------|-----|
| `fastapi-cache2` | Redis-backed response caching (90% DB load reduction) |
| `celery-redbeat` | Dynamic Celery scheduling from Redis (no restart needed) |
| `prometheus-fastapi-instrumentator` | Prometheus metrics for Grafana dashboards |
| `structlog` | JSON structured logging with tenant_id context |
### AI Enhancement
| Library | Why |
|---------|-----|
| `instructor` | Extract structured Pydantic models from LLM outputs |
| `statsforecast` | Fast time-series forecasting (500x faster than Prophet) |
### Testing
| Library | Why |
|---------|-----|
| `pytest-asyncio` | Test async FastAPI endpoints |
| `pytest-cov` | Coverage reporting |
| `factory-boy` | Test data factories for SQLAlchemy models |
## Rejected Libraries
| Library | Why Rejected |
|---------|-------------|
| `prophet` | Heavy dependencies (PyStan), statsforecast is faster |
| `elasticsearch` | Too heavy for current scale, use pg_trgm then Meilisearch |
| `apscheduler` | Already have Celery, celery-redbeat is better fit |
| `fatoora` | Abandoned (2022), built our own ZATCA QR in invoice_generator.py |
## Migration Notes
- **python-jose → PyJWT**: Minor API change. `jose.jwt.decode()` → `jwt.decode()`. Same RSA/HS256 support.
- **Manual LLM fallback → litellm**: Replace `services/llm/provider.py` logic with `litellm.completion()` + fallback list.