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

ailogger_client/errors.py

@@ -0,0 +1,610 @@
+"""
+Typed error vocabulary for the ai-logger client.
+
+This module declares the typed error vocabulary through which the ai-logger
+client communicates failure to its callers. It is a MAPPING OVER the framework
+client's hierarchy, not an invention: every kind declared here translates a
+named member of the adapter framework's ClientError hierarchy
+(mcp_proxy_adapter.client.jsonrpc_client.exceptions), and every member of that
+hierarchy is covered by a kind declared here or by the family base that
+contains it.
+
+EXHAUSTIVENESS BY CONSTRUCTION. The module names ClientError from the adapter
+framework only in this docstring and in the class docstrings that name it.
+The call site (G-012/T-003/A-002) enforces the mapping at runtime by walking
+the framework's hierarchy at import time and asserting that every subclass is
+covered. This design ensures that if the framework adds a new exception member,
+the runtime walk catches it rather than passing silently. SchemaGeneratorError,
+an intermediate base in the framework's hierarchy, is covered by the
+RequestRejectedError family base (which holds three of its four children); the
+fourth child (MethodNotFoundError) is UnknownCommandError. Together, the
+RequestRejectedError family and UnknownCommandError exhaust SchemaGeneratorError
+and all its children.
+
+NO TRANSPORT DETAIL ON THE CALLER'S SURFACE. Under HRS {loe8}, a caller never
+sees a host, connection, retry count, status code or transport envelope. No
+kind declared here carries any of them: no attribute holding a host or
+connection, no retry count, no status code, and no request or response
+envelope. The framework's ClientRequestError carries a status code and response
+dictionary; neither is admitted to this client's error surface.
+
+STRUCTURE. One base error (AiLoggerClientError) from which all others descend,
+so a caller that wants to catch everything this client can raise catches one
+name. Beneath it: (1) ServiceUnreachableError, translating
+ClientConnectionError (transport failure; caller retries or corrects config);
+(2) ServiceRefusalError, translating ClientRequestError (service answered in
+refusal; caller corrects request or accepts). Beneath base: (3) UnknownCommandError,
+translating MethodNotFoundError (service does not publish this command).
+(4) RequestRejectedError family base with three members - MissingArgumentError
+(RequiredParameterMissingError), WrongArgumentTypeError (InvalidParameterTypeError),
+InadmissibleArgumentValueError (InvalidParameterValueError) - caller corrects
+its arguments. (5) SchemaDisagreementError, translating SchemaValidationError
+(client and service are mismatched). (6) QueuedCompletionError family base with
+four members - CompletionTimeoutError (CommandSessionTimeoutError),
+CompletionFailedError (CommandSessionFailedError), ResultUnavailableError
+(CommandSessionResultError), QueuedProtocolError (CommandSessionProtocolError)
+- distinguishes a job still running from a job that failed, for polled
+completion. (7) DialogueFileTransferError, translating the TransferClientError
+family as a whole (translates all seven members: session-not-found,
+resume-conflict, checksum-mismatch, compression, too-large,
+range-not-satisfiable, expired).
+
+THIS MODULE DOES NOT: perform translation (that is A-002), inspect answers,
+know domain error codes, declare the client class or configuration reading
+(those are other steps), or hold a copy of the service's stable error-code
+vocabulary (that lives in G-009 inside the service).
+
+Step citation: G-012/T-003/A-001.
+Translation (A-002) and refusal payload (A-003) extend this same file.
+
+A-002 SECTION: Framework Failure Translation
+
+The module provides a single immutable translation table (_TRANSLATIONS) that
+maps each named member of the framework's ClientError hierarchy to the
+corresponding kind in this client's vocabulary. The table is declared as data
+(types.MappingProxyType over a dict literal) and never modified.
+
+Translation is performed by a single entry point function (translate_framework_failure)
+that takes a raised framework failure and returns the corresponding error of this
+client's vocabulary. The function resolves the most-specific matching member first
+by walking type(failure).__mro__, ensuring that a family member is never swallowed
+by the family base above it. If no MRO member is in the table, the function returns
+an instance of AiLoggerClientError (the fallback) so that no framework-typed failure
+escapes.
+
+A reusable guard (translated_failures) wraps every call the client makes to the
+privately held framework client. It catches ClientError and only ClientError (never
+bare Exception or BaseException), translates it through the entry point, and raises
+the translated error with the original as its cause, so that a maintainer can still
+diagnose via the cause chain while a caller reads only this client's vocabulary.
+
+The translated error is constructed with no arguments: its type carries the meaning,
+the __cause__ chain carries the diagnosis, and its string form is empty. No host,
+connection, retry count, numeric status or envelope is copied from the original.
+This posture ensures that transport details remain behind the client's boundary.
+
+A-003 SECTION: Refusal Payload and Answer Recognition
+
+A refusal reaches this client by two routes. The first is via a raised framework
+failure (ClientRequestError), which is translated by A-002 to ServiceRefusalError.
+The second is via an answer dict that came back intact over a working transport
+and carries the service's own refusal in its payload (success=False, with domain
+code and statement in the data dict).
+
+The recogniser function (refusal_from_answer) is the only place in the client
+where an answer is examined for a refusal. It reads the stable domain code from
+the payload position (data["code"]), never from the framework's numeric code,
+and produces a ServiceRefusalError when it finds the structural refusal marker
+(success=False). Both routes produce the same kind, so a caller catches one name
+and never has to inspect transport markers to tell a transport failure from a
+service refusal.
+
+ServiceRefusalError now carries a payload: the service's stable domain code as
+a plain string (opaque carry-through, never invented), the human-readable
+statement the service sent with it, and the command the refusal answered. A
+caller compares the code, never the prose. The str form of the error contains
+the code and statement only, never transport detail.
+
+No error kind is added; the vocabulary is closed by A-001. No translation entry
+is changed; A-002 is unchanged. The domain code is declared once in the service
+and never replicated here.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import types
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+from mcp_proxy_adapter.client.jsonrpc_client.exceptions import (
+    ClientConnectionError,
+    ClientConnectionRefusedError,
+    ClientConnectTimeoutError,
+    ClientDnsResolutionError,
+    ClientError,
+    ClientRemoteResponseError,
+    ClientRequestError,
+    CommandSessionClientError,
+    CommandSessionFailedError,
+    CommandSessionProtocolError,
+    CommandSessionResultError,
+    CommandSessionTimeoutError,
+    InvalidParameterTypeError,
+    InvalidParameterValueError,
+    MethodNotFoundError,
+    RequiredParameterMissingError,
+    SchemaGeneratorError,
+    SchemaValidationError,
+    TransferClientError,
+)
+
+
+class AiLoggerClientError(Exception):
+    """
+    Base exception for all errors raised by the ai-logger client.
+
+    All exceptions raised by this client descend from this class.
+    Callers may catch this to catch everything the client can raise.
+    """
+
+
+class ServiceUnreachableError(AiLoggerClientError):
+    """
+    The service could not be reached at all.
+
+    Translates ``ClientConnectionError`` from the adapter framework. Indicates
+    a transport failure before the service could be contacted. Caller should
+    retry later or correct the connection material it configured.
+    """
+
+
+class ServiceRefusalError(AiLoggerClientError):
+    """
+    The service was reached and answered in refusal.
+
+    Translates ``ClientRequestError`` from the adapter framework. The service
+    rejected the request at the HTTP level. Caller should correct its request
+    or accept the refusal.
+
+    Carries the service's stable domain error code as a plain string (the
+    service's own code from the closed vocabulary), the human-readable
+    statement that accompanied it, and the command the refusal answered. A
+    caller compares the code, never the prose. The code is opaque to this
+    client: it carries through unchanged so that a code the service adds later
+    reaches a caller without a client release. Details added by A-003.
+
+    A refusal of the request's own shape also carries the three fields the
+    service states in ``data.details``: ``violation`` (``unknown``,
+    ``missing``, ``type`` or ``value``), ``expected`` (what the declaration
+    requires) and ``got`` (what the request carried). They are copied from
+    the answer, never recomputed, and are ``None`` when the answer carries no
+    such datum - always present as attributes.
+    """
+
+    def __init__(
+        self,
+        code: str | None = None,
+        statement: str | None = None,
+        command: str | None = None,
+        violation: str | None = None,
+        expected: object = None,
+        got: object = None,
+    ) -> None:
+        """
+        Args:
+            code: The service's stable domain error code as a plain string.
+                Opaque to this client; carries through unchanged.
+            statement: The human-readable statement the service sent with it.
+            command: The command the refusal answered.
+            violation: The service's ``data.details.violation`` marker, if any.
+            expected: The service's ``data.details.expected``, if any.
+            got: The service's ``data.details.got``, if any.
+
+        The error is constructible with no arguments; every argument is
+        optional to support the guard route (A-002) which instantiates kinds
+        no-arg.
+        """
+        self.code: str | None = code
+        self.statement: str | None = statement
+        self.command: str | None = command
+        self.violation: str | None = violation
+        self.expected: object = expected
+        self.got: object = got
+        message = ""
+        if code is not None and statement is not None:
+            message = f"{code}: {statement}"
+        elif code is not None:
+            message = code
+        elif statement is not None:
+            message = statement
+        super().__init__(message)
+
+
+class UnknownCommandError(AiLoggerClientError):
+    """
+    The client asked for a command this service does not publish.
+
+    Translates ``MethodNotFoundError`` from the adapter framework. One of the
+    two kinds that together (with the RequestRejectedError family) exhausts
+    ``SchemaGeneratorError`` and all its children. Indicates client-and-service
+    drift. The named pipeline check client-surface-agreement exists to catch
+    this before a consumer meets it.
+    """
+
+
+class RequestRejectedError(AiLoggerClientError):
+    """
+    Base for the request-rejected family.
+
+    Gathered base so a caller may catch the whole family at once.
+    Members indicate that arguments were decided invalid before the call left
+    the caller's process. Caller remedy is to correct its own arguments.
+    Together with UnknownCommandError, exhausts ``SchemaGeneratorError`` and
+    all its children from the adapter framework; SchemaGeneratorError itself
+    is covered by this family base as the nearest named coverage.
+    """
+
+
+class MissingArgumentError(RequestRejectedError):
+    """
+    A required argument was missing.
+
+    Translates ``RequiredParameterMissingError`` from the adapter framework.
+    Caller must supply the missing argument.
+    """
+
+
+class WrongArgumentTypeError(RequestRejectedError):
+    """
+    An argument had the wrong type.
+
+    Translates ``InvalidParameterTypeError`` from the adapter framework.
+    Caller must pass a value of the correct type.
+    """
+
+
+class InadmissibleArgumentValueError(RequestRejectedError):
+    """
+    An argument's value was not admitted.
+
+    Translates ``InvalidParameterValueError`` from the adapter framework.
+    Caller must pass a value that satisfies the constraint.
+    """
+
+
+class SchemaDisagreementError(AiLoggerClientError):
+    """
+    What was sent or received does not match the service's schema.
+
+    Translates ``SchemaValidationError`` from the adapter framework. Indicates
+    that the pairing of client and service is wrong rather than the caller's
+    own arguments. Caller should verify client and service versions match.
+    """
+
+
+class QueuedCompletionError(AiLoggerClientError):
+    """
+    Base for the queued-completion family.
+
+    Translates the entire ``CommandSessionClientError`` family from the adapter
+    framework as a whole, covering all four members: CommandSessionTimeoutError,
+    CommandSessionFailedError, CommandSessionResultError, and
+    CommandSessionProtocolError. Gathered base so a caller may distinguish a
+    job that is still running from a job that failed. Members indicate
+    different failure modes of polled completion (the default of G-012/T-002).
+    """
+
+
+class CompletionTimeoutError(QueuedCompletionError):
+    """
+    Waiting for a queued completion timed out.
+
+    Translates ``CommandSessionTimeoutError`` from the adapter framework.
+    Indicates the job did not finish within the configured timeout.
+    """
+
+
+class CompletionFailedError(QueuedCompletionError):
+    """
+    A queued completion reported failure.
+
+    Translates ``CommandSessionFailedError`` from the adapter framework.
+    Indicates the service reported that the job failed after being queued.
+    """
+
+
+class ResultUnavailableError(QueuedCompletionError):
+    """
+    The result of a queued completion could not be fetched.
+
+    Translates ``CommandSessionResultError`` from the adapter framework.
+    Indicates the job was accepted and queued but the result became
+    unavailable, perhaps due to session expiry or server state loss.
+    """
+
+
+class QueuedProtocolError(QueuedCompletionError):
+    """
+    A violation of the queued-answer protocol occurred.
+
+    Translates ``CommandSessionProtocolError`` from the adapter framework.
+    Indicates the service's responses did not follow the expected protocol
+    for queued operations.
+    """
+
+
+class SyncFallbackWaitExhaustedError(AiLoggerClientError):
+    """
+    A command overran the service's sync cap and its queued job did not finish
+    within the client's configured wait.
+
+    When a command exceeds the service's synchronous time cap the service
+    answers with an acknowledgement naming a job instead of the result, and the
+    job finishes on its own. The client follows that job until it ends. When the
+    wait set by ``client.sync_fallback_wait_seconds`` runs out first, this error
+    is raised. It is not ``CompletionTimeoutError`` (the wait of an always-queued
+    command): the command was dispatched exactly once and its job may still
+    complete, so the caller can read the outcome later through ``job_id``.
+
+    Attributes:
+        job_id: The identity of the still-unfinished job.
+    """
+
+    def __init__(self, message: str, job_id: str) -> None:
+        super().__init__(message)
+        self.job_id = job_id
+
+
+class DialogueFileTransferError(AiLoggerClientError):
+    """
+    File transfer between client and service encountered an error.
+
+    Translates the entire ``TransferClientError`` family from the adapter
+    framework as a single kind, covering all seven members: session-not-found,
+    resume-conflict, checksum-mismatch, compression, too-large,
+    range-not-satisfiable, and expired. File transfer between this client and
+    service is wanted only for importing and exporting dialogues; that purpose
+    is not yet designed, and the method that would carry a file raises
+    NotImplementedError. This kind exists to make the mapping exhaustive over
+    the framework hierarchy today. When import and export are taken up, this
+    one kind is widened into individual members rather than a second family
+    being invented.
+    """
+
+
+_TRANSLATIONS: types.MappingProxyType[type[ClientError], type[AiLoggerClientError]] = (
+    types.MappingProxyType(
+        {
+            # The adapter classifies connect-phase failures as siblings of
+            # ClientConnectionError, not as its subclasses, so each is listed.
+            ClientConnectionError: ServiceUnreachableError,
+            ClientConnectionRefusedError: ServiceUnreachableError,
+            ClientConnectTimeoutError: ServiceUnreachableError,
+            ClientDnsResolutionError: ServiceUnreachableError,
+            ClientRequestError: ServiceRefusalError,
+            MethodNotFoundError: UnknownCommandError,
+            RequiredParameterMissingError: MissingArgumentError,
+            InvalidParameterTypeError: WrongArgumentTypeError,
+            InvalidParameterValueError: InadmissibleArgumentValueError,
+            SchemaGeneratorError: RequestRejectedError,
+            SchemaValidationError: SchemaDisagreementError,
+            CommandSessionClientError: QueuedCompletionError,
+            CommandSessionTimeoutError: CompletionTimeoutError,
+            CommandSessionFailedError: CompletionFailedError,
+            CommandSessionResultError: ResultUnavailableError,
+            CommandSessionProtocolError: QueuedProtocolError,
+            TransferClientError: DialogueFileTransferError,
+        }
+    )
+)
+
+
+def translate_framework_failure(failure: ClientError) -> AiLoggerClientError:
+    """
+    Translate a framework failure to a corresponding client error.
+
+    Walks the MRO of the failure's type to find the most-specific matching
+    member in the translation table. If found, returns an instance of the
+    corresponding client error kind. If no MRO member is in the table, returns
+    an instance of AiLoggerClientError (the fallback).
+
+    Args:
+        failure: A ClientError raised by the framework client.
+
+    Returns:
+        An instance of AiLoggerClientError or one of its subclasses.
+    """
+    in_band = _in_band_refusal(failure)
+    if in_band is not None:
+        return in_band
+    for mro_type in type(failure).__mro__:
+        if mro_type in _TRANSLATIONS:
+            return _TRANSLATIONS[mro_type]()
+    return AiLoggerClientError()
+
+
+def _in_band_refusal(failure: ClientError) -> ServiceRefusalError | None:
+    """
+    The service's refusal of a request it declined to queue, when the
+    framework reported it as an in-band JSON-RPC error that carries the
+    service's stable domain code.
+
+    An always-queued command is validated when the request is accepted for
+    queueing, before any job exists, and the framework answers a refusal there
+    as a JSON-RPC error rather than as a command answer. When that error's
+    data carries the stable code of the service's closed vocabulary, it is the
+    same refusal a direct command answers with, and arrives as the same kind:
+    ``ServiceRefusalError`` with that code. An in-band error carrying no such
+    code is not recognised here and keeps the generic translation.
+    """
+    if not isinstance(failure, ClientRemoteResponseError):
+        return None
+    details = failure.details
+    data = details.get("data") if isinstance(details, Mapping) else None
+    code = data.get("code") if isinstance(data, Mapping) else None
+    if not isinstance(code, str) or not code.strip():
+        return None
+    return ServiceRefusalError(
+        code=code, statement=str(failure), **_refusal_fields(data)
+    )
+
+
+def _refusal_fields(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """
+    The ``violation``, ``expected`` and ``got`` of a refusal, copied from the
+    ``details`` of its payload; an absent datum reads as ``None``. Nothing is
+    recomputed here: the service states them.
+    """
+    details = payload.get("details")
+    source: Mapping[str, Any] = details if isinstance(details, Mapping) else {}
+    marker = source.get("violation")
+    return {
+        "violation": marker if isinstance(marker, str) else None,
+        "expected": source.get("expected"),
+        "got": source.get("got"),
+    }
+
+
+@contextlib.contextmanager
+def translated_failures() -> Iterator[None]:
+    """
+    Context manager that translates framework failures to client errors.
+
+    Wraps code that calls the privately held framework client. Catches
+    ClientError and only ClientError (never Exception or BaseException),
+    translates it through translate_framework_failure, and raises the
+    translated error with the original as its cause. Allows other exceptions
+    to propagate unchanged.
+
+    Usage:
+        with translated_failures():
+            result = await framework_client.execute_command(...)
+    """
+    try:
+        yield
+    except ClientError as exc:
+        raise translate_framework_failure(exc) from exc
+
+
+def refusal_from_answer(
+    answer: dict[str, Any] | None,
+    command: str,
+) -> ServiceRefusalError | None:
+    """
+    Recognise a service refusal in an answer dict and produce the error.
+
+    The only place in this client where an answer is examined for a refusal.
+    Reads the refusal from the structural shapes the service's answers
+    actually carry via two call paths. Returns None when the answer is not a
+    refusal (normal result, empty result, or ordinary data).
+
+    TWO ROUTES TO A REFUSAL, two shapes:
+
+    1. FULL ENVELOPE (legacy/fallback path): answer has top-level keys
+       success=False, data (dict), and error (str). Framework wrapping intact.
+       Referenced at: mcp_proxy_adapter.client.jsonrpc_client.transport,
+       _extract_result (line 632).
+
+    2. BARE PAYLOAD (default WS path): answer has no success key and no error
+       key at top level. Framework's execute_command_unified (command_api.py
+       lines 330-336) unwraps the full envelope by taking answer.get("data"),
+       leaving only the service's CommandErrorResult payload dict. Referenced
+       at: mcp_proxy_adapter.client.jsonrpc_client.command_api.py:330-336,
+       where if isinstance(raw_result, dict) and "data" in raw_result:
+       result_value = raw_result.get("data").
+
+    In both cases, the refusal is recognised by the presence of framework_code
+    in the dict (service's CommandErrorResult payload always carries this;
+    ailogger/api/command_result.py:142, 145). The stable domain code is read
+    from the code position in the payload. The framework's numeric code is
+    never used as the domain code.
+
+    In the full envelope, the human-readable statement is at the top level
+    (answer["error"]). In the bare payload, the statement is lost (it was only
+    in the envelope's error field, not in the payload dict that gets unwrapped),
+    so statement is None on the default path.
+
+    Args:
+        answer: An answer dict from the service. May be None.
+        command: The name of the command the answer is for.
+
+    Returns:
+        A ServiceRefusalError with code, statement, and command set, when the
+        answer carries the service's refusal shape. None when it does not.
+    """
+    if answer is None:
+        return None
+
+    if not isinstance(answer, dict):
+        return None
+
+    # Check for both shapes:
+    # - Full envelope: top-level success=False with data and error
+    # - Bare payload: no success key, just payload with framework_code
+
+    is_full_envelope: bool = answer.get("success") is False
+    is_bare_payload: bool = "success" not in answer
+
+    if not (is_full_envelope or is_bare_payload):
+        return None
+
+    # Extract the refusal payload dict
+    if is_full_envelope:
+        data = answer.get("data")
+    else:
+        # Bare payload case: the answer dict itself is the payload
+        data = answer
+
+    if not isinstance(data, dict):
+        return None
+
+    # Validate refusal structure: must have framework_code to be a real refusal
+    # (ordinary data would not have this framework marker)
+    if "framework_code" not in data:
+        return None
+
+    # Read the stable domain code from payload position
+    code: str | None = None
+    code_value = data.get("code")
+    if isinstance(code_value, str):
+        code = code_value
+    elif code_value is not None:
+        # Non-string codes (e.g., from framework) are not the domain code
+        code = None
+
+    # Extract the human-readable statement
+    # Only present in full envelope (full answer["error"]), not in bare payload
+    statement: str | None = None
+    if is_full_envelope:
+        error_value = answer.get("error")
+        if isinstance(error_value, str):
+            statement = error_value
+
+    # Construct and return the refusal
+    return ServiceRefusalError(
+        code=code, statement=statement, command=command, **_refusal_fields(data)
+    )
+
+
+__all__ = [
+    "AiLoggerClientError",
+    "CompletionFailedError",
+    "CompletionTimeoutError",
+    "DialogueFileTransferError",
+    "InadmissibleArgumentValueError",
+    "MissingArgumentError",
+    "QueuedCompletionError",
+    "QueuedProtocolError",
+    "RequestRejectedError",
+    "ResultUnavailableError",
+    "SchemaDisagreementError",
+    "ServiceRefusalError",
+    "ServiceUnreachableError",
+    "SyncFallbackWaitExhaustedError",
+    "UnknownCommandError",
+    "WrongArgumentTypeError",
+    "refusal_from_answer",
+    "translate_framework_failure",
+    "translated_failures",
+]