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

ailogger_client/message_methods.py

@@ -0,0 +1,332 @@
+"""
+Typed methods for appending messages to dialogue sessions.
+
+This module carries the single mixin class whose typed method lets a caller
+append a message to an existing dialogue session. The method names its
+arguments for what the corresponding command's parameter schema declares,
+so a caller appends a message 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 method carries its arguments to the invocation seam of G-012/T-002/A-001
+and returns what the seam returns. The method 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__ = ["MessageMixin"]
+
+
+class MessageMixin:
+    """Mixin providing a typed method for appending messages.
+
+    Declares the single typed method by which a caller appends a message to
+    an existing dialogue session.
+
+    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 _submit_queued(self, command: str, params: dict[str, Any]) -> str:
+        """Provided by QueuedMixin when this mixin is composed."""
+        raise NotImplementedError  # Provided by QueuedMixin
+
+    async def _await_queued_result(
+        self,
+        job_id: str,
+        *,
+        command: str,
+        timeout: float | None = None,
+    ) -> list[Any]:
+        """Provided by QueuedMixin when this mixin is composed."""
+        raise NotImplementedError  # Provided by QueuedMixin
+
+    async def append_message(  # noqa: PLR0913, PLR0917
+        self,
+        session_id: str,
+        text: str,
+        sender_kind: str,
+        sender_identity: str,
+        receiver_kind: str,
+        receiver_identity: str,
+        priority: int | None = None,
+        message_id: str | None = None,
+        relations: list[dict[str, Any]] | None = None,
+        corrects_message_id: str | None = None,
+        attributes: dict[str, Any] | None = None,
+        occurred_at: str | None = None,
+        force_overwrite: bool | None = None,
+    ) -> Any:
+        """Append one message to a dialogue session.
+
+        Appends one message to a dialogue session this service already holds.
+        Six values are required of every append without exception: the session
+        the message goes into, the text, and each of the two participants as a
+        kind together with an identity - the sender and the receiver.
+
+        Seven more are optional: the priority the message is recorded under
+        (recorded; it does not affect ordering or scheduling, and message_search
+        accepts it as an equality filter), the identifier it is accepted under
+        (the service generates one when none is supplied), the links it
+        declares to earlier messages of the same session, the message it
+        corrects, free-form attributes recorded alongside its text, the
+        moment the message happened
+        (``occurred_at``), and ``force_overwrite``.
+
+        When no identifier is supplied, the ordinary case, the service
+        generates a version 4 UUID and the answer carries it back. Sending
+        that identifier back with the same content is a retry and is answered
+        exactly as the first submission was, with no second message created.
+        Sending it back with ANY different content - text, participants,
+        priority, correction target, attributes, relations or stated moment -
+        is refused as a conflict, unless ``force_overwrite`` is true.
+
+        Each declared relation names the earlier message it points at and the
+        kind of the link. Relations the relation model does not admit are
+        refused and nothing is stored. The correction target is stated
+        separately and is never one entry of the relations collection. The
+        free-form attributes are recorded verbatim and never interpreted - no
+        key inside them alters routing, ordering or acceptance.
+
+        Args:
+            session_id: Reference to the dialogue session this message is
+                appended to, as the identifier that session was opened under.
+                Required of every append: this service appends to no default
+                session.
+            text: The text of the message being appended, recorded exactly as
+                submitted. Required of every append.
+            sender_kind: The capacity the sender of this message stands in, as
+                one of the four declared participant kinds (human, model, tool,
+                system). Required of every append, including one that records
+                plain application logging.
+            sender_identity: The concrete participant this message is
+                attributed to. Required of every append: two senders of the
+                same kind stay two participants whenever their identity differs,
+                and are never collapsed into one.
+            receiver_kind: The capacity the receiver of this message stands in,
+                as one of the four declared participant kinds. Required of
+                every append, including one that records plain application
+                logging.
+            receiver_identity: The concrete participant this message is
+                addressed to. Required of every append: two receivers of the
+                same kind stay two participants whenever their identity differs,
+                and are never collapsed into one.
+            priority: The priority this message is recorded under, as a
+                non-negative whole number. Zero marks the ordinary linear flow
+                of the dialogue and a higher value says the message was
+                inserted from outside that flow. Optional: omit it to record
+                under the priority the service resolves.
+            message_id: The identifier this message is to be accepted under, as
+                a well-formed version 4 UUID. Optional and legitimately absent:
+                the ordinary append supplies none, the service generates one
+                and the answer carries it back, and such a submission is a
+                first acceptance by construction. Supply the identifier a
+                previous answer returned to have a retry recognised as the same
+                message.
+            relations: The links this message declares to earlier messages of
+                the same session, in the order declared: each entry is a
+                mapping naming the earlier message (as to_message_id) and the
+                kind of the link (as kind). Optional: omit it or declare the
+                empty collection when this message declares none.
+            corrects_message_id: The identifier of the message this one
+                corrects, as a well-formed version 4 UUID, present only when
+                this message is issued as a correction of an earlier one.
+                Optional: omit it when this message corrects nothing.
+            attributes: Free-form attributes recorded alongside the message
+                text, stored verbatim and never interpreted. Optional and
+                legitimately absent or empty.
+            occurred_at: The moment the message happened, as an RFC 3339
+                timestamp WITH an explicit UTC offset (``Z`` or ``+hh:mm``;
+                fractional seconds allowed). It becomes the message's
+                effective event time, stored and returned normalised to UTC:
+                reads order by it, the period filters and the working-set
+                recency use it. Optional: omit it and the service's receive
+                time stands. Passed through unchanged; the service validates
+                it.
+            force_overwrite: When true, a ``message_id`` that is already
+                stored is REPLACED by this payload without any comparison,
+                keeping its identifier and sequence number and being analysed
+                afresh. Optional, default false (the identifier is recognised:
+                an identical repeat returns the original, a differing one is
+                a conflict). Passed through unchanged; the service validates
+                it.
+
+        Returns:
+            Exactly five facts about the accepted message: the identity it
+            was accepted under, as the identifier supplied when one was
+            supplied and the one the service generated when none was
+            (``message_id``); the position assigned to it within its session
+            by the arrival-order model (``sequence_number``); the audience it
+            carries (``audience``); and ``text_head`` and ``text_tail``, the
+            first and the last five words of the STORED text (words as
+            ``str.split()`` yields, joined by one space; they overlap when the
+            text has fewer than ten words, each holds all the words when it
+            has fewer than five, and both are ``""`` for a text without
+            words). A recognised retry answers with the identity, position,
+            audience and excerpts already accepted for that identifier; a
+            force overwrite answers with the excerpts of the text now stored.
+        """
+        params: dict[str, Any] = {
+            "session_id": session_id,
+            "text": text,
+            "sender_kind": sender_kind,
+            "sender_identity": sender_identity,
+            "receiver_kind": receiver_kind,
+            "receiver_identity": receiver_identity,
+        }
+        if priority is not None:
+            params["priority"] = priority
+        if message_id is not None:
+            params["message_id"] = message_id
+        if relations is not None:
+            params["relations"] = relations
+        if corrects_message_id is not None:
+            params["corrects_message_id"] = corrects_message_id
+        if attributes is not None:
+            params["attributes"] = attributes
+        if occurred_at is not None:
+            params["occurred_at"] = occurred_at
+        if force_overwrite is not None:
+            params["force_overwrite"] = force_overwrite
+        return await self._invoke("append_message", params)
+
+    async def messages_import(
+        self,
+        messages: list[dict[str, Any]],
+        *,
+        timeout: float | None = None,
+    ) -> list[dict[str, Any]]:
+        """Import a batch of messages and return the per-item outcomes.
+
+        ``messages_import`` is ALWAYS queued by the service. This method
+        submits the job, waits for it to finish through the client's own job
+        tracking and returns the job's result: a list with exactly one entry
+        per input item, in input order, each ``{"message_id": <id or None>,
+        "success": <bool>}`` and, when ``success`` is true, also
+        ``"text_head"`` and ``"text_tail"`` (the first and the last five
+        words of the item's stored text, as for ``append_message``).
+        ``success`` is true when the message is stored
+        (newly created, an identical repeat, or overwritten) and false when it
+        was not stored (the item failed validation or conflicts with a stored
+        message). Items are independent: a false item does not roll back the
+        others. Running the same import again answers true for every item and
+        adds no row.
+
+        Args:
+            messages: The items to import - exactly the ``append_message``
+                parameter set per item, with ``message_id`` and
+                ``occurred_at`` required. Passed through unchanged; the
+                service validates them.
+            timeout: The longest to wait for the job, in seconds. Optional:
+                the client's own bound applies when omitted.
+
+        Returns:
+            The per-item outcomes, in input order.
+
+        Raises:
+            ServiceRefusalError: When the whole call is refused (messages
+                missing, not an array, empty, over the configured maximum, an
+                element that is not an object, an unnamed parameter or a
+                repeated message_id) - nothing is written and no job exists.
+            CompletionTimeoutError: When the job does not finish in time.
+            CompletionFailedError: When the job fails.
+        """
+        job_id = await self._submit_queued("messages_import", {"messages": messages})
+        return [
+            dict(entry)
+            for entry in await self._await_queued_result(
+                job_id, command="messages_import", timeout=timeout
+            )
+        ]
+
+    async def mark_messages_for_deletion(
+        self,
+        message_ids: list[str],
+        marked_for_deletion: bool,
+    ) -> Any:
+        """Atomically set or clear the soft-deletion marker for messages.
+
+        Returns the command's boolean outcome. A true value means every UUID
+        reached the requested marker state. A false value means the batch was
+        empty, malformed, duplicate, unknown, or could not be changed, and no
+        marker changed. Repeating a valid set or clear is successful.
+        """
+        return await self._invoke(
+            "messages_mark_for_deletion",
+            {
+                "message_ids": message_ids,
+                "marked_for_deletion": marked_for_deletion,
+            },
+        )
+
+    async def message_get(self, message_id: str) -> Any:
+        """Read one message by its identifier with its vectorization state.
+
+        Returns the messages_read entry of the message plus
+        ``vectorization_state`` (``"pending"``, ``"vectorized"`` or the terminal
+        ``"not_vectorizable"`` for whitespace-only text, which is never
+        embedded). A
+        soft-deleted message is returned with ``soft_deleted`` true.
+
+        Raises:
+            ServiceRefusalError: MESSAGE_UNKNOWN for an unknown id, or the
+                REQUEST_PARAMETER_* code for a refused parameter.
+        """
+        return await self._invoke("message_get", {"message_id": message_id})
+
+    async def message_delete(self, message_id: str, mode: str) -> Any:
+        """Delete one message in the service's soft or hard mode.
+
+        ``mode="soft"`` marks the message deleted so ordinary reads hide it.
+        ``mode="hard"`` physically removes an unreferenced message and its
+        outbound derived rows. The service validates the identifier and mode,
+        and returns the deletion report it publishes.
+        """
+        return await self._invoke(
+            "message_delete",
+            {"message_id": message_id, "mode": mode},
+        )

