cortexdb-connectors 0.2.0__py3-none-any.whl

cortexdb_connectors/hubspot/__init__.py

@@ -0,0 +1,489 @@
+"""
+HubSpot connector for CortexDB.
+
+Polls HubSpot CRM for Contacts, Companies, Deals, Tickets, Notes, Emails,
+Calls, and Tasks, converting them into CortexDB Episodes.  Uses the
+``hubspot-api-client`` library for API v3 access.
+"""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta, timezone
+from typing import Any
+
+from cortexdb_connectors.base import (
+    Actor,
+    CortexConnector,
+    EntityRef,
+    Episode,
+    EpisodeType,
+    RawEvent,
+    Source,
+    Visibility,
+    VisibilityLevel,
+)
+
+logger = logging.getLogger(__name__)
+
+_SOURCE = Source(system="hubspot")
+
+_DEFAULT_OBJECTS = frozenset(
+    ["contacts", "companies", "deals", "tickets", "notes", "emails", "calls", "tasks"]
+)
+
+_OBJECT_TYPE_MAP: dict[str, EpisodeType] = {
+    "contacts": EpisodeType.DOCUMENT,
+    "companies": EpisodeType.DOCUMENT,
+    "deals": EpisodeType.DOCUMENT,
+    "tickets": EpisodeType.ISSUE,
+    "notes": EpisodeType.MESSAGE,
+    "emails": EpisodeType.MESSAGE,
+    "calls": EpisodeType.MESSAGE,
+    "tasks": EpisodeType.ISSUE,
+}
+
+
+class HubSpotConnector(CortexConnector):
+    """Connector that syncs HubSpot CRM objects into CortexDB.
+
+    Parameters
+    ----------
+    cortex_url:
+        Base URL of the CortexDB API.
+    cortex_api_key:
+        Bearer token for CortexDB authentication.
+    access_token:
+        HubSpot private app access token.
+    objects:
+        HubSpot object types to ingest.  Defaults to contacts, companies,
+        deals, tickets, notes, emails, calls, tasks.
+    namespace:
+        CortexDB namespace for ingested episodes.
+    backfill_days:
+        Number of days of historical data to backfill on first sync.
+    tenant_id:
+        CortexDB tenant identifier.
+    """
+
+    connector_name: str = "hubspot"
+
+    def __init__(
+        self,
+        cortex_url: str,
+        cortex_api_key: str,
+        access_token: str,
+        objects: list[str] | None = None,
+        namespace: str = "hubspot",
+        backfill_days: int = 90,
+        tenant_id: str = "default",
+    ) -> None:
+        super().__init__(cortex_url, cortex_api_key, tenant_id)
+        self.access_token = access_token
+        self.object_filter = set(objects) if objects else set(_DEFAULT_OBJECTS)
+        self.namespace = namespace
+        self.backfill_days = backfill_days
+        self._client: Any = None
+
+    # -- HubSpot client management -------------------------------------------
+
+    def _get_client(self) -> Any:
+        """Lazy-initialise and return the HubSpot API client."""
+        if self._client is not None:
+            return self._client
+
+        from hubspot import HubSpot
+
+        self._client = HubSpot(access_token=self.access_token)
+        return self._client
+
+    # -- CortexConnector interface -------------------------------------------
+
+    async def fetch_events(
+        self, since: datetime | None = None
+    ) -> list[RawEvent]:
+        """Fetch records from configured HubSpot objects.
+
+        Uses the CRM search API with ``lastmodifieddate`` filter for
+        incremental sync and handles cursor-based pagination.
+        """
+        cutoff = since or datetime.now(timezone.utc) - timedelta(
+            days=self.backfill_days
+        )
+        cutoff_ms = int(cutoff.timestamp() * 1000)
+        raw_events: list[RawEvent] = []
+
+        crm_objects = {"contacts", "companies", "deals", "tickets"}
+        engagement_objects = {"notes", "emails", "calls", "tasks"}
+
+        for obj_type in self.object_filter:
+            try:
+                if obj_type in crm_objects:
+                    raw_events.extend(
+                        self._fetch_crm_object(obj_type, cutoff_ms)
+                    )
+                elif obj_type in engagement_objects:
+                    raw_events.extend(
+                        self._fetch_engagements(obj_type, cutoff_ms)
+                    )
+            except Exception:
+                logger.exception("Failed to fetch HubSpot %s", obj_type)
+                continue
+
+        return raw_events
+
+    def normalize(self, raw: RawEvent) -> Episode:
+        """Convert a HubSpot record ``RawEvent`` into a CortexDB ``Episode``."""
+        data = raw.data
+        obj_type = data.get("object_type", "unknown")
+        properties = data.get("properties", {})
+        episode_type = _OBJECT_TYPE_MAP.get(obj_type, EpisodeType.CUSTOM)
+
+        actor = self._extract_actor(properties)
+        content = self._build_content(obj_type, properties)
+        entities = self._extract_entities(obj_type, data)
+        tags = ["hubspot", obj_type]
+
+        metadata: dict[str, Any] = {
+            "hubspot_object": obj_type,
+            "hubspot_id": data.get("record_id", ""),
+        }
+        if properties.get("dealstage"):
+            metadata["deal_stage"] = properties["dealstage"]
+        if properties.get("pipeline"):
+            metadata["pipeline"] = properties["pipeline"]
+        if properties.get("hs_ticket_priority"):
+            metadata["priority"] = properties["hs_ticket_priority"]
+
+        thread_id = self._derive_thread_id(obj_type, data)
+
+        return Episode(
+            actor=actor,
+            source=_SOURCE,
+            episode_type=episode_type,
+            occurred_at=raw.timestamp,
+            content=content,
+            raw_payload=data,
+            tenant_id=self.tenant_id,
+            namespace=self.namespace,
+            entities=entities,
+            tags=tags,
+            metadata=metadata,
+            thread_id=thread_id,
+            idempotency_key=f"hs:{obj_type}:{data.get('record_id', raw.external_id)}",
+        )
+
+    def map_permissions(self, raw: RawEvent) -> Visibility:
+        """HubSpot CRM data is internal; always ``Organization`` visibility."""
+        return Visibility(level=VisibilityLevel.ORGANIZATION)
+
+    # -- fetchers ------------------------------------------------------------
+
+    def _fetch_crm_object(
+        self, obj_type: str, cutoff_ms: int
+    ) -> list[RawEvent]:
+        """Fetch a CRM object type via the search API with pagination."""
+        client = self._get_client()
+        api_map = {
+            "contacts": client.crm.contacts,
+            "companies": client.crm.companies,
+            "deals": client.crm.deals,
+            "tickets": client.crm.tickets,
+        }
+        api = api_map.get(obj_type)
+        if api is None:
+            return []
+
+        properties = self._properties_for(obj_type)
+        events: list[RawEvent] = []
+        after: str | None = None
+
+        while True:
+            filter_groups = [
+                {
+                    "filters": [
+                        {
+                            "propertyName": "lastmodifieddate",
+                            "operator": "GTE",
+                            "value": str(cutoff_ms),
+                        }
+                    ]
+                }
+            ]
+            search_request = {
+                "filter_groups": filter_groups,
+                "properties": properties,
+                "limit": 100,
+                "sorts": [
+                    {"propertyName": "lastmodifieddate", "direction": "DESCENDING"}
+                ],
+            }
+            if after:
+                search_request["after"] = after
+
+            try:
+                page = api.search_api.do_search(search_request=search_request)
+            except Exception:
+                logger.exception("HubSpot search failed for %s", obj_type)
+                break
+
+            for result in page.results:
+                props = result.properties or {}
+                ts = self._parse_hubspot_ts(
+                    props.get("lastmodifieddate")
+                    or props.get("hs_lastmodifieddate")
+                )
+                events.append(
+                    RawEvent(
+                        source="hubspot",
+                        external_id=str(result.id),
+                        timestamp=ts,
+                        data={
+                            "object_type": obj_type,
+                            "record_id": str(result.id),
+                            "properties": props,
+                        },
+                        permissions={},
+                    )
+                )
+
+            if page.paging and page.paging.next:
+                after = page.paging.next.after
+            else:
+                break
+
+        return events
+
+    def _fetch_engagements(
+        self, obj_type: str, cutoff_ms: int
+    ) -> list[RawEvent]:
+        """Fetch engagement objects (notes, emails, calls, tasks)."""
+        client = self._get_client()
+        api_map = {
+            "notes": client.crm.objects.notes,
+            "emails": client.crm.objects.emails,
+            "calls": client.crm.objects.calls,
+            "tasks": client.crm.objects.tasks,
+        }
+        api = api_map.get(obj_type)
+        if api is None:
+            return []
+
+        events: list[RawEvent] = []
+        after: str | None = None
+
+        while True:
+            try:
+                kwargs: dict[str, Any] = {"limit": 100}
+                if after:
+                    kwargs["after"] = after
+                page = api.basic_api.get_page(**kwargs)
+            except Exception:
+                logger.exception("HubSpot list failed for %s", obj_type)
+                break
+
+            for result in page.results:
+                props = result.properties or {}
+                ts = self._parse_hubspot_ts(
+                    props.get("hs_lastmodifieddate")
+                    or props.get("hs_timestamp")
+                )
+                if ts.timestamp() * 1000 < cutoff_ms:
+                    continue
+
+                events.append(
+                    RawEvent(
+                        source="hubspot",
+                        external_id=str(result.id),
+                        timestamp=ts,
+                        data={
+                            "object_type": obj_type,
+                            "record_id": str(result.id),
+                            "properties": props,
+                        },
+                        permissions={},
+                    )
+                )
+
+            if page.paging and page.paging.next:
+                after = page.paging.next.after
+            else:
+                break
+
+        return events
+
+    # -- helpers -------------------------------------------------------------
+
+    @staticmethod
+    def _properties_for(obj_type: str) -> list[str]:
+        """Return properties to request for a CRM object type."""
+        props_map: dict[str, list[str]] = {
+            "contacts": [
+                "firstname", "lastname", "email", "company",
+                "phone", "lifecyclestage", "lastmodifieddate",
+                "hubspot_owner_id",
+            ],
+            "companies": [
+                "name", "domain", "industry", "numberofemployees",
+                "annualrevenue", "lastmodifieddate", "hubspot_owner_id",
+            ],
+            "deals": [
+                "dealname", "dealstage", "amount", "pipeline",
+                "closedate", "hubspot_owner_id", "lastmodifieddate",
+            ],
+            "tickets": [
+                "subject", "content", "hs_pipeline", "hs_pipeline_stage",
+                "hs_ticket_priority", "hubspot_owner_id",
+                "lastmodifieddate",
+            ],
+        }
+        return props_map.get(obj_type, ["lastmodifieddate"])
+
+    @staticmethod
+    def _parse_hubspot_ts(value: str | None) -> datetime:
+        """Parse a HubSpot timestamp (epoch-ms string or ISO)."""
+        if not value:
+            return datetime.now(timezone.utc)
+        try:
+            return datetime.fromtimestamp(int(value) / 1000, tz=timezone.utc)
+        except (ValueError, TypeError, OSError):
+            pass
+        try:
+            return datetime.fromisoformat(value.replace("Z", "+00:00"))
+        except (ValueError, TypeError):
+            return datetime.now(timezone.utc)
+
+    @staticmethod
+    def _extract_actor(properties: dict[str, Any]) -> Actor:
+        """Extract actor from HubSpot record properties."""
+        owner_id = properties.get("hubspot_owner_id") or ""
+        email = properties.get("email") or ""
+        name = " ".join(
+            filter(
+                None,
+                [
+                    properties.get("firstname", ""),
+                    properties.get("lastname", ""),
+                ],
+            )
+        ) or owner_id
+        return Actor(id=owner_id or "unknown", name=name, email=email or None)
+
+    @staticmethod
+    def _build_content(obj_type: str, properties: dict[str, Any]) -> str:
+        """Build human-readable content from HubSpot record properties."""
+        if obj_type == "contacts":
+            name = " ".join(
+                filter(
+                    None,
+                    [properties.get("firstname"), properties.get("lastname")],
+                )
+            ) or "Unknown contact"
+            company = properties.get("company", "")
+            email = properties.get("email", "")
+            parts = [f"Contact: {name}"]
+            if company:
+                parts.append(f"Company: {company}")
+            if email:
+                parts.append(f"Email: {email}")
+            return " | ".join(parts)
+
+        if obj_type == "companies":
+            name = properties.get("name", "Unnamed company")
+            industry = properties.get("industry", "")
+            domain = properties.get("domain", "")
+            return f"Company: {name} | {industry} | {domain}".rstrip(" | ")
+
+        if obj_type == "deals":
+            name = properties.get("dealname", "Untitled deal")
+            stage = properties.get("dealstage", "")
+            amount = properties.get("amount")
+            amount_str = f" (${float(amount):,.2f})" if amount else ""
+            return f"Deal [{stage}]: {name}{amount_str}"
+
+        if obj_type == "tickets":
+            subject = properties.get("subject", "Untitled ticket")
+            content = (properties.get("content") or "")[:500]
+            priority = properties.get("hs_ticket_priority", "")
+            return f"Ticket [{priority}]: {subject}\n{content}".strip()
+
+        if obj_type == "notes":
+            body = (properties.get("hs_note_body") or "")[:500]
+            return f"Note: {body}" if body else "Note (empty)"
+
+        if obj_type == "emails":
+            subject = properties.get("hs_email_subject", "No subject")
+            text = (properties.get("hs_email_text") or "")[:500]
+            return f"Email: {subject}\n{text}".strip()
+
+        if obj_type == "calls":
+            title = properties.get("hs_call_title", "Call")
+            body = (properties.get("hs_call_body") or "")[:500]
+            duration = properties.get("hs_call_duration")
+            dur_str = f" ({duration}ms)" if duration else ""
+            return f"Call: {title}{dur_str}\n{body}".strip()
+
+        if obj_type == "tasks":
+            subject = properties.get("hs_task_subject", "Untitled task")
+            body = (properties.get("hs_task_body") or "")[:300]
+            status = properties.get("hs_task_status", "")
+            return f"Task [{status}]: {subject}\n{body}".strip()
+
+        return f"HubSpot {obj_type}"
+
+    @staticmethod
+    def _extract_entities(
+        obj_type: str, data: dict[str, Any]
+    ) -> list[EntityRef]:
+        """Extract entity references from a HubSpot record."""
+        entities: list[EntityRef] = []
+        record_id = data.get("record_id", "")
+        properties = data.get("properties", {})
+
+        if record_id:
+            display = (
+                properties.get("dealname")
+                or properties.get("name")
+                or properties.get("subject")
+                or properties.get("email")
+                or record_id
+            )
+            entities.append(
+                EntityRef(
+                    entity_type=obj_type.rstrip("s"),
+                    entity_id=record_id,
+                    display_name=str(display),
+                )
+            )
+
+        owner_id = properties.get("hubspot_owner_id")
+        if owner_id:
+            entities.append(
+                EntityRef(
+                    entity_type="user",
+                    entity_id=str(owner_id),
+                    display_name=str(owner_id),
+                )
+            )
+
+        pipeline = properties.get("pipeline") or properties.get("hs_pipeline")
+        if pipeline:
+            entities.append(
+                EntityRef(
+                    entity_type="pipeline",
+                    entity_id=str(pipeline),
+                    display_name=str(pipeline),
+                )
+            )
+
+        return entities
+
+    @staticmethod
+    def _derive_thread_id(
+        obj_type: str, data: dict[str, Any]
+    ) -> str | None:
+        """Derive a thread_id for grouping related records."""
+        record_id = data.get("record_id", "")
+        if not record_id:
+            return None
+        return f"hs:{obj_type}:{record_id}"

