deepquery-sdk 1.0.0__py3-none-any.whl

deepquery_sdk/__init__.py

@@ -0,0 +1,101 @@
+"""DeepQuerySDK — the Connector Development Kit for Deep Query.
+
+Build a connector by subclassing `Connector` and declaring reads with
+`@resource` and writes with `@action`. The connector emits a standard MCP
+server (see `deepquery_sdk.mcp_emit`).
+
+See SDK_GUIDE.md for the full specification.
+"""
+
+from __future__ import annotations
+
+from .action import ActionSpec, action
+from .auth import (
+    ApiKeyAuth,
+    AppliedAuth,
+    AuthStrategy,
+    BasicAuth,
+    BearerAuth,
+    Credential,
+    CredentialError,
+    CredentialProvider,
+    MTLSAuth,
+    OAuth2Auth,
+    PKCEPair,
+    build_authorization_url,
+    build_token_request,
+    env_credential_provider,
+    generate_pkce,
+    static_credential_provider,
+)
+from .classification import CapabilityKind
+from .connector import Connector, ConnectorContractError
+from .gate import ActionStatus, ApprovalGate, GateError, PendingAction
+from .compat import (
+    CompatibilityResult,
+    IncompatibleConnectorError,
+    assert_compatible,
+    check_manifest_compatibility,
+)
+from .manifest import (
+    ActionManifest,
+    AuthMethod,
+    DeploymentCompat,
+    Manifest,
+    ResourceManifest,
+    SDK_MAJOR_VERSION,
+    SDK_VERSION,
+)
+from .provenance import CitedRecord, Provenance, make_provenance, now_iso
+from .resource import ResourceSpec, resource
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "Connector",
+    "ConnectorContractError",
+    "resource",
+    "ResourceSpec",
+    "action",
+    "ActionSpec",
+    "CapabilityKind",
+    "CitedRecord",
+    "Provenance",
+    "make_provenance",
+    "now_iso",
+    "Manifest",
+    "ResourceManifest",
+    "ActionManifest",
+    "AuthMethod",
+    "DeploymentCompat",
+    "SDK_MAJOR_VERSION",
+    "SDK_VERSION",
+    # compatibility
+    "assert_compatible",
+    "check_manifest_compatibility",
+    "CompatibilityResult",
+    "IncompatibleConnectorError",
+    # auth
+    "AuthStrategy",
+    "Credential",
+    "CredentialError",
+    "CredentialProvider",
+    "AppliedAuth",
+    "ApiKeyAuth",
+    "BasicAuth",
+    "BearerAuth",
+    "OAuth2Auth",
+    "MTLSAuth",
+    "PKCEPair",
+    "generate_pkce",
+    "build_authorization_url",
+    "build_token_request",
+    "static_credential_provider",
+    "env_credential_provider",
+    # gate
+    "ApprovalGate",
+    "ActionStatus",
+    "PendingAction",
+    "GateError",
+    "__version__",
+]

deepquery_sdk/action.py

