RDBC-967 GenAI Tasks Operations

Author: poissoncorp

ravendb/documents/__init__.py

@@ -0,0 +1,5 @@
+from ravendb.documents.starting_point_change_vector import StartingPointChangeVector
+
+__all__ = [
+    "StartingPointChangeVector",
+]

ravendb/documents/ai/content_part.py

@@ -58,4 +58,3 @@ def to_json(self) -> Dict[str, Any]:
             AiMessagePromptFields.TYPE: self._type,
             AiMessagePromptFields.TEXT: self._text,
         }
-

ravendb/documents/operations/ai/__init__.py

@@ -0,0 +1,31 @@
+from ravendb.documents.operations.ai.ai_connection_string import (
+    AiConnectionString,
+    AiModelType,
+    AiConnectorType,
+)
+from ravendb.documents.operations.ai.ai_task_identifier_helper import AiTaskIdentifierHelper
+from ravendb.documents.operations.ai.gen_ai_transformation import GenAiTransformation
+from ravendb.documents.operations.ai.gen_ai_configuration import GenAiConfiguration
+from ravendb.documents.operations.ai.abstract_ai_integration_configuration import AbstractAiIntegrationConfiguration
+from ravendb.documents.operations.ai.ai_task_operation_results import (
+    AddAiTaskOperationResult,
+    AddGenAiOperationResult,
+    AddEmbeddingsGenerationOperationResult,
+)
+from ravendb.documents.operations.ai.add_gen_ai_operation import AddGenAiOperation
+from ravendb.documents.operations.ai.update_gen_ai_operation import UpdateGenAiOperation
+
+__all__ = [
+    "AiConnectionString",
+    "AiModelType",
+    "AiConnectorType",
+    "AiTaskIdentifierHelper",
+    "GenAiTransformation",
+    "GenAiConfiguration",
+    "AbstractAiIntegrationConfiguration",
+    "AddAiTaskOperationResult",
+    "AddGenAiOperationResult",
+    "AddEmbeddingsGenerationOperationResult",
+    "AddGenAiOperation",
+    "UpdateGenAiOperation",
+]

ravendb/documents/operations/ai/abstract_ai_integration_configuration.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+from abc import ABC
+from typing import TYPE_CHECKING, Optional, List
+
+from ravendb.documents.operations.etl.configuration import EtlConfiguration
+from ravendb.documents.operations.ai.ai_connection_string import AiConnectionString, AiConnectorType
+from ravendb.documents.operations.etl.transformation import Transformation
+
+if TYPE_CHECKING:
+    pass
+
+
+class AbstractAiIntegrationConfiguration(EtlConfiguration[AiConnectionString], ABC):
+    """
+    Base class for AI integration configurations.
+    Extends EtlConfiguration with AiConnectionString as the connection type.
+    """
+
+    def __init__(
+        self,
+        name: Optional[str] = None,
+        task_id: int = 0,
+        connection_string_name: Optional[str] = None,
+        mentor_node: Optional[str] = None,
+        pin_to_mentor_node: bool = False,
+        transforms: Optional[List[Transformation]] = None,
+        disabled: bool = False,
+        allow_etl_on_non_encrypted_channel: bool = False,
+    ):
+        super().__init__(
+            name=name,
+            task_id=task_id,
+            connection_string_name=connection_string_name,
+            mentor_node=mentor_node,
+            pin_to_mentor_node=pin_to_mentor_node,
+            transforms=transforms,
+            disabled=disabled,
+            allow_etl_on_non_encrypted_channel=allow_etl_on_non_encrypted_channel,
+        )
+
+    @property
+    def ai_connector_type(self) -> AiConnectorType:
+        """Returns the AI connector type based on the active provider in the connection."""
+        if self.connection:
+            return self.connection.get_active_provider()
+        return AiConnectorType.NONE

