deepquery-sdk 1.0.0__py3-none-any.whl

deepquery_sdk/cli/commands.py

@@ -0,0 +1,208 @@
+"""Implementations of the `deepquery` CLI subcommands."""
+
+from __future__ import annotations
+
+import inspect
+import json
+import re
+import shutil
+from pathlib import Path
+
+from ..auth.base import Credential, static_credential_provider
+from ..validation import validate_connector
+from .loader import load_connector, load_connector_class
+
+_TEMPLATE_DIR = Path(__file__).resolve().parents[1] / "templates" / "connector"
+
+
+# --------------------------------------------------------------------------- #
+# scaffold
+# --------------------------------------------------------------------------- #
+def _class_name_from(name: str) -> str:
+    parts = re.split(r"[^0-9a-zA-Z]+", name)
+    cls = "".join(p[:1].upper() + p[1:] for p in parts if p)
+    if not cls or not cls[0].isalpha():
+        cls = "My" + cls
+    return cls + "Connector"
+
+
+def cmd_scaffold(args) -> int:
+    name = args.name
+    class_name = _class_name_from(name)
+    title = name.replace("_", " ").replace("-", " ").title()
+    out_dir = Path(args.dir) if args.dir else Path(name)
+    if out_dir.exists() and any(out_dir.iterdir()):
+        print(f"error: target directory '{out_dir}' already exists and is not empty")
+        return 1
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    subs = {
+        "__CONNECTOR_NAME__": name,
+        "__CLASS_NAME__": class_name,
+        "__CONNECTOR_TITLE__": title,
+    }
+    # Walk the template tree recursively, preserving subdirectories (e.g. tests/)
+    # and stripping the .tmpl suffix.
+    for tmpl in sorted(_TEMPLATE_DIR.rglob("*.tmpl")):
+        rel = tmpl.relative_to(_TEMPLATE_DIR).with_suffix("")  # drops .tmpl
+        dest = out_dir / rel
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        text = tmpl.read_text(encoding="utf-8")
+        for key, value in subs.items():
+            text = text.replace(key, value)
+        dest.write_text(text, encoding="utf-8")
+        print(f"  created {dest}")
+
+    print(f"\nScaffolded '{name}' ({class_name}) in {out_dir}/")
+    print(f"Next:  deepquery validate {out_dir / 'connector.py'}")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# validate
+# --------------------------------------------------------------------------- #
+def cmd_validate(args) -> int:
+    try:
+        connector = load_connector(args.target)
+    except Exception as exc:
+        # A connector that violates a structural contract may fail to import
+        # (e.g. an action with no preview raises at class definition). Report it.
+        print(f"FAIL  could not load connector: {exc}")
+        return 1
+    report = validate_connector(connector)
+    print(report.format())
+    return 0 if report.ok else 1
+
+
+# --------------------------------------------------------------------------- #
+# manifest
+# --------------------------------------------------------------------------- #
+def cmd_manifest(args) -> int:
+    connector = load_connector(args.target)
+    text = connector.build_manifest().to_json()
+    if args.out:
+        Path(args.out).write_text(text, encoding="utf-8")
+        print(f"wrote manifest to {args.out}")
+    else:
+        print(text)
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# emit
+# --------------------------------------------------------------------------- #
+_SERVER_TEMPLATE = '''"""Deployable MCP server for the {name} connector (emitted by DeepQuerySDK)."""
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+
+from {module} import {cls}
+from deepquery_sdk.mcp_emit import run_stdio
+
+if __name__ == "__main__":
+    # The gateway injects credentials at call time; wire your secret source here.
+    run_stdio({cls}())
+'''
+
+
+def cmd_emit(args) -> int:
+    cls = load_connector_class(args.target)
+    out_dir = Path(args.out)
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    # manifest.json
+    manifest_path = out_dir / "manifest.json"
+    manifest_path.write_text(cls().build_manifest().to_json(), encoding="utf-8")
+
+    # copy the connector source so the artifact is self-contained
+    src_file = inspect.getsourcefile(cls)
+    if src_file is None:
+        print("error: cannot locate connector source file to emit")
+        return 1
+    src_path = Path(src_file)
+    copied = out_dir / src_path.name
+    shutil.copyfile(src_path, copied)
+
+    # server entry point
+    server_path = out_dir / "server.py"
+    server_path.write_text(
+        _SERVER_TEMPLATE.format(name=cls().name, module=src_path.stem, cls=cls.__name__),
+        encoding="utf-8",
+    )
+
+    print(f"emitted MCP server artifact to {out_dir}/")
+    for p in (manifest_path, copied, server_path):
+        print(f"  {p}")
+    print(f"\nrun it:  python {server_path}")
+    return 0
+
+
+# --------------------------------------------------------------------------- #
+# run-dev
+# --------------------------------------------------------------------------- #
+def cmd_run_dev(args) -> int:
+    import anyio
+
+    connector = load_connector(args.target)
+    # Stand in for the gateway with a dev credential so actions can execute.
+    connector.set_credential_provider(static_credential_provider(Credential(token="dev-token")))
+    anyio.run(_run_dev_session, connector)
+    return 0
+
+
+def _parse_kv(pairs: list[str]) -> dict[str, str]:
+    args: dict[str, str] = {}
+    for pair in pairs:
+        if "=" in pair:
+            key, _, value = pair.partition("=")
+            args[key] = value
+    return args
+
+
+async def _run_dev_session(connector) -> None:
+    from ..harness import HarnessError, MockAgent
+
+    async with MockAgent(connector) as agent:
+        caps = await agent.capabilities()
+        print(f"\nconnected to '{connector.name}' via the mock agent. Capabilities:")
+        for group, entries in caps.items():
+            for e in entries:
+                print(f"  [{group[:-1]}] {e['name']}  (dq.mutates={e['dq.mutates']})")
+        print(
+            "\nCommands:\n"
+            "  read <name> key=value ...\n"
+            "  action <name> key=value ...   (you'll be asked to approve/reject)\n"
+            "  caps | quit\n"
+        )
+        while True:
+            try:
+                line = input("harness> ").strip()
+            except (EOFError, KeyboardInterrupt):
+                print()
+                return
+            if not line:
+                continue
+            parts = line.split()
+            cmd, rest = parts[0], parts[1:]
+            try:
+                if cmd in {"quit", "exit", "q"}:
+                    return
+                if cmd == "caps":
+                    print(json.dumps(await agent.capabilities(), indent=2))
+                elif cmd == "read" and rest:
+                    records = await agent.read(rest[0], **_parse_kv(rest[1:]))
+                    print(json.dumps(records, indent=2))
+                elif cmd == "action" and rest:
+                    preview = await agent.request_action(rest[0], **_parse_kv(rest[1:]))
+                    print(f"\nPREVIEW: {preview['preview']}")
+                    decision = input("approve? [y/N] ").strip().lower()
+                    if decision in {"y", "yes"}:
+                        print(json.dumps(await agent.approve(preview["approval_token"]), indent=2))
+                    else:
+                        print(json.dumps(await agent.reject(preview["approval_token"]), indent=2))
+                else:
+                    print("  unknown command")
+            except (HarnessError, KeyError, Exception) as exc:  # surface, don't crash
+                print(f"  error: {exc}")