@@ -0,0 +1,104 @@
+"""Action definitions — the write/mutation side of a connector.
+
+An action is a state-mutating capability. It is declared with the `@action`
+decorator on a `Connector` method (the *execute* step), and its mandatory
+*preview* is attached with `@<action>.preview`. The separation of preview and
+execute is the architectural heart of the approval-gate safety model: the agent
+and the gate always see the preview first, and execute is only ever called after
+human confirmation.
+
+In Phase 1 the SDK captures and validates this contract and emits the action
+into the MCP server tagged `dq.mutates: true`. The full gated
+`preview → approve → execute` drive is wired through the harness in Phase 2; an
+emitted action invoked directly returns its preview and does **not** execute.
+
+See SDK_GUIDE.md §4.3 and §5.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .classification import CapabilityKind
+
+
+class ActionSpec:
+    """Declarative metadata + bound functions for one action.
+
+    Becomes the class attribute in place of the decorated method, so
+    `@<action>.preview` can register the preview step at class-body time.
+    """
+
+    kind = CapabilityKind.ACTION
+
+    def __init__(
+        self,
+        *,
+        name: str | None,
+        description: str,
+        input_schema: dict[str, Any],
+    ) -> None:
+        self._name = name
+        self.description = description
+        self.input_schema = input_schema
+        self.execute_fn: Callable | None = None
+        self.preview_fn: Callable | None = None
+        self.attr_name: str | None = None
+
+    # -- decorator wiring -------------------------------------------------
+    def __call__(self, fn: Callable) -> "ActionSpec":
+        """Capture the execute function (the body of `@action(...)`)."""
+        self.execute_fn = fn
+        if self._name is None:
+            self._name = fn.__name__
+        return self
+
+    def preview(self, fn: Callable) -> Callable:
+        """Register the mandatory preview function.
+
+        Usage::
+
+            @create_issue.preview
+            def _(self, **params) -> str: ...
+
+        Returns the preview function unchanged so it does not shadow the action
+        attribute on the class.
+        """
+        self.preview_fn = fn
+        return fn
+
+    def __set_name__(self, owner: type, attr_name: str) -> None:
+        self.attr_name = attr_name
+
+    # -- accessors --------------------------------------------------------
+    @property
+    def name(self) -> str:
+        # _name is set either explicitly or from the execute fn in __call__.
+        assert self._name is not None, "action defined without an execute function"
+        return self._name
+
+    def has_preview(self) -> bool:
+        return self.preview_fn is not None
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"ActionSpec(name={self._name!r}, has_preview={self.has_preview()})"
+
+
+def action(
+    *,
+    description: str,
+    name: str | None = None,
+    input_schema: dict[str, Any] | None = None,
+) -> ActionSpec:
+    """Declare a state-mutating action.
+
+    Decorate the *execute* method with `@action(...)`, then attach the mandatory
+    preview with `@<action>.preview`. A connector that declares an action without
+    a preview is a contract violation and is rejected when the connector class is
+    defined.
+    """
+    return ActionSpec(
+        name=name,
+        description=description,
+        input_schema=input_schema or {"type": "object", "properties": {}},
+    )

deepquery_sdk/auth/__init__.py

@@ -0,0 +1,45 @@
+"""Authentication scaffolding for connectors.
+
+Connectors declare an `AuthStrategy` and read an injected `Credential` per call;
+they never store credentials. See SDK_GUIDE.md §7.
+"""
+
+from .base import (
+    AppliedAuth,
+    AuthStrategy,
+    Credential,
+    CredentialError,
+    CredentialProvider,
+    env_credential_provider,
+    static_credential_provider,
+)
+from .oauth2 import (
+    PKCEPair,
+    TokenRequest,
+    build_authorization_url,
+    build_refresh_request,
+    build_token_request,
+    generate_pkce,
+)
+from .strategies import ApiKeyAuth, BasicAuth, BearerAuth, MTLSAuth, OAuth2Auth
+
+__all__ = [
+    "AppliedAuth",
+    "AuthStrategy",
+    "Credential",
+    "CredentialError",
+    "CredentialProvider",
+    "static_credential_provider",
+    "env_credential_provider",
+    "ApiKeyAuth",
+    "BasicAuth",
+    "BearerAuth",
+    "OAuth2Auth",
+    "MTLSAuth",
+    "PKCEPair",
+    "generate_pkce",
+    "build_authorization_url",
+    "build_token_request",
+    "build_refresh_request",
+    "TokenRequest",
+]

deepquery_sdk/auth/base.py

@@ -0,0 +1,96 @@
+"""Auth foundations: credentials, strategies, and the injection hook.
+
+Connectors authenticate to external systems but **never store credentials**
+(SDK_GUIDE.md §7). The gateway owns credential lifecycle and injects a valid
+credential at call time through a `CredentialProvider`. An `AuthStrategy`
+declares *how* to attach that credential to outbound requests; it never holds the
+secret itself — it receives one per call and returns the headers/cert to apply.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any, Callable, Optional
+
+from pydantic import BaseModel, Field
+
+from ..manifest import AuthMethod
+
+
+class Credential(BaseModel):
+    """Opaque secret material injected by the gateway for a single call.
+
+    Only the fields relevant to the connector's declared auth method are set.
+    The connector reads this via `self.current_credential` during a call and must
+    never persist it.
+    """
+
+    token: Optional[str] = None  # OAuth bearer token or API key value
+    username: Optional[str] = None
+    password: Optional[str] = None
+    client_cert_path: Optional[str] = None
+    client_key_path: Optional[str] = None
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class AppliedAuth(BaseModel):
+    """The result of applying a strategy to a credential: what to attach to a request."""
+
+    headers: dict[str, str] = Field(default_factory=dict)
+    # httpx-style client cert: a (cert, key) path tuple, when using mTLS.
+    cert: Optional[tuple[str, str]] = None
+
+
+class CredentialError(Exception):
+    """Raised when a credential is required for a call but none was injected."""
+
+
+# The gateway supplies one of these. It is called per request and may return a
+# different (e.g. per-user) credential each time. Returning None means "no
+# credential available" — strategies that require one will raise.
+CredentialProvider = Callable[[], Optional[Credential]]
+
+
+class AuthStrategy(ABC):
+    """Declares how a connector attaches an injected credential to its requests."""
+
+    method: AuthMethod
+
+    @abstractmethod
+    def apply(self, credential: Credential) -> AppliedAuth:
+        """Return the headers / cert to attach, given an injected credential."""
+        raise NotImplementedError
+
+    @property
+    def scopes(self) -> list[str]:
+        """OAuth scopes this strategy requests (empty for non-OAuth)."""
+        return []
+
+
+def static_credential_provider(credential: Credential) -> CredentialProvider:
+    """A provider that always returns the same credential.
+
+    Used for air-gapped / static injection (API keys, mTLS certs) sourced from
+    the institution's own secret store with no external OAuth round-trip
+    (SDK_GUIDE.md §7).
+    """
+
+    def _provider() -> Credential:
+        return credential
+
+    return _provider
+
+
+def env_credential_provider(*, token_env: str) -> CredentialProvider:
+    """A provider that reads a bearer token / API key from an environment variable.
+
+    Convenient for self-hosted, air-gapped connectors whose secret store exposes
+    credentials through the process environment.
+    """
+    import os
+
+    def _provider() -> Optional[Credential]:
+        value = os.environ.get(token_env)
+        return Credential(token=value) if value else None
+
+    return _provider

