ailogger-client 0.1.1__tar.gz

ailogger_client-0.1.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: ailogger-client
+Version: 0.1.1
+Summary: Published client of the ai-logger dialogue service - a typed wrapper over the mcp-proxy-adapter framework client
+Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
+License: Proprietary
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: mcp-proxy-adapter==8.10.44
+
+# ai-logger Client
+
+This package is the client for the ai-logger dialogue service. It is installed independently from the service itself through the package index.
+
+## What This Distribution Is
+
+The ai-logger client is a published wrapper over the adapter framework's own client, carrying the dialogue vocabulary of the ai-logger service. It depends on the adapter framework and never on the server package, so installing it brings in no part of the service's runtime, storage, or configuration. Version tracks the service version and the client and server are released in step; to work with a particular server instance, select the client version matching that server.
+
+Install directly from the package index as an ordinary Python package. Never install from a source checkout, repository URL, or local path.
+
+## What It Is Made Of
+
+This client wraps the framework's JsonRpcClient privately, holding it as a single private attribute that no caller can reach. Transport, connection handling, retries, request serialization, response parsing, job tracking, queue operations, schema validation, and file transfer all belong to the framework client. This distribution adds only the dialogue vocabulary of the ai-logger service: typed methods named for the service's own commands, and nothing else.
+
+The client carries no transport of its own and imports no additional network library beyond the adapter framework. Auditing the package dependencies finds the adapter framework and nothing else network-bearing.
+
+## How It Is Configured
+
+The client is constructed from a named section of the configuration document of the process that uses it, never from the service's own configuration. The section must be named `ailogger_client` and must carry the same sectioned shape every fleet client uses:
+
+- A top-level `protocol` (http, https, or mtls)
+- A `server` sub-section with `host` and `port`
+- Optional `client` and `ssl` sub-sections carrying certificate material
+- An optional `auth` sub-section carrying a token and the HTTP header name it travels in
+
+Construct the client by passing the section mapping to AiLoggerClient, or use AiLoggerClient.from_document_path() to load configuration from a JSON file.
+
+## What Happens When a Call Fails
+
+Every failure reaches the caller as a typed error of this client, never as an exception of the framework or transport. Catch AiLoggerClientError to catch everything the client can raise.
+
+A transport that failed to reach the service arrives as ServiceUnreachableError. A service that was reached but answered in refusal arrives as ServiceRefusalError, which carries three attributes: a `code` as a plain string from the service's own domain error vocabulary, a `statement` for the human-readable message, and the `command` name. A refusal reaches the caller as ServiceRefusalError whichever route it arrived by, whether as a raised request failure or as a refusing answer; ServiceUnreachableError means the service could not be reached at all. Compare the code to distinguish refusals, not the prose. No host, connection, retry, status code, or transport envelope is ever visible.
+
+## How a Command Is Called
+
+The client declares one typed method per published command of the service, plus a generic `call()` method for commands not yet named, so new commands published after the client release stay reachable without a new client release.
+
+When a command is queued by the service, the client polls it to completion by default and returns the finished result directly. To receive the job identity instead and poll manually, pass `wait_for_result=False` to the command method or to `call()`. Job observation methods `get_job_status()` and `get_job_messages()` let you track progress; `cancel_command()` cancels a queued job.
+
+## A Usage Flow
+
+```python
+import json
+from ailogger_client import AiLoggerClient
+
+# Load configuration and construct the client
+async with AiLoggerClient.from_document_path("config.json") as client:
+    # Open a dialogue session
+    session = await client.open_session(
+        session_id="session-uuid",
+        project_id="project-id",
+        dialogue_kind=("human", "model"),
+        participants=["user", "assistant"]
+    )
+
+    # Append a message with a declared relation
+    msg = await client.append_message(
+        session_id="session-uuid",
+        text="What is the answer?",
+        sender_kind="human",
+        sender_identity="user",
+        receiver_kind="model",
+        receiver_identity="assistant",
+        relations=[{"to_message_id": "earlier-msg-id", "kind": "reply"}]
+    )
+
+    # Read a window of messages
+    window = await client.messages_read(
+        session_id="session-uuid",
+        start_sequence_number=0
+    )
+
+    # Ask for the working set of recent and closest messages
+    working = await client.working_set(
+        session_id="session-uuid",
+        anchor_text="What does it mean?"
+    )
+```
+
+## What Is Not Implemented
+
+Dialogue import from a file and export to a file are the only reasons this client would need file transfer. These methods are deliberately not designed yet: calling `import_dialogue()` or `export_dialogue()` raises NotImplementedError, deliberately and not by omission, and the gap is tracked as an open item of the project. Transfer will be built on the framework client's own transfer surface when import and export are designed.
+
+## Where the Agreement Is Proven
+
+This distribution ships separately from the service, so nothing shared keeps their command sets in step. The project's named pipeline check `client-surface-agreement` proves the agreement by comparing the shipped client's command methods against the surface the service registers as live, distinct from the pipeline's command-set agreement check which compares the service's own contained, declared and published sets. That check is authored under the verification work of G-010/T-004/A-008. This is the reference the distribution owes; the check itself is not explained here.

