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

ailogger_client/retrieval_methods.py

@@ -0,0 +1,314 @@
+"""
+Typed methods for message retrieval through working-set and search queries.
+
+This module carries the single mixin class whose typed methods let a caller
+retrieve messages by two distinct retrieval routes: the working set command,
+which assembles a session's recent tail and its closest matches to an anchor
+in one call, and the message-search command, which pages through messages
+matching a query by closeness of meaning.
+
+Each method names its arguments for what the corresponding command's parameter
+schema declares, so a caller retrieves messages 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.
+
+Each method carries its arguments to the invocation seam of G-012/T-002/A-001
+and returns what the seam returns. No ranking, filtering, de-duplication or
+local similarity computation happens here: a caller asks for a result and
+receives that result exactly as the service published it.
+
+Required and optional parameters are mirrored exactly from the service command
+declarations read as reference: working_set_command.py (G-009/T-005:
+session_id=line 563, anchor_text=line 568, anchor_message_id=line 572,
+recency_count=line 597, similarity_count=line 604, mode=line 621) and
+message_search_command.py (G-009/T-006: query_text=line 1099, scope=line 1012,
+scope_target=line 1025, filters=line 1040, mode=line 1058, page_size=line 1075,
+page_offset=line 1091).
+
+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__ = ["RetrievalMixin"]
+
+
+class RetrievalMixin:
+    """Mixin providing typed methods for message retrieval.
+
+    Declares the two typed methods by which a caller retrieves messages: the
+    working-set command, which assembles a session's recent tail and its
+    closest matches to an anchor in one call, and the message-search command,
+    which pages through messages matching a query by closeness of meaning.
+
+    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 working_set(  # noqa: PLR0913, PLR0917
+        self,
+        session_id: str,
+        anchor_text: str | None = None,
+        anchor_message_id: str | None = None,
+        recency_count: int | None = None,
+        similarity_count: int | None = None,
+        mode: str | None = None,
+    ) -> Any:
+        """Obtain the working set of one dialogue session in a single call.
+
+        The one route through which a consumer obtains everything it must
+        process for one recorded dialogue session without several round trips.
+        One request yields TWO independently sized groups in ONE answer: the
+        RECENT group, the most recently arrived messages of the named session,
+        and the CLOSEST group, the messages of that same session closest in
+        meaning to a supplied anchor.
+
+        THE ANCHOR IS SUPPLIED IN EXACTLY ONE OF TWO FORMS: an inline text,
+        whose meaning closeness is measured against, or a reference to a
+        message, which stands for the meaning of that message. Exactly one form
+        must be present in every call - supply anchor_text for an inline query
+        or anchor_message_id for a message reference, never both and never
+        neither.
+
+        WHAT IT REFUSES. A session this service does not know. A message anchor
+        that is not a message of the named session. A resolved count above the
+        ceiling that governs it. A governed optional parameter that resolves in
+        none of the three sources. The external embedding service being
+        unavailable when the anchor had to be embedded.
+
+        WHAT IT DOES NOT DO. It assembles no working set of its own and
+        re-ranks, re-scores, re-orders, re-groups, substitutes, collapses,
+        de-duplicates, filters, trims and truncates nothing: each group is
+        exactly what the domain's working-set assembly delivered, in that order
+        and with those scores. A message not yet vectorized reaches the caller
+        through the recent group exactly as any other message does and is
+        simply absent from the closest group; that absence is ordinary and is
+        never reported as an error. An empty group of either kind is a success,
+        not a failure.
+
+        Args:
+            session_id: Reference to the dialogue session whose working set is
+                wanted. Required in every request: this service never invents,
+                generates or defaults a session reference.
+            anchor_text: The anchor in its INLINE TEXT form: the text whose
+                meaning the closeness of a message is measured against, used
+                exactly as supplied and never trimmed, normalised, lower-cased
+                or truncated. Exactly one of anchor_text or anchor_message_id
+                must be supplied: supply this when describing what you are
+                looking for, or supply anchor_message_id when you already have
+                a message in hand. Optional.
+            anchor_message_id: The anchor in its MESSAGE REFERENCE form: a
+                reference to a message, standing for the meaning of that
+                message. Exactly one of anchor_text or anchor_message_id must
+                be supplied: supply this when you already have a message in hand,
+                or supply anchor_text when describing what you are looking for.
+                Optional.
+            recency_count: How many of the most recent messages of the named
+                session the answer is to carry. Optional: an omitted count is
+                not a missing value - it resolves through the project's fixed
+                order (call arguments, then service configuration, then shipped
+                constants), and it is additionally held to a ceiling declared by
+                that same order which no caller can state or raise.
+            similarity_count: How many anchor-closest messages of that same
+                session the answer is to carry. Optional: an omitted count is
+                not a missing value - it resolves through the project's fixed
+                order (call arguments, then service configuration, then shipped
+                constants), and it is additionally held to a ceiling declared by
+                that same order which no caller can state or raise.
+            mode: In which form the recorded content of the answer is delivered:
+                'resolved' substitutes the final version of a correction chain,
+                collapses duplicate final messages and keeps the highest
+                similarity score of a collapsed set before the requested counts
+                are applied, and 'full' returns every recorded version as it
+                stands, for analysis over superseded wording. Optional: an
+                omitted mode is not a missing value - it resolves through the
+                project's fixed order (call arguments, then service
+                configuration, then shipped constants).
+
+        Returns:
+            One result carrying both groups together: the RECENT group, holding
+            at most the resolved recency count of messages; and the CLOSEST
+            group, holding at most the resolved similarity count of them. Each
+            group is identified by the member it is carried under and every
+            entry additionally names the criterion it reached the answer by. The
+            answer also states the session the request named and the anchor text
+            the closeness was actually measured against.
+        """
+        params: dict[str, Any] = {"session_id": session_id}
+        if anchor_text is not None:
+            params["anchor_text"] = anchor_text
+        if anchor_message_id is not None:
+            params["anchor_message_id"] = anchor_message_id
+        if recency_count is not None:
+            params["recency_count"] = recency_count
+        if similarity_count is not None:
+            params["similarity_count"] = similarity_count
+        if mode is not None:
+            params["mode"] = mode
+        return await self._invoke("working_set", params)
+
+    async def message_search(  # noqa: PLR0913, PLR0917
+        self,
+        query_text: str,
+        scope: str,
+        scope_target: str | None = None,
+        filters: dict[str, Any] | None = None,
+        mode: str | None = None,
+        page_size: int | None = None,
+        page_offset: int | None = None,
+    ) -> Any:
+        """Search recorded dialogue messages by closeness of meaning to a query.
+
+        The one route through which this service's similarity search over
+        recorded message text is reached. A message matches by closeness of
+        meaning between the embedding of the query text and the embedding held
+        for that message - never because the message contains the query as a
+        substring or happens to share its words.
+
+        Every search states its own bounds explicitly: one named session, one
+        named project, or all projects. Within those bounds a caller may narrow
+        along exactly the axes the vector record carries as filterable metadata
+        - project, session, sender kind, priority and arrival time - and may
+        state which recorded versions to be delivered, resolved or full.
+
+        One page is then produced by filtering, then the mode transformation,
+        then a total sort by similarity score with a deterministic tiebreak on
+        the matched message's own identifier, then the offset, then the window:
+        paging is therefore coherent and repeatable.
+
+        WHAT IT REFUSES. A scope designating a session or a project that does
+        not exist, said as two distinct codes so you tell the two apart
+        mechanically. A filter along an axis the search does not accept. A
+        resolved page size above the ceiling that governs it. The external
+        embedding service being unavailable when the query had to be embedded.
+
+        WHAT IT DOES NOT DO. It performs no matching of its own and re-ranks,
+        re-groups and re-scores nothing: the window it answers with is the
+        window the search produced. A message not yet vectorized cannot be
+        found by similarity and is simply absent from the answer; that absence
+        is ordinary and is never reported as an error. An offset at or past the
+        end of the match set is answered successfully with an empty window
+        rather than refused.
+
+        Args:
+            query_text: The text whose MEANING the search is by. A message
+                matches by closeness of meaning between the embedding of this
+                text and the embedding held for that message, never because the
+                message contains this text as a substring or happens to share its
+                words. Required and non-empty: without it there is nothing to
+                search for.
+            scope: How wide this search reaches, stated explicitly and never
+                inferred: 'session' searches one named session, 'project'
+                searches every session of one named project, and 'all_projects'
+                places no scope bound at all. A bounded reach names its target in
+                scope_target; the all-projects reach names none. Required.
+            scope_target: What the bounded reach applies to: the identifier of
+                the session for the 'session' scope, the identifier of the
+                project for the 'project' scope. Required by exactly those two
+                scopes and admitted by neither of them absent; the 'all_projects'
+                scope applies to no target, so a designation supplied alongside
+                it is refused rather than ignored. Whether the designated
+                session or project exists is a separate question. Optional.
+            filters: Narrowing conditions applied WITHIN the resolved scope,
+                along exactly the axes the search accepts because the vector
+                record carries them as filterable metadata: the project, the
+                session, the sender kind, the priority and the time. Every axis
+                is optional and an axis left unstated is left unconstrained; the
+                filter as a whole may be omitted entirely or supplied empty, in
+                which case the resolved scope alone bounds the search. An axis
+                the search does not accept is refused, naming it, rather than
+                ignored. Optional and legitimately absent or empty.
+            mode: Which recorded versions the search delivers for what it
+                matched: 'resolved' delivers a hit on a superseded message as
+                its correction chain's final version, 'full' delivers every
+                matching recorded version exactly as recorded. Similarity is
+                evaluated over every recorded version under either value.
+                Optional: an omitted mode is not a missing value - it resolves
+                through the project's fixed order (call arguments, then service
+                configuration, then shipped constants).
+            page_size: How many matched messages one window may hold, counted in
+                messages and never in vector records. It bounds this one answer
+                and nothing else: it never bounds the matched set the query
+                found and never says where the window begins. Optional: an
+                omitted page size is not a missing value - it resolves through
+                the project's fixed order (call arguments, then service
+                configuration, then shipped constants).
+            page_offset: Where this answer's window begins: how many matches of
+                the sorted match set to skip first, zero-based and counted in
+                messages. It locates the window and nothing else - it never
+                bounds the matched set and never bounds the window's size. It
+                carries NO ceiling: paging depth is deliberately unbounded, and
+                an offset at or past the end of the match set is answered
+                successfully with an empty window rather than refused. Optional:
+                an omitted offset is not a missing value - it resolves through
+                the project's fixed order (call arguments, then service
+                configuration, then shipped constants).
+
+        Returns:
+            One window of matches taken from the full sorted match set: it
+            begins at the resolved offset and holds at most the resolved page
+            size of matches. Each match carries exactly four members - the
+            matched message as recorded, the identifier of the session that
+            message belongs to, the identifier of the project that session
+            belongs to, and the similarity score of the match. Beside the window
+            the answer states whether further matches remain and, when they do,
+            the offset at which the next window begins (null when none remain),
+            and the size of the WHOLE matched set, counted in messages after the
+            mode has been applied and never trimmed by the page size, the offset
+            or any ceiling. A window with no matches is a success, not a failure.
+        """
+        params: dict[str, Any] = {
+            "query_text": query_text,
+            "scope": scope,
+        }
+        if scope_target is not None:
+            params["scope_target"] = scope_target
+        if filters is not None:
+            params["filters"] = filters
+        if mode is not None:
+            params["mode"] = mode
+        if page_size is not None:
+            params["page_size"] = page_size
+        if page_offset is not None:
+            params["page_offset"] = page_offset
+        return await self._invoke("message_search", params)

