RavenDB-24609 Add GetConversationMessages operation for AI agent conversations

redknightlois · redknightlois · commit 7b2800a24d78 · 2026-07-01T16:33:57.000-03:00
Brings the GetConversationMessages read operation to the Python client,
mirroring the C# client (PR #22619): timestamp paging (before/after,
mutually exclusive, UTC-coerced), page size, and detail level over the
ai/agent/conversation/messages endpoint. Response-timestamp parsing
normalizes fractional-seconds precision for the ~=3.9 floor.
diff --git a/ravendb/__init__.py b/ravendb/__init__.py
@@ -115,6 +115,13 @@
     GetAiAgentsResponse,
     AddOrUpdateAiAgentOperation,
     DeleteAiAgentOperation,
+    GetConversationMessagesOperation,
+    GetConversationMessagesOptions,
+    AiConversationMessagesResult,
+    AiConversationMessage,
+    AiToolCallResult,
+    AiMessageRole,
+    AiConversationDetailLevel,
 )
 from ravendb.documents.operations.ai import (
     ChunkingOptions,
diff --git a/ravendb/documents/ai/ai_operations.py b/ravendb/documents/ai/ai_operations.py
@@ -12,6 +12,8 @@
         AiAgentConfiguration,
         AiAgentConfigurationResult,
         GetAiAgentsResponse,
+        AiConversationMessagesResult,
+        GetConversationMessagesOptions,
     )
 
 
@@ -115,3 +117,23 @@ def conversation_with_id(self, conversation_id: str, change_vector: str = None)
         from ravendb.documents.ai.ai_conversation import AiConversation
 
         return AiConversation.with_conversation_id(self._store, conversation_id, change_vector)
+
+    def get_conversation_messages(
+        self, conversation_id_or_options=None
+    ) -> AiConversationMessagesResult:
+        """
+        Reads messages from an AI conversation. Returns the most recent messages by default.
+
+        Args:
+            conversation_id_or_options: Either a conversation_id string or a
+                GetConversationMessagesOptions with full paging and filtering control.
+
+        Returns:
+            AiConversationMessagesResult containing the messages and metadata.
+        """
+        from ravendb.documents.operations.ai.agents import (
+            GetConversationMessagesOperation,
+        )
+
+        operation = GetConversationMessagesOperation(conversation_id_or_options)
+        return self._store.maintenance.send(operation)
diff --git a/ravendb/documents/operations/ai/agents/__init__.py b/ravendb/documents/operations/ai/agents/__init__.py
@@ -39,6 +39,16 @@
     AiConversationParameterOptions,
 )
 
+from .get_conversation_messages_operation import (
+    GetConversationMessagesOperation,
+    GetConversationMessagesOptions,
+    AiConversationMessagesResult,
+    AiConversationMessage,
+    AiToolCallResult,
+    AiConversationDetailLevel,
+    AiMessageRole,
+)
+
 __all__ = [
     "AiAgentConfiguration",
     "AiAgentConfigurationResult",
@@ -68,4 +78,11 @@
     "GetAiAgentsResponse",
     "AddOrUpdateAiAgentOperation",
     "DeleteAiAgentOperation",
+    "GetConversationMessagesOperation",
+    "GetConversationMessagesOptions",
+    "AiConversationMessagesResult",
+    "AiConversationMessage",
+    "AiToolCallResult",
+    "AiConversationDetailLevel",
+    "AiMessageRole",
 ]