ailogger_client-0.1.1/README.md

@@ -0,0 +1,86 @@
+# ai-logger Client
+
+This package is the client for the ai-logger dialogue service. It is installed independently from the service itself through the package index.
+
+## What This Distribution Is
+
+The ai-logger client is a published wrapper over the adapter framework's own client, carrying the dialogue vocabulary of the ai-logger service. It depends on the adapter framework and never on the server package, so installing it brings in no part of the service's runtime, storage, or configuration. Version tracks the service version and the client and server are released in step; to work with a particular server instance, select the client version matching that server.
+
+Install directly from the package index as an ordinary Python package. Never install from a source checkout, repository URL, or local path.
+
+## What It Is Made Of
+
+This client wraps the framework's JsonRpcClient privately, holding it as a single private attribute that no caller can reach. Transport, connection handling, retries, request serialization, response parsing, job tracking, queue operations, schema validation, and file transfer all belong to the framework client. This distribution adds only the dialogue vocabulary of the ai-logger service: typed methods named for the service's own commands, and nothing else.
+
+The client carries no transport of its own and imports no additional network library beyond the adapter framework. Auditing the package dependencies finds the adapter framework and nothing else network-bearing.
+
+## How It Is Configured
+
+The client is constructed from a named section of the configuration document of the process that uses it, never from the service's own configuration. The section must be named `ailogger_client` and must carry the same sectioned shape every fleet client uses:
+
+- A top-level `protocol` (http, https, or mtls)
+- A `server` sub-section with `host` and `port`
+- Optional `client` and `ssl` sub-sections carrying certificate material
+- An optional `auth` sub-section carrying a token and the HTTP header name it travels in
+
+Construct the client by passing the section mapping to AiLoggerClient, or use AiLoggerClient.from_document_path() to load configuration from a JSON file.
+
+## What Happens When a Call Fails
+
+Every failure reaches the caller as a typed error of this client, never as an exception of the framework or transport. Catch AiLoggerClientError to catch everything the client can raise.
+
+A transport that failed to reach the service arrives as ServiceUnreachableError. A service that was reached but answered in refusal arrives as ServiceRefusalError, which carries three attributes: a `code` as a plain string from the service's own domain error vocabulary, a `statement` for the human-readable message, and the `command` name. A refusal reaches the caller as ServiceRefusalError whichever route it arrived by, whether as a raised request failure or as a refusing answer; ServiceUnreachableError means the service could not be reached at all. Compare the code to distinguish refusals, not the prose. No host, connection, retry, status code, or transport envelope is ever visible.
+
+## How a Command Is Called
+
+The client declares one typed method per published command of the service, plus a generic `call()` method for commands not yet named, so new commands published after the client release stay reachable without a new client release.
+
+When a command is queued by the service, the client polls it to completion by default and returns the finished result directly. To receive the job identity instead and poll manually, pass `wait_for_result=False` to the command method or to `call()`. Job observation methods `get_job_status()` and `get_job_messages()` let you track progress; `cancel_command()` cancels a queued job.
+
+## A Usage Flow
+
+```python
+import json
+from ailogger_client import AiLoggerClient
+
+# Load configuration and construct the client
+async with AiLoggerClient.from_document_path("config.json") as client:
+    # Open a dialogue session
+    session = await client.open_session(
+        session_id="session-uuid",
+        project_id="project-id",
+        dialogue_kind=("human", "model"),
+        participants=["user", "assistant"]
+    )
+
+    # Append a message with a declared relation
+    msg = await client.append_message(
+        session_id="session-uuid",
+        text="What is the answer?",
+        sender_kind="human",
+        sender_identity="user",
+        receiver_kind="model",
+        receiver_identity="assistant",
+        relations=[{"to_message_id": "earlier-msg-id", "kind": "reply"}]
+    )
+
+    # Read a window of messages
+    window = await client.messages_read(
+        session_id="session-uuid",
+        start_sequence_number=0
+    )
+
+    # Ask for the working set of recent and closest messages
+    working = await client.working_set(
+        session_id="session-uuid",
+        anchor_text="What does it mean?"
+    )
+```
+
+## What Is Not Implemented
+
+Dialogue import from a file and export to a file are the only reasons this client would need file transfer. These methods are deliberately not designed yet: calling `import_dialogue()` or `export_dialogue()` raises NotImplementedError, deliberately and not by omission, and the gap is tracked as an open item of the project. Transfer will be built on the framework client's own transfer surface when import and export are designed.
+
+## Where the Agreement Is Proven
+
+This distribution ships separately from the service, so nothing shared keeps their command sets in step. The project's named pipeline check `client-surface-agreement` proves the agreement by comparing the shipped client's command methods against the surface the service registers as live, distinct from the pipeline's command-set agreement check which compares the service's own contained, declared and published sets. That check is authored under the verification work of G-010/T-004/A-008. This is the reference the distribution owes; the check itself is not explained here.