deepquery_sdk/cli/loader.py

@@ -0,0 +1,95 @@
+"""Load a developer's `Connector` from a target spec, for the CLI.
+
+Accepted target forms:
+    module.path:ClassName     import a module and pick the class
+    module.path               import a module, find its single Connector
+    path/to/connector.py:Cls  load a file, pick the class
+    path/to/connector.py      load a file, find its single Connector
+    path/to/dir               load <dir>/connector.py, find its single Connector
+"""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import inspect
+import sys
+from pathlib import Path
+
+from ..connector import Connector
+
+
+class LoaderError(Exception):
+    pass
+
+
+def _load_file_module(path: Path):
+    path = path.resolve()
+    if not path.exists():
+        raise LoaderError(f"file not found: {path}")
+    # Make the file's directory importable so any sibling imports resolve.
+    sys.path.insert(0, str(path.parent))
+    mod_name = f"_dq_connector_{path.stem}"
+    spec = importlib.util.spec_from_file_location(mod_name, path)
+    if spec is None or spec.loader is None:
+        raise LoaderError(f"cannot load module from {path}")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[mod_name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+def _find_single_connector(module) -> type[Connector]:
+    candidates = [
+        obj
+        for _, obj in inspect.getmembers(module, inspect.isclass)
+        if issubclass(obj, Connector) and obj is not Connector and obj.__module__ == module.__name__
+    ]
+    if len(candidates) == 1:
+        return candidates[0]
+    if not candidates:
+        raise LoaderError(f"no Connector subclass found in {module.__name__!r}")
+    names = ", ".join(c.__name__ for c in candidates)
+    raise LoaderError(
+        f"multiple Connector subclasses in {module.__name__!r} ({names}); "
+        f"specify one with 'target:ClassName'."
+    )
+
+
+def load_connector_class(target: str) -> type[Connector]:
+    """Resolve a target spec to a Connector subclass."""
+    # Split a trailing ":ClassName" only when the suffix is a real identifier, so
+    # a Windows drive letter ("C:\\...") or a path is not mistaken for a class.
+    location, sep, classname = target.rpartition(":")
+    if not sep or not classname.isidentifier():
+        location, classname = target, ""
+
+    path = Path(location)
+    looks_like_path = location.endswith(".py") or path.exists() or "/" in location or "\\" in location
+
+    if looks_like_path:
+        if path.is_dir():
+            path = path / "connector.py"
+        module = _load_file_module(path)
+    else:
+        try:
+            module = importlib.import_module(location)
+        except ImportError as exc:
+            raise LoaderError(f"could not import module {location!r}: {exc}") from exc
+
+    if classname:
+        try:
+            cls = getattr(module, classname)
+        except AttributeError as exc:
+            raise LoaderError(f"{classname!r} not found in {location!r}") from exc
+    else:
+        cls = _find_single_connector(module)
+
+    if not (isinstance(cls, type) and issubclass(cls, Connector)):
+        raise LoaderError(f"{cls!r} is not a Connector subclass")
+    return cls
+
+
+def load_connector(target: str) -> Connector:
+    """Resolve a target spec to an instantiated Connector."""
+    return load_connector_class(target)()

deepquery_sdk/compat.py

@@ -0,0 +1,79 @@
+"""Versioning & compatibility contract (SDK_GUIDE.md §11).
+
+Connectors are semantically versioned and declare the SDK major version they
+target. The gateway refuses to load a connector built against an incompatible
+SDK major version — with a clear error, rather than failing mysteriously at call
+time. This module is that negotiation.
+
+Rules:
+- A connector targeting the same SDK major as the runtime is compatible.
+- A connector targeting a *newer* SDK major than the runtime is refused: the
+  deployment's SDK must be upgraded first.
+- A connector targeting an *older* SDK major is refused: the connector must be
+  upgraded to the current major (see MIGRATIONS.md).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from .manifest import SDK_MAJOR_VERSION, SDK_VERSION, Manifest
+
+_SEMVER = re.compile(r"^\d+\.\d+\.\d+([-+].+)?$")
+
+
+class IncompatibleConnectorError(Exception):
+    """Raised when a connector cannot be loaded against the running SDK."""
+
+
+@dataclass(frozen=True)
+class CompatibilityResult:
+    compatible: bool
+    reason: str
+    connector_sdk_major: int
+    runtime_sdk_major: int
+
+
+def is_valid_semver(version: str) -> bool:
+    return bool(_SEMVER.match(version or ""))
+
+
+def check_manifest_compatibility(
+    manifest: Manifest, *, runtime_sdk_major: int = SDK_MAJOR_VERSION
+) -> CompatibilityResult:
+    """Decide whether a connector manifest can be loaded by this SDK runtime."""
+    declared = manifest.sdk_major_version
+
+    if declared == runtime_sdk_major:
+        reason = (
+            f"connector '{manifest.name}' targets SDK major {declared}; "
+            f"runtime SDK is major {runtime_sdk_major} (v{SDK_VERSION}) — compatible."
+        )
+        return CompatibilityResult(True, reason, declared, runtime_sdk_major)
+
+    if declared > runtime_sdk_major:
+        reason = (
+            f"connector '{manifest.name}' targets SDK major {declared}, which is newer than "
+            f"this runtime's SDK major {runtime_sdk_major} (v{SDK_VERSION}). Upgrade the Deep "
+            f"Query SDK to load it."
+        )
+    else:
+        reason = (
+            f"connector '{manifest.name}' targets SDK major {declared}, which is older than "
+            f"this runtime's SDK major {runtime_sdk_major} (v{SDK_VERSION}). The connector must "
+            f"be upgraded to SDK major {runtime_sdk_major} (see MIGRATIONS.md)."
+        )
+    return CompatibilityResult(False, reason, declared, runtime_sdk_major)
+
+
+def assert_compatible(
+    manifest: Manifest, *, runtime_sdk_major: int = SDK_MAJOR_VERSION
+) -> None:
+    """Raise `IncompatibleConnectorError` if the connector cannot be loaded.
+
+    This is the check the Connector Gateway performs before loading a connector.
+    """
+    result = check_manifest_compatibility(manifest, runtime_sdk_major=runtime_sdk_major)
+    if not result.compatible:
+        raise IncompatibleConnectorError(result.reason)

deepquery_sdk/connector.py

@@ -0,0 +1,283 @@
+"""The base `Connector` class developers subclass.
+
+A connector declares three things (SDK_GUIDE.md §4): authentication, resources
+(reads), and actions (writes). This module collects the `@resource` and
+`@action` declarations off a subclass at definition time, enforces the
+structural safety contracts (every action has a preview), and exposes the
+collected capabilities to the `mcp_emit` layer and the manifest generator.
+"""
+
+from __future__ import annotations
+
+import contextvars
+from contextlib import contextmanager
+from typing import Any, Iterable, Iterator
+
+from .action import ActionSpec
+from .auth.base import AppliedAuth, AuthStrategy, Credential, CredentialError, CredentialProvider
+from .gate import ApprovalGate, PendingAction
+from .manifest import (
+    ActionManifest,
+    AuthMethod,
+    DeploymentCompat,
+    Manifest,
+    ResourceManifest,
+    SDK_MAJOR_VERSION,
+)
+from .provenance import CitedRecord, Provenance, make_provenance
+from .resource import ResourceSpec
+
+# Call-scoped credential: the gateway injects one before a tool call and the
+# connector reads it via `self.current_credential`. It is never stored on the
+# connector instance, so it cannot leak between calls or be persisted.
+_active_credential: contextvars.ContextVar[Credential | None] = contextvars.ContextVar(
+    "dq_active_credential", default=None
+)
+
+
+class ConnectorContractError(Exception):
+    """Raised when a connector subclass violates an SDK safety contract."""
+
+
+class Connector:
+    """Base class for all Deep Query connectors.
+
+    Subclasses set the class attributes below and declare capabilities with the
+    `@resource` and `@action` decorators.
+    """
+
+    # -- identity (override in subclasses) --------------------------------
+    name: str = ""
+    version: str = "0.0.0"
+    description: str = ""
+
+    # -- auth & deployment declaration ------------------------------------
+    # Either declare an AuthStrategy instance (preferred — carries scopes), or
+    # just the method enum for connectors with no outbound auth wiring yet.
+    auth: AuthStrategy | None = None
+    auth_method: AuthMethod = AuthMethod.NONE
+    auth_scopes: list[str] = []
+    requires_network: bool = True
+    air_gapped_capable: bool = False
+
+    # -- compatibility ----------------------------------------------------
+    sdk_major_version: int = SDK_MAJOR_VERSION
+
+    # populated by __init_subclass__
+    _resources: list[ResourceSpec]
+    _actions: list[ActionSpec]
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        cls._resources = list(cls._collect_resources())
+        cls._actions = list(cls._collect_actions())
+        cls._validate_contracts()
+
+    # -- collection -------------------------------------------------------
+    @classmethod
+    def _collect_resources(cls) -> Iterable[ResourceSpec]:
+        for attr_name in dir(cls):
+            obj = getattr(cls, attr_name, None)
+            meta = getattr(obj, "__dq_resource__", None)
+            if meta is not None:
+                yield ResourceSpec(
+                    name=meta["name"],
+                    description=meta["description"],
+                    input_schema=meta["input_schema"],
+                    attr_name=attr_name,
+                )
+
+    @classmethod
+    def _collect_actions(cls) -> Iterable[ActionSpec]:
+        seen: set[int] = set()
+        for attr_name in dir(cls):
+            obj = getattr(cls, attr_name, None)
+            if isinstance(obj, ActionSpec) and id(obj) not in seen:
+                seen.add(id(obj))
+                yield obj
+
+    @classmethod
+    def _validate_contracts(cls) -> None:
+        # An abstract base (no name) is allowed to be empty; concrete subclasses
+        # are checked structurally.
+        names: set[str] = set()
+        for spec in cls._resources:
+            if spec.name in names:
+                raise ConnectorContractError(f"duplicate capability name: {spec.name!r}")
+            names.add(spec.name)
+        for spec in cls._actions:
+            if not spec.has_preview():
+                raise ConnectorContractError(
+                    f"action {spec.name!r} has no preview; every action must declare a "
+                    f"preview (use @{spec.name}.preview). See SDK_GUIDE.md §4.3."
+                )
+            if spec.execute_fn is None:
+                raise ConnectorContractError(f"action {spec.name!r} has no execute function")
+            if spec.name in names:
+                raise ConnectorContractError(f"duplicate capability name: {spec.name!r}")
+            names.add(spec.name)
+
+    # -- provenance helper ------------------------------------------------
+    def cite(
+        self,
+        data: Any,
+        *,
+        source_object_id: str,
+        title_or_label: str,
+        deep_link: str | None = None,
+        mutability_note: str | None = None,
+    ) -> CitedRecord:
+        """Wrap a record in the provenance envelope (SDK_GUIDE.md §6).
+
+        Fills in `connector_name` and a fresh `retrieved_at` stamp automatically;
+        the developer supplies the source-specific citation fields.
+        """
+        prov = make_provenance(
+            connector_name=self.name,
+            source_object_id=source_object_id,
+            title_or_label=title_or_label,
+            deep_link=deep_link,
+            mutability_note=mutability_note,
+        )
+        return CitedRecord(data=data, provenance=prov)
+
+    # -- credential injection (SDK_GUIDE.md §7) ---------------------------
+    @property
+    def _gate(self) -> ApprovalGate:
+        gate = self.__dict__.get("_gate_instance")
+        if gate is None:
+            gate = self.__dict__["_gate_instance"] = ApprovalGate()
+        return gate
+
+    def set_credential_provider(self, provider: CredentialProvider | None) -> None:
+        """Register the gateway's per-call credential source. The connector never
+        stores the credential itself — only this provider reference."""
+        self.__dict__["_credential_provider"] = provider
+
+    @contextmanager
+    def _credential_scope(self) -> Iterator[None]:
+        """Activate the injected credential for the duration of one call."""
+        provider: CredentialProvider | None = self.__dict__.get("_credential_provider")
+        credential = provider() if provider is not None else None
+        token = _active_credential.set(credential)
+        try:
+            yield
+        finally:
+            _active_credential.reset(token)
+
+    @property
+    def current_credential(self) -> Credential:
+        """The credential injected for the current call. Raises outside a call,
+        or if the gateway injected none — credentials are never persisted."""
+        credential = _active_credential.get()
+        if credential is None:
+            raise CredentialError(
+                "no credential is active for this call; the gateway must inject one via "
+                "set_credential_provider(...). Credentials are never stored on the connector."
+            )
+        return credential
+
+    def apply_auth(self) -> AppliedAuth:
+        """Apply the declared auth strategy to the injected credential, yielding
+        the headers / client cert to attach to outbound requests."""
+        if self.auth is None:
+            raise CredentialError("connector declares no auth strategy (self.auth is None)")
+        return self.auth.apply(self.current_credential)
+
+    # -- gated action lifecycle (SDK_GUIDE.md §4.3, §5) -------------------
+    def _action_by_name(self, name: str) -> ActionSpec:
+        for spec in self.actions:
+            if spec.name == name:
+                return spec
+        raise KeyError(f"no such action: {name!r}")
+
+    def request_action(self, name: str, arguments: dict[str, Any]) -> PendingAction:
+        """Step 1: preview the action and mint a single-use approval token.
+        Does not execute."""
+        spec = self._action_by_name(name)
+        with self._credential_scope():
+            preview = self.preview_action(spec, arguments)
+        return self._gate.request(name, arguments, preview)
+
+    def execute_approved(self, token: str) -> Any:
+        """Step 2a (after human approval): run execute for the previewed args.
+        The token is consumed first so an action can never double-fire."""
+        pending = self._gate.get(token)
+        spec = self._action_by_name(pending.action_name)
+        self._gate.mark_executed(token)  # consume before running
+        with self._credential_scope():
+            return self.execute_action(spec, pending.arguments)
+
+    def reject_action(self, token: str) -> PendingAction:
+        """Step 2b (human rejection): discard the previewed action unexecuted."""
+        return self._gate.reject(token)
+
+    def fetch_resource(self, name: str, arguments: dict[str, Any]) -> list[CitedRecord]:
+        """Run a resource by name inside an active credential scope."""
+        spec = next((s for s in self.resources if s.name == name), None)
+        if spec is None:
+            raise KeyError(f"no such resource: {name!r}")
+        with self._credential_scope():
+            return self.run_resource(spec, arguments)
+
+    # -- introspection for the emitter ------------------------------------
+    @property
+    def resources(self) -> list[ResourceSpec]:
+        return type(self)._resources
+
+    @property
+    def actions(self) -> list[ActionSpec]:
+        return type(self)._actions
+
+    def run_resource(self, spec: ResourceSpec, arguments: dict[str, Any]) -> list[CitedRecord]:
+        """Invoke a resource's bound fetch method and normalise its output."""
+        bound = getattr(self, spec.attr_name)
+        result = bound(**arguments)
+        records = list(result) if result is not None else []
+        for r in records:
+            if not isinstance(r, CitedRecord):
+                raise ConnectorContractError(
+                    f"resource {spec.name!r} returned a {type(r).__name__}, expected CitedRecord; "
+                    f"use self.cite(...) to wrap each record."
+                )
+        return records
+
+    def preview_action(self, spec: ActionSpec, arguments: dict[str, Any]) -> str:
+        """Invoke an action's preview to describe what execute *would* do."""
+        assert spec.preview_fn is not None  # enforced by _validate_contracts
+        return spec.preview_fn(self, **arguments)
+
+    def execute_action(self, spec: ActionSpec, arguments: dict[str, Any]) -> Any:
+        """Invoke an action's execute. Only ever called after approval (Phase 2)."""
+        assert spec.execute_fn is not None  # enforced by _validate_contracts
+        return spec.execute_fn(self, **arguments)
+
+    # -- manifest ---------------------------------------------------------
+    @property
+    def effective_auth_method(self) -> AuthMethod:
+        return self.auth.method if self.auth is not None else self.auth_method
+
+    @property
+    def effective_auth_scopes(self) -> list[str]:
+        return list(self.auth.scopes) if self.auth is not None else list(self.auth_scopes)
+
+    def build_manifest(self) -> Manifest:
+        return Manifest(
+            name=self.name,
+            version=self.version,
+            description=self.description,
+            sdk_major_version=self.sdk_major_version,
+            auth_method=self.effective_auth_method,
+            auth_scopes=self.effective_auth_scopes,
+            resources=[
+                ResourceManifest(name=s.name, description=s.description) for s in self.resources
+            ],
+            actions=[
+                ActionManifest(name=s.name, description=s.description, has_preview=s.has_preview())
+                for s in self.actions
+            ],
+            deployment=DeploymentCompat(
+                requires_network=self.requires_network,
+                air_gapped_capable=self.air_gapped_capable,
+            ),
+        )