deepquery-sdk 1.0.0__py3-none-any.whl

deepquery_sdk/gate.py

@@ -0,0 +1,83 @@
+"""The approval gate — the runtime mechanism behind preview → execute.
+
+Every action passes through this gate. Calling an action *requests* it: the gate
+records the previewed effect and mints a single-use, argument-bound approval
+token. Execution requires presenting that token. The human-confirmation decision
+itself lives in the Agent Layer / gateway above the SDK (SDK_GUIDE.md §4.3, §5);
+this gate is what makes "execute can't happen without a preview of these exact
+arguments" enforceable at the connector boundary.
+"""
+
+from __future__ import annotations
+
+import secrets
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ActionStatus(str, Enum):
+    PREVIEWED = "previewed"  # preview generated, awaiting a decision
+    EXECUTED = "executed"  # approved and run (terminal)
+    REJECTED = "rejected"  # declined, never run (terminal)
+
+
+class PendingAction(BaseModel):
+    """One requested-but-not-yet-decided action, keyed by its approval token."""
+
+    token: str
+    action_name: str
+    arguments: dict[str, Any]
+    preview: str
+    status: ActionStatus = ActionStatus.PREVIEWED
+    requested_at: str = Field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+
+class GateError(Exception):
+    """Raised when the gate is driven into an invalid state transition."""
+
+
+class ApprovalGate:
+    """In-process registry of pending actions and their lifecycle."""
+
+    def __init__(self) -> None:
+        self._pending: dict[str, PendingAction] = {}
+
+    def request(self, action_name: str, arguments: dict[str, Any], preview: str) -> PendingAction:
+        """Record a previewed action and mint its single-use approval token."""
+        token = secrets.token_urlsafe(24)
+        pending = PendingAction(
+            token=token,
+            action_name=action_name,
+            arguments=dict(arguments),
+            preview=preview,
+        )
+        self._pending[token] = pending
+        return pending
+
+    def get(self, token: str) -> PendingAction:
+        pending = self._pending.get(token)
+        if pending is None:
+            raise GateError(f"unknown or already-consumed approval token: {token!r}")
+        return pending
+
+    def mark_executed(self, token: str) -> PendingAction:
+        """Transition PREVIEWED → EXECUTED. The token is consumed (single use)."""
+        pending = self.get(token)
+        if pending.status is not ActionStatus.PREVIEWED:
+            raise GateError(f"action {pending.action_name!r} is already {pending.status.value}")
+        pending.status = ActionStatus.EXECUTED
+        return pending
+
+    def reject(self, token: str) -> PendingAction:
+        """Transition PREVIEWED → REJECTED. The token is consumed (single use)."""
+        pending = self.get(token)
+        if pending.status is not ActionStatus.PREVIEWED:
+            raise GateError(f"action {pending.action_name!r} is already {pending.status.value}")
+        pending.status = ActionStatus.REJECTED
+        return pending
+
+    def pending_tokens(self) -> list[str]:
+        return [t for t, p in self._pending.items() if p.status is ActionStatus.PREVIEWED]

deepquery_sdk/harness/__init__.py

@@ -0,0 +1,5 @@
+"""Local dev harness for testing connectors without the full platform."""
+
+from .mock_agent import HarnessError, MockAgent
+
+__all__ = ["MockAgent", "HarnessError"]

deepquery_sdk/harness/mock_agent.py

