doc-store-client 0.1.13__py3-none-any.whl

doc_store_client/__init__.py

@@ -0,0 +1,95 @@
+"""Public API for the transport-neutral doc-store client package."""
+
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _distribution_version
+from pathlib import Path as _Path
+import tomllib as _tomllib
+
+from .client import DOC_STORE_COMMANDS, DocStoreClient, DocStoreClientError
+from .models import (
+    ChapterGetRequest,
+    ChapterGetResult,
+    DocumentChunkRequest,
+    DocumentChunkResult,
+    DocumentCreateRequest,
+    DocumentCreateResult,
+    DocumentDeleteRequest,
+    DocumentDeleteResult,
+    DocumentGetRequest,
+    DocumentGetResult,
+    DocumentRebindRequest,
+    DocumentRebindResult,
+    DocumentUpdateRequest,
+    DocumentUpdateResult,
+    DocumentWriteRequest,
+    DocumentWriteResult,
+    EntityGetRequest,
+    EntityGetResult,
+    EntityIdsRequest,
+    EntityLifecycleResult,
+    EntityListRequest,
+    EntityListResult,
+    EntityReferencesRequest,
+    EntityReferencesResult,
+    OperationState,
+    ParagraphGetByNumberRequest,
+    ParagraphGetByNumberResult,
+    ParagraphGetRequest,
+    ParagraphGetResult,
+    ProcessingStatusRequest,
+    ProcessingStatusResult,
+    RankedSearchHit,
+    RetrievalRequest,
+    RetrievalResult,
+    SearchResult,
+    ServerError,
+)
+
+try:
+    __version__ = _distribution_version("doc-store-client")
+except _PackageNotFoundError:
+    _pyproject = _Path(__file__).resolve().parents[2] / "pyproject.toml"
+    __version__ = _tomllib.loads(_pyproject.read_text(encoding="utf-8"))["project"]["version"]
+
+# The package includes ``py.typed`` in its distribution metadata.
+__all__ = [
+    "ChapterGetRequest",
+    "ChapterGetResult",
+    "DOC_STORE_COMMANDS",
+    "DocStoreClient",
+    "DocStoreClientError",
+    "DocumentCreateRequest",
+    "DocumentCreateResult",
+    "DocumentChunkRequest",
+    "DocumentChunkResult",
+    "DocumentDeleteRequest",
+    "DocumentDeleteResult",
+    "DocumentGetRequest",
+    "DocumentGetResult",
+    "DocumentRebindRequest",
+    "DocumentRebindResult",
+    "DocumentUpdateRequest",
+    "DocumentUpdateResult",
+    "DocumentWriteRequest",
+    "DocumentWriteResult",
+    "EntityGetRequest",
+    "EntityGetResult",
+    "EntityIdsRequest",
+    "EntityLifecycleResult",
+    "EntityListRequest",
+    "EntityListResult",
+    "EntityReferencesRequest",
+    "EntityReferencesResult",
+    "OperationState",
+    "ParagraphGetByNumberRequest",
+    "ParagraphGetByNumberResult",
+    "ParagraphGetRequest",
+    "ParagraphGetResult",
+    "ProcessingStatusRequest",
+    "ProcessingStatusResult",
+    "RankedSearchHit",
+    "RetrievalRequest",
+    "RetrievalResult",
+    "SearchResult",
+    "ServerError",
+]

doc_store_client/client.py

