svo-client-dev 4.0.21__py3-none-any.whl

svo_client/core.py

@@ -0,0 +1,330 @@
+"""
+Core: adapter client. Schema/help from server, list commands, direct call.
+
+Uses mcp_proxy_adapter JsonRpcClient. With
+``execute_command_unified(..., auto_poll=True)`` (default in
+:meth:`ClientCore.call`), the adapter opens a command session and waits for
+completion on WebSocket ``/ws``. The server runs non-queued commands in process
+and queued commands in an isolated worker; both return the same client shape.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import asyncio
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+from svo_client.aiohttp_ws_max_message import apply_aiohttp_ws_max_message_patch
+
+apply_aiohttp_ws_max_message_patch()
+
+from mcp_proxy_adapter.client.jsonrpc_client import JsonRpcClient  # noqa: E402
+
+from svo_client.exceptions import (  # noqa: E402
+    SvoConnectionError,
+    SvoTimeoutError,
+    SvoValidationError,
+)
+from svo_client.transfer_precheck import (  # noqa: E402
+    declared_download_size_bytes,
+    ensure_local_free_space_for_download,
+)
+
+# httpx requires a finite timeout; match mcp_proxy_adapter resolve_timeout_strict
+# fallback when command timeout is disabled (no arbitrary 60s ceiling).
+_JSONRPC_HTTP_NO_CEILING_SEC = 21_600_000.0
+
+
+def _normalize_unified_command_response(resp: Any) -> Any:
+    """
+    Map JSON-RPC top-level ``error`` (e.g. -32602 Invalid params) into the same
+    in-band shape as ``result: {success: false, error: {...}}`` for callers that
+    expect a unified dict (queued chunk validation failures).
+    """
+    if not isinstance(resp, dict) or "error" not in resp:
+        return resp
+    if "result" in resp:
+        err = resp.get("error")
+        if isinstance(err, dict):
+            out = dict(resp)
+            out["result"] = {"success": False, "error": err}
+            return out
+        return resp
+    err = resp.get("error")
+    if not isinstance(err, dict):
+        return resp
+    out = dict(resp)
+    out["result"] = {"success": False, "error": err}
+    return out
+
+
+def _resolve_cert_path(path: Optional[str], base_dir: Optional[Path]) -> Optional[str]:
+    if not path:
+        return None
+    p = Path(path)
+    if base_dir and not p.is_absolute():
+        return str(base_dir / p)
+    return path
+
+
+class ClientCore:
+    """
+    Core: adapter client. get_help, list_commands, call(command_name, params).
+    """
+
+    def __init__(
+        self,
+        protocol: str = "mtls",
+        host: str = "127.0.0.1",
+        port: int = 8009,
+        token_header: Optional[str] = None,
+        token: Optional[str] = None,
+        cert: Optional[str] = None,
+        key: Optional[str] = None,
+        ca: Optional[str] = None,
+        check_hostname: bool = False,
+        timeout: Optional[float] = 300.0,
+        certs_dir: Optional[str] = None,
+    ):
+        base = Path(certs_dir) if certs_dir else None
+        cert_path = _resolve_cert_path(cert, base)
+        key_path = _resolve_cert_path(key, base)
+        ca_path = _resolve_cert_path(ca, base)
+        default_http = 60.0 if protocol in ("https", "mtls") else 30.0
+        # None or 0 = no command timeout (wait until completion)
+        self.timeout = None if timeout is None or timeout == 0 else timeout
+        # HTTP client must not expire before a long JSON-RPC response; align with
+        # mcp_proxy_adapter "no timeout" ceiling when command timeout is disabled.
+        if self.timeout is None:
+            http_timeout = _JSONRPC_HTTP_NO_CEILING_SEC
+        else:
+            http_timeout = max(default_http, float(self.timeout))
+
+        self._client: JsonRpcClient = JsonRpcClient(
+            protocol=protocol,
+            host=host,
+            port=port,
+            token_header=token_header,
+            token=token,
+            cert=cert_path,
+            key=key_path,
+            ca=ca_path,
+            check_hostname=check_hostname,
+            timeout=http_timeout,
+        )
+        # region agent log
+        from svo_client.debug_ndjson import agent_debug_log
+
+        agent_debug_log(
+            "H1",
+            "svo_client/core.py:ClientCore.__init__",
+            "JsonRpcClient constructed",
+            {
+                "protocol": protocol,
+                "host": host,
+                "port": port,
+                "has_client_cert": bool(cert_path),
+                "has_client_key": bool(key_path),
+                "has_ca": bool(ca_path),
+                "jsonrpc_http_timeout_sec": http_timeout,
+                "execute_command_unified_timeout": self.timeout,
+                "adapter_ws_wait_timeout_passed": (
+                    0 if self.timeout is None else self.timeout
+                ),
+            },
+        )
+        # endregion
+
+    async def get_help(self, command_name: Optional[str] = None) -> Dict[str, Any]:
+        try:
+            return await self._client.help(command_name=command_name)
+        except Exception as e:
+            raise SvoConnectionError(f"Help failed: {e}") from e
+
+    def _help_data(self, help_result: Dict[str, Any]) -> Dict[str, Any]:
+        if not isinstance(help_result, dict):
+            return {}
+        return help_result.get("data", help_result)
+
+    async def list_commands(self) -> List[str]:
+        help_result = await self.get_help()
+        data = self._help_data(help_result)
+        commands = data.get("commands", {})
+        if isinstance(commands, dict):
+            return sorted(commands.keys())
+        if isinstance(commands, list):
+            return sorted(c for c in commands if isinstance(c, str))
+        return []
+
+    async def get_command_info(self, command_name: str) -> Optional[Dict[str, Any]]:
+        help_result = await self.get_help(command_name=command_name)
+        data = self._help_data(help_result)
+        if not data:
+            return None
+        if data.get("name") or data.get("schema"):
+            return data
+        commands = data.get("commands", {})
+        if isinstance(commands, dict) and command_name in commands:
+            return commands[command_name]
+        return None
+
+    async def call(
+        self,
+        command_name: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        status_hook: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None,
+    ) -> Dict[str, Any]:
+        """Execute command; completion and result via WebSocket when ``job_id`` is returned.
+
+        Matches adapter queue semantics (including post-sync-cap handoff to the
+        queue): the initial response may be a minimal queue envelope; the adapter
+        still completes the job over ``/ws`` when *auto_poll* is enabled inside
+        ``execute_command_unified``.
+
+        Optional *status_hook* is forwarded to the adapter's
+        ``execute_command_unified`` (invoked for the initial queue response and each
+        inbound WebSocket message while waiting for the terminal job event). Hooks
+        may observe fields such as ``queued_after_timeout`` if the server includes them.
+        """
+        try:
+            # Adapter maps None -> default 60s WS wait; 0 means no timeout (see
+            # mcp_proxy_adapter execute_command_unified / wait_for_job_via_websocket).
+            adapter_timeout = 0 if self.timeout is None else self.timeout
+            raw = await self._client.execute_command_unified(
+                command=command_name,
+                params=params or {},
+                auto_poll=True,  # adapter waits via WebSocket for job_id, no HTTP polling
+                timeout=adapter_timeout,
+                status_hook=status_hook,
+            )
+            return _normalize_unified_command_response(raw)
+        except asyncio.TimeoutError as e:
+            msg = (
+                f"Command '{command_name}' timed out (no completion within {self.timeout}s)"
+                if self.timeout is not None
+                else f"Command '{command_name}' timed out"
+            )
+            raise SvoTimeoutError(msg) from e
+        except Exception as e:
+            # region agent log
+            from svo_client.debug_ndjson import agent_debug_log
+
+            cause = getattr(e, "__cause__", None)
+            agent_debug_log(
+                "H3",
+                "svo_client/core.py:ClientCore.call",
+                "execute_command_unified failed",
+                {
+                    "command_name": command_name,
+                    "exc_type": type(e).__name__,
+                    "exc_repr": repr(e),
+                    "cause_type": type(cause).__name__ if cause is not None else None,
+                    "cause_repr": repr(cause) if cause is not None else None,
+                },
+            )
+            # endregion
+            raise SvoConnectionError(
+                f"Command '{command_name}' failed: {e}", remote_error=e
+            ) from e
+
+    async def health(self) -> Dict[str, Any]:
+        try:
+            return await self._client.health()
+        except Exception as e:
+            raise SvoConnectionError(f"Health check failed: {e}") from e
+
+    async def get_openapi_schema(self) -> Dict[str, Any]:
+        """Fetch ``/openapi.json`` via the same adapter transport as JSON-RPC."""
+        try:
+            return await self._client.get_openapi_schema()
+        except Exception as e:
+            raise SvoConnectionError(f"OpenAPI schema fetch failed: {e}") from e
+
+    async def download_transfer_to_path(
+        self,
+        transfer_id: str,
+        destination_path: str,
+        *,
+        acknowledge_after_download: bool = True,
+    ) -> Any:
+        """Download an outbound artifact by adapter transfer id.
+
+        Before starting the download, loads the declared ``size_bytes`` from
+        ``get_download_session`` and refuses to call ``download_file`` if the
+        destination parent directory has insufficient free space (g1).
+
+        After a successful ``download_file``, calls JSON-RPC ``transfer_ack`` with
+        the receipt digest so the adapter can mark the session consumed and, when
+        the download session was created with ``delete_source_on_ack``, remove the
+        staged source file (g1 / t3 atomic 05).
+        """
+        try:
+            need = await declared_download_size_bytes(self._client, transfer_id)
+            ensure_local_free_space_for_download(
+                destination_path=destination_path,
+                declared_size_bytes=need,
+            )
+        except SvoValidationError:
+            raise
+        try:
+            receipt = await self._client.download_file(transfer_id, destination_path)
+        except Exception as e:
+            raise SvoConnectionError(f"Download failed: {e}") from e
+        if acknowledge_after_download:
+            await self._acknowledge_outbound_download(receipt)
+        return receipt
+
+    async def _acknowledge_outbound_download(self, receipt: Any) -> None:
+        """Post-download ``transfer_ack`` via the same JsonRpcClient (adapter JSON-RPC)."""
+        tid = getattr(receipt, "transfer_id", None)
+        algo = getattr(receipt, "checksum_algorithm", None) or "sha256"
+        digest = getattr(receipt, "checksum_value", None)
+        if not isinstance(tid, str) or not tid.strip():
+            raise SvoConnectionError(
+                "Download receipt missing transfer_id; cannot transfer_ack"
+            )
+        if not isinstance(digest, str) or not digest.strip():
+            raise SvoConnectionError(
+                "Download receipt missing checksum_value; cannot transfer_ack"
+            )
+        params: Dict[str, Any] = {
+            "transfer_id": tid.strip(),
+            "checksum_algorithm": str(algo).strip().lower(),
+            "checksum_value": digest.strip().lower(),
+        }
+        try:
+            response = await self._client.jsonrpc_call("transfer_ack", params)
+        except Exception as e:
+            raise SvoConnectionError(f"transfer_ack failed: {e}") from e
+        if isinstance(response, dict) and response.get("error") is not None:
+            err = response["error"]
+            msg = (
+                err.get("message", "transfer_ack error")
+                if isinstance(err, dict)
+                else str(err)
+            )
+            raise SvoConnectionError(f"transfer_ack failed: {msg}")
+        data = response.get("result") if isinstance(response, dict) else None
+        if not isinstance(data, dict) or not data.get("success"):
+            raise SvoConnectionError("transfer_ack did not return success")
+
+    def open_ws_channel(
+        self,
+        receive_timeout: float = 60.0,
+        heartbeat: float = 30.0,
+    ):
+        from mcp_proxy_adapter.client.jsonrpc_client import (
+            open_bidirectional_ws_channel,
+        )
+
+        return open_bidirectional_ws_channel(
+            self._client,
+            receive_timeout=receive_timeout,
+            heartbeat=heartbeat,
+        )
+
+    @property
+    def adapter_client(self) -> JsonRpcClient:
+        return self._client

svo_client/debug_ndjson.py

@@ -0,0 +1,14 @@
+"""Optional NDJSON debug hook for agent instrumentation; no-op by default."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def agent_debug_log(
+    _hypothesis_id: str,
+    _location: str,
+    _message: str,
+    _data: dict[str, Any],
+) -> None:
+    """No-op unless debug instrumentation replaces this hook."""

