Upload 4 files

integrations/__init__.py

@@ -0,0 +1,14 @@
+"""
+Enterprise integrations for the Hausa Voice AI Agent.
+
+This file is what makes `integrations` an explicit package. Without it,
+imports work locally (Python 3.3+ namespace packages) but break in containers
+where the working directory is not what you expect — which is exactly the
+HuggingFace Spaces failure mode.
+
+Submodules are NOT imported here on purpose: `sip` imports twilio and `crm`
+reads environment variables, so eagerly importing them would make a missing
+optional dependency crash the whole app at startup.
+"""
+
+__all__ = ["crm", "sip", "whatsapp"]

integrations/crm.py

@@ -0,0 +1,159 @@
+"""
+CRM / Ticketing Integration
+============================
+Supports Zendesk out of the box; stub adapters for Freshdesk, HubSpot,
+Salesforce, and a generic REST endpoint.
+
+Environment variables (set in HF Space secrets or .env):
+  CRM_PROVIDER          = zendesk | freshdesk | hubspot | generic
+  ZENDESK_SUBDOMAIN     = yourcompany
+  ZENDESK_EMAIL         = agent@yourcompany.com
+  ZENDESK_API_TOKEN     = xxxxx
+  CRM_GENERIC_URL       = https://your-crm.example.com/api/tickets
+  CRM_GENERIC_TOKEN     = bearer_token
+"""
+
+import os
+import uuid
+import logging
+from datetime import datetime
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class CRMClient:
+
+    def __init__(self):
+        self.provider = os.getenv("CRM_PROVIDER", "demo")
+        self._demo    = self.provider == "demo"
+
+    # ── Public API ────────────────────────────────────────────────────────────
+
+    def create_ticket(self, subject: str, description: str,
+                      requester_name: str = "Voice User",
+                      requester_phone: str = "",
+                      priority: str = "normal",
+                      tags: list[str] = None) -> dict:
+        """Create a support ticket and return {ticket_id, url, status}."""
+        tags = tags or ["hausa-voice-agent", "auto-created"]
+        payload = {
+            "subject":         subject,
+            "description":     description,
+            "requester_name":  requester_name,
+            "requester_phone": requester_phone,
+            "priority":        priority,
+            "tags":            tags,
+            "created_at":      datetime.utcnow().isoformat(),
+            "channel":         "voice",
+        }
+
+        if self._demo:
+            return self._demo_ticket(payload)
+        if self.provider == "zendesk":
+            return self._zendesk_create(payload)
+        return self._generic_create(payload)
+
+    def get_ticket(self, ticket_id: str) -> Optional[dict]:
+        if self._demo:
+            return {"ticket_id": ticket_id, "status": "open",
+                    "created_at": datetime.utcnow().isoformat()}
+        if self.provider == "zendesk":
+            return self._zendesk_get(ticket_id)
+        return None
+
+    def update_ticket(self, ticket_id: str, comment: str,
+                       status: str = "pending") -> dict:
+        if self._demo:
+            logger.info(f"[DEMO] Update ticket {ticket_id}: {comment}")
+            return {"ticket_id": ticket_id, "status": status}
+        if self.provider == "zendesk":
+            return self._zendesk_update(ticket_id, comment, status)
+        return {}
+
+    def assign_to_human(self, ticket_id: str,
+                         agent_group: str = "frontline") -> dict:
+        """Transfer ticket to human agent queue."""
+        comment = f"[Voice AI] Escalated to human agent. Group: {agent_group}"
+        return self.update_ticket(ticket_id, comment, status="open")
+
+    # ── Demo stub ─────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _demo_ticket(payload: dict) -> dict:
+        ticket_id = "TKT-" + str(uuid.uuid4())[:8].upper()
+        logger.info(f"[DEMO] CRM ticket created: {ticket_id} | {payload['subject']}")
+        return {
+            "ticket_id": ticket_id,
+            "url":       f"https://demo.zendesk.com/tickets/{ticket_id}",
+            "status":    "created",
+            "provider":  "demo",
+        }
+
+    # ── Zendesk ───────────────────────────────────────────────────────────────
+
+    def _zendesk_create(self, payload: dict) -> dict:
+        import requests
+        subdomain = os.environ["ZENDESK_SUBDOMAIN"]
+        email     = os.environ["ZENDESK_EMAIL"]
+        token     = os.environ["ZENDESK_API_TOKEN"]
+
+        url  = f"https://{subdomain}.zendesk.com/api/v2/tickets.json"
+        body = {
+            "ticket": {
+                "subject":     payload["subject"],
+                "comment":     {"body": payload["description"]},
+                "requester":   {"name": payload["requester_name"]},
+                "priority":    payload["priority"],
+                "tags":        payload["tags"],
+            }
+        }
+        r = requests.post(url, json=body,
+                          auth=(f"{email}/token", token), timeout=10)
+        r.raise_for_status()
+        data = r.json()["ticket"]
+        return {
+            "ticket_id": str(data["id"]),
+            "url":       data["url"],
+            "status":    "created",
+            "provider":  "zendesk",
+        }
+
+    def _zendesk_get(self, ticket_id: str) -> dict:
+        import requests
+        subdomain = os.environ["ZENDESK_SUBDOMAIN"]
+        email     = os.environ["ZENDESK_EMAIL"]
+        token     = os.environ["ZENDESK_API_TOKEN"]
+        url = f"https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json"
+        r = requests.get(url, auth=(f"{email}/token", token), timeout=10)
+        r.raise_for_status()
+        data = r.json()["ticket"]
+        return {"ticket_id": ticket_id, "status": data["status"],
+                "subject": data["subject"]}
+
+    def _zendesk_update(self, ticket_id: str, comment: str, status: str) -> dict:
+        import requests
+        subdomain = os.environ["ZENDESK_SUBDOMAIN"]
+        email     = os.environ["ZENDESK_EMAIL"]
+        token     = os.environ["ZENDESK_API_TOKEN"]
+        url  = f"https://{subdomain}.zendesk.com/api/v2/tickets/{ticket_id}.json"
+        body = {"ticket": {"status": status,
+                           "comment": {"body": comment, "public": False}}}
+        r = requests.put(url, json=body,
+                         auth=(f"{email}/token", token), timeout=10)
+        r.raise_for_status()
+        return {"ticket_id": ticket_id, "status": status}
+
+    # ── Generic REST ──────────────────────────────────────────────────────────
+
+    def _generic_create(self, payload: dict) -> dict:
+        import requests
+        url   = os.environ["CRM_GENERIC_URL"]
+        token = os.environ.get("CRM_GENERIC_TOKEN", "")
+        headers = {"Authorization": f"Bearer {token}",
+                   "Content-Type": "application/json"}
+        r = requests.post(url, json=payload, headers=headers, timeout=10)
+        r.raise_for_status()
+        data = r.json()
+        return {"ticket_id": str(data.get("id", "?")), "status": "created",
+                "provider": "generic"}

