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

ailogger_client/session_methods.py

@@ -0,0 +1,236 @@
+"""
+Typed methods for session lifecycle commands.
+
+This module carries the single mixin class whose typed methods let a caller
+act on the existence and the state of a dialogue session. Each method names
+its arguments for what the corresponding command's parameter schema declares,
+so a caller opens, closes, reopens and deletes a session in the service's own
+terms and never assembles a request envelope, never names a command as a free
+string and never guesses a parameter name.
+
+A parameter the command declares as required is a required argument of the
+method; a parameter the command declares as optional is optional on the method
+and is simply not carried when the caller does not supply it, so the service's
+own resolution of an unsupplied optional parameter is never pre-empted by a
+value invented in this client.
+
+The opening command accepts session_id from the caller and never generates one
+- this client never mints a session identifier, never supplies a default for
+one and calls no identifier-generating function on any path reaching the open
+method. Required and optional parameters are mirrored exactly from the service
+command declarations read in the steps that established them (G-009/T-002 for
+the first three commands and G-009/T-007 for the delete command).
+
+Each method carries its arguments to the invocation seam of G-012/T-002/A-001
+and returns what the seam returns. Performance performs no validation of a
+parameter value beyond what the language's own typing expresses: the command's
+declared schema is validated at the service.
+
+NETWORK LAW. This module imports nothing from the adapter framework's
+implementation and adds no transport of its own. All network interaction goes
+through the invocation seam and thence through the privately held framework
+client instance, and through nothing else.
+
+BOUNDARIES. This module declares no generic call, no completion default, no
+non-blocking path or any job-observing call (all owned by earlier steps).
+Every declaration in this file is fully annotated for the pipeline's named
+strict type check, and the module satisfies its named lint check.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+__all__ = ["SessionMixin"]
+
+
+class SessionMixin:
+    """Mixin providing typed methods for session lifecycle commands.
+
+    Declares the four typed methods by which a caller acts on the existence
+    and the state of a dialogue session: opening, closing, reopening and
+    deleting a session in the service's own terms.
+
+    This mixin expects to be composed with InvocationMixin, which provides
+    the _invoke method.
+    """
+
+    async def _invoke(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        *,
+        wait_for_result: bool = True,
+    ) -> Any:
+        """Private invocation entry point.
+
+        This method is provided by InvocationMixin when this mixin is composed
+        into a class. This stub is declared here for type checking purposes
+        only.
+
+        Args:
+            command: The name of the command to execute.
+            params: An optional mapping of command parameters.
+            wait_for_result: When True (default), wait for queued commands to
+                completion and return the finished result.
+
+        Returns:
+            The command result.
+        """
+        raise NotImplementedError  # Provided by InvocationMixin
+
+    async def open_session(  # noqa: PLR0913, PLR0917
+        self,
+        session_id: str,
+        project_id: str,
+        dialogue_kind: tuple[str, str],
+        participants: list[str],
+        title: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Any:
+        """Open a dialogue session under a caller-supplied identifier.
+
+        Opens a dialogue session under the session identifier the caller
+        supplies. That identifier originates in the code analysis server: the
+        caller obtains it there through that server's published client and
+        hands it to this method, which carries it unchanged to the service.
+        This client never generates a session identifier and never supplies a
+        default for one.
+
+        Beside the identifier the caller states the owning project, the
+        dialogue kind as an ordered pair of participant kinds, the participants
+        of the session, and optionally a title and free-form metadata; the
+        attributes the caller does not supply - the creation time and the
+        initial lifecycle state - are established by the creation itself as the
+        session model defines them.
+
+        The owning project identifier is ordinary dialogue data recorded as
+        given: this method validates it against no other service, looks up no
+        project name for it, and treats nothing outside the service as
+        authority over it.
+
+        Args:
+            session_id: Identifier of the session the dialogue is opened under,
+                issued by the code analysis server and obtained by the caller
+                through that server's published client. This service never
+                generates one and never defaults one, and records the identifier
+                the caller supplies unchanged.
+            project_id: Identifier of the project this session belongs to,
+                required and non-empty. Ordinary dialogue data recorded exactly
+                as given: no other service is consulted to validate it, to look
+                up a name for it or to act as authority over it.
+            dialogue_kind: Tuple[str, str] with exactly two participant kinds
+                - the sender's kind and the receiver's kind in that order. Which
+                two of the four participant kinds (human, model, tool, system)
+                the sender and receiver carry that this session runs between.
+                The two may repeat, so model-to-model and system-to-system are
+                expressible. The service never infers this from messages that
+                arrive afterwards.
+            participants: The concrete participants of this session, required
+                and non-empty. Nothing else populates them, so this is the only
+                point at which a session becomes findable by participant.
+            title: Human-readable title of the session. Optional and
+                legitimately absent: a session opened without one carries none.
+            metadata: Free-form metadata to record on the session. Optional and
+                legitimately absent or empty. Carried exactly as given and never
+                interpreted, inspected or rewritten by the service.
+
+        Returns:
+            The identity of the session together with its resulting lifecycle
+            state, and nothing beyond those two.
+        """
+        params: dict[str, Any] = {
+            "session_id": session_id,
+            "project_id": project_id,
+            "dialogue_kind": list(dialogue_kind),
+            "participants": participants,
+        }
+        if title is not None:
+            params["title"] = title
+        if metadata is not None:
+            params["metadata"] = metadata
+        return await self._invoke("open_session", params)
+
+    async def close_session(self, session_id: str) -> Any:
+        """Close an open dialogue session, removing nothing.
+
+        Moves the addressed dialogue session's lifecycle state from open to
+        closed. That is the entire effect: closing is a state transition and
+        nothing more. It removes no session, no message, no declared relation
+        and no vector record, and it alters no attribute of the session other
+        than its lifecycle state.
+
+        Args:
+            session_id: Identity of the existing dialogue session to close.
+                Required: this method addresses a session that was already
+                opened and never brings one into being.
+
+        Returns:
+            The identity of the session together with its resulting lifecycle
+            state, which is closed, and nothing beyond those two.
+        """
+        return await self._invoke("close_session", {"session_id": session_id})
+
+    async def reopen_session(self, session_id: str) -> Any:
+        """Return a closed dialogue session to the open state.
+
+        Moves the addressed dialogue session's lifecycle state from closed back
+        to open, because the closed state is not final: a dialogue that was
+        closed is not a dead end, and mutability returns with the open state.
+        That is the entire effect - reopening is a state transition and nothing
+        more. It changes no other attribute of the session and touches none of
+        the messages recorded in it.
+
+        Args:
+            session_id: Identity of the existing dialogue session to reopen.
+                Required: this method addresses a session that was already
+                opened and later closed, and never brings one into being.
+
+        Returns:
+            The identity of the session together with its resulting lifecycle
+            state, which is open, and nothing beyond those two.
+        """
+        return await self._invoke("reopen_session", {"session_id": session_id})
+
+    async def session_mark_removed(
+        self, session_id: str, removed_at: str | None = None
+    ) -> Any:
+        """Record terminal source removal, retaining all stored dialogue data."""
+        params: dict[str, Any] = {"session_id": session_id}
+        if removed_at is not None:
+            params["removed_at"] = removed_at
+        return await self._invoke("session_mark_removed", params)
+
+    async def delete_session(self, session_id: str) -> Any:
+        """Delete one dialogue session together with everything derived from it.
+
+        Removes the addressed dialogue session together with everything
+        recorded under it: its messages, the relations declared on those
+        messages, and the vector records built from them. The removal is one
+        whole - the caller names the session and nothing else, and cannot ask
+        for a partial deletion.
+
+        This deletion is caller-triggered and immediate: it happens because
+        this method was called and takes effect within this request, the answer
+        being returned only after the removal has actually gone through.
+
+        Deleting is not a stronger form of closing, and closing is not a soft
+        form of deleting. Closing a session moves its lifecycle state and
+        removes nothing: the whole dialogue stays recorded and readable. This
+        method ends the existence of the session and of everything recorded
+        under it; a deleted session cannot be recovered by any method of the
+        client, and no method of this surface undoes what this one does.
+
+        Args:
+            session_id: Identity of the dialogue session to delete, as the
+                canonical text of the identifier the session was recorded
+                under. The session and everything derived from it are removed
+                as one whole.
+
+        Returns:
+            The identity of the session that was deleted, together with the
+            statement that its messages, the relations declared on those
+            messages and the vector records built from them were removed with
+            it.
+        """
+        return await self._invoke("delete_session", {"session_id": session_id})

ailogger_client_dev-0.1.51.dist-info/METADATA

@@ -0,0 +1,108 @@
+Metadata-Version: 2.4
+Name: ailogger-client-dev
+Version: 0.1.51
+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.11.3
+
+# 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
+    )
+
+    # Atomically hide or restore recorded messages
+    marked = await client.mark_messages_for_deletion(
+        message_ids=["message-uuid"],
+        marked_for_deletion=True,
+    )
+
+    # Soft-delete one message, or pass mode="hard" for an unreferenced row
+    deleted = await client.message_delete(
+        message_id="message-uuid",
+        mode="soft",
+    )
+
+    # 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_dev-0.1.51.dist-info/RECORD

@@ -0,0 +1,18 @@
+ailogger_client/__init__.py,sha256=ah8bHZfu9AenulLeUxuhu3ukrp97mPGEQoehRvsr8WA,3752
+ailogger_client/client.py,sha256=AHGwpG3ubyurIJA7HT9JWz-dhxDQiCI6AFEnlw03cto,8976
+ailogger_client/config.py,sha256=ZrpigmlIkpFCtB836EyNjZKzXRx716z3Xv3bUDbOAhk,14001
+ailogger_client/errors.py,sha256=Ay1v3qoQBHfxJXQjB7v2m5wF37BxFPeHnFSVsXgTNoI,25487
+ailogger_client/file_transfer.py,sha256=1faCVYmoJpPebffWu5bCHSH67NyUbhLNW3ENJ7Y0k8M,5290
+ailogger_client/invocation.py,sha256=e6h7qFjvMdRq9gykoVjkY97nW8CnRTBYIvyLHn4sf2M,23458
+ailogger_client/message_methods.py,sha256=ZGty6PoVhfi_jUzSZGJgpEW2iyixnG8NapuCqpRZDZA,16261
+ailogger_client/observation_methods.py,sha256=SPeKPatsXx_spQip3xK4hde57bK2_3XItLLFeWVsZhY,7868
+ailogger_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ailogger_client/queued_methods.py,sha256=FcShGJBUjQvwMM55ovjZ2QvQTRuUMjKYqIH7_u5KpNo,9441
+ailogger_client/read_methods.py,sha256=j24svGlxW3cl-P2IfuKp7yFOee2VwA2PbUZrHbYJ1Aw,30150
+ailogger_client/retrieval_methods.py,sha256=koirEpslvTzxPjeMzZ_YisyVVlod2WbgeSaIbfcUvwo,17509
+ailogger_client/service_methods.py,sha256=i8zXaLcmRArCDlo5ieeXZMM3GEDoKzEcGuW8FsCI09k,6967
+ailogger_client/session_methods.py,sha256=GXbm_i2vC3S0AHPguqkkUx19UqvN1mRkL0vadMukAe0,11365
+ailogger_client_dev-0.1.51.dist-info/METADATA,sha256=b6vuawdLQScl8YrkXE62tBkfEgmYBA7XPAkivwyoAZs,6707
+ailogger_client_dev-0.1.51.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+ailogger_client_dev-0.1.51.dist-info/top_level.txt,sha256=6ECXCYY3140gfyNGX4QFEg1TssYQelfiBFJ-q-OvG0Q,16
+ailogger_client_dev-0.1.51.dist-info/RECORD,,

ailogger_client_dev-0.1.51.dist-info/WHEEL

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

ailogger_client_dev-0.1.51.dist-info/top_level.txt

@@ -0,0 +1 @@
+ailogger_client