cortexdb_connectors/insights/__init__.py

@@ -0,0 +1,40 @@
+"""Proactive Insights Engine for CortexDB.
+
+Auto-generates intelligence from stored episodes and entities by running
+periodic analysis detectors.  Each detector scans the CortexDB data plane
+for a specific pattern (incident spikes, knowledge gaps, stale runbooks,
+etc.) and produces ``Insight`` objects that surface actionable information
+to operators and AI agents.
+
+Typical usage::
+
+    from cortexdb_connectors.insights import InsightsEngine
+
+    engine = InsightsEngine(cortex_url="http://localhost:8080", cortex_api_key="...")
+    await engine.run_once()           # single analysis pass
+    await engine.start()              # periodic background loop
+"""
+
+from cortexdb_connectors.insights.detectors import (
+    Insight,
+    InsightSeverity,
+    InsightType,
+    IncidentSpikeDetector,
+    KnowledgeGapDetector,
+    NewDependencyDetector,
+    OwnershipGapDetector,
+    StaleRunbookDetector,
+)
+from cortexdb_connectors.insights.engine import InsightsEngine
+
+__all__ = [
+    "Insight",
+    "InsightSeverity",
+    "InsightType",
+    "InsightsEngine",
+    "IncidentSpikeDetector",
+    "KnowledgeGapDetector",
+    "NewDependencyDetector",
+    "OwnershipGapDetector",
+    "StaleRunbookDetector",
+]