ravendb/documents/operations/ai/add_gen_ai_operation.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+import json
+from typing import Optional, TYPE_CHECKING
+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
+from ravendb.documents.starting_point_change_vector import StartingPointChangeVector
+from ravendb.documents.operations.ai.ai_task_operation_results import AddGenAiOperationResult
+import requests
+
+from ravendb.util.util import RaftIdGenerator
+
+if TYPE_CHECKING:
+    from ravendb.documents.operations.ai.gen_ai_configuration import GenAiConfiguration
+
+
+class AddGenAiOperation(MaintenanceOperation[AddGenAiOperationResult]):
+    """
+    Operation to add a new GenAI task to the database.
+    """
+
+    def __init__(
+        self,
+        configuration: GenAiConfiguration,
+        starting_point: Optional[StartingPointChangeVector] = StartingPointChangeVector.LAST_DOCUMENT,
+    ):
+        if configuration is None:
+            raise ValueError("configuration cannot be None")
+
+        self._configuration = configuration
+        self._starting_point = starting_point
+
+    def get_command(self, conventions: DocumentConventions) -> RavenCommand[AddGenAiOperationResult]:
+        return AddGenAiCommand(self._configuration, self._starting_point, conventions)
+
+
+class AddGenAiCommand(RavenCommand[AddGenAiOperationResult]):
+    def __init__(
+        self,
+        configuration: GenAiConfiguration,
+        starting_point: StartingPointChangeVector,
+        conventions: DocumentConventions,
+    ):
+        super().__init__(AddGenAiOperationResult)
+        self._configuration = configuration
+        self._starting_point = starting_point
+        self._conventions = conventions
+
+    def is_read_request(self) -> bool:
+        return False
+
+    def create_request(self, node: ServerNode) -> requests.Request:
+        url = f"{node.url}/databases/{node.database}/admin/etl?changeVector={quote(self._starting_point.value)}"
+
+        body_json = self._configuration.to_json()
+        body = json.dumps(body_json)
+
+        request = requests.Request("PUT", url)
+        request.headers = {"Content-Type": "application/json"}
+        request.data = body
+        return request
+
+    def set_response(self, response: str, from_cache: bool) -> None:
+        if response is None:
+            self.result = AddGenAiOperationResult()
+            return
+
+        response_json = json.loads(response)
+        self.result = AddGenAiOperationResult.from_json(response_json)
+
+    def get_raft_unique_request_id(self) -> str:
+        return RaftIdGenerator.new_id()

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

@@ -214,9 +214,7 @@ def to_json(self) -> Dict[str, Any]:
         )
 
         # 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]
-        )
+        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()

ravendb/documents/operations/ai/ai_connection_string.py

@@ -19,6 +19,18 @@ class AiModelType(enum.Enum):
     CHAT = "Chat"
 
 
