parmana-connector-sdk 0.1.0__tar.gz

parmana_connector_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: parmana-connector-sdk
+Version: 0.1.0
+Summary: Connector authoring contracts and reference implementations for Parmana, the authorization layer for AI execution.
+Author: Parmana
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/pavancharak/parmana
+Project-URL: Website, https://parmanasystems.com/
+Project-URL: Documentation, https://docs.parmanasystems.com
+Project-URL: Repository, https://github.com/pavancharak/parmana
+Project-URL: Issues, https://github.com/pavancharak/parmana/issues
+Keywords: ai,agentic-ai,governance,authorization,connector,integration,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+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 :: Software Development
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: ruff>=0.6.0; extra == "dev"
+Requires-Dist: black>=24.0.0; extra == "dev"
+Requires-Dist: mypy>=1.10.0; extra == "dev"
+
+# parmana-connector-sdk
+
+Contracts and reference implementations for building a Connector for [Parmana](https://github.com/pavancharak/parmana), the authorization layer for AI execution.
+
+A Connector is the last hop in Parmana's pipeline: it receives an already-authorized, already-verified request and carries it out against a real system (an API, a database, anything). A Connector never evaluates policy, never authorizes execution, and never resolves its own credentials — it only executes, using a credential Parmana has already resolved for it.
+
+This is the Python counterpart to the TypeScript [`@parmana/connector-sdk`](https://www.npmjs.com/package/@parmana/connector-sdk) package — same contract, same design, idiomatic Python (synchronous, dataclasses and `Protocol` instead of interfaces).
+
+## Install
+
+```bash
+pip install parmana-connector-sdk
+```
+
+## The contract
+
+Every Connector implements one protocol:
+
+```python
+from parmana_connector_sdk import (
+    Connector,
+    ConnectorRequest,
+    ConnectorExecutionContext,
+    ConnectorResponse,
+    connector_capabilities,
+)
+
+
+class MyConnector:
+    connector_id = "my-service"
+    capabilities = connector_capabilities(["my-service:do-thing"])
+
+    def execute(
+        self, request: ConnectorRequest, context: ConnectorExecutionContext
+    ) -> ConnectorResponse:
+        # request.parameters is exactly what was authorized -- never re-derive it.
+        # context.credential is an opaque, already-resolved CredentialHandle.
+        # context.timeout_ms is how long you have.
+        return ConnectorResponse(success=True, metadata={})
+```
+
+`Connector` is a `typing.Protocol` — `MyConnector` doesn't need to subclass anything, it just
+needs to match the shape (`connector_id`, `capabilities`, `execute`).
+
+`capabilities` must be namespaced verbs (`"namespace:verb"`, e.g. `"crm:update-contact"`),
+validated eagerly by `connector_capabilities()` so a malformed capability fails at
+construction, not mid-execution.
+
+## One reference implementation, for testing
+
+`MockConnector` gives you scripted responses or failure injection, and records every request
+it receives, so you can test your own Connector's callers without standing up a real endpoint:
+
+```python
+from parmana_connector_sdk import MockConnector, MockConnectorOptions, MockConnectorScript, connector_capabilities
+
+connector = MockConnector(
+    MockConnectorOptions(
+        connector_id="billing",
+        capabilities=connector_capabilities(["billing:issue-refund"]),
+        script=MockConnectorScript(
+            respond=lambda request, context: ConnectorResponse(
+                success=True, metadata={"refund_id": "r_1"}
+            )
+        ),
+    )
+)
+
+connector.execute(request, context)
+connector.invocations  # every request it received, for assertions
+```
+
+This package intentionally ships no HTTP-calling reference implementation — only the contract
+and the hermetic mock above. A REST-shaped connector is usually this simple to write directly
+against the contract:
+
+```python
+import urllib.request
+import json
+
+from parmana_connector_sdk import (
+    ConnectorRequest,
+    ConnectorExecutionContext,
+    ConnectorResponse,
+    connector_capabilities,
+)
+
+
+class BillingConnector:
+    connector_id = "billing"
+    capabilities = connector_capabilities(["billing:issue-refund"])
+
+    def __init__(self, base_url: str) -> None:
+        self.base_url = base_url
+
+    def execute(
+        self, request: ConnectorRequest, context: ConnectorExecutionContext
+    ) -> ConnectorResponse:
+        token = context.credential.value  # shape is whatever your CredentialProvider resolved
+        body = json.dumps(request.parameters).encode()
+        req = urllib.request.Request(
+            f"{self.base_url}/{request.action}",
+            data=body,
+            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=context.timeout_ms / 1000) as response:
+            if response.status >= 300:
+                raise RuntimeError(f"HTTP {response.status}")
+            return ConnectorResponse(success=True, metadata=json.load(response))
+```
+
+## Four worked examples
+
+`parmana_connector_sdk.connectors.{oracle,salesforce,sap,workday}` are deterministic
+`MockConnector`s shaped like a real enterprise integration — each declares one realistic
+capability and nothing else. They are explicit mocks, not real integrations; read them as a
+template for structuring your own connector's capability and metadata, not as something to
+call in production.
+
+## Credentials
+
+A Connector never resolves its own credentials. `CredentialProvider` is the seam Parmana's
+Execution Gateway uses upstream of a Connector — `EnvironmentCredentialProvider` (reads a
+mapped env var) and `StaticCredentialProvider` (in-memory, for tests) are the two provided
+implementations.
+
+## Full reference
+
+See the [Connector SDK reference](https://docs.parmanasystems.com/reference/connector-sdk) and
+the [Connector Development Guide](https://docs.parmanasystems.com/integrations/connector-development-guide)
+— written against the TypeScript package, but the contract this package implements is
+identical.

parmana_connector_sdk-0.1.0/README.md

@@ -0,0 +1,133 @@
+# parmana-connector-sdk
+
+Contracts and reference implementations for building a Connector for [Parmana](https://github.com/pavancharak/parmana), the authorization layer for AI execution.
+
+A Connector is the last hop in Parmana's pipeline: it receives an already-authorized, already-verified request and carries it out against a real system (an API, a database, anything). A Connector never evaluates policy, never authorizes execution, and never resolves its own credentials — it only executes, using a credential Parmana has already resolved for it.
+
+This is the Python counterpart to the TypeScript [`@parmana/connector-sdk`](https://www.npmjs.com/package/@parmana/connector-sdk) package — same contract, same design, idiomatic Python (synchronous, dataclasses and `Protocol` instead of interfaces).
+
+## Install
+
+```bash
+pip install parmana-connector-sdk
+```
+
+## The contract
+
+Every Connector implements one protocol:
+
+```python
+from parmana_connector_sdk import (
+    Connector,
+    ConnectorRequest,
+    ConnectorExecutionContext,
+    ConnectorResponse,
+    connector_capabilities,
+)
+
+
+class MyConnector:
+    connector_id = "my-service"
+    capabilities = connector_capabilities(["my-service:do-thing"])
+
+    def execute(
+        self, request: ConnectorRequest, context: ConnectorExecutionContext
+    ) -> ConnectorResponse:
+        # request.parameters is exactly what was authorized -- never re-derive it.
+        # context.credential is an opaque, already-resolved CredentialHandle.
+        # context.timeout_ms is how long you have.
+        return ConnectorResponse(success=True, metadata={})
+```
+
+`Connector` is a `typing.Protocol` — `MyConnector` doesn't need to subclass anything, it just
+needs to match the shape (`connector_id`, `capabilities`, `execute`).
+
+`capabilities` must be namespaced verbs (`"namespace:verb"`, e.g. `"crm:update-contact"`),
+validated eagerly by `connector_capabilities()` so a malformed capability fails at
+construction, not mid-execution.
+
+## One reference implementation, for testing
+
+`MockConnector` gives you scripted responses or failure injection, and records every request
+it receives, so you can test your own Connector's callers without standing up a real endpoint:
+
+```python
+from parmana_connector_sdk import MockConnector, MockConnectorOptions, MockConnectorScript, connector_capabilities
+
+connector = MockConnector(
+    MockConnectorOptions(
+        connector_id="billing",
+        capabilities=connector_capabilities(["billing:issue-refund"]),
+        script=MockConnectorScript(
+            respond=lambda request, context: ConnectorResponse(
+                success=True, metadata={"refund_id": "r_1"}
+            )
+        ),
+    )
+)
+
+connector.execute(request, context)
+connector.invocations  # every request it received, for assertions
+```
+
+This package intentionally ships no HTTP-calling reference implementation — only the contract
+and the hermetic mock above. A REST-shaped connector is usually this simple to write directly
+against the contract:
+
+```python
+import urllib.request
+import json
+
+from parmana_connector_sdk import (
+    ConnectorRequest,
+    ConnectorExecutionContext,
+    ConnectorResponse,
+    connector_capabilities,
+)
+
+
+class BillingConnector:
+    connector_id = "billing"
+    capabilities = connector_capabilities(["billing:issue-refund"])
+
+    def __init__(self, base_url: str) -> None:
+        self.base_url = base_url
+
+    def execute(
+        self, request: ConnectorRequest, context: ConnectorExecutionContext
+    ) -> ConnectorResponse:
+        token = context.credential.value  # shape is whatever your CredentialProvider resolved
+        body = json.dumps(request.parameters).encode()
+        req = urllib.request.Request(
+            f"{self.base_url}/{request.action}",
+            data=body,
+            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=context.timeout_ms / 1000) as response:
+            if response.status >= 300:
+                raise RuntimeError(f"HTTP {response.status}")
+            return ConnectorResponse(success=True, metadata=json.load(response))
+```
+
+## Four worked examples
+
+`parmana_connector_sdk.connectors.{oracle,salesforce,sap,workday}` are deterministic
+`MockConnector`s shaped like a real enterprise integration — each declares one realistic
+capability and nothing else. They are explicit mocks, not real integrations; read them as a
+template for structuring your own connector's capability and metadata, not as something to
+call in production.
+
+## Credentials
+
+A Connector never resolves its own credentials. `CredentialProvider` is the seam Parmana's
+Execution Gateway uses upstream of a Connector — `EnvironmentCredentialProvider` (reads a
+mapped env var) and `StaticCredentialProvider` (in-memory, for tests) are the two provided
+implementations.
+
+## Full reference
+
+See the [Connector SDK reference](https://docs.parmanasystems.com/reference/connector-sdk) and
+the [Connector Development Guide](https://docs.parmanasystems.com/integrations/connector-development-guide)
+— written against the TypeScript package, but the contract this package implements is
+identical.

parmana_connector_sdk-0.1.0/parmana_connector_sdk/__init__.py

@@ -0,0 +1,90 @@
+"""
+Parmana Connector SDK (Python).
+
+Connector authoring contracts: capability definitions, DTOs, metadata, and
+the Connector/CredentialProvider protocols. Passive by design -- this
+package describes capabilities, it does not execute them for real. No
+HTTP-calling reference implementation ships from this package; see the
+README for why, and for how short a real connector is to write directly
+against the Connector protocol.
+
+Mirrors the TypeScript @parmana/connector-sdk package's shape; see that
+package for the canonical design rationale behind each contract.
+"""
+
+from .connectors.oracle import OracleMetadata, create_oracle_connector
+from .connectors.salesforce import SalesforceMetadata, create_salesforce_connector
+from .connectors.sap import SapMetadata, create_sap_connector
+from .connectors.workday import WorkdayMetadata, create_workday_connector
+from .credentials import (
+    CredentialHandle,
+    CredentialProvider,
+    EnvironmentCredentialProvider,
+    StaticCredentialProvider,
+    brand_credential_handle,
+    is_credential_handle,
+)
+from .factory import ConnectorFactory
+from .metadata import (
+    ConnectorHealth,
+    ConnectorHealthStatus,
+    ConnectorMetadata,
+    ConnectorVersion,
+    connector_versions_equal,
+    format_connector_version,
+    healthy_now,
+)
+from .mock_connector import MockConnector, MockConnectorOptions, MockConnectorScript
+from .types import (
+    Connector,
+    ConnectorCapabilities,
+    ConnectorCapability,
+    ConnectorExecutionContext,
+    ConnectorRequest,
+    ConnectorResponse,
+    connector_capabilities,
+    is_namespaced_capability,
+)
+from .version import __version__
+
+__all__ = [
+    "__version__",
+    # Contract
+    "Connector",
+    "ConnectorCapability",
+    "ConnectorCapabilities",
+    "ConnectorExecutionContext",
+    "ConnectorRequest",
+    "ConnectorResponse",
+    "connector_capabilities",
+    "is_namespaced_capability",
+    "ConnectorFactory",
+    # Metadata
+    "ConnectorHealth",
+    "ConnectorHealthStatus",
+    "ConnectorMetadata",
+    "ConnectorVersion",
+    "connector_versions_equal",
+    "format_connector_version",
+    "healthy_now",
+    # Credentials
+    "CredentialHandle",
+    "CredentialProvider",
+    "EnvironmentCredentialProvider",
+    "StaticCredentialProvider",
+    "brand_credential_handle",
+    "is_credential_handle",
+    # Reference implementation
+    "MockConnector",
+    "MockConnectorOptions",
+    "MockConnectorScript",
+    # Four enterprise-named reference mocks
+    "OracleMetadata",
+    "create_oracle_connector",
+    "SalesforceMetadata",
+    "create_salesforce_connector",
+    "SapMetadata",
+    "create_sap_connector",
+    "WorkdayMetadata",
+    "create_workday_connector",
+]

parmana_connector_sdk-0.1.0/parmana_connector_sdk/connectors/__init__.py

@@ -0,0 +1,5 @@
+"""
+Four enterprise-named reference mocks. Not re-exported implicitly from
+here -- import each connector's own module, or use the top-level package
+barrel (``parmana_connector_sdk``).
+"""

parmana_connector_sdk-0.1.0/parmana_connector_sdk/connectors/oracle.py

@@ -0,0 +1,29 @@
+"""
+Mock Oracle connector.
+
+Deterministic, in-memory connector used until a real enterprise connector
+is implemented.
+"""
+
+from __future__ import annotations
+
+from ..metadata import ConnectorMetadata, ConnectorVersion, healthy_now
+from ..mock_connector import MockConnector, MockConnectorOptions
+from ..types import connector_capabilities
+
+OracleMetadata = ConnectorMetadata(
+    connector_id="oracle",
+    display_name="Oracle",
+    version=ConnectorVersion(major=1, minor=0, patch=0),
+    health=healthy_now(),
+    description="Mock connector for Oracle purchase order execution.",
+)
+
+
+def create_oracle_connector() -> MockConnector:
+    return MockConnector(
+        MockConnectorOptions(
+            connector_id="oracle",
+            capabilities=connector_capabilities(["oracle:create-purchase-order"]),
+        )
+    )

parmana_connector_sdk-0.1.0/parmana_connector_sdk/connectors/salesforce.py

@@ -0,0 +1,29 @@
+"""
+Mock Salesforce connector.
+
+Deterministic, in-memory connector used until a real enterprise connector
+is implemented.
+"""
+
+from __future__ import annotations
+
+from ..metadata import ConnectorMetadata, ConnectorVersion, healthy_now
+from ..mock_connector import MockConnector, MockConnectorOptions
+from ..types import connector_capabilities
+
+SalesforceMetadata = ConnectorMetadata(
+    connector_id="salesforce",
+    display_name="Salesforce",
+    version=ConnectorVersion(major=1, minor=0, patch=0),
+    health=healthy_now(),
+    description="Mock connector for Salesforce opportunity execution.",
+)
+
+
+def create_salesforce_connector() -> MockConnector:
+    return MockConnector(
+        MockConnectorOptions(
+            connector_id="salesforce",
+            capabilities=connector_capabilities(["salesforce:update-opportunity"]),
+        )
+    )

parmana_connector_sdk-0.1.0/parmana_connector_sdk/connectors/sap.py

@@ -0,0 +1,29 @@
+"""
+Mock SAP connector.
+
+Deterministic, in-memory connector used until a real enterprise connector
+is implemented.
+"""
+
+from __future__ import annotations
+
+from ..metadata import ConnectorMetadata, ConnectorVersion, healthy_now
+from ..mock_connector import MockConnector, MockConnectorOptions
+from ..types import connector_capabilities
+
+SapMetadata = ConnectorMetadata(
+    connector_id="sap",
+    display_name="SAP",
+    version=ConnectorVersion(major=1, minor=0, patch=0),
+    health=healthy_now(),
+    description="Mock connector for SAP invoice execution.",
+)
+
+
+def create_sap_connector() -> MockConnector:
+    return MockConnector(
+        MockConnectorOptions(
+            connector_id="sap",
+            capabilities=connector_capabilities(["sap:post-invoice"]),
+        )
+    )

parmana_connector_sdk-0.1.0/parmana_connector_sdk/connectors/workday.py

@@ -0,0 +1,29 @@
+"""
+Mock Workday connector.
+
+Deterministic, in-memory connector used until a real enterprise connector
+is implemented.
+"""
+
+from __future__ import annotations
+
+from ..metadata import ConnectorMetadata, ConnectorVersion, healthy_now
+from ..mock_connector import MockConnector, MockConnectorOptions
+from ..types import connector_capabilities
+
+WorkdayMetadata = ConnectorMetadata(
+    connector_id="workday",
+    display_name="Workday",
+    version=ConnectorVersion(major=1, minor=0, patch=0),
+    health=healthy_now(),
+    description="Mock connector for Workday expense report execution.",
+)
+
+
+def create_workday_connector() -> MockConnector:
+    return MockConnector(
+        MockConnectorOptions(
+            connector_id="workday",
+            capabilities=connector_capabilities(["workday:submit-expense-report"]),
+        )
+    )

parmana_connector_sdk-0.1.0/parmana_connector_sdk/credentials.py

@@ -0,0 +1,137 @@
+"""
+Credential resolution seam.
+
+Credential resolution happens exclusively inside the Execution Gateway (via a
+CredentialVault backed by one of these providers). Connectors never resolve,
+retrieve, discover, or store credentials themselves -- they only ever receive
+an opaque, already-resolved CredentialHandle.
+
+This module defines the interface seam for future providers (HashiCorp
+Vault, AWS Secrets Manager, Azure Key Vault, Google Secret Manager). Only the
+seam is defined here; no cloud SDK integration is implemented.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from dataclasses import dataclass, field, replace
+from typing import Any, Protocol, runtime_checkable
+
+
+@dataclass(frozen=True)
+class CredentialHandle:
+    """
+    Opaque credential material resolved by a CredentialProvider.
+
+    ``value`` is never logged, never included in connector evidence, and
+    never serialized into an Execution Trust Record. It exists only to be
+    read, ephemerally, by a Connector's own execution call (e.g. an HTTP
+    header).
+    """
+
+    provider_id: str
+    credential_id: str
+    value: Any
+    _branded: bool = field(default=False, repr=False, compare=False)
+
+
+def brand_credential_handle(handle: CredentialHandle) -> CredentialHandle:
+    """
+    Marks a CredentialHandle as having been produced by a CredentialProvider,
+    as opposed to a raw value supplied directly by a caller. Production
+    connector executors reject any credential that is not branded this way,
+    closing the "raw credential supplied" gap execution must fail closed on.
+    """
+    return replace(handle, _branded=True)
+
+
+def is_credential_handle(value: object) -> bool:
+    return isinstance(value, CredentialHandle) and value._branded
+
+
+@runtime_checkable
+class CredentialProvider(Protocol):
+    """
+    Resolves opaque credential material for a connector.
+
+    Implementations MUST NOT raise errors that embed the resolved secret
+    value -- only identifiers (connector_id, provider_id, credential_id) may
+    appear in error messages.
+    """
+
+    provider_id: str
+
+    def resolve(self, connector_id: str) -> CredentialHandle: ...
+
+
+class EnvironmentCredentialProvider:
+    """
+    Resolves credentials from process environment variables.
+
+    Future providers (HashiCorp Vault, AWS Secrets Manager, Azure Key Vault,
+    Google Secret Manager) implement the same CredentialProvider protocol.
+    None is implemented in this package.
+    """
+
+    provider_id = "environment"
+
+    def __init__(
+        self,
+        connector_environment_variable: Mapping[str, str],
+        environment: Mapping[str, str | None] | None = None,
+    ) -> None:
+        self._connector_environment_variable = dict(connector_environment_variable)
+        self._environment: Mapping[str, str | None] = (
+            environment if environment is not None else os.environ
+        )
+
+    def resolve(self, connector_id: str) -> CredentialHandle:
+        variable_name = self._connector_environment_variable.get(connector_id)
+        if variable_name is None:
+            raise ValueError(
+                "No environment credential mapping configured for connector: "
+                f"{connector_id}."
+            )
+        value = self._environment.get(variable_name)
+        if value is None:
+            raise ValueError(
+                f'Environment variable "{variable_name}" for connector '
+                f'"{connector_id}" is not set.'
+            )
+        return brand_credential_handle(
+            CredentialHandle(
+                provider_id=self.provider_id,
+                credential_id=variable_name,
+                value={"token": value},
+            )
+        )
+
+
+class StaticCredentialProvider:
+    """
+    Resolves credentials from an in-memory map.
+
+    Intended for hermetic tests and local development only.
+    """
+
+    provider_id = "static"
+
+    def __init__(self, entries: Mapping[str, Any] | None = None) -> None:
+        self._credentials: dict[str, Any] = dict(entries or {})
+
+    def set(self, connector_id: str, value: Any) -> None:
+        self._credentials[connector_id] = value
+
+    def resolve(self, connector_id: str) -> CredentialHandle:
+        if connector_id not in self._credentials:
+            raise ValueError(
+                f"No static credential configured for connector: {connector_id}."
+            )
+        return brand_credential_handle(
+            CredentialHandle(
+                provider_id=self.provider_id,
+                credential_id=connector_id,
+                value=self._credentials[connector_id],
+            )
+        )

parmana_connector_sdk-0.1.0/parmana_connector_sdk/factory.py

@@ -0,0 +1,24 @@
+"""
+Construction contract a connector factory can implement.
+"""
+
+from __future__ import annotations
+
+from typing import Generic, Protocol, TypeVar
+
+from .types import Connector
+
+TConfig = TypeVar("TConfig", contravariant=True)
+
+
+class ConnectorFactory(Protocol, Generic[TConfig]):
+    """
+    Constructs a Connector from configuration.
+
+    No concrete factory ships in this package; only the seam is defined so
+    connectors have a single, consistent construction contract to target.
+    """
+
+    connector_type: str
+
+    def create(self, config: TConfig) -> Connector: ...