@@ -0,0 +1,119 @@
+"""Local dev harness — a mock agent that drives a connector like Deep Query would.
+
+The mock agent discovers a connector's capabilities through its emitted MCP
+interface (a real in-memory client session, not direct method calls), lets the
+developer issue reads and inspect the provenance envelope, and drives an action
+through the exact preview → approval → execute sequence the real Agent Layer
+uses — including simulating both an approval and a rejection (SDK_GUIDE.md §10).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp.shared.memory import create_connected_server_and_client_session
+
+from ..connector import Connector
+from ..mcp_emit.emitter import EXECUTE_TOOL, REJECT_TOOL, emit_server
+
+
+class HarnessError(Exception):
+    pass
+
+
+class MockAgent:
+    """Drives a connector over an in-memory MCP session."""
+
+    def __init__(self, connector: Connector) -> None:
+        self.connector = connector
+        self._cm = None
+        self.session = None
+
+    async def __aenter__(self) -> "MockAgent":
+        self._cm = create_connected_server_and_client_session(emit_server(self.connector))
+        self.session = await self._cm.__aenter__()
+        await self.session.initialize()
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        assert self._cm is not None
+        await self._cm.__aexit__(*exc)
+
+    # -- discovery --------------------------------------------------------
+    async def capabilities(self) -> dict[str, list[dict[str, Any]]]:
+        """Group the advertised tools by kind, with their dq.* classification."""
+        tools = (await self.session.list_tools()).tools
+        grouped: dict[str, list[dict[str, Any]]] = {"resources": [], "actions": [], "controls": []}
+        for t in tools:
+            meta = t.meta or {}
+            kind = meta.get("dq.kind", "unknown")
+            entry = {"name": t.name, "description": t.description, "dq.mutates": meta.get("dq.mutates")}
+            if kind == "resource":
+                grouped["resources"].append(entry)
+            elif kind == "action":
+                grouped["actions"].append(entry)
+            else:
+                grouped["controls"].append(entry)
+        return grouped
+
+    # -- reads ------------------------------------------------------------
+    async def read(self, name: str, **arguments: Any) -> list[dict[str, Any]]:
+        """Call a read tool and return its records, validating the provenance
+        envelope the way the gateway would (surfacing problems as errors)."""
+        result = await self.session.call_tool(name, arguments)
+        if result.isError:
+            raise HarnessError(self._error_text(result, name))
+        payload = result.structuredContent or {}
+        records = payload.get("records")
+        if records is None:
+            raise HarnessError(f"read '{name}' did not return a 'records' list")
+        for i, rec in enumerate(records):
+            prov = rec.get("provenance")
+            if not prov:
+                raise HarnessError(f"record {i} from '{name}' is missing its provenance envelope (§6)")
+            for required in ("connector_name", "source_object_id", "retrieved_at", "title_or_label"):
+                if not prov.get(required):
+                    raise HarnessError(
+                        f"record {i} from '{name}' is missing provenance field '{required}' (§6)"
+                    )
+        return records
+
+    # -- gated actions ----------------------------------------------------
+    async def request_action(self, name: str, **arguments: Any) -> dict[str, Any]:
+        """Step 1: request the action; returns the preview + approval token."""
+        result = await self.session.call_tool(name, arguments)
+        if result.isError:
+            raise HarnessError(self._error_text(result, name))
+        payload = result.structuredContent or {}
+        if payload.get("status") != "preview":
+            raise HarnessError(f"action '{name}' did not return a preview (got {payload!r})")
+        return payload
+
+    async def approve(self, token: str) -> dict[str, Any]:
+        """Step 2a: approve and execute by token."""
+        result = await self.session.call_tool(EXECUTE_TOOL, {"approval_token": token})
+        if result.isError:
+            raise HarnessError(self._error_text(result, EXECUTE_TOOL))
+        return result.structuredContent or {}
+
+    async def reject(self, token: str) -> dict[str, Any]:
+        """Step 2b: reject by token; the action never runs."""
+        result = await self.session.call_tool(REJECT_TOOL, {"approval_token": token})
+        if result.isError:
+            raise HarnessError(self._error_text(result, REJECT_TOOL))
+        return result.structuredContent or {}
+
+    async def run_action(self, name: str, *, approve: bool, **arguments: Any) -> dict[str, Any]:
+        """Drive the full sequence: preview, then approve→execute or reject."""
+        preview = await self.request_action(name, **arguments)
+        token = preview["approval_token"]
+        outcome = await self.approve(token) if approve else await self.reject(token)
+        return {"preview": preview, "outcome": outcome}
+
+    # -- helpers ----------------------------------------------------------
+    @staticmethod
+    def _error_text(result, name: str) -> str:
+        for block in result.content:
+            if getattr(block, "text", None):
+                return f"tool '{name}' errored: {block.text}"
+        return f"tool '{name}' errored"

deepquery_sdk/manifest.py

@@ -0,0 +1,78 @@
+"""Connector manifest — identity, capabilities, auth, deployment compatibility.
+
+The manifest is what the Connector Infrastructure layer reads to populate the
+admin approval directory and the user-facing connector list. It also declares
+the SDK major version the connector targets, so the gateway can refuse a
+connector built against an incompatible SDK rather than failing at call time.
+
+See SDK_GUIDE.md §3 and §11.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+# Single source of truth for the SDK's version. The package version in
+# pyproject.toml must match SDK_VERSION (guarded by a test). The contract major
+# version — what a connector manifest targets — is the major of SDK_VERSION.
+SDK_VERSION = "1.0.0"
+SDK_MAJOR_VERSION = int(SDK_VERSION.split(".")[0])
+
+
+class AuthMethod(str, Enum):
+    """How a connector authenticates to its external system.
+
+    Connectors never store credentials — the gateway owns credential lifecycle
+    and injects a valid token at call time (SDK_GUIDE.md §7). This enum only
+    declares *which* method the connector needs.
+    """
+
+    NONE = "none"
+    API_KEY = "api_key"
+    OAUTH2 = "oauth2"  # OAuth 2.1 authorization-code flow with PKCE
+    BASIC = "basic"
+    MTLS = "mtls"
+    CUSTOM = "custom"
+
+
+class ResourceManifest(BaseModel):
+    name: str
+    description: str
+    mutates: bool = False  # always False for resources; present for uniformity
+
+
+class ActionManifest(BaseModel):
+    name: str
+    description: str
+    mutates: bool = True  # always True for actions
+    has_preview: bool = True
+
+
+class DeploymentCompat(BaseModel):
+    """Deployment-mode honesty: a connector must declare its network needs so
+    air-gapped deployments can refuse network-dependent connectors."""
+
+    requires_network: bool = Field(..., description="Does the connector need external network access?")
+    air_gapped_capable: bool = Field(..., description="Can it run in an air-gapped deployment?")
+
+
+class Manifest(BaseModel):
+    """The full connector manifest."""
+
+    name: str
+    version: str
+    description: str = ""
+    sdk_major_version: int = SDK_MAJOR_VERSION
+    auth_method: AuthMethod = AuthMethod.NONE
+    auth_scopes: list[str] = Field(
+        default_factory=list,
+        description="OAuth scopes the connector requests; should be least-privilege (§13).",
+    )
+    resources: list[ResourceManifest] = Field(default_factory=list)
+    actions: list[ActionManifest] = Field(default_factory=list)
+    deployment: DeploymentCompat
+
+    def to_json(self, *, indent: int = 2) -> str:
+        return self.model_dump_json(indent=indent)