svo_client/exceptions.py

@@ -0,0 +1,48 @@
+"""
+Exceptions for SVO Chunker client.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+
+class SvoClientError(Exception):
+    """Base exception for SVO client errors."""
+
+
+class SvoConnectionError(SvoClientError):
+    """Raised when connection to server or WebSocket fails."""
+
+    def __init__(self, message, *, remote_error=None):
+        super().__init__(message)
+        self.remote_error = remote_error
+        self.details = getattr(remote_error, "details", None)
+        self.error = getattr(remote_error, "error", None)
+        self.code = (
+            self.details.get("code")
+            if isinstance(self.details, dict) and "code" in self.details
+            else getattr(remote_error, "code", None)
+        )
+        self.data = (
+            self.details.get("data") if isinstance(self.details, dict) else None
+        )
+
+
+class SvoTimeoutError(SvoClientError):
+    """Raised when request or WebSocket wait times out."""
+
+
+class SvoValidationError(SvoClientError):
+    """Raised when request validation fails."""
+
+
+class SvoChunkingError(SvoClientError):
+    """Raised when chunking operation fails."""
+
+    def __init__(self, message, *, error=None):
+        super().__init__(message)
+        self.error = error
+        self.code = error.get("code") if isinstance(error, dict) else None
+        self.details = (
+            error.get("details", error.get("data")) if isinstance(error, dict) else None
+        )

svo_client/file_processor.py

@@ -0,0 +1,58 @@
+"""
+File processing helpers for SVO Chunker client.
+
+Canonical path: single server ``file_chunk`` RPC via :func:`process_file_via_file_chunk`.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from typing import Any, Dict, Optional
+
+from svo_client.client import (
+    SvoChunkerClient,
+    build_file_chunk_params,
+)
+
+
+async def process_file_via_file_chunk(
+    client: SvoChunkerClient,
+    *,
+    filepath: Optional[str] = None,
+    filename: Optional[str] = None,
+    file_content_base64: Optional[str] = None,
+    transfer_id: Optional[str] = None,
+    filter_name: Optional[str] = None,
+    window: int = 3,
+    chunk_type: Optional[str] = None,
+    language: Optional[str] = None,
+    source_id: Optional[str] = None,
+    project: Optional[str] = None,
+    unit_id: Optional[str] = None,
+    chunking_version: str = "1.0",
+    use_sv: bool = False,
+    aggregation_mode: Optional[str] = None,
+    respect_structural_blocks: Optional[bool] = None,
+    chunk_set: Optional[str] = None,
+    download_path: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Call server ``file_chunk`` with built parameters (single RPC, optional download)."""
+    params = build_file_chunk_params(
+        filepath=filepath,
+        filename=filename,
+        file_content_base64=file_content_base64,
+        transfer_id=transfer_id,
+        filter_name=filter_name,
+        window=window,
+        chunk_type=chunk_type,
+        language=language,
+        source_id=source_id,
+        project=project,
+        unit_id=unit_id,
+        chunking_version=chunking_version,
+        use_sv=use_sv,
+        aggregation_mode=aggregation_mode,
+        respect_structural_blocks=respect_structural_blocks,
+        chunk_set=chunk_set,
+    )
+    return await client.file_chunk(params, download_path=download_path)

svo_client/transfer_precheck.py

@@ -0,0 +1,91 @@
+"""Declared transfer size and local free-space checks before adapter download.
+
+g1: the receiving side must not start the HTTP download if free space is insufficient.
+Uses the adapter ``get_download_session`` response (``size_bytes``) and
+``shutil.disk_usage`` on the destination file's parent directory.
+
+Server-side preflight toward the vectorization service is not implemented in this
+repository; that remains the embedding/adapter stack's responsibility when it exposes
+a comparable hook.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any, Mapping, Optional, Union
+
+
+def coerce_transfer_size_bytes(raw: Any) -> int:
+    """Parse ``size_bytes`` from a transfer session payload (int or decimal string)."""
+    if isinstance(raw, bool) or raw is None:
+        return 0
+    if isinstance(raw, int):
+        return raw if raw > 0 else 0
+    if isinstance(raw, str):
+        s = raw.strip()
+        if not s:
+            return 0
+        try:
+            v = int(s, 10)
+        except ValueError:
+            return 0
+        return v if v > 0 else 0
+    return 0
+
+
+def free_bytes_for_path(destination_path: Union[str, Path]) -> int:
+    """Free space on the filesystem that will hold *destination_path* (parent directory)."""
+    p = Path(destination_path).expanduser()
+    try:
+        parent = p.resolve().parent
+    except OSError:
+        parent = p.parent
+    usage = shutil.disk_usage(str(parent))
+    return int(usage.free)
+
+
+def ensure_local_free_space_for_download(
+    *,
+    destination_path: Union[str, Path],
+    declared_size_bytes: Optional[int],
+) -> None:
+    """Raise ``SvoValidationError`` if the parent dir has less free space than declared.
+
+    Conservative: requires ``free >= declared_size_bytes`` (no partial existing-file
+    accounting). g1: a positive declared size from the transfer session is required
+    before starting the download; missing, zero, or negative values fail closed.
+    """
+    from svo_client.exceptions import SvoValidationError
+
+    if declared_size_bytes is None or declared_size_bytes < 1:
+        raise SvoValidationError(
+            "Declared transfer size is missing or invalid; cannot verify free space "
+            "before download (g1). get_download_session must return a positive "
+            "size_bytes."
+        )
+    free = free_bytes_for_path(destination_path)
+    if free < declared_size_bytes:
+        dest = Path(destination_path).expanduser()
+        raise SvoValidationError(
+            "Insufficient disk space for declared transfer size: "
+            f"need {declared_size_bytes} bytes, "
+            f"available {free} bytes on filesystem for {dest.parent}"
+        )
+
+
+async def declared_download_size_bytes(
+    adapter_client: Any,
+    transfer_id: str,
+) -> int:
+    """Return declared ``size_bytes`` from ``JsonRpcClient.get_download_session``."""
+    get_session = getattr(adapter_client, "get_download_session", None)
+    if not callable(get_session):
+        return 0
+    data = await get_session(transfer_id)
+    if not isinstance(data, Mapping):
+        return 0
+    return coerce_transfer_size_bytes(data.get("size_bytes"))