cortexdb-connectors 0.2.6__tar.gz → 0.2.8__tar.gz

{cortexdb_connectors-0.2.6 → cortexdb_connectors-0.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cortexdb-connectors
-Version: 0.2.6
+Version: 0.2.8
 Summary: Data connectors for CortexDB — ingest from Slack, GitHub, GitLab, Jira, Linear, Confluence, Notion, PagerDuty, Discord, Teams, Google Workspace, Salesforce, HubSpot, Zendesk, Intercom, and ServiceNow into the v1 memory API.
 Author-email: CortexDB Team <team@cortexdb.ai>
 License-Expression: Apache-2.0

{cortexdb_connectors-0.2.6 → cortexdb_connectors-0.2.8}/cortexdb_connectors/__init__.py

@@ -1,40 +1,40 @@
-"""cortexdb_connectors — data connector SDK for the CortexDB v1 API.
-
-Each connector subclass implements `fetch_events`, `normalize`, and
-`map_permissions`; the base class POSTs every normalised Episode to
-`/v1/experience` with the required Authorization + X-Cortex-Actor
-headers. Use the `cortexdb-sync` CLI to run a connector once or in a
-poll loop; or `from cortexdb_connectors.slack import SlackConnector`
-to drive it programmatically.
-"""
-
-__version__ = "0.2.6"
-
-from cortexdb_connectors.base import (
-    Actor,
-    CortexConnector,
-    EntityRef,
-    Episode,
-    EpisodeType,
-    RawEvent,
-    Source,
-    SyncResult,
-    SyncState,
-    Visibility,
-    VisibilityLevel,
-)
-
-__all__ = [
-    "__version__",
-    "Actor",
-    "CortexConnector",
-    "EntityRef",
-    "Episode",
-    "EpisodeType",
-    "RawEvent",
-    "Source",
-    "SyncResult",
-    "SyncState",
-    "Visibility",
-    "VisibilityLevel",
-]
+"""cortexdb_connectors — data connector SDK for the CortexDB v1 API.
+
+Each connector subclass implements `fetch_events`, `normalize`, and
+`map_permissions`; the base class POSTs every normalised Episode to
+`/v1/experience` with the required Authorization + X-Cortex-Actor
+headers. Use the `cortexdb-sync` CLI to run a connector once or in a
+poll loop; or `from cortexdb_connectors.slack import SlackConnector`
+to drive it programmatically.
+"""
+
+__version__ = "0.2.8"
+
+from cortexdb_connectors.base import (
+    Actor,
+    CortexConnector,
+    EntityRef,
+    Episode,
+    EpisodeType,
+    RawEvent,
+    Source,
+    SyncResult,
+    SyncState,
+    Visibility,
+    VisibilityLevel,
+)
+
+__all__ = [
+    "__version__",
+    "Actor",
+    "CortexConnector",
+    "EntityRef",
+    "Episode",
+    "EpisodeType",
+    "RawEvent",
+    "Source",
+    "SyncResult",
+    "SyncState",
+    "Visibility",
+    "VisibilityLevel",
+]

{cortexdb_connectors-0.2.6 → cortexdb_connectors-0.2.8}/cortexdb_connectors/base.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 import hashlib
 import logging
 import os
+import re
 import uuid
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
@@ -24,6 +25,11 @@ DEFAULT_API_URL = "https://api-v1.cortexdb.ai"
 
 logger = logging.getLogger("cortexdb_connectors")
 
+# v1 ActorRef grammar (server: cortex-types identity.rs): `kind:local` where
+# kind ∈ _ACTOR_KINDS and local matches [A-Za-z0-9_.@-]+ (no colons!).
+_ACTOR_KINDS = frozenset({"user", "agent", "service", "system"})
+_ACTOR_LOCAL_ILLEGAL = re.compile(r"[^A-Za-z0-9_.@-]")
+
 # Hard ceiling on content size sent to the server. Real items never approach
 # this; it exists only to stop a pathological payload from exceeding the request
 # body limit. When it trips we truncate on a UTF-8 boundary and log LOUDLY — we
@@ -158,6 +164,13 @@ class Episode:
 class SyncResult:
     episodes_fetched: int = 0
     episodes_ingested: int = 0
+    # Items the connector's content policy deliberately dropped (`normalize`
+    # returned None: empty/attachment-only text, emoji-only, noise subtypes).
+    # Counted separately so operators can tell "filtered by design" from
+    # "failed"; skipped items ADVANCE the cursor like successes — a skip is
+    # a decision, not an error, and treating it as one would stall the sync
+    # at the first attachment-only message.
+    episodes_skipped: int = 0
     errors: list[str] = field(default_factory=list)
     duration_seconds: float = 0.0
     # Watermarks for cursor-safe syncing: the latest source timestamp we
@@ -237,7 +250,13 @@ class CortexConnector(ABC):
         ...
 
     @abstractmethod
-    def normalize(self, raw: RawEvent) -> Episode:
+    def normalize(self, raw: RawEvent) -> Episode | None:
+        """Convert a RawEvent into an Episode, or return None to SKIP it.
+
+        None means the item is dropped by content policy (nothing sent to
+        the server); the sync loop counts it in `episodes_skipped` and the
+        cursor advances past it.
+        """
         ...
 
     @abstractmethod
@@ -257,6 +276,13 @@ class CortexConnector(ABC):
         for raw in raw_events:
             try:
                 episode = self.normalize(raw)
+                if episode is None:
+                    # Content-policy skip: advance the cursor exactly like a
+                    # success so the next incremental run never re-fetches it.
+                    result.episodes_skipped += 1
+                    if result.latest_success is None or raw.timestamp > result.latest_success:
+                        result.latest_success = raw.timestamp
+                    continue
                 episode.visibility = self.map_permissions(raw)
                 await self.ingest_episode(episode)
                 result.episodes_ingested += 1
@@ -356,14 +382,17 @@ class CortexConnector(ABC):
             ),
         }
         if episode.actor and episode.actor.id:
-            # v1 ActorRef requires a `kind:id` form (the server rejects a bare
-            # id with 422: "actor id missing ':' delimiter"). Source actor ids
-            # (Slack "U123", Jira accountId, …) are bare, so default the kind to
-            # `user:` unless the connector already supplied a delimiter.
-            aid = episode.actor.id
-            if ":" not in aid:
-                aid = f"user:{aid}"
-            envelope["observed_actor"] = {"id": aid}
+            # Source actor ids are not guaranteed bare: Jira Cloud accountIds
+            # are `712020:<uuid>`, so a colon does NOT mean the connector
+            # already supplied a kind. Treat the prefix as a kind only when it
+            # is one the server accepts; otherwise the whole source id is the
+            # local part under `user:`, sanitized to the server's charset
+            # (which forbids ':' anywhere in the local part).
+            kind, sep, local = episode.actor.id.partition(":")
+            if not sep or kind not in _ACTOR_KINDS or not local:
+                kind, local = "user", episode.actor.id
+            local = _ACTOR_LOCAL_ILLEGAL.sub("_", local)
+            envelope["observed_actor"] = {"id": f"{kind}:{local}"}
 
         return envelope
 

{cortexdb_connectors-0.2.6 → cortexdb_connectors-0.2.8}/cortexdb_connectors/cli.py

@@ -414,9 +414,10 @@ def _cmd_sync(args: argparse.Namespace) -> None:
     state_store.update_last_synced(args.connector, args.scope, timestamp=new_cursor)
 
     logger.info(
-        "sync done   fetched=%d ingested=%d errors=%d duration=%.1fs",
+        "sync done   fetched=%d ingested=%d skipped=%d errors=%d duration=%.1fs",
         result.episodes_fetched,
         result.episodes_ingested,
+        result.episodes_skipped,
         len(result.errors),
         result.duration_seconds,
     )