ailogger-client-dev 0.1.51__py3-none-any.whl

ailogger_client/file_transfer.py

@@ -0,0 +1,110 @@
+"""
+File transfer methods for dialogue import and export.
+
+This module carries the single mixin class that names the two methods a caller
+would use to import a dialogue from a file and to export a dialogue to a file.
+Import and export are not designed yet: neither method does transfer work when
+called. Each is fully declared and fully annotated, and each raises
+NotImplementedError with a message that states plainly that import and export
+are not designed yet and that transfer will be built on the framework client's
+own transfer surface (upload_file, resume_upload, download_file,
+resume_download, execute_command_with_file) when they are.
+
+The framework client held privately by the client object carries the complete
+chunked transfer surface. This client wraps that framework client and exposes
+only the dialogue vocabulary of the ai-logger service. But the dialogue surface
+has no command that carries a file - no message carries one and no read returns
+one. Transfer between this client and this service is wanted for exactly one
+purpose: importing a dialogue from a file and exporting a dialogue to a file.
+That purpose is not designed yet, and no step of the plan owns its design.
+
+A consumer that reaches for dialogue import or export should meet a definite
+answer rather than a missing attribute error, and the eventual work should have
+a named place already established for it.
+
+NETWORK LAW. This module imports no aiohttp, httpx, requests, fastapi, uvicorn
+or standalone websocket client; opens no socket and no file; assemble no
+address, connection, session or security context by hand; and builds no request
+envelope. This module adds no transport of its own: the privately held framework
+client carries all transfer, and nothing here touches it. Every declaration in
+this file is fully annotated for the pipeline's named strict type check, and the
+module satisfies its named lint check.
+
+BOUNDARIES. This module declares no typed method for any command of the service
+surface. It does not add a generic call, a completion default, a non-blocking
+path or any job-observing call. It defines no error vocabulary and does not
+fold this refusal into any error type: NotImplementedError is the language's
+own. Import and export are not designed here and remain unimplemented: they
+will be built on the framework client's transfer surface (upload_file,
+download_file, execute_command_with_file, etc.) when design work completes.
+"""
+
+from __future__ import annotations
+
+__all__ = ["FileTransferMixin"]
+
+
+class FileTransferMixin:
+    """Mixin providing methods for dialogue file transfer.
+
+    Declares the two methods by which a caller would import a dialogue from a
+    file and export a dialogue to a file. Import and export are not designed
+    yet: each method raises NotImplementedError when called, with a message
+    stating plainly that import and export are not designed yet and that
+    transfer will be built on the framework client's own transfer surface when
+    they are.
+
+    This mixin does not compose with InvocationMixin and does not touch the
+    framework client's transfer surface. When import and export are eventually
+    designed, they will be built on that surface rather than on anything in
+    this mixin.
+    """
+
+    async def import_dialogue(self, source_path: str) -> None:
+        """Import a dialogue from a file.
+
+        Dialogue import is not designed yet. When called, this method raises
+        NotImplementedError. Transfer will be built on the framework client's
+        own transfer surface (upload_file, resume_upload,
+        execute_command_with_file) when import design completes.
+
+        Args:
+            source_path: Path to the file containing the dialogue to import.
+
+        Raises:
+            NotImplementedError: Dialogue import is not designed yet. Transfer
+                will be built on the framework client's transfer surface when
+                designed.
+        """
+        raise NotImplementedError(
+            "Dialogue import is not designed yet. Transfer will be built on "
+            "the framework client's transfer surface when designed."
+        )
+
+    async def export_dialogue(self, destination_path: str) -> None:
+        """Export a dialogue to a file.
+
+        Dialogue export is not designed yet. When called, this method raises
+        NotImplementedError. Transfer will be built on the framework client's
+        own transfer surface (download_file, resume_download,
+        execute_command_with_file) when export design completes.
+
+        Args:
+            destination_path: Path where the exported dialogue file will be
+                written.
+
+        Raises:
+            NotImplementedError: Dialogue export is not designed yet. Transfer
+                will be built on the framework client's transfer surface when
+                designed.
+        """
+        raise NotImplementedError(
+            "Dialogue export is not designed yet. Transfer will be built on "
+            "the framework client's transfer surface when designed."
+        )
+
+
+# TODO(G-012/T-002/A-010): dialogue import/export deliberately deferred -- no
+# step of the plan owns their design yet; build on the framework client's
+# transfer surface (upload_file/download_file/execute_command_with_file) when
+# designed.

