RDBC-967 7.1.4 AI changes

Author: poissoncorp

ravendb/__init__.py

@@ -82,10 +82,15 @@
     AiOperations,
     AiConversation,
     AiConversationResult,
+    ContentPart,
+    TextPart,
+    AiMessagePromptFields,
+    AiMessagePromptTypes,
 )
 from ravendb.documents.operations.ai.agents import (
     AiAgentConfiguration,
     AiAgentConfigurationResult,
+    AiAgentParameter,
     AiAgentToolAction,
     AiAgentToolQuery,
     AiAgentPersistenceConfiguration,

ravendb/documents/ai/__init__.py

@@ -2,11 +2,16 @@
 from .ai_conversation import AiConversation
 from .ai_conversation_result import AiConversationResult
 from .ai_answer import AiAnswer, AiConversationStatus
+from .content_part import ContentPart, TextPart, AiMessagePromptFields, AiMessagePromptTypes
 
 __all__ = [
     "AiOperations",
     "AiConversation",
     "AiConversationResult",
     "AiAnswer",
     "AiConversationStatus",
+    "ContentPart",
+    "TextPart",
+    "AiMessagePromptFields",
+    "AiMessagePromptTypes",
 ]

ravendb/documents/ai/ai_conversation.py

@@ -6,6 +6,7 @@
 from datetime import timedelta
 
 from ravendb.documents.ai.ai_answer import AiAnswer, AiConversationStatus
+from ravendb.documents.ai.content_part import ContentPart, TextPart
 from ravendb.documents.operations.ai.agents import (
     AiAgentActionRequest,
     AiAgentActionResponse,
@@ -53,7 +54,7 @@ def __init__(
         self._conversation_id = conversation_id
         self._change_vector = change_vector
 
-        self._prompt_parts: List[str] = []
+        self._prompt_parts: List[ContentPart] = []
         self._action_responses: List[AiAgentActionResponse] = []
         self._action_requests: Optional[List[AiAgentActionRequest]] = None
 
@@ -269,7 +270,7 @@ def set_user_prompt(self, user_prompt: str) -> None:
         if not user_prompt or user_prompt.isspace():
             raise ValueError("User prompt cannot be empty or whitespace-only")
         self._prompt_parts.clear()
-        self._prompt_parts.append(user_prompt)
+        self.add_user_prompt(user_prompt)
 
     def add_user_prompt(self, *prompts: str) -> None:
         """
@@ -284,7 +285,7 @@ def add_user_prompt(self, *prompts: str) -> None:
         for prompt in prompts:
             if not prompt or prompt.isspace():
                 raise ValueError("User prompt cannot be empty or whitespace-only")
-            self._prompt_parts.append(prompt)
+            self._prompt_parts.append(TextPart(prompt))
 
     def handle(
         self,

ravendb/documents/ai/content_part.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+from typing import Dict, Any
+
+
+class AiMessagePromptFields:
+    """Constants for AI message prompt field names."""
+
+    TEXT = "text"
+    TYPE = "type"
+
+
+class AiMessagePromptTypes:
+    """Constants for AI message prompt types."""
+
+    TEXT = "text"
+
+
+class ContentPart:
+    """
+    Base class for content parts in AI prompts.
+    Content parts allow structured prompt content with different types (text, etc.).
+    """
+
+    def __init__(self, content_type: str):
+        self._type = content_type
+
+    @property
+    def type(self) -> str:
+        return self._type
+
+    def to_json(self) -> Dict[str, Any]:
+        """
+        Converts the content part to a JSON-serializable dictionary.
+        Subclasses should override this method to include their specific fields.
+        """
+        return {AiMessagePromptFields.TYPE: self._type}
+
+
+class TextPart(ContentPart):
+    """
+    Represents a text content part in AI prompts.
+    """
+
+    def __init__(self, text: str):
+        super().__init__(AiMessagePromptTypes.TEXT)
+        self._text = text
+
+    @property
+    def text(self) -> str:
+        return self._text
+
+    @text.setter
+    def text(self, value: str):
+        self._text = value
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            AiMessagePromptFields.TYPE: self._type,
+            AiMessagePromptFields.TEXT: self._text,
+        }
+

ravendb/documents/operations/ai/agents/__init__.py

@@ -1,5 +1,6 @@
 from .ai_agent_configuration import (
     AiAgentConfiguration,
+    AiAgentParameter,
     AiAgentToolAction,
     AiAgentToolQuery,
     AiAgentPersistenceConfiguration,
@@ -33,6 +34,7 @@
 __all__ = [
     "AiAgentConfiguration",
     "AiAgentConfigurationResult",
+    "AiAgentParameter",
     "AiAgentToolAction",
     "AiAgentToolQuery",
     "AiAgentPersistenceConfiguration",

ravendb/documents/operations/ai/agents/ai_agent_configuration.py

@@ -1,5 +1,48 @@
 from __future__ import annotations
-from typing import List, Set, Optional, Dict, Any
+from typing import List, Optional, Dict, Any, Union
+
+
+class AiAgentParameter:
+    """
+    Represents a parameter for an AI agent configuration.
+    Parameters can be used to pass values to the agent's system prompt.
+    """
+
+    def __init__(
+        self,
+        name: str = None,
+        description: str = None,
+        send_to_model: bool = None,
+    ):
+        """
+        Initialize an agent parameter.
+
+        Args:
+            name: The parameter name. Cannot be null or empty.
+            description: A human-readable description. May be null or empty.
+            send_to_model: When False, the parameter is hidden from the model
+                          (it will not be included in prompts/echo messages).
+                          When True, the parameter is exposed to the model.
+                          If None (default), treated as exposed.
+        """
+        self.name = name
+        self.description: Optional[str] = description
+        self.send_to_model: Optional[bool] = send_to_model
+
+    def to_json(self) -> Dict[str, Any]:
+        return {
+            "Name": self.name,
+            "Description": self.description,
+            "SendToModel": self.send_to_model,
+        }
+
+    @classmethod
+    def from_json(cls, json_dict: Dict[str, Any]) -> AiAgentParameter:
+        return cls(
+            name=json_dict.get("name") or json_dict.get("Name"),
+            description=json_dict.get("description") or json_dict.get("Description"),
+            send_to_model=json_dict.get("sendToModel") if "sendToModel" in json_dict else json_dict.get("SendToModel"),
+        )
 
 
 class AiAgentToolQuery:
@@ -260,7 +303,7 @@ def __init__(
         queries: List[AiAgentToolQuery] = None,
         actions: List[AiAgentToolAction] = None,
         persistence: AiAgentPersistenceConfiguration = None,
-        parameters: Set[str] = None,
+        parameters: List[Union[str, AiAgentParameter]] = None,
         chat_trimming: AiAgentChatTrimmingConfiguration = None,
         max_model_iterations_per_call: int = None,
     ):
@@ -273,14 +316,24 @@ def __init__(
         self.queries: List[AiAgentToolQuery] = queries or []
         self.actions: List[AiAgentToolAction] = actions or []
         self.persistence: Optional[AiAgentPersistenceConfiguration] = persistence
-        self.parameters: Set[str] = parameters or set()
+        self.parameters: List[AiAgentParameter] = self._normalize_parameters(parameters)
         self.chat_trimming: Optional[AiAgentChatTrimmingConfiguration] = chat_trimming
         self.max_model_iterations_per_call: Optional[int] = max_model_iterations_per_call
 
-    def to_json(self) -> Dict[str, Any]:
-        # Convert parameters set to list of parameter objects using list comprehension
-        parameters_list = [{"Name": param_name, "Description": None} for param_name in self.parameters]
+    @staticmethod
+    def _normalize_parameters(parameters: List[Union[str, AiAgentParameter]]) -> List[AiAgentParameter]:
+        """Convert a list of strings or AiAgentParameter objects to a list of AiAgentParameter objects."""
+        if not parameters:
+            return []
+        result = []
+        for param in parameters:
+            if isinstance(param, str):
+                result.append(AiAgentParameter(name=param))
+            else:
+                result.append(param)
+        return result
 
+    def to_json(self) -> Dict[str, Any]:
         return {
             "Identifier": self.identifier,
             "Name": self.name,
@@ -291,7 +344,7 @@ def to_json(self) -> Dict[str, Any]:
             "Queries": [q.to_json() for q in self.queries],
             "Actions": [a.to_json() for a in self.actions],
             "Persistence": self.persistence.to_json() if self.persistence else None,
-            "Parameters": parameters_list,
+            "Parameters": [p.to_json() for p in self.parameters],
             "ChatTrimming": self.chat_trimming.to_json() if self.chat_trimming else None,
             "MaxModelIterationsPerCall": self.max_model_iterations_per_call,
         }
@@ -321,13 +374,7 @@ def from_json(cls, json_dict: Dict[str, Any]) -> AiAgentConfiguration:
 
         params_data = json_dict.get("parameters") or json_dict.get("Parameters")
         if params_data:
-            # Handle both string list and object list formats
-            if params_data and isinstance(params_data[0], dict):
-                # New format: list of objects with name property
-                instance.parameters = set(param.get("name") or param.get("Name") for param in params_data)
-            else:
-                # Old format: list of strings
-                instance.parameters = set(params_data)
+            instance.parameters = [AiAgentParameter.from_json(param) for param in params_data]
 
         trimming_data = json_dict.get("chatTrimming") or json_dict.get("ChatTrimming")
         if trimming_data:

ravendb/documents/operations/ai/agents/run_conversation_operation.py

@@ -9,6 +9,7 @@
 from ravendb.http.server_node import ServerNode
 import requests
 from ravendb.http.misc import ResponseDisposeHandling
+from ravendb.documents.ai.content_part import ContentPart
 
 
 TSchema = TypeVar("TSchema")
@@ -64,6 +65,7 @@ class AiUsage:
     completion_tokens: int = 0
     total_tokens: int = 0
     cached_tokens: int = 0
+    reasoning_tokens: int = 0
 
     @classmethod
     def from_json(cls, json_dict: Dict[str, Any]) -> AiUsage:
@@ -72,6 +74,7 @@ def from_json(cls, json_dict: Dict[str, Any]) -> AiUsage:
             completion_tokens=json_dict.get("CompletionTokens", 0),
             total_tokens=json_dict.get("TotalTokens", 0),
             cached_tokens=json_dict.get("CachedTokens", 0),
+            reasoning_tokens=json_dict.get("ReasoningTokens", 0),
         )
 
     def to_json(self) -> Dict[str, Any]:
@@ -80,8 +83,36 @@ def to_json(self) -> Dict[str, Any]:
             "CompletionTokens": self.completion_tokens,
             "TotalTokens": self.total_tokens,
             "CachedTokens": self.cached_tokens,
+            "ReasoningTokens": self.reasoning_tokens,
         }
 
+    @staticmethod
+    def get_usage_difference(current: AiUsage, previous: AiUsage) -> AiUsage:
+        """
+        Calculate the usage difference between current and previous usage.
+
+        Args:
+            current: The current usage statistics
+            previous: The previous usage statistics
+
+        Returns:
+            An AiUsage object representing the difference
+        """
+        previous_total_without_reasoning = (
+            previous.completion_tokens - previous.reasoning_tokens + previous.prompt_tokens
+        )
+        return AiUsage(
+            # in case the model gives us crappy results and current.prompt_tokens - previous_total_without_reasoning < 0
+            prompt_tokens=max(current.prompt_tokens - previous_total_without_reasoning, 0),
+            # in case the model gives us crappy results and current.total_tokens - previous_total_without_reasoning < 0
+            total_tokens=max(current.total_tokens - previous_total_without_reasoning, 0),
+            # we don't want to subtract cached tokens, as they are only for the last response
+            cached_tokens=current.cached_tokens,
+            # we don't want to subtract completion tokens, as they are only for the last response
+            completion_tokens=current.completion_tokens,
+            reasoning_tokens=current.reasoning_tokens,
+        )
+
 
 class ConversationResult(Generic[TSchema]):
     def __init__(
@@ -161,11 +192,11 @@ class ConversationRequestBody:
     def __init__(
         self,
         action_responses: Optional[List[AiAgentActionResponse]] = None,
-        user_prompt: Optional[List[str]] = None,
+        user_prompt: Optional[List[ContentPart]] = None,
         creation_options: Optional[AiConversationCreationOptions] = None,
     ):
         self.action_responses: Optional[List[AiAgentActionResponse]] = action_responses
-        self.user_prompt: Optional[List[str]] = user_prompt  # List of prompt parts
+        self.user_prompt: Optional[List[ContentPart]] = user_prompt  # List of ContentPart objects
         self.creation_options: Optional[AiConversationCreationOptions] = creation_options
 
     def to_json(self) -> Dict[str, Any]:
@@ -182,8 +213,10 @@ def to_json(self) -> Dict[str, Any]:
             None if self.action_responses is None else [resp.to_json() for resp in self.action_responses]
         )
 
-        # UserPrompt: null if None, otherwise array (even if empty)
-        result["UserPrompt"] = self.user_prompt
+        # UserPrompt: null if None, otherwise array of ContentPart JSON objects
+        result["UserPrompt"] = (
+            None if self.user_prompt is None else [part.to_json() for part in self.user_prompt]
+        )
 
         # CreationOptions: always present (create empty if None, matching C# behavior)
         result["CreationOptions"] = (self.creation_options or AiConversationCreationOptions()).to_json()
@@ -203,7 +236,7 @@ def __init__(
         self,
         agent_id: str,
         conversation_id: str,
-        prompt_parts: Optional[List[str]] = None,
+        prompt_parts: Optional[List[ContentPart]] = None,
         action_responses: Optional[List[AiAgentActionResponse]] = None,
         options: Optional[AiConversationCreationOptions] = None,
         change_vector: Optional[str] = None,
@@ -216,7 +249,7 @@ def __init__(
         Args:
             agent_id: The ID of the AI agent (required)
             conversation_id: The ID of the conversation (required)
-            prompt_parts: List of prompt strings to send to the agent
+            prompt_parts: List of ContentPart objects to send to the agent
             action_responses: List of action responses from previous turn
             options: Creation options including parameters and expiration
             change_vector: Change vector for optimistic concurrency
@@ -258,7 +291,7 @@ def __init__(
         self,
         agent_id: str,
         conversation_id: str,
-        prompt_parts: Optional[List[str]] = None,
+        prompt_parts: Optional[List[ContentPart]] = None,
         action_responses: Optional[List[AiAgentActionResponse]] = None,
         options: Optional[AiConversationCreationOptions] = None,
         change_vector: Optional[str] = None,
@@ -309,7 +342,7 @@ def create_request(self, node: ServerNode) -> requests.Request:
         # Build request body with correct structure to match .NET client
         request_body = ConversationRequestBody(
             action_responses=self._action_responses,
-            user_prompt="".join(self._prompt_parts),
+            user_prompt=self._prompt_parts,
             creation_options=self._options,
         )
 

ravendb/documents/operations/ai/azure_open_ai_settings.py

@@ -14,6 +14,8 @@ def __init__(
         temperature: float = None,
     ):
         super().__init__(api_key, endpoint, model, dimensions, temperature)
+        if deployment_name is None:
+            raise ValueError("deployment_name cannot be None")
         self.deployment_name = deployment_name
 
     @classmethod