diff --git a/ravendb/documents/operations/ai/agents/get_conversation_messages_operation.py b/ravendb/documents/operations/ai/agents/get_conversation_messages_operation.py
@@ -0,0 +1,298 @@
+from __future__ import annotations
+import enum
+import json
+import re
+import sys
+from datetime import datetime, timezone
+from typing import Optional, List, Dict, Any
+from urllib.parse import quote
+
+from ravendb.documents.operations.definitions import MaintenanceOperation
+from ravendb.documents.conventions import DocumentConventions
+from ravendb.http.raven_command import RavenCommand
+from ravendb.http.server_node import ServerNode
+import requests
+
+
+class AiConversationDetailLevel(enum.Enum):
+    """Controls the level of detail when reading conversation messages."""
+
+    SIMPLE = "Simple"
+    DETAILED = "Detailed"
+    FULL = "Full"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class AiMessageRole(enum.Enum):
+    """The role of a message sender in an AI conversation."""
+
+    SYSTEM = "System"
+    USER = "User"
+    ASSISTANT = "Assistant"
+    SUMMARY = "Summary"
+    INTERNAL = "Internal"
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class AiToolCallResult:
+    """Represents a tool call result from an AI conversation message."""
+
+    def __init__(
+        self,
+        id: Optional[str] = None,
+        name: Optional[str] = None,
+        arguments: Optional[str] = None,
+        result: Optional[str] = None,
+        sub_conversation_id: Optional[str] = None,
+    ):
+        self.id: Optional[str] = id
+        self.name: Optional[str] = name
+        self.arguments: Optional[str] = arguments
+        self.result: Optional[str] = result
+        self.sub_conversation_id: Optional[str] = sub_conversation_id
+
+    @classmethod
+    def from_json(cls, json_dict: Dict[str, Any]) -> AiToolCallResult:
+        return cls(
+            id=json_dict.get("Id"),
+            name=json_dict.get("Name"),
+            arguments=json_dict.get("Arguments"),
+            result=json_dict.get("Result"),
+            sub_conversation_id=json_dict.get("SubConversationId"),
+        )
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "Id": self.id,
+            "Name": self.name,
+            "Arguments": self.arguments,
+            "Result": self.result,
+            "SubConversationId": self.sub_conversation_id,
+        }
+
+
+class AiConversationMessage:
+    """Represents a single message in an AI conversation."""
+
+    def __init__(
+        self,
+        role: Optional[AiMessageRole] = None,
+        content: Optional[str] = None,
+        attachments: Optional[List[str]] = None,
+        timestamp: Optional[datetime] = None,
+        tool_calls: Optional[List[AiToolCallResult]] = None,
+        usage: Optional[Any] = None,
+        sub_conversation_id: Optional[str] = None,
+    ):
+        self.role: Optional[AiMessageRole] = role
+        self.content: Optional[str] = content
+        self.attachments: List[str] = attachments or []
+        self.timestamp: Optional[datetime] = timestamp
+        self.tool_calls: List[AiToolCallResult] = tool_calls or []
+        self.usage: Optional[Any] = usage
+        self.sub_conversation_id: Optional[str] = sub_conversation_id
+
+    @classmethod
+    def from_json(cls, json_dict: Dict[str, Any]) -> AiConversationMessage:
+        from ravendb.documents.operations.ai.agents.run_conversation_operation import AiUsage
+
+        return cls(
+            role=AiMessageRole(json_dict["Role"]) if json_dict.get("Role") else None,
+            content=json_dict.get("Content"),
+            attachments=json_dict.get("Attachments") or [],
+            timestamp=_parse_raven_datetime(json_dict.get("Timestamp")),
+            tool_calls=(
+                [AiToolCallResult.from_json(tc) for tc in json_dict["ToolCalls"]]
+                if json_dict.get("ToolCalls")
+                else []
+            ),
+            usage=AiUsage.from_json(json_dict["Usage"]) if json_dict.get("Usage") else None,
+            sub_conversation_id=json_dict.get("SubConversationId"),
+        )
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "Role": self.role.value if self.role else None,
+            "Content": self.content,
+            "Attachments": self.attachments,
+            "Timestamp": _format_raven_datetime(self.timestamp) if self.timestamp else None,
+            "ToolCalls": [tc.to_json() for tc in self.tool_calls] if self.tool_calls else None,
+            "Usage": self.usage.to_json() if self.usage else None,
+            "SubConversationId": self.sub_conversation_id,
+        }
+
+
+class AiConversationMessagesResult:
+    """The result of fetching conversation messages."""
+
+    def __init__(
+        self,
+        conversation_id: Optional[str] = None,
+        agent: Optional[str] = None,
+        parameters: Optional[Dict[str, Any]] = None,
+        total_usage: Optional[Any] = None,
+        last_message_at: Optional[datetime] = None,
+        messages: Optional[List[AiConversationMessage]] = None,
+        has_more_messages: bool = False,
+        sub_conversation_ids: Optional[List[str]] = None,
+        attachments: Optional[List[str]] = None,
+    ):
+        self.conversation_id: Optional[str] = conversation_id
+        self.agent: Optional[str] = agent
+        self.parameters: Dict[str, Any] = parameters or {}
+        self.total_usage: Optional[Any] = total_usage
+        self.last_message_at: Optional[datetime] = last_message_at
+        self.messages: List[AiConversationMessage] = messages or []
+        self.has_more_messages: bool = has_more_messages
+        self.sub_conversation_ids: List[str] = sub_conversation_ids or []
+        self.attachments: List[str] = attachments or []
+
+    @classmethod
+    def from_json(cls, json_dict: Dict[str, Any]) -> AiConversationMessagesResult:
+        from ravendb.documents.operations.ai.agents.run_conversation_operation import AiUsage
+
+        return cls(
+            conversation_id=json_dict.get("ConversationId"),
+            agent=json_dict.get("Agent"),
+            parameters=json_dict.get("Parameters") or {},
+            total_usage=AiUsage.from_json(json_dict["TotalUsage"]) if json_dict.get("TotalUsage") else None,
+            last_message_at=_parse_raven_datetime(json_dict.get("LastMessageAt")),
+            messages=(
+                [AiConversationMessage.from_json(msg) for msg in json_dict["Messages"]]
+                if json_dict.get("Messages")
+                else []
+            ),
+            has_more_messages=json_dict.get("HasMoreMessages", False),
+            sub_conversation_ids=json_dict.get("SubConversationIds") or [],
+            attachments=json_dict.get("Attachments") or [],
+        )
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "ConversationId": self.conversation_id,
+            "Agent": self.agent,
+            "Parameters": self.parameters,
+            "TotalUsage": self.total_usage.to_json() if self.total_usage else None,
+            "LastMessageAt": _format_raven_datetime(self.last_message_at) if self.last_message_at else None,
+            "Messages": [msg.to_json() for msg in self.messages] if self.messages else None,
+            "HasMoreMessages": self.has_more_messages,
+            "SubConversationIds": self.sub_conversation_ids,
+            "Attachments": self.attachments,
+        }
+
+
+class GetConversationMessagesOptions:
+    """Parameters for reading messages from an AI agent conversation."""
+
+    def __init__(
+        self,
+        conversation_id: str,
+        before: Optional[datetime] = None,
+        after: Optional[datetime] = None,
+        page_size: int = sys.maxsize,
+        detail_level: AiConversationDetailLevel = AiConversationDetailLevel.SIMPLE,
+    ):
+        if not conversation_id or conversation_id.isspace():
+            raise ValueError("conversation_id cannot be None or empty")
+
+        if before is not None and after is not None:
+            raise ValueError("before and after cannot both be specified")
+
+        if page_size <= 0:
+            raise ValueError("page_size must be greater than 0")
+
+        self.conversation_id: str = conversation_id
+        self.before: Optional[datetime] = before
+        self.after: Optional[datetime] = after
+        self.page_size: int = page_size
+        self.detail_level: AiConversationDetailLevel = detail_level
+
+
+class GetConversationMessagesOperation(MaintenanceOperation[AiConversationMessagesResult]):
+    """
+    Reads messages from an AI agent conversation, with optional timestamp-based paging and view filtering.
+    """
+
+    def __init__(self, conversation_id_or_options: str | GetConversationMessagesOptions):
+        if isinstance(conversation_id_or_options, str):
+            self._parameters = GetConversationMessagesOptions(conversation_id=conversation_id_or_options)
+        elif isinstance(conversation_id_or_options, GetConversationMessagesOptions):
+            self._parameters = conversation_id_or_options
+        else:
+            raise TypeError(
+                "Expected str (conversation_id) or GetConversationMessagesOptions, "
+                f"got {type(conversation_id_or_options).__name__}"
+            )
+
+    def get_command(self, conventions: DocumentConventions) -> RavenCommand[AiConversationMessagesResult]:
+        return GetConversationMessagesCommand(self._parameters)
+
+
+class GetConversationMessagesCommand(RavenCommand[AiConversationMessagesResult]):
+    def __init__(self, parameters: GetConversationMessagesOptions):
+        super().__init__(AiConversationMessagesResult)
+        self._params = parameters
+
+    def is_read_request(self) -> bool:
+        return True
+
+    def create_request(self, node: ServerNode) -> requests.Request:
+        url = (
+            f"{node.url}/databases/{node.database}/ai/agent/conversation/messages"
+            f"?conversationId={quote(self._params.conversation_id, safe='')}"
+        )
+
+        if self._params.before is not None:
+            url += f"&before={quote(_format_raven_datetime(self._params.before), safe='')}"
+
+        if self._params.after is not None:
+            url += f"&after={quote(_format_raven_datetime(self._params.after), safe='')}"
+
+        url += f"&pageSize={self._params.page_size}"
+        url += f"&detailLevel={self._params.detail_level.value}"
+
+        return requests.Request("GET", url)
+
+    def set_response(self, response: str, from_cache: bool) -> None:
+        if response is None:
+            self.result = None
+            return
+
+        response_json = json.loads(response)
+        self.result = AiConversationMessagesResult.from_json(response_json)
+
+
+# ------------------------------------------------------------------
+# Raven datetime helpers — wire contract uses yyyy-MM-ddTHH:mm:ss.fffffffZ
+# ------------------------------------------------------------------
+
+
+def _ensure_utc(dt: datetime) -> datetime:
+    """Ensure a datetime is in UTC."""
+    if dt.tzinfo is None:
+        return dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def _format_raven_datetime(dt: datetime) -> str:
+    """Format a datetime in Raven's default UTC format: yyyy-MM-ddTHH:mm:ss.fffffffZ."""
+    dt = _ensure_utc(dt)
+    return dt.strftime("%Y-%m-%dT%H:%M:%S.%f") + "0Z"
+
+
+def _parse_raven_datetime(value: Optional[str]) -> Optional[datetime]:
+    """Parse a Raven datetime string (e.g. 2025-06-15T12:00:00.0000000Z) into a UTC datetime."""
+    if value is None:
+        return None
+
+    if value.endswith("Z"):
+        value = value[:-1] + "+00:00"
+
+    # fromisoformat before Python 3.11 accepts only 3 or 6 fractional digits; Raven emits 7 (100ns ticks).
+    value = re.sub(r"\.(\d+)", lambda m: "." + (m.group(1) + "000000")[:6], value)
+
+    return datetime.fromisoformat(value)
diff --git a/ravendb/tests/ai_agent_tests/test_get_conversation_messages_operation.py b/ravendb/tests/ai_agent_tests/test_get_conversation_messages_operation.py