deepquery_sdk/mcp_emit/__init__.py

@@ -0,0 +1,5 @@
+"""MCP emission layer — wraps the official MCP server SDK."""
+
+from .emitter import build_tools, emit_server, run_stdio, serve_stdio
+
+__all__ = ["build_tools", "emit_server", "run_stdio", "serve_stdio"]

deepquery_sdk/mcp_emit/emitter.py

@@ -0,0 +1,174 @@
+"""Emit a compliant MCP server from a `Connector`.
+
+This is the layer that makes "everything emits MCP" real (SDK_GUIDE.md §2). It
+wraps the official MCP server SDK's low-level `Server` — it does **not**
+reimplement MCP. Every capability becomes an MCP tool:
+
+- Resources are emitted as **read-only** tools (`annotations.readOnlyHint=True`,
+  `dq.mutates=False`) so the agent can call them freely during context assembly.
+  They return their records wrapped in the provenance envelope.
+- Actions are emitted as tools tagged `dq.mutates=True` /
+  `annotations.destructiveHint=True`. Calling an action *requests* it: the server
+  runs `preview`, mints a single-use approval token, and returns
+  `{status, approval_token, preview, arguments}` without executing. The gateway
+  then drives the decision through two control tools:
+  `dq.execute_action(approval_token)` and `dq.reject_action(approval_token)`.
+
+Reads are modelled as read-only tools (rather than static MCP resources) because
+a connector read takes query parameters from the agent; tools carry an input
+schema, so this is the faithful MCP mapping and keeps `dq.mutates` uniform
+across every capability.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from mcp import types
+from mcp.server.lowlevel import Server
+
+from ..action import ActionSpec
+from ..classification import DQ_CONNECTOR, DQ_KIND, DQ_MUTATES, CapabilityKind, meta_for
+from ..connector import Connector
+from ..resource import ResourceSpec
+
+# Names of the two control tools that drive the gated action lifecycle.
+EXECUTE_TOOL = "dq.execute_action"
+REJECT_TOOL = "dq.reject_action"
+
+_APPROVAL_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "approval_token": {"type": "string", "description": "Token returned when the action was requested."}
+    },
+    "required": ["approval_token"],
+}
+
+
+def _control_meta(connector_name: str, *, mutates: bool) -> dict[str, object]:
+    return {DQ_KIND: "control", DQ_MUTATES: mutates, DQ_CONNECTOR: connector_name}
+
+
+def build_tools(connector: Connector) -> list[types.Tool]:
+    """Build the MCP `Tool` list for a connector, with `dq.*` classification."""
+    tools: list[types.Tool] = []
+
+    for spec in connector.resources:
+        tools.append(
+            types.Tool(
+                name=spec.name,
+                description=spec.description,
+                inputSchema=spec.input_schema,
+                annotations=types.ToolAnnotations(readOnlyHint=True, destructiveHint=False),
+                _meta=meta_for(CapabilityKind.RESOURCE, connector.name),
+            )
+        )
+
+    for spec in connector.actions:
+        tools.append(
+            types.Tool(
+                name=spec.name,
+                description=spec.description,
+                inputSchema=spec.input_schema,
+                annotations=types.ToolAnnotations(readOnlyHint=False, destructiveHint=True),
+                _meta=meta_for(CapabilityKind.ACTION, connector.name),
+            )
+        )
+
+    # Control tools: only emitted when the connector has at least one action.
+    if connector.actions:
+        tools.append(
+            types.Tool(
+                name=EXECUTE_TOOL,
+                description="Execute a previously previewed action, after human approval, by its approval token.",
+                inputSchema=_APPROVAL_SCHEMA,
+                annotations=types.ToolAnnotations(readOnlyHint=False, destructiveHint=True),
+                _meta=_control_meta(connector.name, mutates=True),
+            )
+        )
+        tools.append(
+            types.Tool(
+                name=REJECT_TOOL,
+                description="Reject a previously previewed action by its approval token; it is never executed.",
+                inputSchema=_APPROVAL_SCHEMA,
+                annotations=types.ToolAnnotations(readOnlyHint=True, destructiveHint=False),
+                _meta=_control_meta(connector.name, mutates=False),
+            )
+        )
+
+    return tools
+
+
+def emit_server(connector: Connector) -> Server:
+    """Produce a low-level MCP `Server` backed by the connector."""
+    server: Server = Server(name=connector.name, version=connector.version)
+
+    resources_by_name: dict[str, ResourceSpec] = {s.name: s for s in connector.resources}
+    actions_by_name: dict[str, ActionSpec] = {s.name: s for s in connector.actions}
+
+    @server.list_tools()
+    async def _list_tools() -> list[types.Tool]:
+        return build_tools(connector)
+
+    @server.call_tool()
+    async def _call_tool(name: str, arguments: dict[str, Any]) -> Any:
+        args = arguments or {}
+
+        if name in resources_by_name:
+            records = connector.fetch_resource(name, args)
+            # Structured content: the provenance-wrapped records. The MCP layer
+            # also serialises this to JSON text in `content` for generic clients.
+            return {"records": [r.model_dump(mode="json") for r in records]}
+
+        if name in actions_by_name:
+            # Requesting an action previews it and mints a token; it does NOT run.
+            pending = connector.request_action(name, args)
+            return {
+                "status": "preview",
+                "action": pending.action_name,
+                "approval_token": pending.token,
+                "preview": pending.preview,
+                "arguments": pending.arguments,
+                "dq_mutates": True,
+                "next": {
+                    "approve": f"call {EXECUTE_TOOL} with this approval_token",
+                    "reject": f"call {REJECT_TOOL} with this approval_token",
+                },
+            }
+
+        if name == EXECUTE_TOOL:
+            token = args["approval_token"]
+            result = connector.execute_approved(token)
+            return {"status": "executed", "result": _jsonable(result)}
+
+        if name == REJECT_TOOL:
+            token = args["approval_token"]
+            pending = connector.reject_action(token)
+            return {"status": "rejected", "action": pending.action_name}
+
+        raise ValueError(f"unknown tool: {name!r}")
+
+    return server
+
+
+def _jsonable(value: Any) -> Any:
+    """Best-effort conversion of an execute() return into JSON-safe content."""
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    return value
+
+
+async def serve_stdio(connector: Connector) -> None:
+    """Serve the connector's MCP server over stdio (async)."""
+    from mcp.server.stdio import stdio_server
+
+    server = emit_server(connector)
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def run_stdio(connector: Connector) -> None:
+    """Blocking entry point: serve the connector over stdio until disconnected."""
+    import anyio
+
+    anyio.run(serve_stdio, connector)

