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

ailogger_client/read_methods.py

@@ -0,0 +1,585 @@
+"""
+Typed methods for reading dialogue session data.
+
+This module carries the single mixin class whose typed methods let a caller
+read what a single session holds through five distinct reads: the journal
+window of messages in arrival order, the chain running from a named node to
+its root, the relations declared in the session, the leaves and branching
+points of the session structure, and the graph descending from a named node.
+
+Each method names its arguments for what the corresponding command's parameter
+schema declares, so a caller reads 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 one page exactly as the service publishes it. No iteration, no
+accumulation, no stitching of pages happens here: a caller asks for a window
+and receives that window, and walking a sequence of windows is the caller's
+business.
+
+Required and optional parameters are mirrored exactly from the service command
+declarations read as reference: messages_read_command.py (G-009/T-004/A-002),
+path_read_command.py (G-009/T-004/A-005), relations_read_command.py
+(G-009/T-004/A-008), leaves_read_command.py (G-009/T-004/A-010),
+graph_read_command.py (G-009/T-004/A-012), and sessions_list_command.py
+(G-009/T-004/A-015).
+
+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
+
+from ailogger_client.errors import WrongArgumentTypeError
+
+__all__ = ["ReadMixin"]
+
+
+class ReadMixin:
+    """Mixin providing typed methods for reading dialogue session data.
+
+    Declares six typed methods: five that read what a single dialogue session
+    holds (the journal window of messages in arrival order, the path from a
+    named node to its root, the relations declared within the session, the
+    leaves and branching points of the session structure, and the graph
+    descending from a named node), and one that lists sessions matching
+    constrained filter axes across the whole store.
+
+    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 messages_read(  # noqa: PLR0912, PLR0913, PLR0917
+        self,
+        session_id: str | None = None,
+        start_sequence_number: int | None = None,
+        block_size: int | None = None,
+        continuation: str | None = None,
+        mode: str | None = None,
+        caller_id: str | None = None,
+        recipient_id: str | None = None,
+        period_start: str | None = None,
+        period_end: str | None = None,
+        page_offset: int | None = None,
+        page_size: int | None = None,
+        preview_size: int | None = None,
+        show_deleted: bool | None = None,
+    ) -> Any:
+        """Read a legacy journal window or a filtered message preview.
+
+        Returns one bounded block of the messages of the addressed dialogue
+        session, in arrival order, starting at the requested sequence position.
+        The window is the bounded page that the service delivers at that
+        position, never a whole-session read, and pagination parameters govern
+        how much of the dialogue is retrieved at once.
+
+        The window begins at the sequence position the caller supplies, unless
+        a resumption point from a previous call to this method is present, in
+        which case the resumed request starts at that point instead and the
+        start position is ignored. Sequence positions are service-assigned
+        arrival indices starting from zero.
+
+        The block_size, continuation, and mode parameters are optional. When
+        not supplied, the service resolves them through its own order: the
+        call arguments, otherwise the service configuration, otherwise shipped
+        constants. Omitting block_size does not cause this method to invent
+        one; the service resolves its own bound. Omitting mode does not select
+        a default in this signature; the service resolves which recorded
+        versions the answer delivers.
+
+        Args:
+            session_id: Identity of the dialogue session whose messages are
+                to be read. Required: this method reads from an existing
+                session, never from the whole message store.
+            start_sequence_number: The zero-based arrival position at which
+                the requested window begins. Required unless continuation is
+                supplied: a continuation alone decides where the block begins.
+                The window is addressed by sequence number, not by identifier
+                or offset.
+            block_size: The number of messages one answer may carry. Optional:
+                when not supplied, the service resolves the bound through its
+                own order. This client never invents a page size and never
+                pre-empts the service's resolution of an unsupplied value.
+            continuation: The resumption point a previous call to this method
+                returned, sent back unread and unedited to continue that read.
+                Optional: absent on a first request, in which case the window
+                begins at the requested start position instead.
+            mode: Which recorded versions this read delivers. 'resolved'
+                delivers each correction chain as the version that arrived
+                last; 'full' delivers every recorded version exactly as
+                recorded, superseded wording included. Neither mode changes
+                anything stored. Optional: omit it to read under the mode the
+                service resolves.
+
+        With ``mode="preview"``, session_id, caller_id, recipient_id,
+        period_start and period_end are independent optional filters. Empty
+        filters are omitted. page_offset and page_size identify the requested
+        page; preview_size controls the returned text prefix and defaults to
+        200 characters. The result contains entries, total_messages,
+        total_pages, page_offset and page_size.
+
+        Returns:
+            One page of the journal window exactly as the service publishes it,
+            carrying the bounded block, the statement of whether further
+            results follow, and the resumption point for the next block.
+        """
+        params: dict[str, Any] = {}
+        if session_id is not None:
+            params["session_id"] = session_id
+        if start_sequence_number is not None:
+            params["start_sequence_number"] = start_sequence_number
+        if block_size is not None:
+            params["block_size"] = block_size
+        if continuation is not None:
+            params["continuation"] = continuation
+        if mode is not None:
+            params["mode"] = mode
+        if caller_id is not None:
+            params["caller_id"] = caller_id
+        if recipient_id is not None:
+            params["recipient_id"] = recipient_id
+        if period_start is not None:
+            params["period_start"] = period_start
+        if period_end is not None:
+            params["period_end"] = period_end
+        if page_offset is not None:
+            params["page_offset"] = page_offset
+        if page_size is not None:
+            params["page_size"] = page_size
+        if preview_size is not None:
+            params["preview_size"] = preview_size
+        if isinstance(show_deleted, bool):
+            params["show_deleted"] = show_deleted
+        elif isinstance(show_deleted, str) and not show_deleted.strip():
+            pass
+        elif show_deleted is not None:
+            raise WrongArgumentTypeError()
+        return await self._invoke("messages_read", params)
+
+    async def path_read(
+        self,
+        session_id: str,
+        node_id: str,
+        block_size: int | None = None,
+        continuation: str | None = None,
+        mode: str | None = None,
+    ) -> Any:
+        """Read the chain from a named node to its dialogue root.
+
+        Returns the path running from the named node of the addressed dialogue
+        session back to the root of that node's own line, in the order from the
+        node towards the root. The path is the bounded page that the service
+        delivers at that position, never a whole-session read, and pagination
+        parameters govern how much of the chain is retrieved at once.
+
+        The path is addressed by a specific node within the session. A node
+        belongs to the addressed session by definition of this read: the pair
+        is meaningful only when the node is in fact a node of that session,
+        and a node of another session is not contained in this one.
+
+        The block_size, continuation, and mode parameters are optional. When
+        not supplied, the service resolves them through its own order: the
+        call arguments, otherwise the service configuration, otherwise shipped
+        constants. Omitting block_size does not cause this method to invent
+        one; the service resolves its own bound. Omitting mode does not select
+        a default in this signature; the service resolves which recorded
+        versions the answer delivers.
+
+        Args:
+            session_id: Identity of the dialogue session whose path is to be
+                read. Required: this method walks a line inside an existing
+                session, never across the whole store.
+            node_id: Identity of the node whose line is walked back to its
+                root. Required: the path is addressed by a specific node.
+            block_size: The number of chain nodes one answer may carry.
+                Optional: when not supplied, the service resolves the bound
+                through its own order. This client never invents a page size
+                and never pre-empts the service's resolution of an unsupplied
+                value.
+            continuation: The resumption point a previous call to this method
+                returned, sent back unread and unedited to continue that read.
+                Optional: absent on a first request, in which case the chain
+                begins at the named node instead.
+            mode: Which recorded versions this read delivers. 'resolved'
+                delivers each correction chain along the line represented by
+                the version that arrived last; 'full' delivers every recorded
+                version exactly as recorded, superseded wording included.
+                Neither mode changes anything stored. Optional: omit it to read
+                under the mode the service resolves.
+
+        Returns:
+            One page of the path exactly as the service publishes it, carrying
+            the bounded block of chain nodes, the statement of whether further
+            results follow, and the resumption point for the next block.
+        """
+        params: dict[str, Any] = {
+            "session_id": session_id,
+            "node_id": node_id,
+        }
+        if block_size is not None:
+            params["block_size"] = block_size
+        if continuation is not None:
+            params["continuation"] = continuation
+        if mode is not None:
+            params["mode"] = mode
+        return await self._invoke("path_read", params)
+
+    async def relations_read(
+        self,
+        session_id: str,
+        block_size: int | None = None,
+        continuation: str | None = None,
+    ) -> Any:
+        """Read the relations declared in one dialogue session.
+
+        Returns the relations declared in the addressed dialogue session, each
+        with its kind and its two endpoint nodes. The relation set is the
+        bounded page that the service delivers at that position, never a
+        whole-session read, and pagination parameters govern how much of the
+        declared relations are retrieved at once.
+
+        The relations reported are exactly the links between nodes that are
+        stored: the four kinds the service declares (reply, influence,
+        tool-result, and correction), reported with the correction link visible
+        among the others, because this read is where a consumer reaches the
+        history of a correction at all.
+
+        This read is a structural read: it reports which links exist between
+        which nodes and substitutes nothing whatever a caller states. No mode
+        parameter is declared in the schema, and sending one causes refusal as
+        an unnamed parameter. The answer over a session containing a correction
+        chain is identical to any request, because this read never resolves a
+        correction chain to its final version.
+
+        The block_size and continuation parameters are optional. When not
+        supplied, the service resolves them through its own order: the call
+        arguments, otherwise the service configuration, otherwise shipped
+        constants. Omitting block_size does not cause this method to invent
+        one; the service resolves its own bound.
+
+        Args:
+            session_id: Identity of the dialogue session whose declared
+                relations are to be returned. Required: this method reads the
+                relations of an existing session, never of the whole store.
+            block_size: The number of relations one answer may carry. Optional:
+                when not supplied, the service resolves the bound through its
+                own order. This client never invents a page size and never
+                pre-empts the service's resolution of an unsupplied value.
+            continuation: The resumption point a previous call to this method
+                returned, sent back unread and unedited to continue that read.
+                Optional: absent on a first request.
+
+        Returns:
+            One page of the relation set exactly as the service publishes it,
+            carrying the bounded block of relations, the statement of whether
+            further results follow, and the resumption point for the next block.
+        """
+        params: dict[str, Any] = {
+            "session_id": session_id,
+        }
+        if block_size is not None:
+            params["block_size"] = block_size
+        if continuation is not None:
+            params["continuation"] = continuation
+        return await self._invoke("relations_read", params)
+
+    async def leaves_read(
+        self,
+        session_id: str,
+        block_size: int | None = None,
+        continuation: str | None = None,
+    ) -> Any:
+        """Read the leaves and branching points of a dialogue session.
+
+        Returns, for the addressed dialogue session, the nodes that nothing
+        continues from (reported as leaves) and the nodes that more than one
+        node continues from (reported as branching points together with the
+        count of distinct nodes that continue from each). The computed view
+        is the bounded page that the service delivers at that position, never
+        a whole-session read, and pagination parameters govern how much of the
+        computed view is retrieved at once.
+
+        Each entry names which of the two roles it holds, so a consumer never
+        has to infer one from the other. The view is computed at the moment of
+        each read and never kept: a leaf reported by one call simply ceases to
+        be reported by the next as soon as a node continues from it, with no
+        maintenance step of any kind in between.
+
+        This read is a structural read: it reports which nodes hold which role
+        in the shape of the session and substitutes nothing whatever a caller
+        states. No mode parameter is declared in the schema, and sending one
+        causes refusal as an unnamed parameter. The answer for a session
+        containing a correction chain is identical to any request, because
+        this read never resolves a correction chain to its final version.
+
+        The block_size and continuation parameters are optional. When not
+        supplied, the service resolves them through its own order: the call
+        arguments, otherwise the service configuration, otherwise shipped
+        constants. Omitting block_size does not cause this method to invent
+        one; the service resolves its own bound.
+
+        Args:
+            session_id: Identity of the dialogue session whose leaves and
+                branching points are to be reported. Required: this method
+                reads the view of an existing session, never of the whole store.
+            block_size: The number of view entries one answer may carry.
+                Optional: when not supplied, the service resolves the bound
+                through its own order. This client never invents a page size
+                and never pre-empts the service's resolution of an unsupplied
+                value.
+            continuation: The resumption point a previous call to this method
+                returned, sent back unread and unedited to continue that read.
+                Optional: absent on a first request.
+
+        Returns:
+            One page of the leaves-and-branching view exactly as the service
+            publishes it, carrying the bounded block of nodes, the statement
+            of whether further results follow, and the resumption point for
+            the next block.
+        """
+        params: dict[str, Any] = {
+            "session_id": session_id,
+        }
+        if block_size is not None:
+            params["block_size"] = block_size
+        if continuation is not None:
+            params["continuation"] = continuation
+        return await self._invoke("leaves_read", params)
+
+    async def graph_read(
+        self,
+        session_id: str,
+        anchor_node_id: str,
+        drilldown_depth: int | None = None,
+        block_size: int | None = None,
+        continuation: str | None = None,
+    ) -> Any:
+        """Read the graph descending from a named node.
+
+        Returns the graph descending from the named anchor node of the
+        addressed dialogue session, bounded by a requested depth below that
+        node so that a consumer wanting the shape of a dialogue rather than
+        one line of it reaches it through a command of its own instead of
+        reassembling it out of the flat relation set. The graph is the bounded
+        page that the service delivers at that position, never a whole-session
+        read, and pagination parameters govern how much of the answer is
+        retrieved at once.
+
+        This is a drill-down read: the consumer names one node and the number
+        of levels of descendants it wants below that node. The command never
+        descends from a session as a whole and never picks an anchor for the
+        caller. The drilldown_depth parameter has no default, no default
+        factory and no fallback to a root, a leaf or a most recent node:
+        omitting it causes the service to resolve the bound through its own
+        order (the call arguments, otherwise the configuration, otherwise
+        shipped constants), and omitting it does not select a default in this
+        signature.
+
+        A resolved depth of zero answers with the anchor node alone. A
+        resolved depth of one answers with the anchor and its immediate
+        descendants. A resolved depth larger than the deepest line below the
+        anchor answers with everything below the anchor and is NOT a refusal.
+        Nothing deeper than the resolved number of levels ever appears in the
+        answer.
+
+        The drilldown_depth and block_size are two distinct bounds: the depth
+        bounds how far below the anchor the drill-down reaches, and the block
+        size bounds how much of that result one answer carries. A small block
+        size never shortens the depth, and a small depth never removes the
+        need for pagination.
+
+        Resuming continues the same drill-down: a resumed request whose anchor
+        or whose resolved depth disagrees with that datum is REFUSED rather
+        than silently reinterpreted, so a resumed block can never descend
+        further than the first block was permitted to.
+
+        The drilldown_depth, block_size, and continuation parameters are
+        optional. When not supplied, the service resolves them through its own
+        order: the call arguments, otherwise the service configuration,
+        otherwise shipped constants. Omitting a parameter does not cause this
+        method to invent one; the service resolves its own bounds.
+
+        Args:
+            session_id: Identity of the dialogue session the graph is read
+                inside. Required: this method descends inside an existing
+                session, never from the whole store.
+            anchor_node_id: Identity of the node the drill-down descends from.
+                Required: the graph is addressed by a specific node, and
+                omitting it causes refusal rather than a whole-session read.
+            drilldown_depth: The number of levels of descendants below the
+                anchor node to include in the drill-down. Optional: when not
+                supplied, the service resolves the bound through its own order.
+                This client never invents a depth and never pre-empts the
+                service's resolution of an unsupplied value.
+            block_size: The number of reached nodes one answer may carry.
+                Optional: when not supplied, the service resolves the bound
+                through its own order. This client never invents a page size
+                and never pre-empts the service's resolution of an unsupplied
+                value.
+            continuation: The resumption point a previous call to this method
+                returned, sent back unread and unedited to continue that read.
+                Optional: absent on a first request, in which case the graph
+                begins at the anchor node instead.
+
+        Returns:
+            One page of the graph exactly as the service publishes it, carrying
+            the bounded block of nodes and connecting relations, the statement
+            of whether further results follow, and the resumption point for the
+            next block.
+        """
+        params: dict[str, Any] = {
+            "session_id": session_id,
+            "anchor_node_id": anchor_node_id,
+        }
+        if drilldown_depth is not None:
+            params["drilldown_depth"] = drilldown_depth
+        if block_size is not None:
+            params["block_size"] = block_size
+        if continuation is not None:
+            params["continuation"] = continuation
+        return await self._invoke("graph_read", params)
+
+    async def sessions_list(  # noqa: PLR0913, PLR0917
+        self,
+        project_id: str | None = None,
+        lifecycle: str | None = None,
+        dialogue_kind: str | None = None,
+        participant: str | None = None,
+        created_at_range: dict[str, str] | None = None,
+        block_size: int | None = None,
+        continuation: str | None = None,
+    ) -> Any:
+        """List dialogue sessions matching supplied filter axes.
+
+        Returns one bounded block of the dialogue sessions matching the filter
+        axes a caller chooses to constrain. The sessions reported are constrained
+        by their recorded attributes alone: no message text, no excerpt, no
+        preview and no content-derived data are carried. Each session is
+        identified by its session identity, the project that owns it, its
+        lifecycle state, the pairing of participant kinds it was declared to
+        run between, its recorded participants and its recorded UTC creation
+        time.
+
+        The answer is the bounded page that the service delivers at the
+        requested position, never a whole-store read, and pagination parameters
+        govern how many sessions one answer carries at once. Following the
+        resumption point each answer returns yields every matching session
+        exactly once, with none skipped and none repeated across a block
+        boundary.
+
+        Five optional filter axes may be constrained independently: the owning
+        project, the recorded lifecycle state, the declared pairing of participant
+        kinds, a participant, and the recorded UTC creation time as one range
+        carrying both of its inclusive bounds. An omitted axis constrains nothing
+        and is never filled in from the configuration or the shipped constants.
+        Axes given together compose conjunctively: a session is reported only when
+        it satisfies every axis the caller constrained. A request constraining no
+        axis at all validly lists every session the service knows, still in
+        bounded blocks.
+
+        A combination of axes matching nothing yields an empty block rather than
+        an error, because this read addresses no single session and raises no
+        unknown-session refusal.
+
+        The block_size and continuation parameters are optional. When not
+        supplied, the service resolves them through its own order: the call
+        arguments, otherwise the service configuration, otherwise shipped
+        constants. Omitting block_size does not cause this method to invent
+        one; the service resolves its own bound. Omitting continuation leaves
+        the read unconstrained on a first request; when present it carries the
+        resumption point a previous answer of this same listing returned, sent
+        back unread and unedited.
+
+        Args:
+            project_id: Report only sessions owned by this project. Optional:
+                omit to leave the project axis unconstrained.
+                (sessions_list_command.py:277)
+            lifecycle: Report only sessions recorded in this lifecycle state.
+                Optional: omit to leave the lifecycle axis unconstrained.
+                (sessions_list_command.py:280)
+            dialogue_kind: Report only sessions declared to run between this
+                pairing of participant kinds, named as '<first>-to-<second>'.
+                Optional: omit to leave the dialogue-kind axis unconstrained.
+                (sessions_list_command.py:284)
+            participant: Report only sessions whose recorded participants
+                include this one. Optional: omit to leave the participant axis
+                unconstrained. (sessions_list_command.py:288)
+            created_at_range: Report only sessions whose recorded UTC creation
+                time falls in this range. One axis carrying both bounds: 'from'
+                and 'to' are ISO-8601 instants in UTC, each inclusive at the
+                stated boundary, and either may be omitted to leave that end
+                unbounded. Optional: omit to leave the creation-time axis
+                unconstrained. (sessions_list_command.py:292)
+            block_size: How many sessions one answer may carry. Optional: when
+                not supplied, the service resolves the bound through its own
+                order. This client never invents a page size and never pre-empts
+                the service's resolution of an unsupplied value.
+                (sessions_list_command.py:303)
+            continuation: The resumption point a previous answer of this same
+                listing returned, sent back unread and unedited to continue that
+                read under the same constrained axes. Optional: absent on a first
+                request, in which case the listing begins at the first matching
+                session. (sessions_list_command.py:308)
+
+        Returns:
+            One page of the matching sessions exactly as the service publishes
+            it, carrying the bounded block of session entries, the statement of
+            whether further results follow, and the resumption point for the
+            next block.
+        """
+        params: dict[str, Any] = {}
+        if project_id is not None:
+            params["project_id"] = project_id
+        if lifecycle is not None:
+            params["lifecycle"] = lifecycle
+        if dialogue_kind is not None:
+            params["dialogue_kind"] = dialogue_kind
+        if participant is not None:
+            params["participant"] = participant
+        if created_at_range is not None:
+            params["created_at_range"] = created_at_range
+        if block_size is not None:
+            params["block_size"] = block_size
+        if continuation is not None:
+            params["continuation"] = continuation
+        return await self._invoke("sessions_list", params)