# AI Agent Registry

Dealix runs 18 specialized AI agents. Each agent executes as a Celery task, receives structured input, returns structured output, and follows defined escalation rules. All invocations are logged to `ai_conversations` for audit.

---

## 1. Lead Qualification Agent

| Property | Value |
|----------|-------|
| **ID** | `lead_qualification` |
| **Role** | Score and qualify inbound leads based on profile, behavior, and sector fit |
| **Inputs** | Lead record (name, phone, email, company, sector, city, source), activity history, tenant scoring rules |
| **Outputs** | Qualification score (0-100), status recommendation (qualified/unqualified), reasoning, suggested next action |
| **Escalation** | Score between 40-60 (ambiguous) -> flag for human review. Missing critical fields -> request enrichment before scoring |

## 2. Affiliate Recruitment Evaluator

| Property | Value |
|----------|-------|
| **ID** | `affiliate_evaluator` |
| **Role** | Evaluate affiliate applications for approval based on profile, network reach, and sector alignment |
| **Inputs** | Affiliate application (profile, experience, sector, network size, motivation), tenant criteria |
| **Outputs** | Approval recommendation (approve/reject/review), tier suggestion, risk flags, onboarding notes |
| **Escalation** | High-risk indicators (fraud history, competitor affiliation) -> escalate to admin. Borderline cases -> queue for manual review |

## 3. Onboarding Coach

| Property | Value |
|----------|-------|
| **ID** | `onboarding_coach` |
| **Role** | Guide new affiliates and agents through platform onboarding with step-by-step instructions |
| **Inputs** | User profile, role (affiliate/agent), completed onboarding steps, language preference |
| **Outputs** | Next onboarding step, instructional message (Arabic or English), checklist status, resource links |
| **Escalation** | User stuck for >48 hours -> notify manager. Repeated confusion on same step -> flag UX issue |

## 4. Outreach Writer

| Property | Value |
|----------|-------|
| **ID** | `outreach_writer` |
| **Role** | Draft personalized outreach messages for leads across channels (WhatsApp, email, SMS) |
| **Inputs** | Lead profile, sector, channel, language, campaign context, previous interactions, template (optional) |
| **Outputs** | Draft message, subject line (email), suggested send time, A/B variant (optional) |
| **Escalation** | Compliance flag on content (regulated sector) -> route to Compliance Reviewer. Lead marked do-not-contact -> block and alert |

## 5. Arabic WhatsApp Agent

| Property | Value |
|----------|-------|
| **ID** | `arabic_whatsapp` |
| **Role** | Handle Arabic WhatsApp conversations with leads and contacts autonomously |
| **Inputs** | Inbound WhatsApp message, conversation history, lead/contact record, active campaign context |
| **Outputs** | Reply message (Arabic), detected intent, sentiment, extracted entities, conversation state update |
| **Escalation** | Negative sentiment for 2+ consecutive messages -> transfer to human. Request for pricing/legal terms -> transfer to agent. Unrecognized intent after 2 attempts -> transfer to human |

## 6. English Conversation Agent

| Property | Value |
|----------|-------|
| **ID** | `english_conversation` |
| **Role** | Handle English conversations across WhatsApp, email, and chat |
| **Inputs** | Inbound message, channel, conversation history, lead/contact record |
| **Outputs** | Reply message (English), detected intent, sentiment, extracted entities, conversation state update |
| **Escalation** | Same rules as Arabic WhatsApp Agent. Language switch detected -> hand off to Arabic WhatsApp Agent |

## 7. Voice Call Agent

| Property | Value |
|----------|-------|
| **ID** | `voice_call` |
| **Role** | Analyze voice call transcripts and provide real-time call guidance |
| **Inputs** | Call transcript (live or post-call), lead/contact record, deal context, call direction |
| **Outputs** | Call summary, sentiment analysis, key topics extracted, recommended follow-up actions, objections detected |
| **Escalation** | Customer threat or legal mention -> alert supervisor immediately. Competitor mention -> flag for strategy review |

## 8. Meeting Booking Agent

| Property | Value |
|----------|-------|
| **ID** | `meeting_booking` |
| **Role** | Negotiate and book meeting times with leads via conversational exchange |
| **Inputs** | Lead record, assigned agent calendar availability, preferred channel, language, timezone |
| **Outputs** | Proposed time slots, booking confirmation message, calendar event payload, auto_booking record |
| **Escalation** | Lead rejects 3+ proposed times -> escalate to human agent. Calendar conflict detected -> alert assigned agent |

## 9. Sector Strategist

| Property | Value |
|----------|-------|
| **ID** | `sector_strategist` |
| **Role** | Generate sector-specific sales strategies, talking points, and competitive positioning |
| **Inputs** | Sector identifier, company profile, deal context, knowledge base articles, competitor data |
| **Outputs** | Strategy brief, key talking points, objection predictions, recommended assets, pricing guidance |
| **Escalation** | Unknown sector with no knowledge base data -> flag for content team. Conflicting market data -> flag for review |

## 10. Objection Handler

| Property | Value |
|----------|-------|
| **ID** | `objection_handler` |
| **Role** | Detect objections in conversations and generate contextual responses |
| **Inputs** | Conversation message(s), detected objection type, lead/deal context, sector, language |
| **Outputs** | Objection classification, recommended response (Arabic/English), supporting evidence, confidence score |
| **Escalation** | Pricing objection on deal >100K SAR -> involve manager. Legal/compliance objection -> route to Compliance Reviewer |

