workflow.py

"""
Workflow Engine for Context Graph

Demonstrates human-in-the-loop automation where:
1. Agents propose actions
2. Context is gathered from multiple systems
3. Approvals are routed and recorded
4. Decision traces become searchable precedent
"""

from dataclasses import dataclass, field
from datetime import datetime
from typing import Any, Callable, Optional
from enum import Enum

from models import Entity, EntityType, DecisionTrace, DecisionType, Context
from graph import ContextGraph
from search import PrecedentSearch


class WorkflowStatus(Enum):
    PENDING = "pending"
    AWAITING_APPROVAL = "awaiting_approval"
    APPROVED = "approved"
    REJECTED = "rejected"
    AUTO_APPROVED = "auto_approved"


@dataclass
class WorkflowRequest:
    """A request that needs a decision."""
    id: str
    request_type: str
    description: str
    requestor_id: str
    requestor_name: str
    entity_ids: list[str] = field(default_factory=list)
    data: dict[str, Any] = field(default_factory=dict)
    tags: list[str] = field(default_factory=list)
    created_at: datetime = field(default_factory=datetime.now)
    status: WorkflowStatus = WorkflowStatus.PENDING


class ContextGatherer:
    """
    Simulates gathering context from multiple systems.

    In a real implementation, this would connect to:
    - CRM (Salesforce, HubSpot)
    - Support (Zendesk, Intercom)
    - Finance (Stripe, billing systems)
    - Internal tools
    """

    def __init__(self):
        # Simulated system data
        self._crm_data = {
            "CUST-001": {"tier": "enterprise", "arr": 150000, "health_score": 85},
            "CUST-002": {"tier": "startup", "arr": 12000, "health_score": 92},
            "CUST-003": {"tier": "enterprise", "arr": 500000, "health_score": 45},
        }
        self._support_data = {
            "CUST-001": {"open_tickets": 2, "avg_resolution_time": "4h", "csat": 4.5},
            "CUST-002": {"open_tickets": 0, "avg_resolution_time": "2h", "csat": 4.8},
            "CUST-003": {"open_tickets": 8, "avg_resolution_time": "24h", "csat": 2.1},
        }
        self._finance_data = {
            "CUST-001": {"payment_status": "current", "lifetime_value": 450000},
            "CUST-002": {"payment_status": "current", "lifetime_value": 36000},
            "CUST-003": {"payment_status": "30_days_overdue", "lifetime_value": 1500000},
        }

    def gather(self, entity_ids: list[str]) -> list[Context]:
        """Gather context from all systems for given entities."""
        contexts = []

        for entity_id in entity_ids:
            # CRM context
            if entity_id in self._crm_data:
                contexts.append(Context(
                    source_system="crm",
                    data={"entity_id": entity_id, **self._crm_data[entity_id]}
                ))

            # Support context
            if entity_id in self._support_data:
                contexts.append(Context(
                    source_system="support",
                    data={"entity_id": entity_id, **self._support_data[entity_id]}
                ))

            # Finance context
            if entity_id in self._finance_data:
                contexts.append(Context(
                    source_system="finance",
                    data={"entity_id": entity_id, **self._finance_data[entity_id]}
                ))

        return contexts


