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

svo_client/client.py

@@ -0,0 +1,1104 @@
+"""
+Asynchronous SVO Chunker client. All network I/O goes only through
+``mcp_proxy_adapter.client.jsonrpc_client.JsonRpcClient`` (no ad-hoc HTTP
+clients in this package).
+
+Commands use ``execute_command_unified(..., auto_poll=True)``: the adapter
+delivers command-session completion on WebSocket ``/ws``. JSON-RPC submission
+and binary artifact fetch (e.g. outbound JSON after ``file_chunk``) use the
+adapter's HTTP(S) transport.
+
+This package does **not** call the embedding / vectorization HTTP API
+(``embed_client``) directly; vectorization runs inside the chunker service,
+which uses embed-client's in-process execute_async/WebSocket completion path.
+With mcp-proxy-adapter **>= 8.10**, queued commands still return a ``job_id``
+and the client receives their full results after WebSocket completion.
+
+chunk(texts) calls server method "chunk" (list of texts in, list of results out).
+``chunk`` runs in the server process; the long-running ``file_chunk`` command
+uses an isolated queue worker. Server command sessions expose completion via /ws.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+import asyncio
+import json
+import os
+import tempfile
+import copy
+from typing import TYPE_CHECKING, Any, Awaitable, Callable, Dict, List, Optional
+
+from chunk_metadata_adapter.semantic_chunk import SemanticChunk
+
+from svo_client.chunk_presets import warn_if_unknown_chunk_set
+from svo_client.core import ClientCore
+from svo_client.exceptions import (
+    SvoChunkingError,
+    SvoClientError,
+    SvoConnectionError,
+    SvoTimeoutError,
+    SvoValidationError,
+)
+
+if TYPE_CHECKING:
+    from mcp_proxy_adapter.client.jsonrpc_client.ws_job_status import (
+        BidirectionalWsChannel,
+    )
+
+
+def _validate_embedding_pair(model: Optional[str], dimension: Optional[int]) -> None:
+    """Validate the optional model/dimension request pair before any RPC."""
+    if (model is None) != (dimension is None):
+        raise SvoValidationError(
+            "Parameters 'model' and 'dimension' must be provided together "
+            "or both omitted"
+        )
+    if model is not None and (not isinstance(model, str) or not model.strip()):
+        raise SvoValidationError(
+            "Parameter 'model' must be a non-empty string when provided"
+        )
+    if dimension is not None and (
+        isinstance(dimension, bool) or not isinstance(dimension, int) or dimension <= 0
+    ):
+        raise SvoValidationError(
+            "Parameter 'dimension' must be a positive integer when provided"
+        )
+
+
+def _unwrap_queued_command_result(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """If the adapter returned a job envelope, return the inner command payload."""
+    nested = raw.get("result")
+    if isinstance(nested, dict) and (
+        "success" in nested
+        or nested.get("error") is not None
+        or "results" in nested
+        or "body" in nested
+        or nested.get("transfer_id")
+        or isinstance(nested.get("data"), dict)
+    ):
+        return nested
+    return raw
+
+
+def unwrap_command_result(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """Unwrap transport, queue and SuccessResult envelopes without losing errors."""
+    current = raw
+    for _ in range(12):
+        if not isinstance(current, dict):
+            raise SvoChunkingError("Invalid command response envelope")
+        if (
+            current.get("error") is not None
+            or current.get("mime")
+            or current.get("type") in ("file", "file_chunk")
+            or isinstance(current.get("results"), list)
+        ):
+            return current
+        nested = current.get("result")
+        if isinstance(nested, dict):
+            current = nested
+            continue
+        nested = current.get("data")
+        if isinstance(nested, dict) and ("success" in current or len(current) == 1):
+            current = nested
+            continue
+        return current
+    raise SvoChunkingError("Command response nesting is too deep")
+
+
+def _semantic_chunk_dict_from_wire(raw: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Validate and normalize a chunk dict from JSON-RPC / NDJSON using
+    ``chunk_metadata_adapter`` (same contract as the server).
+    """
+    semantic_chunk, errors = SemanticChunk.validate_and_fill(raw)
+    if errors:
+        msg = errors.get("error") if isinstance(errors, dict) else str(errors)
+        raise SvoChunkingError(
+            f"chunk: SemanticChunk validation failed: {msg}"
+        ) from None
+    dumped = semantic_chunk.model_dump()
+    for policy_key in (
+        "chunk_set",
+        "chunk_policy_version",
+        "atom_count",
+        "merged_atom_kinds",
+        "ignored_structural_markers",
+        "global_start",
+        "global_end",
+    ):
+        if raw.get(policy_key) is not None:
+            dumped[policy_key] = raw[policy_key]
+    return dumped
+
+
+def _normalize_chunk_dict_list(chunks: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    return [_semantic_chunk_dict_from_wire(c) for c in chunks]
+
+
+def _extract_timing_breakdown(result: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    result_data = result.get("result")
+    if not isinstance(result_data, dict):
+        return None
+    tb = result_data.get("timing_breakdown")
+    if isinstance(tb, dict):
+        return tb
+    data = result_data.get("data", {})
+    if isinstance(data, dict):
+        tb = data.get("timing_breakdown")
+        if isinstance(tb, dict):
+            return tb
+    return None
+
+
+def _extract_chunks_from_result(result: Dict[str, Any]) -> List[Dict[str, Any]]:
+    if "result" not in result:
+        if "error" in result:
+            raise SvoChunkingError(
+                result.get("message", result.get("error", "Unknown error"))
+            )
+        raise SvoChunkingError("No chunks returned from server")
+
+    result_data = result["result"]
+
+    if isinstance(result_data, list) and result_data:
+        return result_data
+
+    if isinstance(result_data, dict):
+        nested = result_data.get("result", {})
+        if isinstance(nested, dict):
+            data = nested.get("data", {})
+            if isinstance(data, dict):
+                chunks = data.get("chunks", [])
+                if chunks and isinstance(chunks, list):
+                    return chunks
+        chunks = result_data.get("chunks", [])
+        if chunks and isinstance(chunks, list):
+            return chunks
+        data = result_data.get("data", {})
+        if isinstance(data, dict):
+            chunks = data.get("chunks", [])
+            if chunks and isinstance(chunks, list):
+                return chunks
+        if "error" in result_data:
+            raise SvoChunkingError(
+                result_data.get("message", result_data.get("error", "Chunking failed"))
+            )
+
+    raise SvoChunkingError("No chunks in server response")
+
+
+def _ndjson_body_to_per_text_chunk_lists(
+    body: str,
+    text_chunk_counts: List[int],
+) -> List[List[Dict[str, Any]]]:
+    """Split flat NDJSON chunk lines using per-text ``text_chunk_counts``."""
+    lines = [ln for ln in body.split("\n") if ln.strip()]
+    chunks_flat: List[Dict[str, Any]] = []
+    for ln in lines:
+        try:
+            parsed = json.loads(ln)
+        except json.JSONDecodeError:
+            raise SvoChunkingError("chunk: invalid NDJSON line in body") from None
+        if not isinstance(parsed, dict):
+            raise SvoChunkingError("chunk: NDJSON line must be a JSON object")
+        chunks_flat.append(_semantic_chunk_dict_from_wire(parsed))
+    out: List[List[Dict[str, Any]]] = []
+    pos = 0
+    for cnt in text_chunk_counts:
+        if isinstance(cnt, bool) or not isinstance(cnt, int) or cnt < 0:
+            raise SvoChunkingError("chunk: invalid text_chunk_counts")
+        out.append(chunks_flat[pos : pos + cnt])
+        pos += cnt
+    if pos != len(chunks_flat):
+        raise SvoChunkingError(
+            "chunk: text_chunk_counts does not match NDJSON body line count"
+        )
+    return out
+
+
+def parse_chunk_ndjson(
+    body: str, text_chunk_counts: List[int]
+) -> List[List[Dict[str, Any]]]:
+    """Parse exact chunk metadata and split NDJSON by original input index."""
+    if not isinstance(body, str) or not isinstance(text_chunk_counts, list):
+        raise SvoChunkingError("chunk: invalid NDJSON body or text_chunk_counts")
+    return _ndjson_body_to_per_text_chunk_lists(body, text_chunk_counts)
+
+
+def parse_chunk_ndjson_file(
+    path: str, text_chunk_counts: Optional[List[int]] = None
+) -> List[List[Dict[str, Any]]]:
+    """Parse an artifact; absent counts return its chunks as one sequence."""
+    with open(path, encoding="utf-8", newline="") as stream:
+        body = stream.read()
+    if text_chunk_counts is None:
+        text_chunk_counts = [sum(bool(line.strip()) for line in body.split("\n"))]
+    return parse_chunk_ndjson(body, text_chunk_counts)
+
+
+def _ndjson_path_to_per_text_chunk_lists(
+    path: str,
+    text_chunk_counts: List[int],
+) -> List[List[Dict[str, Any]]]:
+    """Split flat NDJSON file using per-text ``text_chunk_counts`` (line-oriented read)."""
+    chunks_flat: List[Dict[str, Any]] = []
+    with open(path, encoding="utf-8") as f:
+        for ln in f:
+            ln = ln.strip()
+            if not ln:
+                continue
+            try:
+                parsed = json.loads(ln)
+            except json.JSONDecodeError:
+                raise SvoChunkingError("chunk: invalid NDJSON line in body") from None
+            if not isinstance(parsed, dict):
+                raise SvoChunkingError("chunk: NDJSON line must be a JSON object")
+            chunks_flat.append(_semantic_chunk_dict_from_wire(parsed))
+    out: List[List[Dict[str, Any]]] = []
+    pos = 0
+    for cnt in text_chunk_counts:
+        if cnt < 0:
+            raise SvoChunkingError("chunk: invalid text_chunk_counts")
+        out.append(chunks_flat[pos : pos + cnt])
+        pos += cnt
+    if pos != len(chunks_flat):
+        raise SvoChunkingError(
+            "chunk: text_chunk_counts does not match NDJSON body line count"
+        )
+    return out
+
+
+async def _chunk_success_ndjson_per_text_lists(
+    core: ClientCore,
+    raw: Dict[str, Any],
+) -> List[List[Dict[str, Any]]]:
+    """
+    Resolve NDJSON payload from inline ``body`` or ``transfer_id`` download.
+    """
+    counts_raw = raw.get("text_chunk_counts")
+    if not isinstance(counts_raw, list):
+        raise SvoChunkingError("chunk: invalid text_chunk_counts")
+    if any(isinstance(x, bool) or not isinstance(x, int) or x < 0 for x in counts_raw):
+        raise SvoChunkingError("chunk: invalid text_chunk_counts")
+    counts = counts_raw
+    tid = raw.get("transfer_id")
+    if isinstance(tid, str) and tid.strip():
+        tmp = tempfile.NamedTemporaryFile(delete=False, suffix=".jsonl")
+        tmp_path = tmp.name
+        tmp.close()
+        try:
+            await core.download_transfer_to_path(tid.strip(), tmp_path)
+            return _ndjson_path_to_per_text_chunk_lists(tmp_path, counts)
+        finally:
+            try:
+                os.unlink(tmp_path)
+            except OSError:
+                pass
+    body = raw.get("body")
+    if isinstance(body, str):
+        return _ndjson_body_to_per_text_chunk_lists(body, counts)
+    raise SvoChunkingError("chunk: missing NDJSON body and transfer_id")
+
+
+def _extract_batch_results(raw: Dict[str, Any]) -> List[Dict[str, Any]]:
+    """
+    Extract batch item results from top-level ``results`` or nested ``data.results``.
+
+    Canonical:
+      {"result": {"success": true, "results": [...]}}
+    Alternate nested shape:
+      {"result": {"success": true, "data": {"success": true, "results": [...]}}}
+    """
+    results_list = raw.get("results")
+    if isinstance(results_list, list):
+        return results_list
+
+    nested_result = raw.get("result")
+    if isinstance(nested_result, list):
+        return nested_result
+
+    nested_data = raw.get("data")
+    if isinstance(nested_data, dict):
+        data_results = nested_data.get("results")
+        if isinstance(data_results, list):
+            return data_results
+
+    return []
+
+
+def build_file_chunk_params(
+    *,
+    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,
+    model: Optional[str] = None,
+    dimension: Optional[int] = None,
+    chunk_only: Optional[bool] = None,
+    split_level: Optional[str] = None,
+    max_chars: Optional[int] = None,
+) -> Dict[str, Any]:
+    """
+    Build JSON-RPC parameters for the ``file_chunk`` command.
+
+    File acquisition matches ``file`` (oneOf): ``filepath``, or ``filename`` +
+    ``file_content_base64``, or ``transfer_id`` + ``filename``. Chunk fields match
+    ``chunk_batch`` without ``texts``.
+    """
+    _validate_embedding_pair(model, dimension)
+
+    params: Dict[str, Any] = {
+        "window": window,
+        "use_sv": use_sv,
+    }
+    if filepath is not None:
+        params["filepath"] = filepath
+    if filename is not None:
+        params["filename"] = filename
+    if file_content_base64 is not None:
+        params["file_content_base64"] = file_content_base64
+    if transfer_id is not None:
+        params["transfer_id"] = transfer_id
+    if filter_name is not None:
+        params["filter_name"] = filter_name
+    if chunk_type is not None:
+        params["type"] = chunk_type
+    if language is not None:
+        params["language"] = language
+    if source_id is not None:
+        params["source_id"] = source_id
+    if project is not None:
+        params["project"] = project
+    if unit_id is not None:
+        params["unit_id"] = unit_id
+    if chunking_version is not None:
+        params["chunking_version"] = chunking_version
+    if aggregation_mode is not None:
+        params["aggregation_mode"] = aggregation_mode
+    if respect_structural_blocks is not None:
+        params["respect_structural_blocks"] = respect_structural_blocks
+    warn_if_unknown_chunk_set(chunk_set)
+    if chunk_set is not None:
+        params["chunk_set"] = chunk_set
+    if model is not None:
+        params["model"] = model
+        params["dimension"] = dimension
+    for name, value in (
+        ("chunk_only", chunk_only),
+        ("split_level", split_level),
+        ("max_chars", max_chars),
+    ):
+        if value is not None:
+            params[name] = value
+    return params
+
+
+def _unwrap_file_chunk_payload_dict(payload: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Walk nested ``{"success", "data": {...}}`` envelopes until the ``file_chunk``
+    contract dict (``type == "file_chunk"``) is at the current level.
+
+    WebSocket ``job_completed`` results are normalized in
+    ``mcp_proxy_adapter`` ``execute_command_unified`` by stripping a single
+    ``data`` wrapper from the ``result`` field. Long-running jobs may still
+    carry one extra ``SuccessResult``-shaped layer, so the client must peel
+    repeatedly (same idea as :func:`_extract_chunks_from_result` for ``chunk``).
+    """
+    cur: Any = payload
+    for _ in range(8):
+        if not isinstance(cur, dict):
+            break
+        if cur.get("type") == "file_chunk":
+            return cur
+        nxt = cur.get("data")
+        if isinstance(nxt, dict):
+            cur = nxt
+            continue
+        break
+    if not isinstance(cur, dict):
+        raise SvoChunkingError("file_chunk: invalid result payload")
+    return cur
+
+
+def extract_file_chunk_success_payload(unified: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Extract the successful ``file_chunk`` data dict from ``ClientCore.call`` /
+    ``execute_command_unified`` return value.
+    """
+    inner = unified.get("result")
+    if not isinstance(inner, dict):
+        raise SvoChunkingError("file_chunk: missing or invalid result")
+
+    # Queued jobs: top-level ``result`` is { job_id, command, result: {...}, status }
+    nested_cmd = inner.get("result")
+    if isinstance(nested_cmd, dict) and (
+        "success" in nested_cmd
+        or nested_cmd.get("error") is not None
+        or isinstance(nested_cmd.get("data"), dict)
+    ):
+        inner = nested_cmd
+
+    if inner.get("error"):
+        err = inner["error"]
+        if isinstance(err, dict):
+            msg = err.get("message", str(err))
+        else:
+            msg = str(err)
+        raise SvoChunkingError(msg, error=err)
+
+    if isinstance(inner.get("data"), dict):
+        payload = inner["data"]
+    else:
+        payload = inner
+
+    payload = _unwrap_file_chunk_payload_dict(payload)
+
+    if payload.get("status") == "error" and payload.get("message") is not None:
+        raise SvoChunkingError(str(payload["message"]))
+
+    if payload.get("type") != "file_chunk":
+        raise SvoChunkingError(
+            f"file_chunk: result type mismatch (got {payload.get('type')!r})"
+        )
+    if not payload.get("success", False):
+        raise SvoChunkingError("file_chunk: server reported failure")
+    tid = payload.get("transfer_id")
+    if not isinstance(tid, str) or not tid:
+        raise SvoChunkingError("file_chunk: missing transfer_id")
+
+    return payload
+
+
+class SvoChunkerClient:
+    """
+    Asynchronous client for SVO Chunker.
+
+    File vectorization uses ``file_chunk`` (server RPC). ``chunk`` runs in the
+    server process and ``file_chunk`` uses a queue worker; :class:`ClientCore` /
+    ``JsonRpcClient`` command sessions deliver completion over WebSocket. Text
+    embedding inside the pipeline is handled by the server (embed-client); this
+    client only drives chunker RPC.
+    Optional artifact download after ``file_chunk`` uses
+    :meth:`ClientCore.download_transfer_to_path` (declared-size precheck,
+    then ``JsonRpcClient.download_file``). Use ``open_ws_channel()`` for a
+    long-lived WebSocket when needed.
+    """
+
+    def __init__(
+        self,
+        protocol: str = "https",
+        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,
+        poll_interval: float = 1.0,
+        certs_dir: Optional[str] = None,
+        file_batch_size: Optional[int] = None,
+    ):
+        self._core = ClientCore(
+            protocol=protocol,
+            host=host,
+            port=port,
+            token_header=token_header,
+            token=token,
+            cert=cert,
+            key=key,
+            ca=ca,
+            check_hostname=check_hostname,
+            timeout=timeout,
+            certs_dir=certs_dir,
+        )
+        self.timeout = timeout
+        self.poll_interval = poll_interval
+        self._last_timing_breakdown: Optional[Dict[str, Any]] = None
+        self._file_batch_size = file_batch_size
+
+    @property
+    def file_batch_size(self) -> Optional[int]:
+        """Optional value copied from the client config (JSON/env), for documentation only.
+
+        The server ``file_chunk`` batch width is controlled by **server** ``config`` key
+        ``file_batch_size``. This property is **not** sent on RPC; it exists so callers
+        can display or log the expected batch size without re-reading the server file.
+        """
+        return self._file_batch_size
+
+    @property
+    def last_timing_breakdown(self) -> Optional[Dict[str, Any]]:
+        """Server-side timing breakdown from the last chunk() call, if present."""
+        return self._last_timing_breakdown
+
+    async def call(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        status_hook: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None,
+    ) -> Dict[str, Any]:
+        try:
+            return await self._core.call(command, params or {}, status_hook=status_hook)
+        except SvoClientError:
+            raise
+        except Exception as e:
+            raise SvoConnectionError(f"Command '{command}' failed: {e}") from e
+
+    execute = call
+
+    async def help(self, command_name: Optional[str] = None) -> Dict[str, Any]:
+        return await self._core.get_help(command_name)
+
+    async def list_commands(self) -> List[str]:
+        return await self._core.list_commands()
+
+    async def command_contract(self, command: str) -> Dict[str, Any]:
+        """Fetch a live command contract including every inherited API parameter."""
+        response = await self.help(command)
+        current = response
+        for _ in range(12):
+            if not isinstance(current, dict):
+                break
+            if isinstance(current.get("schema"), dict):
+                return copy.deepcopy(current)
+            commands = current.get("commands")
+            if isinstance(commands, dict) and isinstance(commands.get(command), dict):
+                current = commands[command]
+                continue
+            nested = current.get("data")
+            if not isinstance(nested, dict):
+                nested = current.get("result")
+            if not isinstance(nested, dict):
+                break
+            current = nested
+        raise SvoValidationError(f"No live schema returned for command {command!r}")
+
+    async def prepare_command(
+        self, command: str, params: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        """Validate against the live schema without dispatch or default injection.
+
+        This is the explicit schema-backed surface for inherited adapter commands,
+        including nested settings. Omission, null, false and zero are preserved.
+        """
+        from jsonschema import Draft7Validator, FormatChecker
+
+        contract = await self.command_contract(command)
+        schema = contract["schema"]
+        if not isinstance(params, dict):
+            raise SvoValidationError("Command parameters must be an object")
+        unknown = set(params) - set(schema.get("properties", {}))
+        if unknown:
+            raise SvoValidationError(
+                f"Unknown parameters for {command}: {sorted(unknown)}"
+            )
+        errors = list(
+            Draft7Validator(schema, format_checker=FormatChecker()).iter_errors(params)
+        )
+        if errors:
+            errors.sort(
+                key=lambda error: (error.validator != "required", str(list(error.path)))
+            )
+            raise SvoValidationError(errors[0].message)
+        return copy.deepcopy(params)
+
+    async def chunk(
+        self,
+        text: str,
+        window: int = 3,
+        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,
+        chunk_type: Optional[str] = None,
+        aggregation_mode: Optional[str] = None,
+        respect_structural_blocks: Optional[bool] = None,
+        chunk_set: Optional[str] = None,
+        model: Optional[str] = None,
+        dimension: Optional[int] = None,
+        chunk_only: Optional[bool] = None,
+        split_level: Optional[str] = None,
+        max_chars: Optional[int] = None,
+    ) -> List[Dict[str, Any]]:
+        if not isinstance(text, str) or (
+            not text.strip() and split_level is None and max_chars is None
+        ):
+            raise SvoValidationError("Text cannot be empty")
+
+        _validate_embedding_pair(model, dimension)
+
+        warn_if_unknown_chunk_set(chunk_set)
+
+        params: Dict[str, Any] = {
+            "texts": [text],
+            "window": window,
+            "use_sv": use_sv,
+        }
+        if chunk_type is not None:
+            params["type"] = chunk_type
+        if language is not None:
+            params["language"] = language
+        if source_id is not None:
+            params["source_id"] = source_id
+        if project is not None:
+            params["project"] = project
+        if unit_id is not None:
+            params["unit_id"] = unit_id
+        if chunking_version is not None:
+            params["chunking_version"] = chunking_version
+        if aggregation_mode is not None:
+            params["aggregation_mode"] = aggregation_mode
+        if respect_structural_blocks is not None:
+            params["respect_structural_blocks"] = respect_structural_blocks
+        if chunk_set is not None:
+            params["chunk_set"] = chunk_set
+        if model is not None:
+            params["model"] = model
+            params["dimension"] = dimension
+
+        for name, value in (
+            ("chunk_only", chunk_only),
+            ("split_level", split_level),
+            ("max_chars", max_chars),
+        ):
+            if value is not None:
+                params[name] = value
+
+        try:
+            result = await self._core.call("chunk", params)
+            self._last_timing_breakdown = _extract_timing_breakdown(result)
+            raw = result.get("result")
+            if not isinstance(raw, dict):
+                raise SvoChunkingError("chunk: invalid result shape")
+            raw = _unwrap_queued_command_result(raw)
+
+            if raw.get("success") is False and raw.get("error"):
+                err = raw["error"]
+                if isinstance(err, dict) and err.get("message"):
+                    raise SvoChunkingError(str(err["message"]), error=err)
+                raise SvoChunkingError("chunk: server reported failure")
+
+            if (
+                raw.get("mime") == "application/x-ndjson"
+                and isinstance(raw.get("text_chunk_counts"), list)
+                and (
+                    isinstance(raw.get("body"), str)
+                    or (
+                        isinstance(raw.get("transfer_id"), str)
+                        and raw.get("transfer_id", "").strip()
+                    )
+                )
+            ):
+                for te in raw.get("text_errors") or []:
+                    if isinstance(te, dict) and te.get("index") == 0:
+                        ep = te.get("error") or {}
+                        if isinstance(ep, dict) and ep.get("message"):
+                            raise SvoChunkingError(str(ep["message"]), error=ep)
+                        raise SvoChunkingError("chunk failed for input text")
+                per_text = await _chunk_success_ndjson_per_text_lists(
+                    self._core,
+                    raw,
+                )
+                if not per_text:
+                    raise SvoChunkingError("chunk: empty NDJSON result")
+                return per_text[0]
+
+            results_list = _extract_batch_results(raw)
+            if not isinstance(results_list, list) or not results_list:
+                raise SvoChunkingError("chunk: no results list")
+
+            first = results_list[0]
+            if not isinstance(first, dict):
+                raise SvoChunkingError("chunk: invalid item result shape")
+            if not first.get("success", False):
+                error_payload = first.get("error", {})
+                if isinstance(error_payload, dict) and error_payload.get("message"):
+                    raise SvoChunkingError(
+                        str(error_payload["message"]), error=error_payload
+                    )
+                raise SvoChunkingError("chunk failed for input text")
+            chunks = first.get("chunks")
+            if isinstance(chunks, list):
+                if any(not isinstance(c, dict) for c in chunks):
+                    raise SvoChunkingError("chunk: invalid chunk entry in batch item")
+                return _normalize_chunk_dict_list(chunks)
+            data = first.get("data", {})
+            if isinstance(data, dict):
+                fallback_chunks = data.get("chunks", [])
+                if isinstance(fallback_chunks, list):
+                    if any(not isinstance(c, dict) for c in fallback_chunks):
+                        raise SvoChunkingError(
+                            "chunk: invalid chunk entry in batch item data"
+                        )
+                    return _normalize_chunk_dict_list(fallback_chunks)
+            raise SvoChunkingError("chunk: no chunks in first batch item")
+        except SvoTimeoutError:
+            raise
+        except SvoClientError:
+            raise
+        except Exception as e:
+            raise SvoConnectionError(f"Chunk failed: {e}") from e
+
+    async def chunk_batch(
+        self,
+        texts: List[str],
+        window: int = 3,
+        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,
+        chunk_type: Optional[str] = None,
+        aggregation_mode: Optional[str] = None,
+        respect_structural_blocks: Optional[bool] = None,
+        chunk_set: Optional[str] = None,
+        model: Optional[str] = None,
+        dimension: Optional[int] = None,
+        chunk_only: Optional[bool] = None,
+        split_level: Optional[str] = None,
+        max_chars: Optional[int] = None,
+    ) -> List[List[Dict[str, Any]]]:
+        if not texts or not isinstance(texts, list):
+            raise SvoValidationError("texts must be a non-empty list")
+
+        _validate_embedding_pair(model, dimension)
+
+        warn_if_unknown_chunk_set(chunk_set)
+
+        params: Dict[str, Any] = {
+            "texts": texts,
+            "window": window,
+            "use_sv": use_sv,
+        }
+        if chunk_type is not None:
+            params["type"] = chunk_type
+        if language is not None:
+            params["language"] = language
+        if source_id is not None:
+            params["source_id"] = source_id
+        if project is not None:
+            params["project"] = project
+        if unit_id is not None:
+            params["unit_id"] = unit_id
+        if chunking_version is not None:
+            params["chunking_version"] = chunking_version
+        if aggregation_mode is not None:
+            params["aggregation_mode"] = aggregation_mode
+        if respect_structural_blocks is not None:
+            params["respect_structural_blocks"] = respect_structural_blocks
+        if chunk_set is not None:
+            params["chunk_set"] = chunk_set
+        if model is not None:
+            params["model"] = model
+            params["dimension"] = dimension
+
+        for name, value in (
+            ("chunk_only", chunk_only),
+            ("split_level", split_level),
+            ("max_chars", max_chars),
+        ):
+            if value is not None:
+                params[name] = value
+
+        try:
+            result = await self._core.call("chunk", params)
+            self._last_timing_breakdown = _extract_timing_breakdown(result)
+        except SvoTimeoutError:
+            raise
+        except SvoClientError:
+            raise
+        except Exception as e:
+            raise SvoConnectionError(f"chunk failed: {e}") from e
+
+        raw = result.get("result")
+        if not isinstance(raw, dict):
+            raise SvoChunkingError("chunk: invalid result shape")
+        raw = _unwrap_queued_command_result(raw)
+
+        if raw.get("success") is False and raw.get("error"):
+            err = raw["error"]
+            # region agent log
+            try:
+                from svo_client.debug_session_log import write_debug_ndjson
+
+                write_debug_ndjson(
+                    "H_client",
+                    "svo_client/client.py:chunk_batch",
+                    "chunk command returned top-level error",
+                    {
+                        "error_keys": (
+                            list(err.keys()) if isinstance(err, dict) else None
+                        ),
+                        "message": (
+                            err.get("message") if isinstance(err, dict) else None
+                        ),
+                        "code": err.get("code") if isinstance(err, dict) else None,
+                        "details": (
+                            err.get("details") if isinstance(err, dict) else None
+                        ),
+                    },
+                )
+            except Exception:
+                pass
+            # endregion
+            if isinstance(err, dict) and err.get("message"):
+                raise SvoChunkingError(str(err["message"]), error=err)
+            raise SvoChunkingError("chunk: server reported failure")
+
+        if (
+            raw.get("mime") == "application/x-ndjson"
+            and isinstance(raw.get("text_chunk_counts"), list)
+            and (
+                isinstance(raw.get("body"), str)
+                or (
+                    isinstance(raw.get("transfer_id"), str)
+                    and raw.get("transfer_id", "").strip()
+                )
+            )
+        ):
+            return await _chunk_success_ndjson_per_text_lists(self._core, raw)
+
+        results_list = _extract_batch_results(raw)
+        if not isinstance(results_list, list):
+            raise SvoChunkingError("chunk: no results list")
+
+        out: List[List[Dict[str, Any]]] = []
+        for item in results_list:
+            if isinstance(item, dict) and item.get("success"):
+                data = item.get("data", {})
+                chunks = data.get("chunks", []) if isinstance(data, dict) else []
+                if isinstance(chunks, list):
+                    if any(not isinstance(c, dict) for c in chunks):
+                        raise SvoChunkingError(
+                            "chunk_batch: invalid chunk entry in batch item"
+                        )
+                    out.append(_normalize_chunk_dict_list(chunks))
+                else:
+                    out.append([])
+            else:
+                out.append([])
+        return out
+
+    async def health(self) -> Dict[str, Any]:
+        return await self._core.health()
+
+    async def info(self) -> Dict[str, Any]:
+        """Return the server's complete documentation payload."""
+        return await self.call("info")
+
+    async def stanza_runtime(self, action: str) -> Dict[str, Any]:
+        """Read or change Stanza runtime state (status, on, off)."""
+        return await self.call("stanza_runtime", {"action": action})
+
+    async def file(
+        self,
+        *,
+        filename: Optional[str] = None,
+        file_content_base64: Optional[str] = None,
+        filepath: Optional[str] = None,
+        transfer_id: Optional[str] = None,
+        filter_name: Optional[str] = None,
+        status_hook: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None,
+    ) -> Dict[str, Any]:
+        """Extract text through any of the server's three file acquisition modes."""
+        params = {
+            name: value
+            for name, value in (
+                ("filename", filename),
+                ("file_content_base64", file_content_base64),
+                ("filepath", filepath),
+                ("transfer_id", transfer_id),
+                ("filter_name", filter_name),
+            )
+            if value is not None
+        }
+        return await self.call("file", params, status_hook=status_hook)
+
+    async def parse_chunk_result(
+        self, raw: Dict[str, Any]
+    ) -> List[List[Dict[str, Any]]]:
+        """Resolve inline/transfer NDJSON or legacy per-text chunk envelopes.
+
+        Per-text failures retain their place as empty sequences; inspect the
+        original text_errors for their structured error. Command errors raise
+        SvoChunkingError with the complete wire error in its error attribute.
+        """
+        payload = raw
+        for _ in range(8):
+            if not isinstance(payload, dict):
+                raise SvoChunkingError("chunk: invalid result shape")
+            err = payload.get("error")
+            if err:
+                message = (
+                    err.get("message", str(err)) if isinstance(err, dict) else str(err)
+                )
+                raise SvoChunkingError(message, error=err)
+            if payload.get("mime") == "application/x-ndjson":
+                return await _chunk_success_ndjson_per_text_lists(self._core, payload)
+            results = payload.get("results")
+            if not isinstance(results, list):
+                results = payload.get("result")
+            if isinstance(results, list):
+                out = []
+                for item in results:
+                    if not isinstance(item, dict) or not item.get("success"):
+                        out.append([])
+                        continue
+                    chunks = item.get("chunks")
+                    if chunks is None:
+                        chunks = (item.get("data") or {}).get("chunks", [])
+                    out.append(_normalize_chunk_dict_list(chunks))
+                return out
+            nested = payload.get("result")
+            if not isinstance(nested, dict):
+                nested = payload.get("data")
+            if not isinstance(nested, dict):
+                break
+            payload = nested
+        raise SvoChunkingError("chunk: missing chunks or NDJSON payload")
+
+    async def download_transfer_to_path(
+        self,
+        transfer_id: str,
+        destination_path: str,
+        *,
+        acknowledge_after_download: bool = True,
+    ) -> Any:
+        """Download with declared-size precheck and optional checksum ACK."""
+        return await self._core.download_transfer_to_path(
+            transfer_id,
+            destination_path,
+            acknowledge_after_download=acknowledge_after_download,
+        )
+
+    async def get_download_session(self, transfer_id: str) -> Dict[str, Any]:
+        """Read the adapter's declared artifact size and checksum."""
+        return await self._core.adapter_client.get_download_session(transfer_id)
+
+    async def transfer_ack(
+        self,
+        transfer_id: str,
+        *,
+        checksum_value: str,
+        checksum_algorithm: str = "sha256",
+    ) -> Dict[str, Any]:
+        """Acknowledge a received artifact using its actual checksum."""
+        return await self._core.adapter_client.jsonrpc_call(
+            "transfer_ack",
+            {
+                "transfer_id": transfer_id,
+                "checksum_algorithm": checksum_algorithm,
+                "checksum_value": checksum_value,
+            },
+        )
+
+    async def rpc_call(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Send one raw parameter invocation without command-session wrapping."""
+        return await self._core.adapter_client.jsonrpc_call(command, params or {})
+
+    async def upload_file(
+        self,
+        source_path: str,
+        filename: Optional[str] = None,
+        compression: str = "identity",
+        chunk_size: Optional[int] = None,
+        on_progress: Optional[Callable[[int, int], None]] = None,
+    ) -> Any:
+        """Upload through the adapter and return its verified transfer receipt."""
+        return await self._core.adapter_client.upload_file(
+            source_path,
+            filename=filename,
+            compression=compression,
+            chunk_size=chunk_size,
+            on_progress=on_progress,
+        )
+
+    async def get_openapi_schema(self) -> Dict[str, Any]:
+        """Return OpenAPI document from the chunker (adapter ``GET /openapi.json``)."""
+        return await self._core.get_openapi_schema()
+
+    def open_ws_channel(
+        self,
+        receive_timeout: float = 60.0,
+        heartbeat: float = 30.0,
+    ) -> "BidirectionalWsChannel":
+        return self._core.open_ws_channel(
+            receive_timeout=receive_timeout,
+            heartbeat=heartbeat,
+        )
+
+    async def file_chunk(
+        self,
+        params: Dict[str, Any],
+        *,
+        download_path: Optional[str] = None,
+        status_hook: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Run the server ``file_chunk`` command.
+
+        On success, returns the normalized data payload (``success``, ``type``,
+        ``transfer_id``, ``filename``, ``filter_name``, optional ``metadata``).
+        When *download_path* is set, fetches the outbound JSON artifact via
+        :meth:`ClientCore.download_transfer_to_path` (free-space precheck using
+        declared size from the adapter download session, then ``transfer_ack`` so
+        the server can release staging per g1).
+
+        Optional *status_hook* is passed to :meth:`ClientCore.call` for queued
+        jobs (adapter WebSocket lifecycle / progress before completion).
+        """
+        try:
+            raw = await self._core.call("file_chunk", params, status_hook=status_hook)
+            data = extract_file_chunk_success_payload(raw)
+            if download_path:
+                await self._core.download_transfer_to_path(
+                    data["transfer_id"],
+                    download_path,
+                )
+            return data
+        except SvoTimeoutError:
+            raise
+        except SvoClientError:
+            raise
+        except SvoChunkingError:
+            raise
+        except Exception as e:
+            raise SvoConnectionError(f"file_chunk failed: {e}") from e
+
+    async def close(self) -> None:
+        """Close underlying adapter client if it has a close method (e.g. HTTP session)."""
+        adapter = self._core.adapter_client
+        close_fn = getattr(adapter, "close", None)
+        if close_fn is not None and callable(close_fn):
+            result = close_fn()
+            if asyncio.iscoroutine(result):
+                await result
+
+    async def __aenter__(self) -> "SvoChunkerClient":
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        await self.close()