deepquery_sdk/auth/oauth2.py

@@ -0,0 +1,106 @@
+"""OAuth 2.1 flow-construction scaffolding (authorization code + PKCE).
+
+These are the pure building blocks a gateway uses to run the authorization-code
+flow with PKCE: generate a PKCE pair, build the authorization URL, and build the
+token-exchange request. The SDK intentionally does **not** perform token storage,
+exchange-over-the-wire, or refresh — credential lifecycle is owned by the gateway
+(SDK_GUIDE.md §7). Keeping these helpers pure also makes them testable offline.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import secrets
+from dataclasses import dataclass
+from urllib.parse import urlencode
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+@dataclass(frozen=True)
+class PKCEPair:
+    """A PKCE code verifier and its S256-derived challenge."""
+
+    verifier: str
+    challenge: str
+    method: str = "S256"
+
+
+def generate_pkce() -> PKCEPair:
+    """Generate a PKCE verifier/challenge pair (RFC 7636, S256)."""
+    verifier = _b64url(secrets.token_bytes(32))  # 43-char high-entropy verifier
+    challenge = _b64url(hashlib.sha256(verifier.encode("ascii")).digest())
+    return PKCEPair(verifier=verifier, challenge=challenge)
+
+
+def build_authorization_url(
+    *,
+    authorize_endpoint: str,
+    client_id: str,
+    redirect_uri: str,
+    scopes: list[str],
+    code_challenge: str,
+    state: str | None = None,
+    code_challenge_method: str = "S256",
+) -> str:
+    """Build the authorization-request URL the user is redirected to."""
+    params = {
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": redirect_uri,
+        "scope": " ".join(scopes),
+        "code_challenge": code_challenge,
+        "code_challenge_method": code_challenge_method,
+    }
+    if state is not None:
+        params["state"] = state
+    return f"{authorize_endpoint}?{urlencode(params)}"
+
+
+@dataclass(frozen=True)
+class TokenRequest:
+    """A ready-to-send token-exchange request (the gateway performs the POST)."""
+
+    url: str
+    data: dict[str, str]
+
+
+def build_token_request(
+    *,
+    token_endpoint: str,
+    client_id: str,
+    code: str,
+    code_verifier: str,
+    redirect_uri: str,
+) -> TokenRequest:
+    """Build the authorization-code → token exchange request body."""
+    return TokenRequest(
+        url=token_endpoint,
+        data={
+            "grant_type": "authorization_code",
+            "client_id": client_id,
+            "code": code,
+            "code_verifier": code_verifier,
+            "redirect_uri": redirect_uri,
+        },
+    )
+
+
+def build_refresh_request(
+    *,
+    token_endpoint: str,
+    client_id: str,
+    refresh_token: str,
+) -> TokenRequest:
+    """Build a refresh-token request (gateway performs and stores the result)."""
+    return TokenRequest(
+        url=token_endpoint,
+        data={
+            "grant_type": "refresh_token",
+            "client_id": client_id,
+            "refresh_token": refresh_token,
+        },
+    )

deepquery_sdk/auth/strategies.py

@@ -0,0 +1,91 @@
+"""Concrete auth strategies: API key, basic, bearer/OAuth2, mTLS.
+
+Each strategy receives an injected `Credential` per call and returns the headers
+(or client cert) to attach. None of them store the credential.
+"""
+
+from __future__ import annotations
+
+import base64
+
+from ..manifest import AuthMethod
+from .base import AppliedAuth, AuthStrategy, Credential, CredentialError
+
+
+class ApiKeyAuth(AuthStrategy):
+    """Attach an API key as a header, e.g. `Authorization: Bearer <key>` or `X-API-Key: <key>`."""
+
+    method = AuthMethod.API_KEY
+
+    def __init__(self, *, header_name: str = "Authorization", value_prefix: str = "") -> None:
+        self.header_name = header_name
+        self.value_prefix = value_prefix
+
+    def apply(self, credential: Credential) -> AppliedAuth:
+        if not credential.token:
+            raise CredentialError("ApiKeyAuth requires credential.token")
+        value = f"{self.value_prefix}{credential.token}" if self.value_prefix else credential.token
+        return AppliedAuth(headers={self.header_name: value})
+
+
+class BasicAuth(AuthStrategy):
+    """HTTP Basic auth from an injected username/password."""
+
+    method = AuthMethod.BASIC
+
+    def apply(self, credential: Credential) -> AppliedAuth:
+        if credential.username is None or credential.password is None:
+            raise CredentialError("BasicAuth requires credential.username and credential.password")
+        raw = f"{credential.username}:{credential.password}".encode()
+        encoded = base64.b64encode(raw).decode()
+        return AppliedAuth(headers={"Authorization": f"Basic {encoded}"})
+
+
+class BearerAuth(AuthStrategy):
+    """Attach a bearer token (the shape an OAuth access token takes on requests)."""
+
+    method = AuthMethod.OAUTH2
+
+    def apply(self, credential: Credential) -> AppliedAuth:
+        if not credential.token:
+            raise CredentialError("BearerAuth requires credential.token")
+        return AppliedAuth(headers={"Authorization": f"Bearer {credential.token}"})
+
+
+class OAuth2Auth(BearerAuth):
+    """OAuth 2.1 strategy: declares endpoints + scopes, attaches the bearer token.
+
+    The connector declares the flow's endpoints and the minimum scopes it needs
+    (least-privilege, SDK_GUIDE.md §13). The gateway runs and stores the grant
+    (§7); see `deepquery_sdk.auth.oauth2` for the PKCE flow-construction helpers.
+    """
+
+    method = AuthMethod.OAUTH2
+
+    def __init__(
+        self,
+        *,
+        authorize_endpoint: str,
+        token_endpoint: str,
+        scopes: list[str] | None = None,
+    ) -> None:
+        self.authorize_endpoint = authorize_endpoint
+        self.token_endpoint = token_endpoint
+        self._scopes = list(scopes or [])
+
+    @property
+    def scopes(self) -> list[str]:
+        return self._scopes
+
+
+class MTLSAuth(AuthStrategy):
+    """Mutual TLS: attach an injected client certificate/key pair."""
+
+    method = AuthMethod.MTLS
+
+    def apply(self, credential: Credential) -> AppliedAuth:
+        if not credential.client_cert_path or not credential.client_key_path:
+            raise CredentialError(
+                "MTLSAuth requires credential.client_cert_path and credential.client_key_path"
+            )
+        return AppliedAuth(cert=(credential.client_cert_path, credential.client_key_path))

deepquery_sdk/classification.py

@@ -0,0 +1,43 @@
+"""Read / Action classification — the safety contract.
+
+Every capability a connector exposes is classified *at definition time* as
+either a read (Resource) or an action (mutating tool). This classification is
+declared by the developer, never inferred at runtime, and is embedded in the
+emitted MCP server as metadata the Connector Infrastructure layer reads to
+decide gating.
+
+See SDK_GUIDE.md §5.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class CapabilityKind(str, Enum):
+    """How a capability is classified for the approval gate."""
+
+    RESOURCE = "resource"  # read-only, ungated, citeable
+    ACTION = "action"  # mutates external state, gated behind human approval
+
+
+# Metadata keys attached to the emitted MCP `Tool._meta`. The Connector
+# Infrastructure gateway reads these to decide gating and citation handling.
+# Namespaced under `dq.` so they never collide with other MCP metadata.
+DQ_MUTATES = "dq.mutates"  # bool — True for actions, False for resources
+DQ_KIND = "dq.kind"  # CapabilityKind value
+DQ_CONNECTOR = "dq.connector"  # originating connector name
+
+
+def mutates(kind: CapabilityKind) -> bool:
+    """Whether a capability of this kind mutates external state."""
+    return kind is CapabilityKind.ACTION
+
+
+def meta_for(kind: CapabilityKind, connector_name: str) -> dict[str, object]:
+    """Build the `dq.*` metadata block for a capability's emitted MCP tool."""
+    return {
+        DQ_KIND: kind.value,
+        DQ_MUTATES: mutates(kind),
+        DQ_CONNECTOR: connector_name,
+    }