+class AiConnectorType(enum.Enum):
+    NONE = "None"
+    OPEN_AI = "OpenAi"
+    AZURE_OPEN_AI = "AzureOpenAi"
+    OLLAMA = "Ollama"
+    EMBEDDED = "Embedded"
+    GOOGLE = "Google"
+    HUGGING_FACE = "HuggingFace"
+    MISTRAL_AI = "MistralAi"
+    VERTEX = "Vertex"
+
+
 class AiConnectionString(ConnectionString):
     def __init__(
         self,
@@ -87,6 +99,50 @@ def __init__(
     def get_type(self):
         return ConnectionStringType.AI.value
 
+    def get_active_provider(self) -> AiConnectorType:
+        """Returns the active AI connector type based on which settings are configured."""
+        if self.openai_settings:
+            return AiConnectorType.OPEN_AI
+        if self.azure_openai_settings:
+            return AiConnectorType.AZURE_OPEN_AI
+        if self.ollama_settings:
+            return AiConnectorType.OLLAMA
+        if self.embedded_settings:
+            return AiConnectorType.EMBEDDED
+        if self.google_settings:
+            return AiConnectorType.GOOGLE
+        if self.huggingface_settings:
+            return AiConnectorType.HUGGING_FACE
+        if self.mistral_ai_settings:
+            return AiConnectorType.MISTRAL_AI
+        if self.vertex_settings:
+            return AiConnectorType.VERTEX
+        return AiConnectorType.NONE
+
+    def using_encrypted_communication_channel(self) -> bool:
+        """Returns True if the connection uses HTTPS (encrypted communication)."""
+        active_settings = None
+        if self.openai_settings:
+            active_settings = self.openai_settings
+        elif self.azure_openai_settings:
+            active_settings = self.azure_openai_settings
+        elif self.ollama_settings:
+            active_settings = self.ollama_settings
+        elif self.google_settings:
+            active_settings = self.google_settings
+        elif self.huggingface_settings:
+            active_settings = self.huggingface_settings
+        elif self.mistral_ai_settings:
+            active_settings = self.mistral_ai_settings
+        elif self.vertex_settings:
+            active_settings = self.vertex_settings
+
+        if active_settings and hasattr(active_settings, "endpoint") and active_settings.endpoint:
+            return active_settings.endpoint.lower().startswith("https://")
+
+        # Embedded settings don't have an endpoint
+        return False
+
     def to_json(self) -> Dict[str, Any]:
         return {
             "Name": self.name,

ravendb/documents/operations/ai/ai_task_identifier_helper.py

@@ -0,0 +1,94 @@
+import unicodedata
+from typing import List, Tuple
+
+
+class AiTaskIdentifierHelper:
+    """Helper class for validating and generating AI task identifiers."""
+
+    @staticmethod
+    def validate_identifier(identifier: str) -> Tuple[bool, List[str]]:
+        """
+        Validates an AI task identifier.
+
+        Args:
+            identifier: The identifier to validate.
+
+        Returns:
+            A tuple of (is_valid, errors). If valid, errors is an empty list.
+        """
+        errors: List[str] = []
+
+        if not identifier or identifier.isspace():
+            errors.append("Identifier cannot be empty or contain only whitespace;")
+            return False, errors
+
+        # Check that the string is already normalized (contains only a-z, 0-9 and hyphens)
+        normalized = unicodedata.normalize("NFD", identifier)
+        if identifier != normalized:
+            errors.append("Identifier contains diacritical marks or non-ASCII characters;")
+
+        # Check that there are no uppercase letters
+        if any(c.isupper() for c in identifier):
+            errors.append("Identifier contains uppercase letters;")
+
+        # Check for invalid characters and collect them
+        invalid_chars = set()
+        for c in identifier:
+            if not (("a" <= c <= "z") or ("0" <= c <= "9") or c == "-"):
+                invalid_chars.add(c)
+
+        if invalid_chars:
+            chars_str = ", ".join(f"'{c}'" for c in sorted(invalid_chars))
+            errors.append(
+                f"Identifier contains invalid characters: {chars_str}. "
+                f"Only lowercase letters (a-z), numbers (0-9) and hyphens (-) are allowed."
+            )
+
+        # Check that there are no consecutive hyphens
+        if "--" in identifier:
+            errors.append("Identifier contains consecutive hyphens;")
+
+        # Check that the string does not end with a hyphen
+        if identifier.endswith("-"):
+            errors.append("Identifier ends with a hyphen;")
+
+        return len(errors) == 0, errors
+
+    @staticmethod
+    def generate_identifier(input_str: str) -> str:
+        """
+        Generates a valid identifier from an input string.
+
+        Args:
+            input_str: The input string to convert to an identifier.
+
+        Returns:
+            A valid identifier string, or a default identifier if input is empty.
+        """
+        if not input_str or input_str.isspace():
+            return None
+
+        result = []
+        last_was_hyphen = False
+
+        # First normalize to FormD to separate letters from their diacritics
+        normalized = unicodedata.normalize("NFD", input_str)
+
+        for c in normalized:
+            # Check if this is a letter that needs to be preserved
+            if "a" <= c <= "z" or "0" <= c <= "9":
+                result.append(c)
+                last_was_hyphen = False
+            elif "A" <= c <= "Z":
+                result.append(c.lower())
+                last_was_hyphen = False
+            elif not last_was_hyphen and len(result) > 0:
+                # Add hyphen for any other character
+                result.append("-")
+                last_was_hyphen = True
+
+        # Trim any trailing hyphens
+        final_result = "".join(result).rstrip("-")
+
+        # Ensure we have at least one character
+        return final_result if final_result else "AiConnectionStringIdentifier"

ravendb/documents/operations/ai/ai_task_operation_results.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+from typing import Dict, Any, Optional
+
+from ravendb.documents.operations.etl.etl_operation_results import AddEtlOperationResult
+
+
+class AddAiTaskOperationResult(AddEtlOperationResult):
+    """Base result class for AI task add operations."""
+
+    def __init__(
+        self,
+        raft_command_index: int = 0,
+        task_id: int = 0,
+        identifier: Optional[str] = None,
+    ):
+        super().__init__(raft_command_index=raft_command_index, task_id=task_id)
+        self.identifier = identifier
+
+    @classmethod
+    def from_json(cls, json_dict: Dict[str, Any]) -> "AddAiTaskOperationResult":
+        return cls(
+            raft_command_index=json_dict.get("RaftCommandIndex", 0),
+            task_id=json_dict.get("TaskId", 0),
+            identifier=json_dict.get("Identifier"),
+        )
+
+
+class AddGenAiOperationResult(AddAiTaskOperationResult):
+    """Result of adding a GenAI task."""
+
+    @classmethod
+    def from_json(cls, json_dict: Dict[str, Any]) -> "AddGenAiOperationResult":
+        return cls(
+            raft_command_index=json_dict.get("RaftCommandIndex", 0),
+            task_id=json_dict.get("TaskId", 0),
+            identifier=json_dict.get("Identifier"),
+        )
+
+
+class AddEmbeddingsGenerationOperationResult(AddAiTaskOperationResult):
+    """Result of adding an Embeddings Generation task."""
+
+    @classmethod
+    def from_json(cls, json_dict: Dict[str, Any]) -> "AddEmbeddingsGenerationOperationResult":
+        return cls(
+            raft_command_index=json_dict.get("RaftCommandIndex", 0),
+            task_id=json_dict.get("TaskId", 0),
+            identifier=json_dict.get("Identifier"),
+        )