AI Lead Scoring for Perfex CRM

Module documentation for installation, configuration, and full feature usage.

This is a Perfex CRM module (not standalone).
Required: Perfex CRM installed and active.

1. Installation

1. Zip folder name should be ai_lead_scoring (standard Perfex module structure).
2. Go to Setup → Modules.
3. Upload module zip and click Install.
4. Click Activate.
5. Go to Setup → Settings → AI → AI Lead Scoring and configure provider/API key.

2. Menu & Pages

• Dashboard - KPIs, charts, AI usage & cost, recent scores.
• AI Scores - table view with filters and bulk score actions.
• Rules - condition-based score points.
• Labels - score range labels (Hot/Warm/Cold defaults protected).
• Settings - provider/model/API key, auto-rescore, retry, payload fields.

3. Settings

AI Provider & Model

• Providers: OpenAI, Anthropic, Gemini, Grok, OpenRouter.
• OpenRouter requires custom model name and input/output token pricing.

Automatic Rescoring

• Enable/Disable automatic rescoring.
• Frequency: Daily, Bi-weekly, Weekly, Monthly.
• Retry count, retry delay (minutes), batch size per run.

Lead Data Sent to AI

• Select exactly which standard lead fields are sent.
• Select which lead custom fields are sent.
• Default behavior includes all available fields until changed.

4. Lead Modal AI Score Tab

• Shows final score, label, confidence, reasons, recommended action.
• Shows AI base score + rules points + final calculation.
• Shows last scored at and scored by (staff/cron).
• Actions: Score Lead, Rescore Lead, Cancel queued job.
• Admin-only raw JSON debug section.

5. AI Scores Page

• Columns: Lead, Final Score, Label, Last Activity, Last Scored At, Scored By, Actions.
• Top KPI cards: Total Leads, Scored Leads, Pending Jobs, Unscored Leads.
• Filters via App_table_filter (score/label/staff/source/unscored).
• Bulk scoring queues selected leads asynchronously.

6. Scoring Rules

• Supported conditions: has_website, has_phone, has_company, has_email, lead_source_is, lead_status_is, custom_field_exists.
• has_* uses Yes/No mode.
• Score points accept positive and negative values.
• Rule points are added to AI base score before final clamping to 0-100.

7. Scoring Labels

• Define label names and score ranges.
• Color per label for UI consistency.
• Default labels Hot/Warm/Cold are undeletable for system stability.

8. Dashboard

• KPI cards with icons.
• Charts: Hot/Warm/Cold donut, score distribution, rescore volume, usage/cost.
• Recent Scores table sorted by latest timestamp first.
• Empty states for no-data charts and lists.

9. Queue, Cron, and Retries

• Manual/bulk actions create queue jobs (not inline scoring).
• Cron processes jobs in batches and runs scheduled rescoring.
• Non-retryable failures (e.g., API key/provider config, quota/billing limits) are marked failed directly.

10. Support

For help with setup, migration, or troubleshooting:
support@maniss.dev