deepquery_sdk/provenance.py

@@ -0,0 +1,65 @@
+"""Provenance contract — how live data stays citeable.
+
+Live connector data is never ingested or persisted. It enters an agent's
+context for a single query, gets cited, and is discarded. For that to preserve
+groundedness, every record a resource returns must carry enough provenance to
+build an honest, verifiable citation.
+
+See SDK_GUIDE.md §6.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+def now_iso() -> str:
+    """Current UTC time as an ISO 8601 string (the `retrieved_at` stamp)."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+class Provenance(BaseModel):
+    """The required envelope wrapping every record a resource returns.
+
+    `retrieved_at` is not decoration: a document citation is stable forever, but
+    a live citation is a snapshot of a moving target. The timestamp is what lets
+    an answer say "Jira DQ-431, status 'In Review', as of 2026-06-06 14:32" —
+    true at that instant and honest that it may not be true later.
+    """
+
+    connector_name: str = Field(..., description="Which connector produced this record.")
+    source_object_id: str = Field(..., description="Stable ID of the source object, e.g. 'DQ-431'.")
+    retrieved_at: str = Field(default_factory=now_iso, description="ISO 8601 retrieval timestamp.")
+    title_or_label: str = Field(..., description="Human-readable label for the citation.")
+    deep_link: str | None = Field(default=None, description="Direct URL to the source object, when available.")
+    mutability_note: str | None = Field(default=None, description="Hint that this data can change, e.g. 'live status field'.")
+
+
+class CitedRecord(BaseModel):
+    """A single record returned by a resource: the payload plus its provenance."""
+
+    data: Any = Field(..., description="The record payload the agent will read.")
+    provenance: Provenance
+
+
+def make_provenance(
+    *,
+    connector_name: str,
+    source_object_id: str,
+    title_or_label: str,
+    deep_link: str | None = None,
+    mutability_note: str | None = None,
+    retrieved_at: str | None = None,
+) -> Provenance:
+    """Build a `Provenance` envelope, stamping `retrieved_at` to now if omitted."""
+    return Provenance(
+        connector_name=connector_name,
+        source_object_id=source_object_id,
+        retrieved_at=retrieved_at or now_iso(),
+        title_or_label=title_or_label,
+        deep_link=deep_link,
+        mutability_note=mutability_note,
+    )