ailogger_client/invocation.py

@@ -0,0 +1,550 @@
+"""
+Invocation entry point for the ai-logger client.
+
+This module declares the single seam through which every caller-facing method of
+the client reaches the service. It carries no typed method of any command, only:
+
+- A private invocation entry point that takes a command name and a mapping of
+  parameters, carries them unchanged to the framework client's own invocation
+  surface, and returns what that surface returns.
+
+- A public generic call that takes a command name and a mapping of parameters
+  and reaches any command of the service, including a command the service
+  publishes after this client was released, so a growing surface stays usable
+  from an already installed client.
+
+The private entry point is a naming, not machinery: request and answer
+serialisation, connection handling, retries, timeouts, OpenAPI schema fetching,
+and schema validation are the framework client's own work and are reached
+through the held instance. No request envelope, no JSON-RPC payload, no address,
+no header set, and no transport concept in any signature, argument or return
+type appears here.
+
+NETWORK LAW. This module imports nothing from the adapter framework's
+implementation; it does not reach the framework client except through the single
+private route (_client attribute) and calls only the methods it publishes.
+Connection handling, retries, timeouts, and all other transport concerns remain
+the framework's responsibility.
+
+COMPOSITION. This module defines a mixin class, intended to be composed into
+the AiLoggerClient so the typed methods added by the plan's later steps reach
+the service through the single invocation entry point here.
+
+JOB OBSERVATION. When a command is executed with wait_for_result=False and the
+service queues the command, the client returns a job identity envelope. The
+caller may then use the job observation methods (get_job_status, get_job_messages,
+cancel_command) to track the job's progress. These methods are not typed commands
+of the service; they are observation surfaces over the framework client's own
+job-tracking API and are not counted in the client-surface-agreement comparison.
+
+A-007 SECTION: Guarded Seam and Refusal Recognition
+
+Every route through which this module reaches the privately held framework
+client is wrapped in the reusable translation guard (translated_failures) from
+G-012/T-003/A-002. The guard catches framework ClientError, translates it to
+this client's vocabulary via translate_framework_failure, and raises it with the
+original as its cause. Plain programming errors (ValueError, RuntimeError) and
+the NotImplementedError from undesigned file-transfer methods propagate
+unchanged.
+
+The answer-borne refusal recogniser (refusal_from_answer) is applied exactly
+once: in _invoke, on the completed answer (the default wait_for_result=True
+path), immediately before the return, so a refusal carried intact over a working
+transport becomes the same service-refusal kind as one that arrives as a raised
+failure. The non-blocking queued envelope and the job-observing calls' answers
+are not passed through the recogniser. Both routes (raised and answer-borne)
+end in the same ServiceRefusalError kind.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from collections.abc import Mapping
+from typing import Any, Final, Protocol
+
+from .config import SYNC_FALLBACK_WAIT_SECONDS
+from .errors import (
+    CompletionFailedError,
+    ResultUnavailableError,
+    SyncFallbackWaitExhaustedError,
+    refusal_from_answer,
+    translated_failures,
+)
+
+__all__ = ["InvocationMixin", "is_sync_timeout_fallback"]
+
+#: How often the client asks the queue for the status of a followed job, in
+#: seconds.
+_FALLBACK_POLL_SECONDS: Final[float] = 1.0
+
+#: Job-status values that end a job without a usable result.
+_FALLBACK_FAILED_STATUSES: Final[frozenset[str]] = frozenset(
+    {"failed", "error", "timeout", "stopped", "cancelled"}
+)
+
+#: Job-status values that end a job with its result.
+_FALLBACK_DONE_STATUSES: Final[frozenset[str]] = frozenset({"completed"})
+
+
+def is_sync_timeout_fallback(answer: object) -> bool:
+    """
+    Whether ``answer`` is the service's sync-timeout queue fallback: the
+    acknowledgement of a command that overran the synchronous cap, carrying a job
+    identity and ``queued_after_timeout`` true instead of the command's result.
+    """
+    if not isinstance(answer, Mapping):
+        return False
+    job_id = answer.get("job_id")
+    return (
+        answer.get("queued_after_timeout") is True
+        and isinstance(job_id, str)
+        and bool(job_id.strip())
+    )
+
+
+def _job_answer(outcome: object) -> dict[str, Any] | None:
+    """
+    The command's own answer inside a finished job's ``result``: the envelope the
+    job's command returned (``result.result``), or the result itself when it is
+    already an envelope. ``None`` when the job carries none.
+    """
+    if not isinstance(outcome, Mapping):
+        return None
+    inner = outcome.get("result")
+    if isinstance(inner, Mapping):
+        return dict(inner)
+    if "success" in outcome:
+        return dict(outcome)
+    return None
+
+
+class _FrameworkClientProtocol(Protocol):
+    """Protocol for the type of the held framework client instance.
+
+    Defines the minimal interface this mixin expects from the held _client
+    attribute, allowing strict type checking without importing the concrete
+    JsonRpcClient class.
+    """
+
+    async def execute_command_unified(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        *,
+        expect_queue: bool | None = None,
+        auto_poll: bool = True,
+        timeout: float | None = None,
+    ) -> Any:
+        """Execute a command, transparently handling queued or immediate responses.
+
+        When the service answers by queueing, this method waits for the job to
+        reach a terminal state via the framework's WebSocket facilities and
+        returns the finished answer. When the service answers directly, it
+        returns the answer immediately. To the caller, both paths are
+        indistinguishable: the return value in both cases is the finished
+        command result.
+
+        Args:
+            command: Name of the command to execute.
+            params: Optional mapping of command parameters.
+            auto_poll: When True (default), wait for queued jobs to completion.
+            timeout: Maximum seconds to wait for a queued job. Defaults to
+                the framework's configured timeout.
+
+        Returns:
+            A dictionary with "mode" and "result" keys. The "mode" field
+            indicates whether the response was "immediate" or "queued"; the
+            "result" field holds the finished command result.
+        """
+        ...
+
+    async def get_job_status(
+        self,
+        job_id: str,
+        *,
+        sync_from_queue: bool = False,
+    ) -> Any:
+        """Return the status snapshot for a job.
+
+        Args:
+            job_id: The job identifier.
+            sync_from_queue: When True, fetch status from the server queue
+                and merge it with locally recorded events.
+
+        Returns:
+            A job status snapshot with normalized fields.
+        """
+        ...
+
+    async def get_job_messages(
+        self,
+        job_id: str,
+        *,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Return the progress messages recorded for a job.
+
+        Args:
+            job_id: The job identifier.
+            limit: Maximum number of recent messages to return.
+
+        Returns:
+            A list of message dictionaries (oldest first).
+        """
+        ...
+
+    async def queue_get_job_status(self, job_id: str) -> dict[str, Any]:
+        """Return the raw ``queue_get_job_status`` answer of the service.
+
+        Args:
+            job_id: The job identifier.
+
+        Returns:
+            The queue's answer: ``{"success": ..., "data": {"status": ...,
+            "result": ...}}``.
+        """
+        ...
+
+    async def cancel_command(
+        self,
+        job_id: str,
+    ) -> dict[str, Any]:
+        """Cancel a queued command execution.
+
+        Args:
+            job_id: The job identifier.
+
+        Returns:
+            The result of the cancellation operation.
+        """
+        ...
+
+
+class InvocationMixin:
+    """Mixin providing the single invocation seam for the ai-logger client.
+
+    Declares the private invocation entry point through which all typed methods
+    reach the service, and the public generic call for commands not yet named.
+
+    The held _client attribute (an instance of the adapter framework's
+    JsonRpcClient) is accessed only through the private invocation entry point,
+    so the service is reached through exactly one place in the client codebase.
+    """
+
+    # _client is declared here for type annotation purposes only.
+    # At runtime, _client is set by AiLoggerClient.__init__ to an instance
+    # of mcp_proxy_adapter.client.jsonrpc_client.JsonRpcClient.
+    _client: _FrameworkClientProtocol
+
+    # How long a command that overran the service's sync cap is followed to the
+    # end of its queued job; AiLoggerClient.__init__ replaces it with the
+    # configured ``client.sync_fallback_wait_seconds``.
+    _sync_fallback_wait_seconds: float = SYNC_FALLBACK_WAIT_SECONDS
+
+    async def _invoke(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        *,
+        wait_for_result: bool = True,
+    ) -> Any:
+        """Private invocation entry point.
+
+        Forwards the command name and parameters to the held framework
+        client's execute_command_unified method with ``expect_queue=False``.
+        Every ai-logger command is declared direct, so this selects the
+        adapter's HTTP JSON-RPC path and avoids opening a WebSocket command
+        session before the request. The caller receives the direct command
+        result without any job identity or status.
+
+        The ``wait_for_result`` argument remains part of the public client
+        surface for compatibility, but direct commands do not queue and return
+        their result on either path.
+
+        This is the single seam through which every typed method of the
+        client reaches the service.
+
+        Every call to the framework client is wrapped in the reusable
+        translation guard (A-007): a ClientError from the framework is
+        translated to this client's vocabulary and raised with the original
+        as its cause. Plain programming errors propagate unchanged.
+
+        SYNC-TIMEOUT FALLBACK. A command that overruns the service's sync cap
+        is answered with the acknowledgement of a detached job (``job_id``,
+        ``queued_after_timeout`` true) instead of its result. The client then
+        follows that job with ``queue_get_job_status`` until it ends, within
+        ``client.sync_fallback_wait_seconds``, and continues with the answer
+        the job finished with, so the caller sees what an inline call returns.
+        The command is dispatched once. When the wait runs out,
+        ``SyncFallbackWaitExhaustedError`` (with the ``job_id``) is raised.
+
+        The answer-borne refusal recogniser is applied exactly once, on the
+        completed answer (the default wait_for_result=True path), immediately
+        before the return (A-007): a refusal carried in the answer dict is
+        recognised and converted to ServiceRefusalError, matching the path
+        where a refusal is raised as a translated framework failure.
+
+        Args:
+            command: The name of the command to execute.
+            params: An optional mapping of command parameters. If None, passed
+                as None to the framework client, which treats it as an empty
+                mapping.
+            wait_for_result: Retained for the public client API. ai-logger
+                commands are direct, so it does not change their result.
+
+        Returns:
+            The direct result returned by the service.
+
+        Raises:
+            ServiceRefusalError: When the service or transport indicates refusal.
+            ServiceUnreachableError: When the service cannot be reached.
+            Any error subclassing AiLoggerClientError: From other failures of
+                the service or transport, translated from framework ClientError.
+            RuntimeError or ValueError: Propagated unchanged if raised by the
+                client itself or the caller's code.
+        """
+        result = await self._invoke_unconverted(command, params, wait_for_result)
+
+        # A command that overran the service's sync cap is answered with the
+        # acknowledgement of a detached job instead of its result: follow that
+        # job (the command is not dispatched again) and carry on with the
+        # command's own answer exactly as if it had been given inline.
+        if is_sync_timeout_fallback(result):
+            result = await self._follow_sync_fallback(result, command)
+
+        # Apply the refusal recogniser exactly once, on the completed answer.
+        # Both the raised route (framework ClientRequestError translated to
+        # ServiceRefusalError) and the answer-borne route (refusal dict
+        # carrying framework_code) end in the same kind.
+        refusal = refusal_from_answer(result, command)
+        if refusal is not None:
+            raise refusal
+
+        return result
+
+    async def _follow_sync_fallback(
+        self, acknowledgement: Mapping[str, Any], command: str
+    ) -> Any:
+        """The command's own answer, taken from the job a sync timeout queued.
+
+        The service answered ``command`` with the sync-timeout acknowledgement:
+        the command was dispatched once and runs on as a job. Poll that job
+        through ``queue_get_job_status`` until it ends and return the answer it
+        finished with - the command's ``{success, data}`` envelope, from
+        ``data.result.result`` of the status answer. A refusing envelope is
+        returned as it is, so the caller's refusal recogniser turns it into the
+        same ``ServiceRefusalError`` the inline answer would have raised.
+
+        Raises:
+            SyncFallbackWaitExhaustedError: When the job does not end within
+                ``client.sync_fallback_wait_seconds``; carries the job id.
+            CompletionFailedError: When the job ends failed without an answer.
+            ResultUnavailableError: When the job ends without an answer.
+        """
+        job_id = str(acknowledgement["job_id"]).strip()
+        limit = self._sync_fallback_wait_seconds
+        deadline = time.monotonic() + limit
+        while True:
+            with translated_failures():
+                raw = await self._client.queue_get_job_status(job_id)
+            data = raw.get("data") if isinstance(raw, Mapping) else None
+            status = ""
+            if isinstance(data, Mapping):
+                status = str(data.get("status") or "").lower()
+            if status in _FALLBACK_DONE_STATUSES or status in _FALLBACK_FAILED_STATUSES:
+                assert isinstance(data, Mapping)
+                answer = _job_answer(data.get("result"))
+                if answer is not None:
+                    return answer
+                if status in _FALLBACK_FAILED_STATUSES:
+                    raise CompletionFailedError(
+                        f"{command} job {job_id} ended {status!r} without an answer"
+                    )
+                raise ResultUnavailableError(
+                    f"{command} job {job_id} ended {status!r} without an answer"
+                )
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise SyncFallbackWaitExhaustedError(
+                    f"{command} exceeded the service's sync timeout and its job "
+                    f"{job_id} did not finish within {limit:g} seconds "
+                    "(client.sync_fallback_wait_seconds)",
+                    job_id,
+                )
+            await asyncio.sleep(min(_FALLBACK_POLL_SECONDS, remaining))
+
+    async def _invoke_unconverted(
+        self,
+        command: str,
+        params: dict[str, Any] | None,
+        wait_for_result: bool,
+    ) -> Any:
+        """The answer of one command as the service gave it, refusals unconverted.
+
+        Everything ``_invoke`` does except recognising an answer-borne refusal:
+        the request goes out through the translation guard (a framework failure
+        arrives as a typed error of this client) and the command's answer comes
+        back as it was, a refusal answer included. Used by the observation
+        methods that classify an answer rather than act on it.
+        """
+        with translated_failures():
+            response: dict[str, Any] = await self._client.execute_command_unified(
+                command,
+                params,
+                expect_queue=False,
+                auto_poll=wait_for_result,
+            )
+
+        # The direct execution path returns the command answer in ``result``.
+        return response.get("result")
+
+    async def call(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        *,
+        wait_for_result: bool = True,
+    ) -> Any:
+        """Execute any command the service publishes.
+
+        A generic invocation interface for commands not yet named in this
+        client. Reaches the service through the private invocation entry
+        point. The command name and parameters are carried unchanged.
+
+        This is an escape hatch, allowing an already-installed client to
+        reach commands published after the client was released, without
+        waiting for a new client release. The client-surface-agreement check
+        owned by the plan counts this method on neither side of its comparison,
+        as it is not a typed method of any command and does not commit the
+        client to any specific command name or contract.
+
+        Args:
+            command: The name of the command to execute. The service need not
+                have published a typed method for this command; any command
+                the service publishes can be reached.
+            params: An optional mapping of command parameters.
+            wait_for_result: When True (default), wait for queued commands to
+                completion and return the finished result. When False, return
+                the job identity if queued, or the direct result if immediate.
+
+        Returns:
+            When wait_for_result is True: the result returned by the service.
+
+            When wait_for_result is False: the job identity envelope if the
+            command was queued, or the direct result if immediate.
+        """
+        return await self._invoke(command, params, wait_for_result=wait_for_result)
+
+    async def get_job_status(
+        self,
+        job_id: str,
+        *,
+        sync_from_queue: bool = False,
+    ) -> Any:
+        """Get the status of a queued command.
+
+        Delegates to the framework client's job-status observation surface to
+        return the current snapshot of a job's execution state. This method
+        is not a command of the service; it is an observation surface over
+        the framework's own job-tracking API and is not counted in the
+        client-surface-agreement comparison.
+
+        The call to the framework client is wrapped in the reusable
+        translation guard (A-007): a ClientError from the framework is
+        translated to this client's vocabulary and raised with the original
+        as its cause.
+
+        Args:
+            job_id: The job identifier, typically returned by a non-blocking
+                command execution (when wait_for_result=False).
+            sync_from_queue: When True, fetch the latest status from the
+                server queue and merge it with locally recorded events. When
+                False (default), use only events recorded locally.
+
+        Returns:
+            A job status snapshot with normalized fields from the framework
+            client's tracking API.
+
+        Raises:
+            Any error subclassing AiLoggerClientError: From failures of
+                the transport, translated from framework ClientError.
+            RuntimeError or ValueError: Propagated unchanged if raised by the
+                client itself.
+        """
+        with translated_failures():
+            return await self._client.get_job_status(
+                job_id, sync_from_queue=sync_from_queue
+            )
+
+    async def get_job_messages(
+        self,
+        job_id: str,
+        *,
+        limit: int | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get progress messages for a queued command.
+
+        Delegates to the framework client's job-message observation surface to
+        return the bounded recent history of progress messages emitted by a
+        job. This method is not a command of the service; it is an observation
+        surface over the framework's own job-tracking API and is not counted
+        in the client-surface-agreement comparison.
+
+        The call to the framework client is wrapped in the reusable
+        translation guard (A-007): a ClientError from the framework is
+        translated to this client's vocabulary and raised with the original
+        as its cause.
+
+        Args:
+            job_id: The job identifier, typically returned by a non-blocking
+                command execution (when wait_for_result=False).
+            limit: Maximum number of recent messages to return. If None, the
+                framework client determines the default limit.
+
+        Returns:
+            A list of message dictionaries in chronological order (oldest
+            first), each containing the fields published by the service or
+            framework for that message.
+
+        Raises:
+            Any error subclassing AiLoggerClientError: From failures of
+                the transport, translated from framework ClientError.
+            RuntimeError or ValueError: Propagated unchanged if raised by the
+                client itself.
+        """
+        with translated_failures():
+            return await self._client.get_job_messages(job_id, limit=limit)
+
+    async def cancel_command(
+        self,
+        job_id: str,
+    ) -> dict[str, Any]:
+        """Cancel a queued command execution.
+
+        Delegates to the framework client's cancellation surface to stop and
+        remove a queued job. This method is not a command of the service; it
+        is an observation surface over the framework's own job-tracking API
+        and is not counted in the client-surface-agreement comparison.
+
+        The call to the framework client is wrapped in the reusable
+        translation guard (A-007): a ClientError from the framework is
+        translated to this client's vocabulary and raised with the original
+        as its cause.
+
+        Args:
+            job_id: The job identifier, typically returned by a non-blocking
+                command execution (when wait_for_result=False).
+
+        Returns:
+            The result dictionary from the framework client's cancellation
+            operation.
+
+        Raises:
+            Any error subclassing AiLoggerClientError: From failures of
+                the transport, translated from framework ClientError.
+            RuntimeError or ValueError: Propagated unchanged if raised by the
+                client itself.
+        """
+        with translated_failures():
+            return await self._client.cancel_command(job_id)