ailogger_client-0.1.1/ailogger_client/__init__.py

@@ -0,0 +1,93 @@
+"""
+ailogger service client.
+
+This package provides the client for the ai-logger service, distributed and
+installed independently of the service itself. It is a wrapper around the
+adapter framework's ``JsonRpcClient`` (from ``mcp_proxy_adapter.client.jsonrpc_client``)
+and adds only the dialogue vocabulary of the ai-logger service: the command
+methods, the generic call surface and the typed error vocabulary.
+
+The wrapper is constructed from a named section of the consuming process's
+configuration document - the same sectioned shape every fleet client in the
+ai-logger fleet uses: a top-level ``protocol``, a ``server`` sub-section
+carrying host and port, a ``client`` sub-section that may carry ssl material
+overriding the server's own, a top-level ``ssl`` sub-section used as a
+fallback, and an ``auth`` sub-section carrying a token and the header it
+travels in.
+
+Transport, request serialization, response parsing, retries, job tracking,
+queue operations, file transfer with integrity checking and connection
+management all belong to the adapter framework's client: this package wraps
+that client and adds only the dialogue vocabulary on top.
+
+A-009 SECTION: Published Surface
+
+The package's public surface is declared explicitly by ``__all__`` and holds
+the client class, the construction entry points, and the complete typed error
+vocabulary. A caller that wants to catch everything this client can raise
+catches the single base kind (``AiLoggerClientError``), and every specific kind
+is reachable from the package root. This closes the vocabulary: a consumer
+never reaches into a private module path to catch a typed error of this client.
+
+Deliberately unpublished from the package root (but still importable via
+submodule paths like ``ailogger_client.errors`` or ``ailogger_client.client``):
+the adapter framework's client class and its entire transport and exception
+hierarchy; the seven mixin classes (InvocationMixin, SessionMixin,
+MessageMixin, ReadMixin, RetrievalMixin, ServiceMixin, FileTransferMixin)
+that compose the client; the translation table and its supporting machinery
+(``translate_framework_failure``, ``translated_failures``, ``refusal_from_answer``);
+and the private attribute holding the framework client. This design keeps
+this package a wrapper over the framework rather than a second way of
+importing it, and ensures that transport details remain behind the client's
+boundary.
+"""
+
+from __future__ import annotations
+
+from .client import AiLoggerClient
+from .config import (
+    ConfigError,
+    load_client_section,
+    load_config_kwargs,
+    load_config_kwargs_from_document,
+)
+from .errors import (
+    AiLoggerClientError,
+    CompletionFailedError,
+    CompletionTimeoutError,
+    DialogueFileTransferError,
+    InadmissibleArgumentValueError,
+    MissingArgumentError,
+    QueuedCompletionError,
+    QueuedProtocolError,
+    RequestRejectedError,
+    ResultUnavailableError,
+    SchemaDisagreementError,
+    ServiceRefusalError,
+    ServiceUnreachableError,
+    UnknownCommandError,
+    WrongArgumentTypeError,
+)
+
+__all__ = [
+    "AiLoggerClient",
+    "AiLoggerClientError",
+    "CompletionFailedError",
+    "CompletionTimeoutError",
+    "ConfigError",
+    "DialogueFileTransferError",
+    "InadmissibleArgumentValueError",
+    "MissingArgumentError",
+    "QueuedCompletionError",
+    "QueuedProtocolError",
+    "RequestRejectedError",
+    "ResultUnavailableError",
+    "SchemaDisagreementError",
+    "ServiceRefusalError",
+    "ServiceUnreachableError",
+    "UnknownCommandError",
+    "WrongArgumentTypeError",
+    "load_client_section",
+    "load_config_kwargs",
+    "load_config_kwargs_from_document",
+]