ailogger_client/observation_methods.py

@@ -0,0 +1,195 @@
+"""
+Public observation methods of the client: the negative-case probe, the typed
+help, the typed health route and the answer-mode observation.
+
+These are not typed methods of any one command of the service. They are the
+caller-facing surface a consumer that has to look at the service from the
+outside - a verification suite above all - needs, so that it never reaches for
+a private attribute of the client, the framework's own client, a raw JSON-RPC
+call, a queue poll or an envelope:
+
+- ``probe_command`` sends EXACTLY the parameters it is given to a named
+  command - missing, unknown, null and wrongly typed values included, nothing
+  added, dropped or validated here - and returns or raises exactly as a typed
+  method does. An always-queued command is waited for like its typed method.
+- ``help`` is the service's own ``help`` command, typed.
+- ``health_route`` is the one declared exception to "everything is a command":
+  the ``GET /health`` route, answered as the bare report it is.
+- ``command_answer_mode`` reports HOW the service answered a command - inline
+  (``direct``) or with a job identity (``queued``) - without the caller looking
+  at an envelope and without waiting for a job.
+
+This module is deliberately outside the set of modules whose public coroutine
+methods the client-surface agreement counts as typed commands: none of these
+methods is a command of the service.
+
+NETWORK LAW. This module imports nothing from the adapter framework and adds
+no transport of its own; everything goes through the invocation seam and the
+privately held framework client that ``ailogger_client.invocation`` guards.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from .errors import translated_failures
+from .queued_methods import find_job_id
+
+__all__ = ["ObservationMixin"]
+
+
+class ObservationMixin:
+    """
+    Mixin providing the probe, help, health-route and answer-mode methods.
+
+    This mixin expects to be composed with InvocationMixin (``_invoke``,
+    ``_invoke_unconverted`` and the private framework client) and QueuedMixin
+    (``_await_queued_result``).
+    """
+
+    _client: Any
+
+    async def _invoke(
+        self,
+        command: str,
+        params: dict[str, Any] | None = None,
+        *,
+        wait_for_result: bool = True,
+    ) -> Any:
+        """Private invocation entry point, provided by InvocationMixin."""
+        raise NotImplementedError  # Provided by InvocationMixin
+
+    async def _invoke_unconverted(
+        self,
+        command: str,
+        params: dict[str, Any] | None,
+        wait_for_result: bool,
+    ) -> Any:
+        """Unconverted invocation, provided by InvocationMixin."""
+        raise NotImplementedError  # Provided by InvocationMixin
+
+    async def _await_queued_result(
+        self,
+        job_id: str,
+        *,
+        command: str,
+        timeout: float | None = None,
+    ) -> list[Any]:
+        """Queued completion, provided by QueuedMixin."""
+        raise NotImplementedError  # Provided by QueuedMixin
+
+    async def probe_command(
+        self, command: str, params: Mapping[str, Any] | None
+    ) -> Any:
+        """Send EXACTLY these parameters to a command and return its answer.
+
+        The negative-case probe. The parameter map is sent as given: a missing
+        required parameter, an unknown one, an explicit ``None`` and a value of
+        the wrong type all go through unchanged - nothing is added, removed,
+        defaulted or validated by the client, so the answer is the service's
+        own verdict on exactly this request. ``None`` sends no parameters.
+
+        The outcome is what a typed method's would be: the command's answer in
+        the service's ``{success, data}`` form, or a typed error of this
+        client (``ServiceRefusalError`` carrying the service's stable code for
+        a refusal, ``ServiceUnreachableError``, ...). A command the service
+        always queues is waited for as its typed method waits: the answer is
+        then ``{"success": True, "data": <the job's result array>}``.
+
+        Args:
+            command: The name of the command to send.
+            params: The parameter map to send exactly, or ``None`` for none.
+
+        Returns:
+            The command's answer.
+
+        Raises:
+            ServiceRefusalError: When the service refuses the request.
+            AiLoggerClientError: For every other failure, translated.
+        """
+        sent = None if params is None else dict(params)
+        answer = await self._invoke(command, sent, wait_for_result=False)
+        job_id = find_job_id(answer)
+        if job_id is None:
+            return answer
+        result = await self._await_queued_result(job_id, command=command)
+        return {"success": True, "data": result}
+
+    async def help(
+        self,
+        cmdname: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> Any:
+        """The service's ``help`` command: the catalogue, or one command.
+
+        Only the arguments that are not ``None`` are sent. The service
+        validates them (its help command names ``cmdname``); this method adds
+        no check of its own.
+
+        Args:
+            cmdname: A command to describe in detail; omitted lists them all.
+            limit: How many entries to return, when the service pages them.
+            offset: Where the page starts, when the service pages them.
+
+        Returns:
+            The answer of the ``help`` command.
+        """
+        params: dict[str, Any] = {}
+        if cmdname is not None:
+            params["cmdname"] = cmdname
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+        return await self._invoke("help", params)
+
+    async def health_route(self) -> dict[str, Any]:
+        """The service's ``GET /health`` route, answered as its bare report.
+
+        The one declared exception to "everything is a command": the health
+        route is not a command of the service, and its answer is the report
+        itself - not a command envelope.
+
+        Returns:
+            The health report mapping, as the route answers it.
+
+        Raises:
+            ServiceUnreachableError: When the route cannot be reached.
+            AiLoggerClientError: For every other failure, translated.
+        """
+        with translated_failures():
+            report: dict[str, Any] = await self._client.health()
+        return report
+
+    async def command_answer_mode(
+        self, command: str, params: Mapping[str, Any] | None = None
+    ) -> dict[str, Any]:
+        """Report how the service answers a command: inline or queued.
+
+        Sends the command once with the given parameters and classifies the
+        answer: a job identity means ``queued``, anything else means
+        ``direct``. A queued command is never waited for - its job is left to
+        run. A direct command is run, and an inline refusal of it still answers
+        ``direct``: the service answered on the spot, which is what is being
+        observed. A request the service declined before queueing, and every
+        transport failure, arrives as a typed error.
+
+        Args:
+            command: The command to observe.
+            params: The parameters to send, or ``None`` for none.
+
+        Returns:
+            Exactly ``{"answer_mode": "direct" | "queued", "job_id": str | None}``.
+
+        Raises:
+            AiLoggerClientError: When the request fails before the service
+                answers it.
+        """
+        sent = None if params is None else dict(params)
+        answer = await self._invoke_unconverted(command, sent, False)
+        job_id = find_job_id(answer)
+        if job_id is None:
+            return {"answer_mode": "direct", "job_id": None}
+        return {"answer_mode": "queued", "job_id": job_id}