cortexdb-connectors 0.2.0__tar.gz

cortexdb_connectors-0.2.0/PKG-INFO

@@ -0,0 +1,207 @@
+Metadata-Version: 2.4
+Name: cortexdb-connectors
+Version: 0.2.0
+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
+Project-URL: Homepage, https://cortexdb.ai
+Project-URL: Documentation, https://cortexdb.ai/docs/connectors/slack
+Project-URL: Repository, https://github.com/cortexdb/cortexdb
+Project-URL: Issues, https://github.com/cortexdb/cortexdb/issues
+Keywords: ai,memory,connectors,etl,slack,github,jira,cortexdb
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Requires-Dist: croniter>=2.0
+Provides-Extra: slack
+Requires-Dist: slack-sdk>=3.0; extra == "slack"
+Provides-Extra: github
+Requires-Dist: pygithub>=2.0; extra == "github"
+Provides-Extra: pagerduty
+Requires-Dist: pdpyras>=5.0; extra == "pagerduty"
+Provides-Extra: jira
+Requires-Dist: jira>=3.0; extra == "jira"
+Provides-Extra: confluence
+Requires-Dist: atlassian-python-api>=3.0; extra == "confluence"
+Provides-Extra: notion
+Requires-Dist: notion-client>=2.0; extra == "notion"
+Provides-Extra: linear
+Provides-Extra: discord
+Requires-Dist: aiohttp>=3.9; extra == "discord"
+Provides-Extra: teams
+Requires-Dist: msal>=1.28; extra == "teams"
+Provides-Extra: google-workspace
+Requires-Dist: google-api-python-client>=2.0; extra == "google-workspace"
+Requires-Dist: google-auth>=2.0; extra == "google-workspace"
+Provides-Extra: salesforce
+Requires-Dist: simple-salesforce>=1.12; extra == "salesforce"
+Provides-Extra: hubspot
+Requires-Dist: hubspot-api-client>=9.0; extra == "hubspot"
+Provides-Extra: zendesk
+Provides-Extra: intercom
+Provides-Extra: servicenow
+Provides-Extra: gitlab
+Requires-Dist: python-gitlab>=4.0; extra == "gitlab"
+Provides-Extra: webhooks
+Requires-Dist: starlette>=0.37; extra == "webhooks"
+Requires-Dist: uvicorn>=0.29; extra == "webhooks"
+Requires-Dist: python-multipart>=0.0.9; extra == "webhooks"
+Provides-Extra: all
+Requires-Dist: slack-sdk>=3.0; extra == "all"
+Requires-Dist: pygithub>=2.0; extra == "all"
+Requires-Dist: pdpyras>=5.0; extra == "all"
+Requires-Dist: jira>=3.0; extra == "all"
+Requires-Dist: atlassian-python-api>=3.0; extra == "all"
+Requires-Dist: notion-client>=2.0; extra == "all"
+Requires-Dist: aiohttp>=3.9; extra == "all"
+Requires-Dist: msal>=1.28; extra == "all"
+Requires-Dist: google-api-python-client>=2.0; extra == "all"
+Requires-Dist: google-auth>=2.0; extra == "all"
+Requires-Dist: simple-salesforce>=1.12; extra == "all"
+Requires-Dist: hubspot-api-client>=9.0; extra == "all"
+Requires-Dist: python-gitlab>=4.0; extra == "all"
+Requires-Dist: PyYAML>=6.0; extra == "all"
+Requires-Dist: starlette>=0.37; extra == "all"
+Requires-Dist: uvicorn>=0.29; extra == "all"
+Requires-Dist: python-multipart>=0.0.9; extra == "all"
+
+# cortexdb-connectors
+
+Managed data connectors for [CortexDB](https://cortexdb.ai). Run them yourself, or let CortexDB host them for you on the [Starter tier](https://cortexdb.ai/pricing).
+
+Each connector pulls from a third-party system (Slack, GitHub, Jira, …) and writes every event into CortexDB as a v1 experience.
+
+## Install
+
+```bash
+# core only — no third-party SDK dependencies
+pip install cortexdb-connectors
+
+# with one source's SDK
+pip install 'cortexdb-connectors[slack]'
+
+# everything
+pip install 'cortexdb-connectors[all]'
+```
+
+Requires Python 3.10+.
+
+## Auth
+
+The connectors talk to the CortexDB v1 API. Two things you need:
+
+- **A PASETO bearer token** (`Authorization: Bearer …`)
+- **An actor id** that matches the token's `sub` claim (`X-Cortex-Actor: …`)
+
+The fastest way to get both is to install [`cortexdb-cli`](https://pypi.org/project/cortexdb-cli/) and run `cortexdb init` — anonymous signup, no email or card, 7-day free-tier token. The connectors read `~/.cortexdb/state.json` automatically.
+
+Or set env vars:
+
+```bash
+export CORTEXDB_URL=https://api-v1.cortexdb.ai
+export CORTEXDB_API_KEY=v4.public...
+export CORTEXDB_ACTOR=user:u_019e...
+export CORTEXDB_SCOPE_TEMPLATE='org:acme/source:{source}'   # optional
+```
+
+`{source}` (and `{tenant}`, `{namespace}`, `{actor}`, `{entity.<type>}`) get filled in per event.
+
+## Run
+
+```bash
+# one shot
+cortexdb-sync sync slack
+
+# poll loop, 60s between cycles
+cortexdb-sync watch slack --interval 60
+
+# resume from a specific point
+cortexdb-sync sync github --since 2026-05-01T00:00:00Z
+
+# see what's available
+cortexdb-sync list
+
+# check resolved CortexDB creds
+cortexdb-sync auth
+
+# cursor state across every connector
+cortexdb-sync status
+```
+
+## Available connectors
+
+```
+slack            SLACK_BOT_TOKEN
+github           GITHUB_TOKEN
+gitlab           GITLAB_TOKEN
+jira             JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN
+linear           LINEAR_API_KEY
+confluence       CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN
+notion           NOTION_TOKEN
+pagerduty        PAGERDUTY_API_KEY
+discord          DISCORD_BOT_TOKEN
+teams            TEAMS_TENANT_ID, TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET
+google-workspace GW_SERVICE_ACCOUNT_KEY, GW_DELEGATED_USER
+salesforce       SF_INSTANCE_URL, SF_CLIENT_ID, SF_CLIENT_SECRET, SF_USERNAME, SF_PASSWORD
+hubspot          HUBSPOT_TOKEN
+zendesk          ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN
+intercom         INTERCOM_TOKEN
+servicenow       SNOW_INSTANCE, SNOW_USERNAME, SNOW_PASSWORD
+```
+
+Per-connector setup pages live at https://cortexdb.ai/docs/connectors/ (e.g. [Slack](https://cortexdb.ai/docs/connectors/slack)).
+
+## YAML config
+
+If env vars get unwieldy, drop a `cortexdb-connectors.yaml` next to your sync invocation:
+
+```yaml
+slack:
+  slack_bot_token: xoxb-...
+  channels: [C01ABCDEF, C02GHIJKL]
+
+github:
+  github_token: ghp_...
+  repos: [acme/api, acme/web]
+  events: [pull_request, issue_comment]
+```
+
+## Programmatic use
+
+Skip the CLI entirely:
+
+```python
+import asyncio
+from cortexdb_connectors.slack import SlackConnector
+
+connector = SlackConnector(
+    cortex_url="https://api-v1.cortexdb.ai",
+    cortex_api_key="v4.public...",
+    actor="user:u_019e...",
+    scope_template="org:acme/source:slack/channel:{entity.channel}",
+    slack_bot_token="xoxb-...",
+    channels=["C01ABC", "C02DEF"],
+)
+
+result = asyncio.run(connector.sync())
+print(result.episodes_ingested, "ingested,", len(result.errors), "errors")
+```
+
+## Webhooks
+
+The `cortexdb-connectors[webhooks]` extra ships a Starlette-based webhook receiver for sources that push (Slack Events API, GitHub Apps, Jira webhooks, …) instead of polling. See `cortexdb_connectors/webhooks.py`.
+
+## License
+
+Apache-2.0

cortexdb_connectors-0.2.0/README.md

@@ -0,0 +1,129 @@
+# cortexdb-connectors
+
+Managed data connectors for [CortexDB](https://cortexdb.ai). Run them yourself, or let CortexDB host them for you on the [Starter tier](https://cortexdb.ai/pricing).
+
+Each connector pulls from a third-party system (Slack, GitHub, Jira, …) and writes every event into CortexDB as a v1 experience.
+
+## Install
+
+```bash
+# core only — no third-party SDK dependencies
+pip install cortexdb-connectors
+
+# with one source's SDK
+pip install 'cortexdb-connectors[slack]'
+
+# everything
+pip install 'cortexdb-connectors[all]'
+```
+
+Requires Python 3.10+.
+
+## Auth
+
+The connectors talk to the CortexDB v1 API. Two things you need:
+
+- **A PASETO bearer token** (`Authorization: Bearer …`)
+- **An actor id** that matches the token's `sub` claim (`X-Cortex-Actor: …`)
+
+The fastest way to get both is to install [`cortexdb-cli`](https://pypi.org/project/cortexdb-cli/) and run `cortexdb init` — anonymous signup, no email or card, 7-day free-tier token. The connectors read `~/.cortexdb/state.json` automatically.
+
+Or set env vars:
+
+```bash
+export CORTEXDB_URL=https://api-v1.cortexdb.ai
+export CORTEXDB_API_KEY=v4.public...
+export CORTEXDB_ACTOR=user:u_019e...
+export CORTEXDB_SCOPE_TEMPLATE='org:acme/source:{source}'   # optional
+```
+
+`{source}` (and `{tenant}`, `{namespace}`, `{actor}`, `{entity.<type>}`) get filled in per event.
+
+## Run
+
+```bash
+# one shot
+cortexdb-sync sync slack
+
+# poll loop, 60s between cycles
+cortexdb-sync watch slack --interval 60
+
+# resume from a specific point
+cortexdb-sync sync github --since 2026-05-01T00:00:00Z
+
+# see what's available
+cortexdb-sync list
+
+# check resolved CortexDB creds
+cortexdb-sync auth
+
+# cursor state across every connector
+cortexdb-sync status
+```
+
+## Available connectors
+
+```
+slack            SLACK_BOT_TOKEN
+github           GITHUB_TOKEN
+gitlab           GITLAB_TOKEN
+jira             JIRA_URL, JIRA_EMAIL, JIRA_API_TOKEN
+linear           LINEAR_API_KEY
+confluence       CONFLUENCE_URL, CONFLUENCE_EMAIL, CONFLUENCE_API_TOKEN
+notion           NOTION_TOKEN
+pagerduty        PAGERDUTY_API_KEY
+discord          DISCORD_BOT_TOKEN
+teams            TEAMS_TENANT_ID, TEAMS_CLIENT_ID, TEAMS_CLIENT_SECRET
+google-workspace GW_SERVICE_ACCOUNT_KEY, GW_DELEGATED_USER
+salesforce       SF_INSTANCE_URL, SF_CLIENT_ID, SF_CLIENT_SECRET, SF_USERNAME, SF_PASSWORD
+hubspot          HUBSPOT_TOKEN
+zendesk          ZENDESK_SUBDOMAIN, ZENDESK_EMAIL, ZENDESK_TOKEN
+intercom         INTERCOM_TOKEN
+servicenow       SNOW_INSTANCE, SNOW_USERNAME, SNOW_PASSWORD
+```
+
+Per-connector setup pages live at https://cortexdb.ai/docs/connectors/ (e.g. [Slack](https://cortexdb.ai/docs/connectors/slack)).
+
+## YAML config
+
+If env vars get unwieldy, drop a `cortexdb-connectors.yaml` next to your sync invocation:
+
+```yaml
+slack:
+  slack_bot_token: xoxb-...
+  channels: [C01ABCDEF, C02GHIJKL]
+
+github:
+  github_token: ghp_...
+  repos: [acme/api, acme/web]
+  events: [pull_request, issue_comment]
+```
+
+## Programmatic use
+
+Skip the CLI entirely:
+
+```python
+import asyncio
+from cortexdb_connectors.slack import SlackConnector
+
+connector = SlackConnector(
+    cortex_url="https://api-v1.cortexdb.ai",
+    cortex_api_key="v4.public...",
+    actor="user:u_019e...",
+    scope_template="org:acme/source:slack/channel:{entity.channel}",
+    slack_bot_token="xoxb-...",
+    channels=["C01ABC", "C02DEF"],
+)
+
+result = asyncio.run(connector.sync())
+print(result.episodes_ingested, "ingested,", len(result.errors), "errors")
+```
+
+## Webhooks
+
+The `cortexdb-connectors[webhooks]` extra ships a Starlette-based webhook receiver for sources that push (Slack Events API, GitHub Apps, Jira webhooks, …) instead of polling. See `cortexdb_connectors/webhooks.py`.
+
+## License
+
+Apache-2.0

cortexdb_connectors-0.2.0/cortexdb_connectors/__init__.py

@@ -0,0 +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.0"
+
+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",
+]