class WorkflowEngine:
    """
    Orchestrates decision-making workflows with context graph integration.

    Key behaviors:
    - Gathers cross-system context at decision time
    - Searches for precedent before routing decisions
    - Can auto-approve based on sufficient precedent
    - Records all decisions as traces for future reference
    """

    def __init__(self, graph: ContextGraph):
        self.graph = graph
        self.search = PrecedentSearch(graph)
        self.gatherer = ContextGatherer()
        self._requests: dict[str, WorkflowRequest] = {}
        self._auto_approve_threshold = 0.8  # Confidence threshold for auto-approval

    def submit_request(self, request: WorkflowRequest) -> dict:
        """
        Submit a new request for decision.

        This triggers:
        1. Context gathering from multiple systems
        2. Precedent search
        3. Potentially auto-approval if precedent is strong enough
        """
        self._requests[request.id] = request

        # Step 1: Gather context
        contexts = self.gatherer.gather(request.entity_ids)

        # Step 2: Search for precedent
        suggestion = self.search.suggest_decision(
            description=request.description,
            entity_ids=request.entity_ids,
            tags=request.tags
        )

        result = {
            "request_id": request.id,
            "contexts": contexts,
            "precedent_found": suggestion is not None,
            "suggestion": suggestion,
            "auto_approved": False
        }

        # Step 3: Check for auto-approval
        if suggestion and suggestion["confidence"] >= self._auto_approve_threshold:
            # Strong precedent exists - auto-approve
            request.status = WorkflowStatus.AUTO_APPROVED

            decision = DecisionTrace(
                type=DecisionType.AUTOMATION,
                description=request.description,
                outcome=suggestion["suggested_outcome"],
                actor_id="system",
                actor_name="Auto-Approval System",
                entity_ids=request.entity_ids,
                contexts=contexts,
                tags=request.tags + ["auto-approved"],
                attributes={
                    "confidence": suggestion["confidence"],
                    "precedent_count": suggestion["based_on"]
                }
            )
            self.graph.record_decision(decision)
            result["auto_approved"] = True
            result["decision_id"] = decision.id

        else:
            # Route for human approval
            request.status = WorkflowStatus.AWAITING_APPROVAL
            result["requires_approval"] = True

        return result

    def approve(
        self,
        request_id: str,
        approver_id: str,
        approver_name: str,
        outcome: str,
        reason: str = "",
        channel: str = "system"
    ) -> DecisionTrace:
        """
        Approve a pending request and record the decision trace.
        """
        request = self._requests.get(request_id)
        if not request:
            raise ValueError(f"Request {request_id} not found")

        if request.status != WorkflowStatus.AWAITING_APPROVAL:
            raise ValueError(f"Request {request_id} is not awaiting approval")

        # Gather fresh context at approval time
        contexts = self.gatherer.gather(request.entity_ids)

        # Create the decision trace
        decision = DecisionTrace(
            type=DecisionType.APPROVAL,
            description=request.description,
            outcome=outcome,
            actor_id=approver_id,
            actor_name=approver_name,
            entity_ids=request.entity_ids,
            contexts=contexts,
            tags=request.tags
        )

        # Record the approval
        decision.add_approval(
            approver_id=approver_id,
            approver_name=approver_name,
            reason=reason,
            channel=channel
        )

        # Store the decision
        self.graph.record_decision(decision)
        request.status = WorkflowStatus.APPROVED

        # Rebuild search index
        return decision

    def reject(
        self,
        request_id: str,
        rejector_id: str,
        rejector_name: str,
        reason: str = ""
    ) -> DecisionTrace:
        """Reject a pending request."""
        request = self._requests.get(request_id)
        if not request:
            raise ValueError(f"Request {request_id} not found")

        contexts = self.gatherer.gather(request.entity_ids)

        decision = DecisionTrace(
            type=DecisionType.APPROVAL,
            description=request.description,
            outcome="rejected",
            actor_id=rejector_id,
            actor_name=rejector_name,
            entity_ids=request.entity_ids,
            contexts=contexts,
            tags=request.tags + ["rejected"],
            attributes={"rejection_reason": reason}
        )

        self.graph.record_decision(decision)
        request.status = WorkflowStatus.REJECTED

        return decision

    def record_exception(
        self,
        description: str,
        entity_ids: list[str],
        outcome: str,
        actor_id: str,
        actor_name: str,
        reason: str,
        tags: Optional[list[str]] = None
    ) -> DecisionTrace:
        """
        Record an exception decision.

        Exceptions are deviations from standard policy that should
        be captured as precedent for future reference.
        """
        contexts = self.gatherer.gather(entity_ids)

        decision = DecisionTrace(
            type=DecisionType.EXCEPTION,
            description=description,
            outcome=outcome,
            actor_id=actor_id,
            actor_name=actor_name,
            entity_ids=entity_ids,
            contexts=contexts,
            tags=(tags or []) + ["exception"],
            attributes={"exception_reason": reason}
        )

        decision.add_approval(
            approver_id=actor_id,
            approver_name=actor_name,
            reason=reason,
            channel="exception_process"
        )

        self.graph.record_decision(decision)

        return decision