superdoc-sdk 1.0.0__py3-none-any.whl

superdoc/__init__.py

@@ -0,0 +1,28 @@
+from .client import AsyncSuperDocClient, AsyncSuperDocDocument, SuperDocClient, SuperDocDocument
+from .errors import SuperDocError
+from .skill_api import get_skill, install_skill, list_skills
+from .tools_api import (
+    choose_tools,
+    dispatch_superdoc_tool,
+    dispatch_superdoc_tool_async,
+    get_system_prompt,
+    get_tool_catalog,
+    list_tools,
+)
+
+__all__ = [
+    "SuperDocClient",
+    "AsyncSuperDocClient",
+    "SuperDocDocument",
+    "AsyncSuperDocDocument",
+    "SuperDocError",
+    "get_skill",
+    "install_skill",
+    "list_skills",
+    "get_tool_catalog",
+    "list_tools",
+    "choose_tools",
+    "dispatch_superdoc_tool",
+    "dispatch_superdoc_tool_async",
+    "get_system_prompt",
+]

superdoc/client.py

@@ -0,0 +1,424 @@
+"""SuperDoc client and document handle classes.
+
+The client manages transport lifecycle and acts as a document factory.
+Document handles bind a single open session and expose all document operations.
+
+    client = AsyncSuperDocClient(user={"name": "bot"})
+    await client.connect()
+    doc = await client.open({"doc": "path/to/file.docx"})
+    markdown = await doc.get_markdown()
+    await doc.close()
+    await client.dispose()
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Literal, Optional
+
+from .errors import SuperDocError
+from .generated.client import _AsyncDocApi, _SyncDocApi, _AsyncBoundDocApi, _SyncBoundDocApi
+from .runtime import SuperDocAsyncRuntime, SuperDocSyncRuntime
+
+UserIdentity = Dict[str, str]
+
+
+# ---------------------------------------------------------------------------
+# Session-bound runtime wrapper
+# ---------------------------------------------------------------------------
+
+class _BoundSyncRuntime:
+    """Wraps a raw runtime and injects a fixed sessionId into every invoke call."""
+
+    def __init__(self, runtime: SuperDocSyncRuntime, session_id: str) -> None:
+        self._runtime = runtime
+        self._session_id = session_id
+        self._closed = False
+
+    def invoke(
+        self,
+        operation_id: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Dict[str, Any]:
+        if self._closed:
+            raise SuperDocError(
+                'Document handle is closed.',
+                code='DOCUMENT_CLOSED',
+                details={'sessionId': self._session_id},
+            )
+        merged = {**(params or {}), 'sessionId': self._session_id}
+        return self._runtime.invoke(operation_id, merged, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+
+    def mark_closed(self) -> None:
+        self._closed = True
+
+
+class _BoundAsyncRuntime:
+    """Async version of _BoundSyncRuntime."""
+
+    def __init__(self, runtime: SuperDocAsyncRuntime, session_id: str) -> None:
+        self._runtime = runtime
+        self._session_id = session_id
+        self._closed = False
+
+    async def invoke(
+        self,
+        operation_id: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Dict[str, Any]:
+        if self._closed:
+            raise SuperDocError(
+                'Document handle is closed.',
+                code='DOCUMENT_CLOSED',
+                details={'sessionId': self._session_id},
+            )
+        merged = {**(params or {}), 'sessionId': self._session_id}
+        return await self._runtime.invoke(operation_id, merged, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+
+    def mark_closed(self) -> None:
+        self._closed = True
+
+
+# ---------------------------------------------------------------------------
+# Document handles
+# ---------------------------------------------------------------------------
+
+class SuperDocDocument:
+    """Bound document handle for synchronous workflows.
+
+    All document operations are available as methods on this handle.
+    The handle injects its session id automatically — callers never pass
+    doc or sessionId.
+    """
+
+    def __init__(
+        self,
+        bound_runtime: _BoundSyncRuntime,
+        session_id: str,
+        open_result: Dict[str, Any],
+        client: SuperDocClient,
+    ) -> None:
+        self._bound_runtime = bound_runtime
+        self._session_id = session_id
+        self._open_result = open_result
+        self._client = client
+        self._api = _SyncBoundDocApi(bound_runtime)
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    @property
+    def open_result(self) -> Dict[str, Any]:
+        """Read-only snapshot of the initial doc.open response metadata."""
+        return self._open_result
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._api, name)
+
+    def close(
+        self,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        result = self._bound_runtime.invoke(
+            'doc.close', params or {}, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes,
+        )
+        self._bound_runtime.mark_closed()
+        self._client._remove_handle(self._session_id)
+        return result
+
+    def save(
+        self,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        return self._bound_runtime.invoke(
+            'doc.save', params or {}, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes,
+        )
+
+    def mark_closed(self) -> None:
+        """Mark this handle as closed. Called by client.dispose()."""
+        self._bound_runtime.mark_closed()
+
+
+class AsyncSuperDocDocument:
+    """Bound document handle for asynchronous workflows.
+
+    All document operations are available as methods on this handle.
+    The handle injects its session id automatically — callers never pass
+    doc or sessionId.
+    """
+
+    def __init__(
+        self,
+        bound_runtime: _BoundAsyncRuntime,
+        session_id: str,
+        open_result: Dict[str, Any],
+        client: AsyncSuperDocClient,
+    ) -> None:
+        self._bound_runtime = bound_runtime
+        self._session_id = session_id
+        self._open_result = open_result
+        self._client = client
+        self._api = _AsyncBoundDocApi(bound_runtime)
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    @property
+    def open_result(self) -> Dict[str, Any]:
+        """Read-only snapshot of the initial doc.open response metadata."""
+        return self._open_result
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._api, name)
+
+    async def close(
+        self,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        result = await self._bound_runtime.invoke(
+            'doc.close', params or {}, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes,
+        )
+        self._bound_runtime.mark_closed()
+        self._client._remove_handle(self._session_id)
+        return result
+
+    async def save(
+        self,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        return await self._bound_runtime.invoke(
+            'doc.save', params or {}, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes,
+        )
+
+    def mark_closed(self) -> None:
+        """Mark this handle as closed. Called by client.dispose()."""
+        self._bound_runtime.mark_closed()
+
+
+# ---------------------------------------------------------------------------
+# Clients
+# ---------------------------------------------------------------------------
+
+class SuperDocClient:
+    """Synchronous SuperDoc client — transport manager and document factory.
+
+    Use client.open() to get bound document handles. Each handle is
+    independently session-scoped and safe for concurrent use.
+    """
+
+    def __init__(
+        self,
+        *,
+        env: dict[str, str] | None = None,
+        startup_timeout_ms: int = 5_000,
+        shutdown_timeout_ms: int = 5_000,
+        request_timeout_ms: int | None = None,
+        watchdog_timeout_ms: int = 30_000,
+        default_change_mode: Literal['direct', 'tracked'] | None = None,
+        user: UserIdentity | None = None,
+    ) -> None:
+        self._runtime = SuperDocSyncRuntime(
+            env=env,
+            startup_timeout_ms=startup_timeout_ms,
+            shutdown_timeout_ms=shutdown_timeout_ms,
+            request_timeout_ms=request_timeout_ms,
+            watchdog_timeout_ms=watchdog_timeout_ms,
+            default_change_mode=default_change_mode,
+            user=user,
+        )
+        self._raw_api = _SyncDocApi(self._runtime)
+        self._handles: Dict[str, SuperDocDocument] = {}
+
+    def connect(self) -> None:
+        """Explicitly connect to the host process.
+
+        Optional — the first invoke() call will auto-connect if needed.
+        """
+        self._runtime.connect()
+
+    def open(
+        self,
+        params: Dict[str, Any],
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> SuperDocDocument:
+        """Open a document and return a bound document handle.
+
+        The returned handle injects its session id into every operation
+        automatically. The same file can be opened multiple times with
+        different session ids (useful for diff workflows).
+        """
+        explicit_session_id = params.get('sessionId')
+        if explicit_session_id and explicit_session_id in self._handles:
+            raise SuperDocError(
+                f'Session id already open in this client: {explicit_session_id}',
+                code='SESSION_ALREADY_OPEN',
+                details={'sessionId': explicit_session_id},
+            )
+
+        result = self._raw_api.open(params, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+        context_id = result.get('contextId', '')
+
+        bound = _BoundSyncRuntime(self._runtime, context_id)
+        handle = SuperDocDocument(bound, context_id, result, self)
+        self._handles[context_id] = handle
+        return handle
+
+    def describe(
+        self,
+        params: Dict[str, Any] | None = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        return self._raw_api.describe(params, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+
+    def describe_command(
+        self,
+        params: Dict[str, Any] | None = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        return self._raw_api.describe_command(params, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+
+    def dispose(self) -> None:
+        """Gracefully shut down the host process and invalidate all open handles."""
+        for handle in self._handles.values():
+            handle.mark_closed()
+        self._handles.clear()
+        self._runtime.dispose()
+
+    def _remove_handle(self, session_id: str) -> None:
+        self._handles.pop(session_id, None)
+
+    def __enter__(self) -> SuperDocClient:
+        self.connect()
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.dispose()
+
+
+class AsyncSuperDocClient:
+    """Asynchronous SuperDoc client — transport manager and document factory.
+
+    Use client.open() to get bound document handles. Each handle is
+    independently session-scoped and safe for concurrent use.
+    """
+
+    def __init__(
+        self,
+        *,
+        env: dict[str, str] | None = None,
+        startup_timeout_ms: int = 5_000,
+        shutdown_timeout_ms: int = 5_000,
+        request_timeout_ms: int | None = None,
+        watchdog_timeout_ms: int = 30_000,
+        max_queue_depth: int = 100,
+        default_change_mode: Literal['direct', 'tracked'] | None = None,
+        user: UserIdentity | None = None,
+    ) -> None:
+        self._runtime = SuperDocAsyncRuntime(
+            env=env,
+            startup_timeout_ms=startup_timeout_ms,
+            shutdown_timeout_ms=shutdown_timeout_ms,
+            request_timeout_ms=request_timeout_ms,
+            watchdog_timeout_ms=watchdog_timeout_ms,
+            max_queue_depth=max_queue_depth,
+            default_change_mode=default_change_mode,
+            user=user,
+        )
+        self._raw_api = _AsyncDocApi(self._runtime)
+        self._handles: Dict[str, AsyncSuperDocDocument] = {}
+
+    async def connect(self) -> None:
+        """Explicitly connect to the host process.
+
+        Optional — the first invoke() call will auto-connect if needed.
+        """
+        await self._runtime.connect()
+
+    async def open(
+        self,
+        params: Dict[str, Any],
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> AsyncSuperDocDocument:
+        """Open a document and return a bound document handle.
+
+        The returned handle injects its session id into every operation
+        automatically. The same file can be opened multiple times with
+        different session ids (useful for diff workflows).
+        """
+        explicit_session_id = params.get('sessionId')
+        if explicit_session_id and explicit_session_id in self._handles:
+            raise SuperDocError(
+                f'Session id already open in this client: {explicit_session_id}',
+                code='SESSION_ALREADY_OPEN',
+                details={'sessionId': explicit_session_id},
+            )
+
+        result = await self._raw_api.open(params, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+        context_id = result.get('contextId', '')
+
+        bound = _BoundAsyncRuntime(self._runtime, context_id)
+        handle = AsyncSuperDocDocument(bound, context_id, result, self)
+        self._handles[context_id] = handle
+        return handle
+
+    async def describe(
+        self,
+        params: Dict[str, Any] | None = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        return await self._raw_api.describe(params, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+
+    async def describe_command(
+        self,
+        params: Dict[str, Any] | None = None,
+        *,
+        timeout_ms: Optional[int] = None,
+        stdin_bytes: Optional[bytes] = None,
+    ) -> Any:
+        return await self._raw_api.describe_command(params, timeout_ms=timeout_ms, stdin_bytes=stdin_bytes)
+
+    async def dispose(self) -> None:
+        """Gracefully shut down the host process and invalidate all open handles."""
+        for handle in self._handles.values():
+            handle.mark_closed()
+        self._handles.clear()
+        await self._runtime.dispose()
+
+    def _remove_handle(self, session_id: str) -> None:
+        self._handles.pop(session_id, None)
+
+    async def __aenter__(self) -> AsyncSuperDocClient:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.dispose()

superdoc/embedded_cli.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+import os
+import platform
+from importlib import resources
+from pathlib import Path
+from typing import Optional
+
+from .errors import SuperDocError
+
+
+# Maps target triple → companion package module name.
+_TARGET_TO_COMPANION_MODULE = {
+    'darwin-arm64': 'superdoc_sdk_cli_darwin_arm64',
+    'darwin-x64': 'superdoc_sdk_cli_darwin_x64',
+    'linux-x64': 'superdoc_sdk_cli_linux_x64',
+    'linux-arm64': 'superdoc_sdk_cli_linux_arm64',
+    'windows-x64': 'superdoc_sdk_cli_windows_x64',
+}
+
+
+def _normalized_machine(value: str) -> str:
+    normalized = value.strip().lower()
+    if normalized in {'x86_64', 'amd64'}:
+        return 'x64'
+    if normalized in {'aarch64', 'arm64'}:
+        return 'arm64'
+    return normalized
+
+
+def _resolve_target() -> Optional[str]:
+    system = platform.system().lower()
+    machine = _normalized_machine(platform.machine())
+
+    if system == 'darwin' and machine == 'arm64':
+        return 'darwin-arm64'
+    if system == 'darwin' and machine == 'x64':
+        return 'darwin-x64'
+    if system == 'linux' and machine == 'x64':
+        return 'linux-x64'
+    if system == 'linux' and machine == 'arm64':
+        return 'linux-arm64'
+    if system == 'windows' and machine == 'x64':
+        return 'windows-x64'
+
+    return None
+
+
+def _resolve_binary_name(target: str) -> str:
+    return 'superdoc.exe' if target.startswith('windows-') else 'superdoc'
+
+
+def _resolve_from_companion_package(target: str) -> Optional[str]:
+    """Try #1: import the installed platform companion package."""
+    module_name = _TARGET_TO_COMPANION_MODULE.get(target)
+    if not module_name:
+        return None
+    try:
+        module = __import__(module_name)
+        return module.get_binary_path()
+    except (ImportError, FileNotFoundError):
+        return None
+
+
+def _resolve_from_vendor_fallback(target: str) -> Optional[str]:
+    """Try #2: legacy _vendor/cli/ path (source/dev environments only).
+
+    This path only exists when running from a source checkout with
+    manually staged binaries — it is NOT shipped in published wheels.
+    """
+    binary_name = _resolve_binary_name(target)
+    resource = resources.files('superdoc').joinpath('_vendor', 'cli', target, binary_name)
+    try:
+        candidate = Path(str(resource))
+    except Exception:
+        return None
+    return str(candidate) if candidate.exists() else None
+
+
+def resolve_embedded_cli_path() -> str:
+    target = _resolve_target()
+    if target is None:
+        raise SuperDocError(
+            'No embedded SuperDoc CLI binary is available for this platform.',
+            code='UNSUPPORTED_PLATFORM',
+            details={'platform': platform.system(), 'machine': platform.machine()},
+        )
+
+    # Companion package (primary — used in published wheels)
+    path = _resolve_from_companion_package(target)
+
+    # Legacy vendor fallback (source/dev only — not shipped in wheels)
+    if path is None:
+        path = _resolve_from_vendor_fallback(target)
+
+    if path is None:
+        raise SuperDocError(
+            f'Embedded SuperDoc CLI binary is missing for this platform.\n'
+            f'Install the companion package: pip install superdoc-sdk-cli-{target}\n'
+            f'Or set SUPERDOC_CLI_BIN to a compatible superdoc binary path.',
+            code='CLI_BINARY_MISSING',
+            details={'target': target},
+        )
+
+    # Ensure binary is executable on unix
+    if os.name != 'nt':
+        try:
+            mode = os.stat(path).st_mode
+            os.chmod(path, mode | 0o111)
+        except Exception:
+            pass
+
+    return path

superdoc/errors.py

@@ -0,0 +1,19 @@
+"""SuperDoc SDK error types and host transport error codes."""
+
+# Host transport error codes — used by transport.py and protocol.py.
+HOST_DISCONNECTED = 'HOST_DISCONNECTED'
+HOST_TIMEOUT = 'HOST_TIMEOUT'
+HOST_QUEUE_FULL = 'HOST_QUEUE_FULL'
+HOST_HANDSHAKE_FAILED = 'HOST_HANDSHAKE_FAILED'
+HOST_PROTOCOL_ERROR = 'HOST_PROTOCOL_ERROR'
+
+# JSON-RPC error code emitted by the CLI for operation timeouts.
+JSON_RPC_TIMEOUT_CODE = -32011
+
+
+class SuperDocError(Exception):
+    def __init__(self, message: str, code: str, details=None, exit_code=None):
+        super().__init__(message)
+        self.code = code
+        self.details = details
+        self.exit_code = exit_code

superdoc/generated/__init__.py

@@ -0,0 +1,2 @@
+from .client import _SyncDocApi, _AsyncDocApi
+from .client import _SyncBoundDocApi, _AsyncBoundDocApi