ailogger_client-0.1.1/ailogger_client/client.py

@@ -0,0 +1,209 @@
+"""
+Client for the ai-logger service.
+
+This module declares the client class of the ai-logger service: the construction
+and encapsulation boundary before any command of the surface reaches it.
+
+CONSTRUCTION SHAPE. The client is built from its own named section of the
+configuration document of the process that uses it, in the sectioned fleet shape,
+by handing that section to the configuration translation of ailogger_client.config
+and passing the resulting keyword arguments straight to the framework client's
+constructor. Two construction routes are offered: from a section already read as
+a mapping, and from a configuration document identified by path together with the
+name of the section to read. Both routes end in the same single place where the
+framework client is built, so there is exactly one construction path in the class.
+
+ENCAPSULATION. The client holds an instance of JsonRpcClient from
+mcp_proxy_adapter.client.jsonrpc_client on a private attribute. The held instance
+leaves the object by no route: no public attribute, no property, no accessor method,
+no return value, no argument default, no representation string or attribute-forwarding
+hook. A caller holding this client cannot reach a connection through it. Inside the
+package a single private route to the held instance exists, so the typed methods
+have somewhere to call through without the attribute becoming part of the caller-facing
+surface.
+
+LIFECYCLE. Whatever opening and closing the client needs is delegated to the held
+instance. The client supports use as an asynchronous context manager, so entering
+and leaving a client is entering and leaving what the framework client already
+provides. Closing twice is harmless.
+
+CALLER SURFACE. No host, no connection, no retry, no status code and no transport
+envelope appears in any argument, in any return value or in any readable attribute
+of this class. The caller works only in the terms the service itself publishes.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from mcp_proxy_adapter.client.jsonrpc_client import JsonRpcClient
+
+from .config import (
+    ConfigError,
+    load_client_section,
+    load_config_kwargs,
+)
+from .file_transfer import FileTransferMixin
+from .invocation import InvocationMixin
+from .message_methods import MessageMixin
+from .read_methods import ReadMixin
+from .retrieval_methods import RetrievalMixin
+from .service_methods import ServiceMixin
+from .session_methods import SessionMixin
+
+__all__ = ["AiLoggerClient"]
+
+
+class AiLoggerClient(
+    InvocationMixin,
+    SessionMixin,
+    MessageMixin,
+    ReadMixin,
+    RetrievalMixin,
+    ServiceMixin,
+    FileTransferMixin,
+):
+    """
+    Wrapper over the installed adapter framework's JsonRpcClient, adding the
+    dialogue vocabulary of the ai-logger service.
+
+    The client is constructed from the consuming process's configuration document,
+    in the sectioned fleet shape. It holds an instance of JsonRpcClient privately,
+    delegating all transport, connection, retry and job tracking to the framework
+    client.
+
+    The client supports use as an asynchronous context manager. Lifecycle operations
+    (enter, exit, close) are delegated to the held JsonRpcClient instance.
+
+    COMPOSITION (G-012/T-003/A-008). The client is assembled from seven mixin
+    classes, each contributing a set of typed methods to the caller-facing surface:
+    InvocationMixin provides the private invocation seam and the generic call, plus
+    job observation; SessionMixin provides session lifecycle commands; MessageMixin
+    provides message append; ReadMixin provides the five session reads and session
+    listing; RetrievalMixin provides working-set assembly and similarity search;
+    ServiceMixin provides info and health; FileTransferMixin declares dialogue
+    import and export (not yet designed). Every caller-facing method reaches the
+    held JsonRpcClient through the single private _invoke entry point that
+    InvocationMixin establishes, so there is one seam and one route. The composition
+    is order-independent for callers: all typed methods are reachable on an instance
+    regardless of the base order, because each mixin declares disjoint public names.
+    """
+
+    def __init__(
+        self,
+        section: Mapping[str, Any],
+        base_dir: str | None = None,
+    ) -> None:
+        """
+        Construct the client from a configuration section.
+
+        Args:
+            section: The "ailogger_client" section from the consuming process's
+                configuration document, as a mapping. Must carry the sectioned
+                fleet shape: a top-level ``protocol``, a ``server`` sub-section
+                with ``host`` and ``port``, optional ``client`` and ``ssl``
+                sub-sections, and an optional ``auth`` sub-section.
+
+            base_dir: When provided, the directory against which relative certificate
+                paths in the section are resolved. When absent, paths are resolved
+                against the calling process's current working directory.
+
+        Raises:
+            ConfigError: If the section is missing required keys or if any key
+                has the wrong type.
+        """
+        kwargs = load_config_kwargs(section, base_dir)
+        self._client: JsonRpcClient = JsonRpcClient(**kwargs)
+
+    @classmethod
+    def from_document_path(
+        cls,
+        path: str | Path,
+        section_name: str = "ailogger_client",
+    ) -> AiLoggerClient:
+        """
+        Construct the client from a configuration document file.
+
+        Reads the specified JSON configuration file, extracts the named section,
+        resolves relative certificate paths against the document's directory,
+        and constructs the client. This is a convenience route that combines
+        file reading, section extraction, and client construction.
+
+        Args:
+            path: The filesystem path to a JSON configuration document.
+
+            section_name: The name of the section to read from the document.
+                Defaults to "ailogger_client". This parameter exists for
+                flexibility but should remain at the default for the ai-logger client.
+
+        Returns:
+            An AiLoggerClient instance.
+
+        Raises:
+            ConfigError: If the document carries no section with the given name
+                or if the section is malformed.
+            FileNotFoundError: If the file does not exist.
+            json.JSONDecodeError: If the file is not valid JSON.
+        """
+        path_obj = Path(path).resolve()
+        with open(path_obj) as f:
+            document = json.load(f)
+
+        base_dir = str(path_obj.parent)
+
+        # Extract the section from the document
+        if section_name == "ailogger_client":
+            section = load_client_section(document)
+        else:
+            section = document.get(section_name)
+        if not isinstance(section, Mapping):
+            raise ConfigError(
+                f"configuration document carries no '{section_name}' "
+                "section for this client"
+            )
+
+        # Use the main constructor (single construction path)
+        return cls(section, base_dir=base_dir)
+
+    async def close(self) -> None:
+        """
+        Close the underlying transport and release resources.
+
+        Delegates to the held JsonRpcClient's close method. Closing twice
+        is harmless; the underlying client handles idempotency.
+        """
+        await self._client.close()
+
+    async def __aenter__(self) -> AiLoggerClient:
+        """
+        Async context manager entry.
+
+        Returns self for use in `async with` statements. The held JsonRpcClient
+        does not require explicit initialization, so no setup is performed here.
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: Any,
+    ) -> None:
+        """
+        Async context manager exit.
+
+        Closes the underlying transport and releases resources by delegating
+        to close().
+        """
+        await self.close()
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation of the client.
+
+        Does not expose the held instance or any transport details.
+        """
+        return f"{self.__class__.__name__}()"