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

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
    )

    # Atomically hide or restore recorded messages
    marked = await client.mark_messages_for_deletion(
        message_ids=["message-uuid"],
        marked_for_deletion=True,
    )

    # 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.