Add AICL example: 37_crm_platform.aicl

data/aicl/examples/37_crm_platform.aicl

@@ -0,0 +1,352 @@
+# AICL Example: CRM Platform
+# Comprehensive customer relationship management platform with contact management, sales pipeline, marketing automation, analytics, and third-party integration capabilities
+
+Goal: Deliver a CRM platform that unifies customer data across all touchpoints, accelerates sales velocity through intelligent pipeline management, automates marketing campaigns with behavioral triggers, and provides actionable analytics for revenue optimization and customer lifetime value maximization
+
+Constraint: All customer data must respect consent preferences and honor opt-out requests within 24 hours across all channels
+Constraint: Sales pipeline stage transitions must enforce required data completeness before advancement
+Constraint: Marketing automation must throttle outbound communications per contact to prevent spam fatigue
+Constraint: API integrations must implement circuit breaker patterns to prevent downstream failures from affecting core CRM operations
+Constraint: Reporting queries must not impact transactional system performance during business hours
+
+Risk: Data deduplication failure creating fragmented customer profiles across modules
+Recovery: Execute automated merge detection using fuzzy matching on email, phone, and company attributes; flag unresolved duplicates for manual review; preserve activity history from both records during merge
+
+Risk: Sales pipeline manipulation via unauthorized stage regression or forecast inflation
+Recovery: Enforce immutable audit log for all pipeline changes; detect anomalous stage movement patterns; alert sales operations on suspicious modifications; enable one-click revert to previous state
+
+Risk: Marketing campaign blowback from segment misconfiguration sending to wrong audience
+Recovery: Implement pre-send preview with recipient count validation; require dual approval for campaigns exceeding threshold; enable immediate kill switch to halt in-progress sends; auto-generate apology workflow for affected contacts
+
+Risk: Integration API credential exposure or unauthorized third-party data access
+Recovery: Rotate all affected API keys immediately; audit access logs for unauthorized data exfiltration; notify affected customers per breach disclosure requirements; enforce scoped token permissions going forward
+
+Risk: Analytics report inaccuracy from stale or incorrectly joined data across modules
+Recovery: Implement data freshness checks with timestamp validation; flag reports using data older than threshold; provide cache invalidation trigger; regenerate reports from source on demand
+
+Risk: Lead assignment bias causing uneven distribution and revenue impact
+Recovery: Monitor assignment distribution metrics in real-time; detect deviation from round-robin or territory rules; auto-rebalance queued assignments; alert sales manager on persistent imbalance
+
+Layer: ContactManagement
+    SubLayer: ContactRecords
+    SubLayer: CompanyAccounts
+    SubLayer: ActivityTracking
+    SubLayer: DataEnrichment
+
+Layer: SalesPipeline
+    SubLayer: LeadManagement
+    SubLayer: OpportunityTracking
+    SubLayer: ForecastManagement
+    SubLayer: DealRoom
+
+Layer: MarketingAutomation
+    SubLayer: CampaignBuilder
+    SubLayer: SegmentEngine
+    SubLayer: EmailOrchestration
+    SubLayer: LeadScoring
+
+Layer: Analytics
+    SubLayer: RevenueAnalytics
+    SubLayer: FunnelAnalytics
+    SubLayer: CustomerHealth
+    SubLayer: PredictiveInsights
+
+Layer: Integration
+    SubLayer: APIGateway
+    SubLayer: ConnectorFramework
+    SubLayer: DataSync
+    SubLayer: WebhookRouter
+
+Validation: Contact records must have at least one validated communication channel (email or phone)
+Validation: Opportunity amounts must be positive and currency must match account billing currency
+Validation: Marketing campaign segments must contain at least one consented contact before activation
+Validation: Sales forecast rollups must reconcile with individual opportunity projections
+Validation: API integration tokens must have explicit scope declarations and expiration policies
+Validation: Lead assignment must verify active sales representative with valid territory coverage
+
+Entity Contact
+    contactId: string
+    firstName: string
+    lastName: string
+    email: string
+    phone: string
+    companyId: string
+    jobTitle: string
+    lifecycleStage: string
+    leadScore: float
+    lastActivityDate: datetime
+    consentStatus: dict
+    customFields: dict
+    owner: string
+
+Entity Opportunity
+    opportunityId: string
+    dealName: string
+    accountId: string
+    contactId: string
+    amount: float
+    currencyCode: string
+    stage: string
+    probability: float
+    closeDate: datetime
+    owner: string
+    pipeline: string
+    products: list
+    competitors: list
+    activityCount: integer
+
+Entity Campaign
+    campaignId: string
+    campaignName: string
+    campaignType: string
+    status: string
+    startDate: datetime
+    endDate: datetime
+    targetSegment: string
+    budgetAllocated: float
+    budgetSpent: float
+    channelMix: dict
+    goals: dict
+    approvalStatus: string
+    sendsCompleted: integer
+
+Entity SalesForecast
+    forecastId: string
+    period: string
+    owner: string
+    pipeline: string
+    committedAmount: float
+    bestCaseAmount: float
+    worstCaseAmount: float
+    weightedPipeline: float
+    closedWonAmount: float
+    forecastAccuracy: float
+    lastUpdated: datetime
+    adjustmentReason: string
+
+Entity IntegrationConnector
+    connectorId: string
+    connectorName: string
+    connectorType: string
+    endpoint: string
+    authMethod: string
+    tokenScope: list
+    syncFrequency: string
+    lastSyncTime: datetime
+    status: string
+    errorCount: integer
+    rateLimit: integer
+    fieldMappings: dict
+
+Entity ActivityLog
+    activityId: string
+    entityType: string
+    entityId: string
+    activityType: string
+    description: string
+    performedBy: string
+    performedAt: datetime
+    channel: string
+    outcome: string
+    duration: integer
+    linkedRecords: list
+
+Behavior CreateOpportunity
+    Input: accountId: string, contactId: string, dealName: string, amount: float, stage: string, owner: string
+    Output: opportunity: Opportunity
+    Action: Validate account and contact existence; check territory alignment with owner; calculate initial probability based on stage; validate amount and currency; persist opportunity; trigger pipeline stage automation; emit opportunity created event; assign activity sequence; update forecast projection
+
+Behavior ExecuteCampaign
+    Input: campaignId: string, approvalToken: string
+    Output: executionResult: dict
+    Action: Validate campaign approval status; resolve target segment membership; check consent compliance per contact; apply communication throttling rules; schedule send batches; execute multi-channel delivery; track send and engagement events; update campaign metrics in real-time; emit campaign activated event
+
+Behavior ScoreLead
+    Input: contactId: string, scoringModel: string
+    Output: leadScore: float
+    Action: Load contact demographic and firmographic data; aggregate behavioral signals across touchpoints; apply scoring model weights; compute composite lead score; determine lifecycle stage transition eligibility; update contact record; emit lead score changed event; trigger assignment or nurture path based on score threshold
+
+Behavior GenerateForecast
+    Input: period: string, owner: string, pipeline: string
+    Output: forecast: SalesForecast
+    Action: Aggregate open opportunities by stage; apply stage-based probability weighting; calculate committed best case and worst case scenarios; incorporate historical forecast accuracy adjustments; validate against quota targets; persist forecast; emit forecast generated event; push to analytics dashboard
+
+Behavior SyncIntegrationData
+    Input: connectorId: string, direction: string, entityTypes: list
+    Output: syncResult: dict
+    Action: Retrieve connector configuration and field mappings; check rate limit capacity; execute data extraction from source; transform data per mapping rules; validate data integrity; apply conflict resolution strategy; persist synced records; update last sync timestamp; emit sync completed event; log sync statistics
+
+Behavior MergeContacts
+    Input: primaryContactId: string, duplicateContactId: string, mergeStrategy: dict
+    Output: mergedContact: Contact
+    Action: Validate both contacts exist; determine field-level winner per merge strategy; consolidate activity history; reassign all related records to primary; archive duplicate record; emit contact merged event; update segmentation memberships; recalculate lead score; notify contact owner of merge
+
+Condition:
+    When contact.leadScore exceeds hotThreshold AND contact.lifecycleStage is not yet "opportunity"
+    Then auto-promote to sales qualified lead; assign to territory owner; create opportunity draft; trigger sales notification sequence; log promotion event in activity timeline
+
+Condition:
+    When opportunity.closeDate is within 3 days AND opportunity.stage is not "closed_won" or "closed_lost"
+    Then escalate to sales manager; add to deal review queue; send reminder to opportunity owner; adjust probability weighting in forecast; flag for pipeline review
+
+Condition:
+    When campaign.budgetSpent exceeds campaign.budgetAllocated by more than 5 percent
+    Then pause active campaign sends; notify marketing operations; generate budget overrun report; require explicit approval to resume; adjust remaining segment volumes
+
+Condition:
+    When integrationConnector.errorCount exceeds 5 consecutive failures
+    Then circuit breaker opens and disables connector; notify integration admin; switch to fallback data source if available; log diagnostic information; enable manual reactivation after health check
+
+Condition:
+    When salesForecast.forecastAccuracy drops below 60 percent for 2 consecutive periods
+    Then flag forecast for review by sales operations; trigger pipeline inspection workflow; suggest probability recalibration; adjust weighting factors; notify forecast owner
+
+Event:
+    On OpportunityStageChanged
+    Action: Update pipeline analytics; recalculate forecast projections; trigger stage-specific automation sequence; update contact lifecycle stage if applicable; notify deal team; log stage transition in activity timeline
+
+Event:
+    On CampaignEmailEngaged
+    Action: Update contact engagement score; record interaction in activity log; trigger follow-up nurture sequence if applicable; update segment membership; feed real-time campaign performance dashboard; increment engagement counter
+
+Event:
+    On LeadScoreThresholdCrossed
+    Action: Evaluate lifecycle stage transition eligibility; trigger assignment routing if sales qualified; add to appropriate nurture track if not; notify assigned sales rep; update pipeline health metrics; log threshold event
+
+Event:
+    On IntegrationSyncFailed
+    Action: Log error with diagnostic context; increment error counter; evaluate circuit breaker threshold; notify integration admin if threshold approached; queue retry with exponential backoff; preserve data consistency with transaction boundary
+
+Event:
+    On ContactMerged
+    Action: Update all segment memberships; recalculate aggregate analytics; refresh search index; archive duplicate record; notify downstream integrations; update activity timeline with merge notation
+
+Parallel:
+    - Contact data enrichment from third-party providers
+    - Lead scoring model batch computation
+    - Campaign delivery execution across channels
+    - Forecast aggregation and rollup processing
+    - Integration data synchronization cycles
+
+Optimize: Sales pipeline velocity and forecast accuracy
+    Priority: Data integrity and consent compliance over campaign throughput
+    Priority: Sales representative productivity over administrative completeness
+    Priority: Customer experience personalization over batch efficiency
+    Priority: Real-time engagement responsiveness over resource conservation
+
+Learn: Lead scoring model accuracy
+    Goal: Achieve lead-to-opportunity conversion prediction AUC above 0.82
+    Adapt: Scoring model feature weights and thresholds
+    Based: Historical conversion outcomes, engagement pattern analysis, and demographic correlation
+
+Learn: Optimal campaign send timing
+    Goal: Increase email open rates by 25 percent through timing optimization
+    Adapt: Per-contact send time scheduling
+    Based: Historical engagement timestamps, timezone patterns, and channel preference signals
+
+Learn: Forecast prediction precision
+    Goal: Reduce forecast deviation from actual results to under 10 percent
+    Adapt: Stage probability weightings and historical adjustment factors
+    Based: Win/loss patterns, close date accuracy trends, and pipeline velocity metrics
+
+Learn: Customer churn prediction
+    Goal: Identify at-risk accounts 60 days before renewal with 75 percent recall
+    Adapt: Customer health score calculation
+    Based: Usage frequency decline, support ticket escalation, engagement drop-off, and competitive signals
+
+Security:
+    Encrypt: All customer personally identifiable information including email, phone, and address
+    Encrypt: Sales opportunity amounts and deal terms at rest and in transit
+    Encrypt: Integration API tokens and authentication credentials
+    Protect: Campaign execution endpoints with multi-level approval gates
+    Protect: Contact merge operations with audit logging and undo capability
+    Protect: Forecast modification with change tracking and manager visibility
+    Protect: Integration connector configurations from unauthorized modification
+
+Native: python
+{
+from datetime import datetime, timedelta
+from typing import Dict, List, Optional
+
+class LeadScoringEngine:
+    """ML-driven lead scoring with behavioral and demographic signal fusion."""
+
+    def __init__(self, model_config: Dict):
+        self.weights = model_config.get("weights", {})
+        self.thresholds = model_config.get("thresholds", {})
+        self.decay_factor = model_config.get("decay_factor", 0.95)
+
+    def compute_score(self, contact: Dict, activities: List[Dict]) -> float:
+        demographic_score = self._demographic_score(contact)
+        behavioral_score = self._behavioral_score(activities)
+        engagement_recency = self._recency_multiplier(activities)
+
+        composite = (
+            demographic_score * self.weights.get("demographic", 0.3) +
+            behavioral_score * self.weights.get("behavioral", 0.5) +
+            engagement_recency * self.weights.get("recency", 0.2)
+        )
+        return round(min(max(composite, 0), 100), 2)
+
+    def _demographic_score(self, contact: Dict) -> float:
+        score = 50.0
+        if contact.get("job_title") in ["VP", "Director", "C-Suite"]:
+            score += 20
+        if contact.get("company_size", 0) > 500:
+            score += 15
+        if contact.get("industry") in self.weights.get("target_industries", []):
+            score += 15
+        return min(score, 100)
+
+    def _behavioral_score(self, activities: List[Dict]) -> float:
+        if not activities:
+            return 0.0
+        score = 0.0
+        for act in activities[-20:]:
+            weight = self.weights.get(f"activity_{act['type']}", 1.0)
+            score += weight * 10
+        return min(score, 100)
+
+    def _recency_multiplier(self, activities: List[Dict]) -> float:
+        if not activities:
+            return 0.0
+        latest = max(a["timestamp"] for a in activities)
+        days_since = (datetime.utcnow() - latest).days
+        return max(0, 100 * (self.decay_factor ** days_since))
+
+
+class CircuitBreaker:
+    """Protects CRM integrations from cascading failures."""
+
+    def __init__(self, failure_threshold: int = 5, recovery_timeout: int = 300):
+        self.failure_threshold = failure_threshold
+        self.recovery_timeout = recovery_timeout
+        self.failure_count = 0
+        self.state = "CLOSED"
+        self.last_failure_time = None
+
+    def execute(self, operation, *args, **kwargs):
+        if self.state == "OPEN":
+            if (datetime.utcnow() - self.last_failure_time).seconds > self.recovery_timeout:
+                self.state = "HALF_OPEN"
+            else:
+                raise CircuitBreakerOpenError("Circuit breaker is open")
+
+        try:
+            result = operation(*args, **kwargs)
+            self._on_success()
+            return result
+        except Exception as e:
+            self._on_failure()
+            raise
+
+    def _on_success(self):
+        self.failure_count = 0
+        self.state = "CLOSED"
+
+    def _on_failure(self):
+        self.failure_count += 1
+        self.last_failure_time = datetime.utcnow()
+        if self.failure_count >= self.failure_threshold:
+            self.state = "OPEN"
+}