integrations/sip.py

@@ -0,0 +1,186 @@
+"""
+Phone / SIP Integration  (Twilio + Bandwidth stubs)
+=====================================================
+Handles inbound calls → streams audio → runs pipeline → streams TTS back.
+
+For a real deployment, use:
+  - Twilio Media Streams (WebSocket) + <Stream> TwiML verb
+  - Bandwidth BXML + WebSocket audio streaming
+  - Vonage Voice API + WebSocket
+
+Environment variables:
+  TWILIO_ACCOUNT_SID  = ACxxxx
+  TWILIO_AUTH_TOKEN   = xxxx
+  TWILIO_PHONE_NUMBER = +1234567890
+  SIP_PROVIDER        = twilio | bandwidth | demo
+"""
+
+import os
+import logging
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class TwilioAdapter:
+    """
+    Twilio Media Streams WebSocket adapter.
+    
+    Flow:
+      1.  Inbound call → Twilio webhook → /voice endpoint
+      2.  Return TwiML with <Connect><Stream> → Twilio opens WS
+      3.  WebSocket handler receives mulaw 8kHz chunks
+      4.  Chunks accumulated → ASR → NLU → TTS → send back over WS
+    """
+
+    def __init__(self):
+        self.sid   = os.getenv("TWILIO_ACCOUNT_SID",  "DEMO")
+        self.token = os.getenv("TWILIO_AUTH_TOKEN",   "DEMO")
+        self.phone = os.getenv("TWILIO_PHONE_NUMBER", "+0000000000")
+        self._demo = self.sid == "DEMO"
+
+    def incoming_call_twiml(self, websocket_url: str) -> str:
+        """
+        Returns TwiML that Twilio will execute when a call arrives.
+        websocket_url: wss://yourserver.com/ws/audio
+        """
+        return f"""<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Say language="ha-NG">Sannu, barka da zuwa PlotWeaver. Muna jira…</Say>
+  <Connect>
+    <Stream url="{websocket_url}">
+      <Parameter name="language" value="hausa"/>
+    </Stream>
+  </Connect>
+</Response>"""
+
+    def handle_ws_message(self, message: dict,
+                           on_audio_chunk: Callable[[bytes], None]) -> None:
+        """
+        Called for each WebSocket message from Twilio.
+        Twilio sends: start, media (base64 mulaw), stop events.
+        """
+        import base64
+        event = message.get("event")
+        if event == "media":
+            chunk = base64.b64decode(message["media"]["payload"])
+            on_audio_chunk(chunk)
+        elif event == "stop":
+            logger.info(f"Call ended: {message.get('stop', {}).get('callSid')}")
+
+    def send_audio_twiml(self, call_sid: str, audio_url: str) -> dict:
+        """
+        Interrupt the current call and play synthesised audio.
+        Production: POST to Twilio API to update call.
+        """
+        if self._demo:
+            logger.info(f"[DEMO] Would play {audio_url} on call {call_sid}")
+            return {"status": "demo"}
+        from twilio.rest import Client
+        client = Client(self.sid, self.token)
+        call = client.calls(call_sid).update(
+            twiml=f'<Response><Play>{audio_url}</Play></Response>'
+        )
+        return {"status": call.status}
+
+    def make_outbound_call(self, to: str, message_en: str,
+                            message_ha: str = "") -> dict:
+        """Outbound IVR call with TTS message."""
+        twiml = f"""<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <Say language="ha-NG">{message_ha or message_en}</Say>
+</Response>"""
+        if self._demo:
+            logger.info(f"[DEMO] Outbound to {to}: {message_en[:60]}…")
+            return {"status": "demo_queued", "to": to}
+        from twilio.rest import Client
+        client = Client(self.sid, self.token)
+        call = client.calls.create(
+            to=to, from_=self.phone, twiml=twiml
+        )
+        return {"sid": call.sid, "status": call.status}
+
+    @staticmethod
+    def mulaw_to_pcm(mulaw_bytes: bytes) -> bytes:
+        """
+        Convert 8kHz G.711 mu-law to 16-bit PCM at 16kHz for Whisper.
+
+        Implemented in numpy rather than the stdlib `audioop` module, which
+        was removed in Python 3.13. Keeping this dependency-free means the
+        telephony path works on any modern image.
+        """
+        import numpy as np
+
+        u = np.frombuffer(mulaw_bytes, dtype=np.uint8).astype(np.int32)
+        u = ~u & 0xFF                                  # mu-law is stored inverted
+        sign     = u & 0x80
+        exponent = (u >> 4) & 0x07
+        mantissa = u & 0x0F
+        # ITU-T G.711: t = ((mantissa << 3) + BIAS) << exponent, BIAS = 0x84
+        t = ((mantissa << 3) + 0x84) << exponent
+        pcm8k = np.where(sign != 0, 0x84 - t, t - 0x84).astype(np.int16)
+
+        # 8kHz → 16kHz (linear interpolation; the band-limited content of a
+        # phone call makes a higher-order filter unnecessary here)
+        if len(pcm8k) == 0:
+            return b""
+        x  = np.arange(len(pcm8k))
+        xi = np.arange(len(pcm8k) * 2) / 2.0      # exact 2x: 0, 0.5, 1, 1.5, …
+        pcm16k = np.interp(xi, x, pcm8k).astype(np.int16)
+        return pcm16k.tobytes()
+
+
+class BandwidthAdapter:
+    """Bandwidth BXML + WebSocket audio streaming (stub)."""
+
+    def __init__(self):
+        self.account_id   = os.getenv("BANDWIDTH_ACCOUNT_ID",   "DEMO")
+        self.api_token    = os.getenv("BANDWIDTH_API_TOKEN",     "DEMO")
+        self._demo        = self.account_id == "DEMO"
+
+    def incoming_call_bxml(self, websocket_url: str) -> str:
+        return f"""<?xml version="1.0" encoding="UTF-8"?>
+<Response>
+  <SpeakSentence locale="ha-NG">Sannu da zuwa PlotWeaver.</SpeakSentence>
+  <StartStream url="{websocket_url}" streamEventUrl="{websocket_url}/events"/>
+</Response>"""
+
+    def send_tts(self, call_id: str, text: str, locale: str = "ha-NG") -> dict:
+        if self._demo:
+            logger.info(f"[DEMO] Bandwidth TTS on call {call_id}: {text[:60]}…")
+            return {"status": "demo"}
+        # Production: PATCH /calls/{callId} with BXML
+        raise NotImplementedError
+
+
+class SIPRouter:
+    """
+    Routes a call to the correct adapter based on SIP_PROVIDER env var.
+    Also manages human-agent transfer via SIP REFER.
+    """
+
+    PROVIDERS = {"twilio": TwilioAdapter, "bandwidth": BandwidthAdapter}
+
+    def __init__(self):
+        provider = os.getenv("SIP_PROVIDER", "demo").lower()
+        if provider in self.PROVIDERS:
+            self.adapter = self.PROVIDERS[provider]()
+        else:
+            self.adapter = TwilioAdapter()   # demo mode
+        logger.info(f"SIP provider: {provider}")
+
+    def transfer_to_human(self, call_sid: str,
+                           agent_extension: str = "+0000000001") -> dict:
+        """
+        REFER / warm transfer to human agent queue.
+        In demo mode just logs.
+        """
+        logger.info(f"[SIP] Transferring {call_sid} → agent {agent_extension}")
+        if isinstance(self.adapter, TwilioAdapter) and not self.adapter._demo:
+            from twilio.rest import Client
+            client = Client(self.adapter.sid, self.adapter.token)
+            call = client.calls(call_sid).update(
+                url=f"http://twimlets.com/forward?PhoneNumber={agent_extension}"
+            )
+            return {"status": call.status, "agent": agent_extension}
+        return {"status": "demo_transfer", "agent": agent_extension}