deepquery_sdk/resource.py

@@ -0,0 +1,65 @@
+"""Resource definitions — the read side of a connector.
+
+A resource is a read-only capability. It is declared with the `@resource`
+decorator on a method of a `Connector` subclass. Resources are exempt from the
+approval gate; the SDK enforces read-only classification structurally by giving
+reads and actions different decorators that cannot be confused.
+
+See SDK_GUIDE.md §4.2.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .classification import CapabilityKind
+
+# Marker attribute the Connector base class scans for at subclass-definition time.
+_RESOURCE_MARKER = "__dq_resource__"
+
+
+class ResourceSpec:
+    """Declarative metadata for one resource, attached to its fetch function."""
+
+    kind = CapabilityKind.RESOURCE
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        description: str,
+        input_schema: dict[str, Any],
+        attr_name: str,
+    ) -> None:
+        self.name = name
+        self.description = description
+        self.input_schema = input_schema
+        self.attr_name = attr_name  # method name on the connector, used to bind at emit time
+
+    def __repr__(self) -> str:  # pragma: no cover - debug aid
+        return f"ResourceSpec(name={self.name!r})"
+
+
+def resource(
+    *,
+    description: str,
+    name: str | None = None,
+    input_schema: dict[str, Any] | None = None,
+) -> Callable[[Callable], Callable]:
+    """Declare a read-only resource.
+
+    The decorated method runs the search/fetch and must return an iterable of
+    `CitedRecord` (use `self.cite(...)` to build them). The `description` is read
+    by the agent's planner, so it should explain in natural language when to use
+    this resource. (It is also a prompt-injection surface — see SDK_GUIDE.md §13.)
+    """
+
+    def deco(fn: Callable) -> Callable:
+        fn.__dq_resource__ = {
+            "name": name or fn.__name__,
+            "description": description,
+            "input_schema": input_schema or {"type": "object", "properties": {}},
+        }
+        return fn
+
+    return deco

deepquery_sdk/templates/connector/.gitignore.tmpl

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.pytest_cache/
+.env

deepquery_sdk/templates/connector/README.md.tmpl

@@ -0,0 +1,22 @@
+# __CONNECTOR_TITLE__ connector
+
+A Deep Query connector built with [DeepQuerySDK](https://deepquery.local/sdk).
+
+## Develop
+
+```bash
+deepquery validate connector.py     # check the safety contracts (§5, §6, §13)
+deepquery manifest connector.py     # print the connector manifest
+deepquery run-dev connector.py      # drive it with the mock agent locally
+deepquery emit connector.py --out dist/   # produce the deployable MCP server artifact
+```
+
+## What to fill in
+
+1. **Auth** — set the real endpoints/scopes (or switch strategy). Request the
+   minimum scopes you need.
+2. **`search`** — call your system's read API; wrap each record with `self.cite(...)`.
+3. **`do_thing`** — implement `preview` (describe the effect) and `execute` (perform it).
+
+Resources are read-only and ungated; actions always pass through
+preview → approve → execute. `validate` enforces both.