ailogger_client/service_methods.py

@@ -0,0 +1,148 @@
+"""
+Typed methods for service's self-describing commands.
+
+This module carries the single mixin class whose typed methods let a caller
+invoke the service's own self-describing commands: the info command, which
+describes the service's capabilities by section, and the health command, which
+reports the service's liveness and its dependencies.
+
+Each method names its arguments for what the corresponding command's parameter
+schema declares, so a caller describes the service 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.
+
+The info command declares one optional parameter, a section name, which
+legitimately admits absence: called without it the command answers with its
+table of contents, called with a section name it answers with exactly that
+section. That optional parameter is mirrored exactly on the method: when the
+caller does not supply it, no value for it is carried at all rather than
+substituting a name or a placeholder, so the service's own meaning for an
+absent section - its table of contents - is what the caller receives. The
+health command declares no parameters at all; its method takes no arguments.
+
+Each method carries its arguments to the invocation seam of G-012/T-002/A-001
+and returns what the seam returns exactly as published. No caching, no local
+documentation assembly, no section-name list, no recomputation of any status,
+and no reinterpretation of a health report appears here - in particular no
+overall status is computed from its parts.
+
+The info command is declared by G-011/T-004. The health command is this
+service's override of the framework's own platform command, declared by
+G-013/T-001. Both are commands of this service's own, and the named
+client-surface-agreement check of G-010/T-004/A-008 will demand a typed
+method for each: without these methods the client would be short by two and
+that check would fail.
+
+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. The health method probes no
+dependency of the service directly.
+
+BOUNDARIES. This module declares no typed method for any other command.
+Platform commands the service does not override (the plain help command in
+particular) get no typed method here. This module declares no class, dataclass,
+typed dictionary or schema describing an info section, a table of contents, a
+health report, a dependency or a status, and no enumeration of section names
+or status values.
+
+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__ = ["ServiceMixin"]
+
+
+class ServiceMixin:
+    """Mixin providing typed methods for the service's self-describing commands.
+
+    Declares the two typed methods by which a caller invokes the service's own
+    self-describing commands: the info command, which describes the service's
+    capabilities by section, and the health command, which reports the service's
+    liveness and its dependencies.
+
+    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 info(self, section: str | None = None) -> Any:
+        """Describe the service's capabilities by section.
+
+        Invokes the service's info command, declared by G-011/T-004, to obtain
+        a description of the service's capabilities. Called without a section
+        name, the command answers with its table of contents. Called with a
+        section name, the command answers with exactly that section.
+
+        This method carries the section parameter to the invocation seam only
+        when the caller supplies it; when the caller does not supply it, no
+        value for it is carried at all, so the service's own resolution of an
+        absent section - its table of contents - is never pre-empted by a value
+        invented in this client.
+
+        Args:
+            section: The name of the section whose description is wanted.
+                Optional and legitimately absent: omit it to obtain the table of
+                contents. When supplied, the section name is carried to the
+                service, which answers with exactly that section or refuses the
+                request with its specific contracted error.
+
+        Returns:
+            When called without a section, the table of contents of the service's
+            capabilities. When called with a section name, the description of
+            exactly that section. The answer is the finished result exactly as
+            the service published it, without caching, local documentation
+            assembly, section-name validation or reinterpretation.
+        """
+        params: dict[str, Any] | None = None
+        if section is not None:
+            params = {"section": section}
+        return await self._invoke("info", params)
+
+    async def health(self) -> Any:
+        """Report the service's liveness and the state of its dependencies.
+
+        Invokes the service's health command, declared by G-013/T-001, to obtain
+        the composed report of the service's liveness and its dependencies. This
+        service overrides the framework's own platform health command and thereby
+        makes it its own.
+
+        This method takes no arguments: the command declares no parameters, and
+        no request parameter is passed through. The health method probes no
+        dependency of the service directly; all probing is delegated to the
+        service itself through the invocation seam.
+
+        Returns:
+            The composed report of the service's liveness and its dependencies,
+            exactly as the service published it. No recomputation, no overall
+            status derivation, and no reinterpretation of the health report
+            occurs here - the answer is what the service returns.
+        """
+        return await self._invoke("health", None)