@@ -0,0 +1,620 @@
+"""Thin typed facade over an injected ``mcp-proxy-adapter`` client."""
+
+from __future__ import annotations
+
+from dataclasses import is_dataclass
+from typing import Any, ClassVar, Mapping, Protocol, TypeVar
+
+from chunk_metadata_adapter import ChunkQuery
+
+from .models import (
+    ChapterGetRequest,
+    ChapterGetResult,
+    DocumentChunkRequest,
+    DocumentChunkResult,
+    DocumentCreateRequest,
+    DocumentCreateResult,
+    DocumentDeleteRequest,
+    DocumentDeleteResult,
+    DocumentGetRequest,
+    DocumentGetResult,
+    DocumentRebindRequest,
+    DocumentRebindResult,
+    DocumentUpdateRequest,
+    DocumentUpdateResult,
+    EntityGetRequest,
+    EntityGetResult,
+    EntityIdsRequest,
+    EntityLifecycleResult,
+    EntityListRequest,
+    EntityListResult,
+    EntityReferencesRequest,
+    EntityReferencesResult,
+    ParagraphGetByNumberRequest,
+    ParagraphGetByNumberResult,
+    ParagraphGetRequest,
+    ParagraphGetResult,
+    ProcessingStatusRequest,
+    ProcessingStatusResult,
+    SearchResult,
+    ServerError,
+)
+
+DOC_STORE_COMMANDS: tuple[str, ...] = (
+    "echo",
+    "long_task",
+    "job_status",
+    "queue_add_job",
+    "queue_start_job",
+    "queue_stop_job",
+    "queue_delete_job",
+    "queue_get_job_status",
+    "queue_get_job_logs",
+    "queue_list_jobs",
+    "queue_health",
+    "document_get",
+    "chapter_get",
+    "paragraph_get",
+    "paragraph_get_by_number",
+    "document_create",
+    "document_update",
+    "document_chunk",
+    "document_rebind",
+    "processing_status",
+    "document_delete",
+    "entity_list",
+    "entity_get",
+    "entity_soft_delete",
+    "entity_undelete",
+    "entity_hard_delete",
+    "entity_references",
+    "chunk_query_search",
+    "help",
+    "health",
+    "config",
+    "reload",
+    "settings",
+    "load",
+    "unload",
+    "plugins",
+    "transport_management",
+    "proxy_registration",
+    "roletest",
+    "transfer_upload_begin",
+    "transfer_upload_status",
+    "transfer_upload_complete",
+    "transfer_download_begin",
+    "transfer_download_status",
+)
+
+
+class JsonRpcClientLike(Protocol):
+    """Minimal adapter surface used by the typed facade."""
+
+    async def execute_command_unified(self, command: str, params: Mapping[str, Any]) -> Any:
+        """Execute a doc-store command through the adapter."""
+
+
+class TransferClientLike(JsonRpcClientLike, Protocol):
+    """Adapter surface when file-transfer ingestion is used."""
+
+    async def upload_file(
+        self,
+        source_path: str,
+        *,
+        filename: str | None = None,
+        compression: str = "identity",
+        chunk_size: int | None = None,
+        on_progress: Any = None,
+    ) -> Any:
+        """Delegate file transfer to the adapter implementation."""
+
+
+T = TypeVar("T")
+
+
+class DocStoreClientError(RuntimeError):
+    """Raised when the adapter or server returns a structured command error."""
+
+    def __init__(self, error: ServerError) -> None:
+        self.error = error
+        super().__init__(error.message)
+
+
+class DocStoreClient:
+    """Typed doc-store operations backed by an injected adapter client."""
+
+    commands: ClassVar[tuple[str, ...]] = DOC_STORE_COMMANDS
+
+    def __init__(self, adapter_client: JsonRpcClientLike) -> None:
+        self._adapter_client = adapter_client
+
+    async def call(
+        self,
+        command: str,
+        params: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Execute any server command through the injected adapter client.
+
+        The adapter owns networking, TLS/mTLS, authentication, queue delivery, and
+        retries.  This method only gives callers a stable command-level facade.
+        """
+
+        command_name = command.strip()
+        if not command_name:
+            raise ValueError("command must be non-empty")
+        return _unwrap_response(
+            await self._adapter_client.execute_command_unified(
+                command_name, _merge_params(params, kwargs)
+            )
+        )
+
+    async def echo(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("echo", params, **kwargs)
+
+    async def long_task(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("long_task", params, **kwargs)
+
+    async def job_status(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("job_status", params, **kwargs)
+
+    async def queue_add_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_add_job", params, **kwargs)
+
+    async def queue_start_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_start_job", params, **kwargs)
+
+    async def queue_stop_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_stop_job", params, **kwargs)
+
+    async def queue_delete_job(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_delete_job", params, **kwargs)
+
+    async def queue_get_job_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_get_job_status", params, **kwargs)
+
+    async def queue_get_job_logs(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_get_job_logs", params, **kwargs)
+
+    async def queue_list_jobs(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_list_jobs", params, **kwargs)
+
+    async def queue_health(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("queue_health", params, **kwargs)
+
+    async def document_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_get", params, **kwargs)
+
+    async def chapter_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chapter_get", params, **kwargs)
+
+    async def paragraph_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("paragraph_get", params, **kwargs)
+
+    async def paragraph_get_by_number(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("paragraph_get_by_number", params, **kwargs)
+
+    async def document_create(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_create", params, **kwargs)
+
+    async def document_update(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_update", params, **kwargs)
+
+    async def document_chunk(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_chunk", params, **kwargs)
+
+    async def document_rebind(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_rebind", params, **kwargs)
+
+    async def processing_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("processing_status", params, **kwargs)
+
+    async def document_delete(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("document_delete", params, **kwargs)
+
+    async def entity_list(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_list", params, **kwargs)
+
+    async def entity_get(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_get", params, **kwargs)
+
+    async def entity_soft_delete(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_soft_delete", params, **kwargs)
+
+    async def entity_undelete(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_undelete", params, **kwargs)
+
+    async def entity_hard_delete(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_hard_delete", params, **kwargs)
+
+    async def entity_references(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("entity_references", params, **kwargs)
+
+    async def chunk_query_search(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("chunk_query_search", params, **kwargs)
+
+    async def help(
+        self,
+        cmdname: str | None = None,
+        params: Mapping[str, Any] | None = None,
+        **kwargs: Any,
+    ) -> Any:
+        request = _merge_params(params, kwargs)
+        if cmdname is not None:
+            if "cmdname" in request:
+                raise ValueError("cmdname supplied twice")
+            request["cmdname"] = cmdname
+        return await self.call("help", request)
+
+    async def health(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("health", params, **kwargs)
+
+    async def config(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("config", params, **kwargs)
+
+    async def reload(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("reload", params, **kwargs)
+
+    async def settings(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("settings", params, **kwargs)
+
+    async def load(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("load", params, **kwargs)
+
+    async def unload(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("unload", params, **kwargs)
+
+    async def plugins(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("plugins", params, **kwargs)
+
+    async def transport_management(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transport_management", params, **kwargs)
+
+    async def proxy_registration(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("proxy_registration", params, **kwargs)
+
+    async def roletest(self, params: Mapping[str, Any] | None = None, **kwargs: Any) -> Any:
+        return await self.call("roletest", params, **kwargs)
+
+    async def transfer_upload_begin(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_upload_begin", params, **kwargs)
+
+    async def transfer_upload_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_upload_status", params, **kwargs)
+
+    async def transfer_upload_complete(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_upload_complete", params, **kwargs)
+
+    async def transfer_download_begin(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_download_begin", params, **kwargs)
+
+    async def transfer_download_status(
+        self, params: Mapping[str, Any] | None = None, **kwargs: Any
+    ) -> Any:
+        return await self.call("transfer_download_status", params, **kwargs)
+
+    async def create_document(
+        self,
+        request: DocumentCreateRequest,
+        *,
+        source_path: str | None = None,
+        filename: str | None = None,
+    ) -> DocumentCreateResult:
+        params = await self._write_params(request, source_path=source_path, filename=filename)
+        return await self._execute("document_create", params, DocumentCreateResult)
+
+    async def update_document(
+        self,
+        request: DocumentUpdateRequest,
+        *,
+        source_path: str | None = None,
+        filename: str | None = None,
+    ) -> DocumentUpdateResult:
+        params = await self._write_params(request, source_path=source_path, filename=filename)
+        return await self._execute("document_update", params, DocumentUpdateResult)
+
+    async def chunk_document(self, request: DocumentChunkRequest) -> DocumentChunkResult:
+        return await self._execute("document_chunk", request.to_params(), DocumentChunkResult)
+
+    async def rebind_document(self, request: DocumentRebindRequest) -> DocumentRebindResult:
+        return await self._execute(
+            "document_rebind", request.to_params(), DocumentRebindResult
+        )
+
+    async def get_processing_status(
+        self, request: ProcessingStatusRequest
+    ) -> ProcessingStatusResult:
+        return await self._execute(
+            "processing_status", request.to_params(), ProcessingStatusResult
+        )
+
+    async def get_document(self, request: DocumentGetRequest) -> DocumentGetResult:
+        return await self._execute("document_get", request.to_params(), DocumentGetResult)
+
+    async def get_chapter(self, request: ChapterGetRequest) -> ChapterGetResult:
+        return await self._execute("chapter_get", request.to_params(), ChapterGetResult)
+
+    async def get_paragraph(self, request: ParagraphGetRequest) -> ParagraphGetResult:
+        return await self._execute("paragraph_get", request.to_params(), ParagraphGetResult)
+
+    async def get_paragraph_by_number(
+        self,
+        request: ParagraphGetByNumberRequest,
+    ) -> ParagraphGetByNumberResult:
+        return await self._execute(
+            "paragraph_get_by_number",
+            request.to_params(),
+            ParagraphGetByNumberResult,
+        )
+
+    async def delete_document(self, request: DocumentDeleteRequest) -> DocumentDeleteResult:
+        return await self._execute("document_delete", request.to_params(), DocumentDeleteResult)
+
+    async def list_entities(self, request: EntityListRequest) -> EntityListResult:
+        return await self._execute("entity_list", request.to_params(), EntityListResult)
+
+    async def get_entity(self, request: EntityGetRequest) -> EntityGetResult:
+        return await self._execute("entity_get", request.to_params(), EntityGetResult)
+
+    async def soft_delete_entities(self, request: EntityIdsRequest) -> EntityLifecycleResult:
+        return await self._execute("entity_soft_delete", request.to_params(), EntityLifecycleResult)
+
+    async def undelete_entities(self, request: EntityIdsRequest) -> EntityLifecycleResult:
+        return await self._execute("entity_undelete", request.to_params(), EntityLifecycleResult)
+
+    async def hard_delete_entities(self, request: EntityIdsRequest) -> EntityLifecycleResult:
+        return await self._execute("entity_hard_delete", request.to_params(), EntityLifecycleResult)
+
+    async def get_entity_references(self, request: EntityReferencesRequest) -> EntityReferencesResult:
+        return await self._execute("entity_references", request.to_params(), EntityReferencesResult)
+
+    async def search(self, query: ChunkQuery) -> SearchResult:
+        return await self._execute("chunk_query_search", {"query": _dump_query(query)}, SearchResult)
+
+    async def upload_file(
+        self,
+        source_path: str,
+        *,
+        filename: str | None = None,
+        compression: str = "identity",
+        chunk_size: int | None = None,
+        on_progress: Any = None,
+    ) -> Mapping[str, Any]:
+        """Upload a file through the injected adapter and return a transfer reference."""
+
+        upload = getattr(self._adapter_client, "upload_file", None)
+        if upload is None:
+            raise TypeError("adapter client does not expose upload_file")
+        receipt = await upload(
+            source_path,
+            filename=filename,
+            compression=compression,
+            chunk_size=chunk_size,
+            on_progress=on_progress,
+        )
+        return _completed_transfer_reference(receipt)
+
+    async def _write_params(
+        self,
+        request: DocumentCreateRequest | DocumentUpdateRequest,
+        *,
+        source_path: str | None,
+        filename: str | None,
+    ) -> dict[str, Any]:
+        if source_path is None:
+            if request.raw_text is None and request.transferred_file is None:
+                raise ValueError("raw_text, transferred_file, or source_path is required")
+            return request.to_params()
+        transfer_ref = await self.upload_file(source_path, filename=filename)
+        params = request.to_params()
+        params.pop("raw_text", None)
+        params["transferred_file"] = transfer_ref
+        return params
+
+    async def _execute(self, command: str, params: Mapping[str, Any], result_type: type[T]) -> T:
+        response = await self._adapter_client.execute_command_unified(command, dict(params))
+        payload = _unwrap_response(response, expect_mapping=True)
+        if hasattr(result_type, "from_payload"):
+            return result_type.from_payload(payload)  # type: ignore[attr-defined,no-any-return]
+        return result_type(**payload)  # type: ignore[call-arg]
+
+
+def _merge_params(
+    params: Mapping[str, Any] | None,
+    kwargs: Mapping[str, Any],
+) -> dict[str, Any]:
+    if params is None:
+        result: dict[str, Any] = {}
+    elif isinstance(params, Mapping):
+        result = dict(params)
+    else:
+        raise TypeError("params must be a mapping")
+    duplicate = sorted(set(result).intersection(kwargs))
+    if duplicate:
+        raise ValueError(f"duplicate parameters: {', '.join(duplicate)}")
+    result.update(kwargs)
+    return result
+
+
+def _unwrap_response(response: Any, *, expect_mapping: bool = False) -> Any:
+    if isinstance(response, Mapping):
+        if _is_adapter_envelope(response):
+            return _unwrap_response(response["result"], expect_mapping=expect_mapping)
+        if _is_queue_status_payload(response):
+            return _unwrap_response(response["result"], expect_mapping=expect_mapping)
+        if response.get("success") is False:
+            raise DocStoreClientError(_error_from_payload(response))
+        data = response.get("data", response)
+        if isinstance(data, Mapping) or not expect_mapping:
+            return data
+    data = getattr(response, "data", response)
+    success = getattr(response, "success", True)
+    if success is False:
+        raise DocStoreClientError(
+            ServerError(
+                code=str(getattr(response, "code", "SERVER_ERROR")),
+                message=str(getattr(response, "error", "command failed")),
+                details=getattr(response, "details", None),
+            )
+        )
+    if isinstance(data, Mapping) or not expect_mapping:
+        return data
+    raise TypeError("adapter response data must be an object")
+
+
+def _is_adapter_envelope(response: Mapping[str, Any]) -> bool:
+    return "mode" in response and "result" in response
+
+
+def _is_queue_status_payload(response: Mapping[str, Any]) -> bool:
+    result = response.get("result")
+    return (
+        "job_id" in response
+        and "command" in response
+        and isinstance(result, Mapping)
+    )
+
+
+def _error_from_payload(payload: Mapping[str, Any]) -> ServerError:
+    details = payload.get("details")
+    error = payload.get("error")
+    if isinstance(error, Mapping):
+        values = dict(error)
+        values.setdefault("code", str(payload.get("code", "SERVER_ERROR")))
+        values.setdefault("message", str(values.get("message", "command failed")))
+        return ServerError.from_payload(values)
+    return ServerError(
+        code=str(payload.get("code", "SERVER_ERROR")),
+        message=str(error or "command failed"),
+        details=details if isinstance(details, Mapping) else None,
+    )
+
+
+def _completed_transfer_reference(receipt: Any) -> Mapping[str, Any]:
+    completed = (
+        receipt.get("completed")
+        if isinstance(receipt, Mapping)
+        else getattr(receipt, "completed", False)
+    )
+    if completed is not True:
+        raise DocStoreClientError(
+            ServerError(code="TRANSFER_INCOMPLETE", message="file transfer did not complete")
+        )
+    if isinstance(receipt, Mapping):
+        transfer_id = receipt.get("transfer_id") or receipt.get("id")
+        values = dict(receipt)
+    else:
+        transfer_id = getattr(receipt, "transfer_id", None) or getattr(receipt, "id", None)
+        values = {
+            key: getattr(receipt, key, None)
+            for key in (
+                "transfer_id",
+                "id",
+                "filename",
+                "path",
+                "size_bytes",
+                "checksum_algorithm",
+                "checksum_value",
+                "compression",
+                "chunk_size",
+                "status",
+                "plaintext_size_bytes",
+            )
+        }
+    values["transfer_id"] = transfer_id
+    result = {
+        key: value
+        for key, value in values.items()
+        if key != "completed" and value is not None and key != "id"
+    }
+    if not result:
+        raise DocStoreClientError(
+            ServerError(code="TRANSFER_REFERENCE_MISSING", message="file transfer reference is missing")
+        )
+    return result
+
+
+def _dump_query(query: ChunkQuery) -> Mapping[str, Any]:
+    if hasattr(query, "model_dump"):
+        return query.model_dump(mode="python", exclude_none=True, exclude_unset=True)
+    if is_dataclass(query):
+        return {
+            key: value
+            for key, value in query.__dict__.items()
+            if value is not None
+        }
+    if isinstance(query, Mapping):
+        return dict(query)
+    raise TypeError("query must be a chunk_metadata_adapter.ChunkQuery")
+
+
+__all__ = [
+    "DOC_STORE_COMMANDS",
+    "DocStoreClient",
+    "DocStoreClientError",
+    "JsonRpcClientLike",
+    "TransferClientLike",
+]

doc_store_client/models.py

@@ -0,0 +1,491 @@
+"""Stable, transport-neutral public contracts for ``doc-store-client``.
+
+The models intentionally contain validation and payload conversion only.  They
+do not know how a command is sent, queued, retried, persisted, or transferred.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, fields
+from typing import Any, ClassVar, Mapping, Self
+
+from chunk_metadata_adapter import ChunkQuery
+
+
+Payload = Mapping[str, Any]
+
+
+def _payload(model: Any, *, omit_none: bool = True) -> dict[str, Any]:
+    """Return fields in declaration order using their public server names."""
+
+    result: dict[str, Any] = {}
+    for model_field in fields(model):
+        value = getattr(model, model_field.name)
+        if omit_none and value is None:
+            continue
+        if isinstance(value, tuple):
+            value = list(value)
+        result[model_field.name] = value
+    return result
+
+
+def _read(cls: type[Any], payload: Payload) -> Any:
+    """Build a model while rejecting unknown server fields deterministically."""
+
+    known = {model_field.name for model_field in fields(cls)}
+    unknown = sorted(set(payload) - known)
+    if unknown:
+        raise ValueError(f"unknown {cls.__name__} fields: {', '.join(unknown)}")
+    return cls(
+        **{
+            model_field.name: payload[model_field.name]
+            for model_field in fields(cls)
+            if model_field.name in payload
+        }
+    )
+
+
+class PublicModel:
+    """Small common API shared by all public payload models."""
+
+    _omit_none: ClassVar[bool] = True
+
+    def to_params(self) -> dict[str, Any]:
+        return _payload(self, omit_none=self._omit_none)
+
+    def to_payload(self) -> dict[str, Any]:
+        return self.to_params()
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        if not isinstance(payload, Mapping):
+            raise TypeError(f"{cls.__name__} payload must be an object")
+        return _read(cls, payload)
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentWriteRequest(PublicModel):
+    """Shared source contract for document create and update."""
+
+    document_id: str
+    source_version_id: str
+    raw_text: str | None = None
+    transferred_file: Mapping[str, Any] | None = None
+    chunking_strategy: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.document_id.strip() or not self.source_version_id.strip():
+            raise ValueError("document_id and source_version_id must be non-empty")
+        if self.raw_text is not None and self.transferred_file is not None:
+            raise ValueError("raw_text and transferred_file are mutually exclusive")
+        if self.raw_text is not None and not self.raw_text:
+            raise ValueError("raw_text must be non-empty")
+        if self.chunking_strategy is not None and self.chunking_strategy not in {
+            "paragraph",
+            "sentence",
+            "semantic",
+        }:
+            raise ValueError("chunking_strategy must be paragraph, sentence, or semantic")
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentCreateRequest(DocumentWriteRequest):
+    """Request payload for ``document_create``."""
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if self.chunking_strategy is None:
+            raise ValueError("chunking_strategy is required")
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentUpdateRequest(DocumentWriteRequest):
+    """Request payload for ``document_update``."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentWriteResult(PublicModel):
+    """Stable result returned by document create/update operations."""
+
+    status: str
+    operation_id: str
+    document_id: str
+    source_version_id: str
+    details: Mapping[str, Any] | None = None
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        known = {model_field.name for model_field in fields(cls)}
+        extras = {key: values.pop(key) for key in sorted(set(values) - known)}
+        if extras:
+            details = dict(values.get("details") or {})
+            details.update(extras)
+            values["details"] = details
+        return _read(cls, values)
+
+
+DocumentCreateResult = DocumentWriteResult
+DocumentUpdateResult = DocumentWriteResult
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentChunkRequest(PublicModel):
+    document_id: str
+    chunking_strategy: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.document_id.strip():
+            raise ValueError("document_id must be non-empty")
+        if self.chunking_strategy is not None and self.chunking_strategy not in {
+            "paragraph",
+            "sentence",
+            "semantic",
+        }:
+            raise ValueError("chunking_strategy must be paragraph, sentence, or semantic")
+
+
+DocumentChunkResult = DocumentWriteResult
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentRebindRequest(PublicModel):
+    document_id: str
+    project: str | None = None
+    document_properties: Mapping[str, Any] | None = None
+    chunk_properties: Mapping[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        if not self.document_id.strip():
+            raise ValueError("document_id must be non-empty")
+        if self.project is not None and not self.project.strip():
+            raise ValueError("project must be non-empty when supplied")
+        if not any(
+            value is not None
+            for value in (self.project, self.document_properties, self.chunk_properties)
+        ):
+            raise ValueError("at least one rebind field is required")
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentRebindResult(PublicModel):
+    outcome: str
+    document_id: str
+    project: str | None = None
+    document_properties: Mapping[str, Any] | None = None
+    chunk_properties: Mapping[str, Any] | None = None
+    updated: Mapping[str, Any] | None = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentDeleteRequest(PublicModel):
+    document_id: str
+    version_token: str
+
+    def __post_init__(self) -> None:
+        if not self.document_id.strip() or not self.version_token.strip():
+            raise ValueError("document_id and version_token must be non-empty")
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentDeleteResult(PublicModel):
+    outcome: str
+    document_id: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityListRequest(PublicModel):
+    entity_type: str
+    fields: tuple[str, ...] | None = None
+    filters: Mapping[str, Any] | None = None
+    limit: int = 50
+    offset: int = 0
+    show_deleted: bool = False
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityGetRequest(PublicModel):
+    entity_type: str
+    entity_id: str
+    fields: tuple[str, ...] | None = None
+    show_deleted: bool = False
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityIdsRequest(PublicModel):
+    entity_type: str
+    ids: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        if not self.ids:
+            raise ValueError("ids must be non-empty")
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityReferencesRequest(PublicModel):
+    entity_type: str
+    entity_id: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityListResult(PublicModel):
+    entity_type: str
+    items: tuple[Mapping[str, Any], ...] = ()
+    limit: int = 50
+    offset: int = 0
+    total: int = 0
+    show_deleted: bool = False
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        values["items"] = tuple(values.get("items", ()))
+        return _read(cls, values)
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityGetResult(PublicModel):
+    entity_type: str
+    id: str
+    value: Mapping[str, Any]
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityLifecycleResult(PublicModel):
+    outcome: str
+    updated: Mapping[str, int] | None = None
+    deleted: Mapping[str, int] | None = None
+    blocked: tuple[Mapping[str, Any], ...] = ()
+    is_deleted: bool | None = None
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        values["blocked"] = tuple(values.get("blocked", ()))
+        return _read(cls, values)
+
+
+@dataclass(frozen=True, kw_only=True)
+class EntityReferencesResult(PublicModel):
+    entity_type: str
+    id: str
+    references: tuple[Mapping[str, Any], ...] = ()
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        values["references"] = tuple(values.get("references", ()))
+        return _read(cls, values)
+
+
+@dataclass(frozen=True, kw_only=True)
+class ProcessingStatusRequest(PublicModel):
+    operation_id: str
+    document_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.operation_id.strip() or (
+            self.document_id is not None and not self.document_id.strip()
+        ):
+            raise ValueError("operation_id and document_id must be non-empty when supplied")
+
+
+@dataclass(frozen=True, kw_only=True)
+class ServerError(PublicModel):
+    """Structured error data returned by a server command."""
+
+    code: str
+    message: str
+    details: Mapping[str, Any] | None = None
+    type: str | None = None
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        known = {model_field.name for model_field in fields(cls)}
+        extras = {key: values.pop(key) for key in sorted(set(values) - known)}
+        if extras:
+            details = dict(values.get("details") or {})
+            details.update(extras)
+            values["details"] = details
+        return _read(cls, values)
+
+
+@dataclass(frozen=True, kw_only=True)
+class ProcessingStatusResult(PublicModel):
+    operation_id: str
+    status: str
+    progress: int | float | None = None
+    timestamps: Mapping[str, Any] = field(default_factory=dict)
+    document_reference: str | None = None
+    version_reference: str | None = None
+    failure: ServerError | Mapping[str, Any] | None = None
+    document_id: str | None = None
+    requested_document_id: str | None = None
+
+    def to_params(self) -> dict[str, Any]:
+        result = _payload(self)
+        if isinstance(self.failure, ServerError):
+            result["failure"] = self.failure.to_payload()
+        return result
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        failure = values.get("failure")
+        if isinstance(failure, Mapping):
+            values["failure"] = ServerError.from_payload(failure)
+        return _read(cls, values)
+
+
+@dataclass(frozen=True, kw_only=True)
+class RetrievalRequest(PublicModel):
+    source_version: int | None = None
+
+    def __post_init__(self) -> None:
+        if self.source_version is not None and (
+            isinstance(self.source_version, bool) or self.source_version <= 0
+        ):
+            raise ValueError("source_version must be a positive integer")
+
+
+@dataclass(frozen=True, kw_only=True)
+class DocumentGetRequest(RetrievalRequest):
+    document_id: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class ChapterGetRequest(RetrievalRequest):
+    chapter_id: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class ParagraphGetRequest(RetrievalRequest):
+    paragraph_id: str
+
+
+@dataclass(frozen=True, kw_only=True)
+class ParagraphGetByNumberRequest(RetrievalRequest):
+    document_id: str
+    paragraph_number: int
+
+    def __post_init__(self) -> None:
+        super().__post_init__()
+        if not self.document_id.strip():
+            raise ValueError("document_id must be non-empty")
+        if isinstance(self.paragraph_number, bool) or self.paragraph_number < 1:
+            raise ValueError("paragraph_number must be a positive integer")
+
+
+@dataclass(frozen=True, kw_only=True)
+class RetrievalResult(PublicModel):
+    entity: str
+    identifier: str
+    source_version: int | None = None
+    value: Any = None
+
+
+DocumentGetResult = RetrievalResult
+ChapterGetResult = RetrievalResult
+ParagraphGetResult = RetrievalResult
+
+
+@dataclass(frozen=True, kw_only=True)
+class ParagraphGetByNumberResult(PublicModel):
+    entity: str
+    document_id: str
+    paragraph_number: int
+    identifier: str | None = None
+    source_version: int | None = None
+    text: str | None = None
+    value: Any = None
+
+
+@dataclass(frozen=True, kw_only=True)
+class RankedSearchHit(PublicModel):
+    chunk_id: str
+    chunk: Mapping[str, Any]
+    bm25_score: float | None = None
+    semantic_score: float | None = None
+    hybrid_score: float | None = None
+    rank: int = 0
+    matched_fields: tuple[str, ...] | None = None
+    highlights: Mapping[str, tuple[str, ...]] | None = None
+    search_metadata: Mapping[str, Any] | None = None
+
+    def __post_init__(self) -> None:
+        for name in ("bm25_score", "semantic_score", "hybrid_score"):
+            score = getattr(self, name)
+            if score is not None and not 0 <= score <= 1:
+                raise ValueError(f"{name} must be between 0 and 1")
+        if self.rank < 0:
+            raise ValueError("rank must be non-negative")
+
+
+@dataclass(frozen=True, kw_only=True)
+class SearchResult(PublicModel):
+    status: str
+    results: tuple[RankedSearchHit, ...] = ()
+    total_results: int | None = None
+    search_time: float | None = None
+    query_time: float | None = None
+    metadata: Mapping[str, Any] | None = None
+    error: ServerError | Mapping[str, Any] | None = None
+
+    def to_params(self) -> dict[str, Any]:
+        result = _payload(self)
+        result["results"] = [hit.to_payload() for hit in self.results]
+        if isinstance(self.error, ServerError):
+            result["error"] = self.error.to_payload()
+        return result
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        nested = values.pop("data", None)
+        if isinstance(nested, Mapping):
+            values = {**dict(nested), **values}
+        values.setdefault("status", "success")
+        values["results"] = tuple(
+            RankedSearchHit.from_payload(item) for item in values.get("results", ())
+        )
+        if isinstance(values.get("error"), Mapping):
+            values["error"] = ServerError.from_payload(values["error"])
+        return _read(cls, values)
+
+
+@dataclass(frozen=True, kw_only=True)
+class OperationState(PublicModel):
+    operation_id: str
+    status: str
+    document_id: str | None = None
+    source_version_id: str | None = None
+    message: str | None = None
+    error: ServerError | Mapping[str, Any] | None = None
+
+    def to_params(self) -> dict[str, Any]:
+        result = _payload(self)
+        if isinstance(self.error, ServerError):
+            result["error"] = self.error.to_payload()
+        return result
+
+    @classmethod
+    def from_payload(cls, payload: Payload) -> Self:
+        values = dict(payload)
+        if isinstance(values.get("error"), Mapping):
+            values["error"] = ServerError.from_payload(values["error"])
+        return _read(cls, values)
+
+
+__all__ = [
+    "ChapterGetRequest", "ChapterGetResult", "ChunkQuery", "DocumentCreateRequest",
+    "DocumentCreateResult", "DocumentChunkRequest", "DocumentChunkResult",
+    "DocumentDeleteRequest", "DocumentDeleteResult", "DocumentGetRequest", "DocumentGetResult",
+    "DocumentRebindRequest", "DocumentRebindResult", "DocumentUpdateRequest", "DocumentUpdateResult",
+    "DocumentWriteRequest", "DocumentWriteResult", "EntityGetRequest", "EntityGetResult",
+    "EntityIdsRequest", "EntityLifecycleResult", "EntityListRequest", "EntityListResult",
+    "EntityReferencesRequest", "EntityReferencesResult", "OperationState",
+    "ParagraphGetByNumberRequest", "ParagraphGetByNumberResult", "ParagraphGetRequest",
+    "ParagraphGetResult", "ProcessingStatusRequest", "ProcessingStatusResult", "RankedSearchHit",
+    "RetrievalRequest", "RetrievalResult", "SearchResult", "ServerError",
+]

doc_store_client-0.1.13.dist-info/METADATA

@@ -0,0 +1,28 @@
+Metadata-Version: 2.4
+Name: doc-store-client
+Version: 0.1.13
+Summary: Client library for the doc-store documentation service.
+Author: Vasiliy Zdanovskiy
+License-Expression: MIT
+Keywords: documentation,client,search,json-rpc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: chunk-metadata-adapter>=1.0
+Requires-Dist: mcp-proxy-adapter>=8.10.19
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Provides-Extra: dev
+Requires-Dist: doc-store-client[test]; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"

doc_store_client-0.1.13.dist-info/RECORD

@@ -0,0 +1,8 @@
+doc_store_client/__init__.py,sha256=zGdwYZUcKnJOKOkiIoC-_sOUTZhfl8eLN_MS4eAevzY,2645
+doc_store_client/client.py,sha256=WKclGLa5bMwyYd2x3StyFdS67RyPSMP7PJ5DeIeUQ7M,22347
+doc_store_client/models.py,sha256=N0cs9xqQThIdTY7HKLzztkMh3wW1TmN3pOsvuo24yQo,15867
+doc_store_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+doc_store_client-0.1.13.dist-info/METADATA,sha256=eEIhhS_nFF7QSaU8nLyyFUWvid24MtCDfh4VmoGKkrc,1143
+doc_store_client-0.1.13.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+doc_store_client-0.1.13.dist-info/top_level.txt,sha256=cSF9OOihvUVfWDssZhp9dafdIvYdC6y3qgsHn57o85U,17
+doc_store_client-0.1.13.dist-info/RECORD,,

doc_store_client-0.1.13.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

doc_store_client-0.1.13.dist-info/top_level.txt

@@ -0,0 +1 @@
+doc_store_client