## 11. Proposal Drafter

| Property | Value |
|----------|-------|
| **ID** | `proposal_drafter` |
| **Role** | Generate structured proposals and pitch decks based on deal context and sector assets |
| **Inputs** | Deal record, company profile, sector assets, pricing data, template, language |
| **Outputs** | Proposal document (structured JSON), executive summary, pricing table, terms section, version number |
| **Escalation** | Deal value >500K SAR -> require manager approval before sending. Custom terms requested -> flag for legal review |

## 12. QA Reviewer

| Property | Value |
|----------|-------|
| **ID** | `qa_reviewer` |
| **Role** | Review AI-generated content (messages, proposals, responses) for quality, accuracy, and tone |
| **Inputs** | Generated content, content type, target audience, language, context |
| **Outputs** | Quality score (0-100), issues found, suggested corrections, approval status (pass/revise/fail) |
| **Escalation** | Score below 50 -> block content from sending, alert content team. Factual error detected -> block and flag |

## 13. Compliance Reviewer

| Property | Value |
|----------|-------|
| **ID** | `compliance_reviewer` |
| **Role** | Check messages, proposals, and actions for regulatory compliance (Saudi regulations, data protection, marketing laws) |
| **Inputs** | Content to review, content type, target region, sector, applicable policies |
| **Outputs** | Compliance status (compliant/non_compliant/review_needed), violations found, required changes, regulation references |
| **Escalation** | Clear violation -> block action and alert compliance officer. Ambiguous case -> queue for human legal review |

## 14. Knowledge Retrieval Agent

| Property | Value |
|----------|-------|
| **ID** | `knowledge_retrieval` |
| **Role** | Search and retrieve relevant knowledge base articles using semantic search (RAG) |
| **Inputs** | Query (natural language), sector filter, language, context (which agent is requesting) |
| **Outputs** | Ranked article list with relevance scores, extracted snippets, source references |
| **Escalation** | No relevant results found (all scores below threshold) -> flag knowledge gap for content team |

## 15. Revenue Attribution Agent

| Property | Value |
|----------|-------|
| **ID** | `revenue_attribution` |
| **Role** | Attribute revenue to affiliates, campaigns, and channels using multi-touch attribution |
| **Inputs** | Deal record, lead journey (touchpoints), affiliate referral data, campaign history |
| **Outputs** | Attribution breakdown (affiliate %, campaign %, channel %), commission calculation, confidence score |
| **Escalation** | Multiple affiliates claim same lead -> flag for dispute resolution. Attribution confidence below 70% -> flag for manual review |

## 16. Fraud Reviewer

| Property | Value |
|----------|-------|
| **ID** | `fraud_reviewer` |
| **Role** | Detect fraudulent patterns in affiliate activity, lead generation, and commission claims |
| **Inputs** | Affiliate activity log, lead generation patterns, commission history, IP/device data, behavioral signals |
| **Outputs** | Risk score (0-100), fraud indicators found, recommended action (clear/monitor/suspend/block), evidence summary |
| **Escalation** | Risk score >80 -> auto-suspend affiliate and alert admin. Coordinated fraud pattern (multiple accounts) -> escalate to platform security |

## 17. Guarantee Reviewer

| Property | Value |
|----------|-------|
| **ID** | `guarantee_reviewer` |
| **Role** | Evaluate gold guarantee claims for validity and recommend approval or denial |
| **Inputs** | Guarantee claim, deal record, customer record, service delivery evidence, policy rules |
| **Outputs** | Validity assessment, recommendation (approve/deny/partial), refund amount suggestion, reasoning, policy references |
| **Escalation** | Claim >50K SAR -> require director approval. Repeat claimant (3+ claims) -> flag for fraud review. Policy ambiguity -> escalate to legal |

## 18. Management Summary Agent

| Property | Value |
|----------|-------|
| **ID** | `management_summary` |
| **Role** | Generate executive summaries and reports for management dashboards |
| **Inputs** | Time period, metrics scope (revenue, pipeline, affiliates, agents, guarantees), tenant data |
| **Outputs** | Executive summary (Arabic/English), key metrics, trend analysis, alerts, recommended actions |
| **Escalation** | Revenue decline >20% period-over-period -> urgent alert to owner. Data anomaly detected -> flag for investigation |

---

## Agent Invocation Flow

```
Event Received
     |
     v
Agent Router --> selects agent(s) by event type
     |
     v
Input Validation --> schema check
     |
     v
Celery Task Dispatch --> async execution
     |
     v
LLM Call --> OpenAI / provider
     |
     v
Output Parsing --> structured response
     |
     v
Escalation Check --> meets escalation criteria?
     |                    |
     No                  Yes
     |                    |
     v                    v
Action Handler      Human Handoff
(DB update,         (notify agent,
 send message,       create task,
 book meeting)       alert manager)
     |                    |
     v                    v
Log to ai_conversations
```

## Agent Configuration

Each agent is defined in `ai-agents/` with:

- `prompt.md` - System prompt and instructions
- `schema.json` - Input/output JSON schema
- `config.yml` - Model, temperature, max tokens, retry policy, escalation rules
- `tests/` - Example inputs and expected outputs