Skip to main content

ADR-015: Python as Connector SDK Language

Status​

Accepted (de facto, formalised 2026-03-13)

Context​

The platform has two separately deployed codebases:

  • sv0-platform — API, ingestion pipeline, evaluator, UI. Owned by the core platform team.
  • sv0-connectors — Data source connectors that transform raw API data into NormalizedGraph payloads. Each connector is a standalone Python package.

During early design (see docs/architecture/00-overview.md Open Question #5, now removed), the question was: should connectors be written in TypeScript (matching the platform) or Python?

The choice was never formally recorded, but Python was adopted from the start — sv0-connectors/ uses pyproject.toml, uv for dependency management, and all existing connectors (entra-servicenow, azure-foundry, shared sv0_azure library) are Python.

Decision​

Python for all connectors in sv0-connectors.

Rationale​

1. API client library quality​

APIPython ClientTypeScript Client
Microsoft Graph (Entra ID)msgraph-sdk-python — Microsoft-official, typed@microsoft/msgraph-sdk-typescript — official but newer, less coverage
ServiceNow RESTpysnow + raw requests — well-established ecosystemNo official SDK; community only
Azure ARM / RBACazure-mgmt-* family — comprehensive, official@azure/arm-* — official, comparable
Azure AI Foundryazure-ai-projects — official Python SDKLimited TypeScript coverage at time of adoption

Python has materially better API client coverage for the enterprise systems SecurityV0 targets.

2. Separation of concerns​

Connectors are read-only data extractors. They have no dependency on platform internals — they only produce NormalizedGraph JSON payloads. Language isolation is a feature, not a problem: connector failures cannot crash the platform, and connectors can be deployed independently.

3. Data engineering ecosystem​

Python's pandas, requests, httpx, and similar libraries are the default for data pipeline work. Connector development is closer to data engineering than application development.

4. Existing implementation​

By the time this decision was explicitly surfaced, two complete connectors (entra-servicenow, azure-foundry) and a shared library (sv0_azure) were already in Python. Rewriting in TypeScript would have no functional benefit.

Consequences​

  • All new connectors in sv0-connectors must be Python.
  • The NormalizedGraph contract (src/ingestion/types.ts in sv0-platform) is the integration boundary. Connectors are only required to produce valid JSON matching that schema.
  • Connector developers need Python + uv toolchain, not TypeScript/Node.js.
  • Type safety at the boundary: connector output is validated against the NormalizedGraph JSON schema on ingest. Python-side type annotations use TypedDict or dataclasses — not enforced at compile time, but the platform's ingest validation is the safety net.

Rejected Alternative: TypeScript​

TypeScript connectors would share the platform's toolchain (Node.js, tsc, vitest) and allow code reuse for the NormalizedGraph types. However:

  • API client library gaps for ServiceNow and Foundry at time of adoption
  • No practical code reuse exists — connectors and platform share only a JSON schema, not executable code
  • Language consistency is not a goal when the components are independently deployed