deepquery_sdk/cli/__init__.py

@@ -0,0 +1,5 @@
+"""DeepQuerySDK command-line tooling (scaffold / validate / run-dev / emit / manifest)."""
+
+from .__main__ import main
+
+__all__ = ["main"]

deepquery_sdk/cli/__main__.py

@@ -0,0 +1,64 @@
+"""The `deepquery` command-line entry point.
+
+Built on stdlib argparse — no third-party CLI dependency — so the SDK stays a
+thin install (mcp + pydantic).
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import commands
+
+_TARGET_HELP = (
+    "connector target: 'module.path:ClassName', a module, or a path to a "
+    "connector .py file (or a directory containing connector.py)"
+)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="deepquery", description="DeepQuerySDK connector tooling.")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_scaffold = sub.add_parser("scaffold", help="generate a new connector from the template")
+    p_scaffold.add_argument("name", help="connector name, e.g. 'jira' or 'acme-crm'")
+    p_scaffold.add_argument("--dir", help="output directory (default: ./<name>)")
+    p_scaffold.set_defaults(func=commands.cmd_scaffold)
+
+    p_validate = sub.add_parser("validate", help="static-check a connector against the safety contracts")
+    p_validate.add_argument("target", help=_TARGET_HELP)
+    p_validate.set_defaults(func=commands.cmd_validate)
+
+    p_manifest = sub.add_parser("manifest", help="print or export the connector manifest")
+    p_manifest.add_argument("target", help=_TARGET_HELP)
+    p_manifest.add_argument("--out", help="write manifest JSON to this file instead of stdout")
+    p_manifest.set_defaults(func=commands.cmd_manifest)
+
+    p_emit = sub.add_parser("emit", help="produce the deployable MCP server artifact")
+    p_emit.add_argument("target", help=_TARGET_HELP)
+    p_emit.add_argument("--out", default="dist", help="output directory (default: ./dist)")
+    p_emit.set_defaults(func=commands.cmd_emit)
+
+    p_run = sub.add_parser("run-dev", help="drive the connector locally with the mock agent")
+    p_run.add_argument("target", help=_TARGET_HELP)
+    p_run.set_defaults(func=commands.cmd_run_dev)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    # The guide references sections with '§' and uses em dashes; make sure those
+    # render on legacy Windows consoles (cp1252) rather than showing as '�'.
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")  # type: ignore[attr-defined]
+        except (AttributeError, ValueError):
+            pass
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())