integrations/whatsapp.py

@@ -0,0 +1,145 @@
+"""
+WhatsApp Business API Integration
+===================================
+Handles inbound webhook messages and outbound replies via the
+Meta WhatsApp Cloud API (v18+).
+
+In the POC demo, all send/receive calls are stubbed and logged.
+In production, set:
+  WHATSAPP_TOKEN        = Bearer token from Meta Business Portal
+  WHATSAPP_PHONE_ID     = Phone Number ID
+  WHATSAPP_VERIFY_TOKEN = Webhook verification token
+"""
+
+import os
+import json
+import logging
+import hashlib
+from datetime import datetime
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+WHATSAPP_API_URL = "https://graph.facebook.com/v18.0/{phone_id}/messages"
+
+
+class WhatsAppClient:
+
+    def __init__(self):
+        self.token    = os.getenv("WHATSAPP_TOKEN", "DEMO_TOKEN")
+        self.phone_id = os.getenv("WHATSAPP_PHONE_ID", "DEMO_PHONE_ID")
+        self.verify   = os.getenv("WHATSAPP_VERIFY_TOKEN", "plotweaver_verify")
+        self._demo    = self.token == "DEMO_TOKEN"
+
+    # ── Outbound ─────────────────────────────────────────────────────────────
+
+    def send_text(self, to: str, body: str) -> dict:
+        """Send a plain text message."""
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": to,
+            "type": "text",
+            "text": {"preview_url": False, "body": body},
+        }
+        return self._post(payload)
+
+    def send_audio(self, to: str, audio_url: str) -> dict:
+        """Send a voice note (ogg/opus recommended by Meta)."""
+        payload = {
+            "messaging_product": "whatsapp",
+            "recipient_type": "individual",
+            "to": to,
+            "type": "audio",
+            "audio": {"link": audio_url},
+        }
+        return self._post(payload)
+
+    def send_interactive_buttons(self, to: str, body: str,
+                                  buttons: list[dict]) -> dict:
+        """
+        Quick-reply buttons for disambiguation.
+        buttons = [{"id": "yes", "title": "Yes ✓"}, {"id": "no", "title": "No ✗"}]
+        """
+        payload = {
+            "messaging_product": "whatsapp",
+            "to": to,
+            "type": "interactive",
+            "interactive": {
+                "type": "button",
+                "body": {"text": body},
+                "action": {
+                    "buttons": [
+                        {"type": "reply", "reply": btn} for btn in buttons
+                    ]
+                },
+            },
+        }
+        return self._post(payload)
+
+    # ── Inbound webhook ──────────────────────────────────────────────────────
+
+    def verify_webhook(self, mode: str, token: str, challenge: str) -> Optional[str]:
+        """GET verification handshake from Meta."""
+        if mode == "subscribe" and token == self.verify:
+            logger.info("WhatsApp webhook verified.")
+            return challenge
+        return None
+
+    def parse_inbound(self, raw_body: dict) -> Optional[dict]:
+        """
+        Extract relevant fields from inbound webhook payload.
+        Returns normalized event dict or None if not a user message.
+        """
+        try:
+            entry   = raw_body["entry"][0]
+            changes = entry["changes"][0]["value"]
+            message = changes["messages"][0]
+            contact = changes["contacts"][0]
+
+            event = {
+                "from":      message["from"],
+                "name":      contact["profile"]["name"],
+                "timestamp": datetime.fromtimestamp(int(message["timestamp"])).isoformat(),
+                "msg_id":    message["id"],
+                "type":      message["type"],
+            }
+
+            if message["type"] == "text":
+                event["text"] = message["text"]["body"]
+            elif message["type"] == "audio":
+                event["audio_id"] = message["audio"]["id"]
+                event["mime"]     = message["audio"].get("mime_type", "audio/ogg")
+            elif message["type"] == "interactive":
+                event["button_id"] = message["interactive"]["button_reply"]["id"]
+
+            return event
+        except (KeyError, IndexError) as e:
+            logger.warning(f"Could not parse WhatsApp payload: {e}")
+            return None
+
+    def download_media(self, media_id: str) -> Optional[bytes]:
+        """Fetch audio bytes for voice messages."""
+        if self._demo:
+            logger.info(f"[DEMO] Would download media: {media_id}")
+            return b""    # Return empty bytes in demo mode
+        # Production: GET https://graph.facebook.com/v18.0/{media_id}
+        # then fetch the returned URL with Bearer auth
+        raise NotImplementedError("Set WHATSAPP_TOKEN in production.")
+
+    # ── Internals ─────────────────────────────────────────────────────────────
+
+    def _post(self, payload: dict) -> dict:
+        if self._demo:
+            logger.info(f"[DEMO] WhatsApp → {payload['to']}: "
+                        f"{json.dumps(payload)[:120]} …")
+            return {"status": "demo_ok",
+                    "message_id": "demo_" + hashlib.md5(
+                        json.dumps(payload).encode()).hexdigest()[:8]}
+        import requests
+        url = WHATSAPP_API_URL.format(phone_id=self.phone_id)
+        headers = {"Authorization": f"Bearer {self.token}",
+                   "Content-Type": "application/json"}
+        r = requests.post(url, headers=headers, json=payload, timeout=10)
+        r.raise_for_status()
+        return r.json()