unique_toolkit 0.7.25__py3-none-any.whl → 0.7.27__py3-none-any.whl

unique_toolkit/app/schemas.py

@@ -1,10 +1,14 @@
+import json
 from enum import StrEnum
+from pathlib import Path
 from typing import Any, Optional
 
 from humps import camelize
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 from typing_extensions import deprecated
 
+from unique_toolkit.smart_rules.compile import UniqueQL, parse_uniqueql
+
 # set config to convert camelCase to snake_case
 model_config = ConfigDict(
     alias_generator=camelize,
@@ -25,6 +29,14 @@ class BaseEvent(BaseModel):
     user_id: str
     company_id: str
 
+    @classmethod
+    def from_json_file(cls, file_path: Path) -> "BaseEvent":
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        with file_path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        return cls.model_validate(data)
+
 
 ###
 # ChatEvent schemas
@@ -95,15 +107,31 @@ class ChatEventPayload(BaseModel):
     assistant_id: str
     user_message: ChatEventUserMessage
     assistant_message: ChatEventAssistantMessage
-    text: Optional[str] = None
-    additional_parameters: Optional[ChatEventAdditionalParameters] = None
-    user_metadata: Optional[dict[str, Any]] = None
-    tool_choices: Optional[list[str]] = Field(
-        default=[],
+    text: str | None = None
+    additional_parameters: ChatEventAdditionalParameters | None = None
+    user_metadata: dict[str, Any] | None = Field(
+        default_factory=dict,
+    )
+    tool_choices: list[str] = Field(
+        default_factory=list,
         description="A list containing the tool names the user has chosen to be activated.",
     )
-    tool_parameters: Optional[dict[str, Any]] = None
-    metadata_filter: Optional[dict[str, Any]] = None
+    tool_parameters: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Parameters extracted from module selection function calling the tool.",
+    )
+    metadata_filter: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Metadata filter compiled after module selection function calling and scope rules.",
+    )
+    raw_scope_rules: UniqueQL | None = Field(
+        default=None,
+        description="Raw UniqueQL rule that can be compiled to a metadata filter.",
+    )
+
+    @field_validator("raw_scope_rules", mode="before")
+    def validate_scope_rules(cls, value: dict[str, Any]) -> UniqueQL:
+        return parse_uniqueql(value)
 
 
 @deprecated("""Use `ChatEventPayload` instead.
@@ -122,6 +150,14 @@ class ChatEvent(BaseEvent):
     created_at: Optional[int] = None
     version: Optional[str] = None
 
+    @classmethod
+    def from_json_file(cls, file_path: Path) -> "ChatEvent":
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        with file_path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        return cls.model_validate(data)
+
 
 @deprecated(
     """Use the more specific `ChatEvent` instead that has the same properties. \
@@ -132,3 +168,11 @@ class Event(ChatEvent):
     # The below should only affect type hints
     # event: EventName T
     # payload: EventPayload
+
+    @classmethod
+    def from_json_file(cls, file_path: Path) -> "Event":
+        if not file_path.exists():
+            raise FileNotFoundError(f"File not found: {file_path}")
+        with file_path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+        return cls.model_validate(data)

unique_toolkit/chat/functions.py

@@ -3,6 +3,7 @@ import re
 from typing import Any, Dict, List, cast
 
 import unique_sdk
+from typing_extensions import deprecated
 from unique_sdk._list_object import ListObject
 
 from unique_toolkit._common import _time_utils
@@ -673,6 +674,7 @@ async def modify_message_assessment_async(
         raise e
 
 
+@deprecated("Use stream_complete_with_references instead")
 def stream_complete_to_chat(
     company_id: str,
     user_id: str,
@@ -682,7 +684,43 @@ def stream_complete_to_chat(
     assistant_id: str,
     messages: LanguageModelMessages,
     model_name: LanguageModelName | str,
-    content_chunks: list[ContentChunk] = [],
+    content_chunks: list[ContentChunk] | None = None,
+    debug_info: dict = {},
+    temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
+    timeout: int = DEFAULT_COMPLETE_TIMEOUT,
+    tools: list[LanguageModelTool | LanguageModelToolDescription] | None = None,
+    start_text: str | None = None,
+    other_options: dict | None = None,
+) -> LanguageModelStreamResponse:
+    return stream_complete_with_references(
+        company_id=company_id,
+        user_id=user_id,
+        assistant_message_id=assistant_message_id,
+        user_message_id=user_message_id,
+        chat_id=chat_id,
+        assistant_id=assistant_id,
+        messages=messages,
+        model_name=model_name,
+        content_chunks=content_chunks,
+        debug_info=debug_info,
+        temperature=temperature,
+        timeout=timeout,
+        tools=tools,
+        start_text=start_text,
+        other_options=other_options,
+    )
+
+
+def stream_complete_with_references(
+    company_id: str,
+    user_id: str,
+    assistant_message_id: str,
+    user_message_id: str,
+    chat_id: str,
+    assistant_id: str,
+    messages: LanguageModelMessages,
+    model_name: LanguageModelName | str,
+    content_chunks: list[ContentChunk] | None = None,
     debug_info: dict = {},
     temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
     timeout: int = DEFAULT_COMPLETE_TIMEOUT,
@@ -719,7 +757,7 @@ def stream_complete_to_chat(
         temperature=temperature,
         tools=tools,
         other_options=other_options,
-        content_chunks=content_chunks,
+        content_chunks=content_chunks or [],
     )
 
     try:
@@ -747,6 +785,7 @@ def stream_complete_to_chat(
         raise e
 
 
+@deprecated("Use stream_complete_with_references_async instead")
 async def stream_complete_to_chat_async(
     company_id: str,
     user_id: str,
@@ -756,7 +795,43 @@ async def stream_complete_to_chat_async(
     assistant_id: str,
     messages: LanguageModelMessages,
     model_name: LanguageModelName | str,
-    content_chunks: list[ContentChunk] = [],
+    content_chunks: list[ContentChunk] | None = None,
+    debug_info: dict = {},
+    temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
+    timeout: int = DEFAULT_COMPLETE_TIMEOUT,
+    tools: list[LanguageModelTool | LanguageModelToolDescription] | None = None,
+    start_text: str | None = None,
+    other_options: dict | None = None,
+) -> LanguageModelStreamResponse:
+    return await stream_complete_with_references_async(
+        company_id=company_id,
+        user_id=user_id,
+        assistant_message_id=assistant_message_id,
+        user_message_id=user_message_id,
+        chat_id=chat_id,
+        assistant_id=assistant_id,
+        messages=messages,
+        model_name=model_name,
+        content_chunks=content_chunks,
+        debug_info=debug_info,
+        temperature=temperature,
+        timeout=timeout,
+        tools=tools,
+        start_text=start_text,
+        other_options=other_options,
+    )
+
+
+async def stream_complete_with_references_async(
+    company_id: str,
+    user_id: str,
+    assistant_message_id: str,
+    user_message_id: str,
+    chat_id: str,
+    assistant_id: str,
+    messages: LanguageModelMessages,
+    model_name: LanguageModelName | str,
+    content_chunks: list[ContentChunk] | None = None,
     debug_info: dict = {},
     temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
     timeout: int = DEFAULT_COMPLETE_TIMEOUT,
@@ -778,7 +853,7 @@ async def stream_complete_to_chat_async(
         temperature=temperature,
         tools=tools,
         other_options=other_options,
-        content_chunks=content_chunks,
+        content_chunks=content_chunks or [],
     )
 
     try:

unique_toolkit/chat/service.py

@@ -48,8 +48,8 @@ from unique_toolkit.language_model.schemas import (
 )
 
 from .functions import (
-    stream_complete_to_chat,
-    stream_complete_to_chat_async,
+    stream_complete_with_references,
+    stream_complete_with_references_async,
 )
 
 logger = logging.getLogger(f"toolkit.{DOMAIN_NAME}.{__name__}")
@@ -1084,11 +1084,36 @@ class ChatService:
             label=label,
         )
 
+    @deprecated("Use complete_with_references instead")
     def stream_complete(
         self,
         messages: LanguageModelMessages,
         model_name: LanguageModelName | str,
-        content_chunks: list[ContentChunk] = [],
+        content_chunks: list[ContentChunk] | None = None,
+        debug_info: dict = {},
+        temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
+        timeout: int = DEFAULT_COMPLETE_TIMEOUT,
+        tools: Optional[list[LanguageModelTool | LanguageModelToolDescription]] = None,
+        start_text: Optional[str] = None,
+        other_options: Optional[dict] = None,
+    ) -> LanguageModelStreamResponse:
+        return self.complete_with_references(
+            messages=messages,
+            model_name=model_name,
+            content_chunks=content_chunks,
+            debug_info=debug_info,
+            temperature=temperature,
+            timeout=timeout,
+            tools=tools,
+            start_text=start_text,
+            other_options=other_options,
+        )
+
+    def complete_with_references(
+        self,
+        messages: LanguageModelMessages,
+        model_name: LanguageModelName | str,
+        content_chunks: list[ContentChunk] | None = None,
         debug_info: dict = {},
         temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
         timeout: int = DEFAULT_COMPLETE_TIMEOUT,
@@ -1117,7 +1142,7 @@ class ChatService:
             ]
         )
 
-        return stream_complete_to_chat(
+        return stream_complete_with_references(
             company_id=company_id,
             user_id=user_id,
             assistant_message_id=assistant_message_id,
@@ -1139,7 +1164,7 @@ class ChatService:
         self,
         messages: LanguageModelMessages,
         model_name: LanguageModelName | str,
-        content_chunks: list[ContentChunk] = [],
+        content_chunks: list[ContentChunk] | None = None,
         debug_info: dict = {},
         temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
         timeout: int = DEFAULT_COMPLETE_TIMEOUT,
@@ -1147,7 +1172,7 @@ class ChatService:
         start_text: Optional[str] = None,
         other_options: Optional[dict] = None,
     ) -> LanguageModelResponse:
-        response = self.stream_complete(
+        response = self.complete_with_references(
             messages=messages,
             model_name=model_name,
             content_chunks=content_chunks,
@@ -1161,11 +1186,12 @@ class ChatService:
 
         return LanguageModelResponse.from_stream_response(response)
 
+    @deprecated("use complete_with_references_async instead.")
     async def stream_complete_async(
         self,
         messages: LanguageModelMessages,
         model_name: LanguageModelName | str,
-        content_chunks: list[ContentChunk] = [],
+        content_chunks: list[ContentChunk] | None = None,
         debug_info: dict = {},
         temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
         timeout: int = DEFAULT_COMPLETE_TIMEOUT,
@@ -1173,10 +1199,31 @@ class ChatService:
         start_text: Optional[str] = None,
         other_options: Optional[dict] = None,
     ) -> LanguageModelStreamResponse:
-        """
-        Streams a completion in the chat session asynchronously.
-        """
+        """Stream a completion in the chat session asynchronously."""
+        return await self.complete_with_references_async(
+            messages=messages,
+            model_name=model_name,
+            content_chunks=content_chunks,
+            debug_info=debug_info,
+            temperature=temperature,
+            timeout=timeout,
+            tools=tools,
+            start_text=start_text,
+            other_options=other_options,
+        )
 
+    async def complete_with_references_async(
+        self,
+        messages: LanguageModelMessages,
+        model_name: LanguageModelName | str,
+        content_chunks: list[ContentChunk] | None = None,
+        debug_info: dict = {},
+        temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
+        timeout: int = DEFAULT_COMPLETE_TIMEOUT,
+        tools: Optional[list[LanguageModelTool | LanguageModelToolDescription]] = None,
+        start_text: Optional[str] = None,
+        other_options: Optional[dict] = None,
+    ) -> LanguageModelStreamResponse:
         [
             company_id,
             user_id,
@@ -1195,7 +1242,7 @@ class ChatService:
             ]
         )
 
-        return await stream_complete_to_chat_async(
+        return await stream_complete_with_references_async(
             company_id=company_id,
             user_id=user_id,
             assistant_message_id=assistant_message_id,
@@ -1217,7 +1264,7 @@ class ChatService:
         self,
         messages: LanguageModelMessages,
         model_name: LanguageModelName | str,
-        content_chunks: list[ContentChunk] = [],
+        content_chunks: list[ContentChunk] | None,
         debug_info: dict = {},
         temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
         timeout: int = DEFAULT_COMPLETE_TIMEOUT,
@@ -1225,7 +1272,7 @@ class ChatService:
         start_text: Optional[str] = None,
         other_options: Optional[dict] = None,
     ) -> LanguageModelResponse:
-        response = self.stream_complete_async(
+        response = self.complete_with_references_async(
             messages=messages,
             model_name=model_name,
             content_chunks=content_chunks,

unique_toolkit/content/functions.py

@@ -3,6 +3,7 @@ import os
 import re
 import tempfile
 from pathlib import Path
+from typing import Any
 
 import requests
 import unique_sdk
@@ -214,7 +215,7 @@ def upload_content_from_bytes(
     chat_id: str | None = None,
     skip_ingestion: bool = False,
     ingestion_config: unique_sdk.Content.IngestionConfig | None = None,
-    metadata: dict[str, any] | None = None,
+    metadata: dict[str, Any] | None = None,
 ):
     """
     Uploads content to the knowledge base.
@@ -229,7 +230,7 @@ def upload_content_from_bytes(
         chat_id (str | None): The chat ID. Defaults to None.
         skip_ingestion (bool): Whether to skip ingestion. Defaults to False.
         ingestion_config (unique_sdk.Content.IngestionConfig | None): The ingestion configuration. Defaults to None.
-        metadata ( dict[str, any] | None): The metadata for the content. Defaults to None.
+        metadata ( dict[str, Any] | None): The metadata for the content. Defaults to None.
 
     Returns:
         Content: The uploaded content.
@@ -263,7 +264,7 @@ def upload_content(
     chat_id: str | None = None,
     skip_ingestion: bool = False,
     ingestion_config: unique_sdk.Content.IngestionConfig | None = None,
-    metadata: dict[str, any] | None = None,
+    metadata: dict[str, Any] | None = None,
 ):
     """
     Uploads content to the knowledge base.
@@ -278,7 +279,7 @@ def upload_content(
         chat_id (str | None): The chat ID. Defaults to None.
         skip_ingestion (bool): Whether to skip ingestion. Defaults to False.
         ingestion_config (unique_sdk.Content.IngestionConfig | None): The ingestion configuration. Defaults to None.
-        metadata ( dict[str, any] | None): The metadata for the content. Defaults to None.
+        metadata ( dict[str, Any] | None): The metadata for the content. Defaults to None.
 
     Returns:
         Content: The uploaded content.
@@ -312,7 +313,7 @@ def _trigger_upload_content(
     chat_id: str | None = None,
     skip_ingestion: bool = False,
     ingestion_config: unique_sdk.Content.IngestionConfig | None = None,
-    metadata: dict[str, any] | None = None,
+    metadata: dict[str, Any] | None = None,
 ):
     """
     Uploads content to the knowledge base.
@@ -327,7 +328,7 @@ def _trigger_upload_content(
         chat_id (str | None): The chat ID. Defaults to None.
         skip_ingestion (bool): Whether to skip ingestion. Defaults to False.
         ingestion_config (unique_sdk.Content.IngestionConfig | None): The ingestion configuration. Defaults to None.
-        metadata (dict[str, any] | None): The metadata for the content. Defaults to None.
+        metadata (dict[str, Any] | None): The metadata for the content. Defaults to None.
 
     Returns:
         Content: The uploaded content.

unique_toolkit/content/schemas.py

@@ -1,6 +1,6 @@
 from datetime import datetime
 from enum import StrEnum
-from typing import Optional
+from typing import Any, Optional
 
 from humps import camelize
 from pydantic import BaseModel, ConfigDict, Field
@@ -54,7 +54,7 @@ class Content(BaseModel):
     read_url: str | None = None
     created_at: datetime | None = None
     updated_at: datetime | None = None
-    metadata: dict[str, any] | None = None
+    metadata: dict[str, Any] | None = None
     ingestion_config: dict | None = None
 
 

unique_toolkit/content/service.py

@@ -422,7 +422,7 @@ class ContentService:
             chat_id (str | None): The chat ID. Defaults to None.
             skip_ingestion (bool): Whether to skip ingestion. Defaults to False.
             ingestion_config (unique_sdk.Content.IngestionConfig | None): The ingestion configuration. Defaults to None.
-            metadata (dict[str, any] | None): The metadata to associate with the content. Defaults to None.
+            metadata (dict[str, Any] | None): The metadata to associate with the content. Defaults to None.
 
         Returns:
             Content: The uploaded content.

unique_toolkit/language_model/functions.py

@@ -1,23 +1,33 @@
+import copy
 import logging
-from typing import cast
+from datetime import datetime, timezone
+from typing import Any, cast
 
 import unique_sdk
 from pydantic import BaseModel
 
+from unique_toolkit.chat.schemas import ChatMessage, ChatMessageRole
 from unique_toolkit.content.schemas import ContentChunk
 from unique_toolkit.evaluators import DOMAIN_NAME
-
-from .constants import (
-    DEFAULT_COMPLETE_TEMPERATURE,
-    DEFAULT_COMPLETE_TIMEOUT,
-)
-from .infos import LanguageModelName
-from .schemas import (
+from unique_toolkit.language_model import (
+    LanguageModelMessageRole,
     LanguageModelMessages,
     LanguageModelResponse,
+    LanguageModelStreamResponse,
+    LanguageModelStreamResponseMessage,
     LanguageModelTool,
     LanguageModelToolDescription,
 )
+from unique_toolkit.language_model.infos import LanguageModelName
+from unique_toolkit.language_model.reference import (
+    PotentialReference,
+    add_references_to_message,
+)
+
+from .constants import (
+    DEFAULT_COMPLETE_TEMPERATURE,
+    DEFAULT_COMPLETE_TIMEOUT,
+)
 
 logger = logging.getLogger(f"toolkit.{DOMAIN_NAME}.{__name__}")
 
@@ -36,6 +46,7 @@ def complete(
     """Call the completion endpoint synchronously without streaming the response.
 
     Args:
+    ----
         company_id (str): The company ID associated with the request.
         messages (LanguageModelMessages): The messages to complete.
         model_name (LanguageModelName | str): The model name to use for the completion.
@@ -45,6 +56,7 @@ def complete(
         other_options (Optional[dict]): Additional options to use. Defaults to None.
 
     Returns:
+    -------
         LanguageModelResponse: The response object containing the completed result.
 
     """
@@ -93,6 +105,7 @@ async def complete_async(
     the completed result.
 
     Args:
+    ----
         company_id (str): The company ID associated with the request.
         messages (LanguageModelMessages): The messages to complete.
         model_name (LanguageModelName | str): The model name to use for the completion.
@@ -102,9 +115,11 @@ async def complete_async(
         other_options (Optional[dict]): The other options to use. Defaults to None.
 
     Returns:
+    -------
         LanguageModelResponse: The response object containing the completed result.
 
     Raises:
+    ------
         Exception: If an error occurs during the request, an exception is raised
         and logged.
 
@@ -198,7 +213,8 @@ def _prepare_completion_params_util(
 ) -> tuple[dict, str, dict, dict | None]:
     """Prepare common parameters for completion requests.
 
-    Returns:
+    Returns
+    -------
         tuple containing:
         - options (dict): Combined options including tools and temperature
         - model (str): Resolved model name
@@ -232,3 +248,120 @@ def _prepare_completion_params_util(
     )
 
     return options, model, messages_dict, search_context
+
+
+def complete_with_references(
+    company_id: str,
+    messages: LanguageModelMessages,
+    model_name: LanguageModelName | str,
+    content_chunks: list[ContentChunk] | None = None,
+    debug_dict: dict = {},
+    temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
+    timeout: int = DEFAULT_COMPLETE_TIMEOUT,
+    tools: list[LanguageModelTool | LanguageModelToolDescription] | None = None,
+    start_text: str | None = None,
+    other_options: dict[str, Any] | None = None,
+) -> LanguageModelStreamResponse:
+    # Use toolkit language model functions for chat completion
+    response = complete(
+        company_id=company_id,
+        model_name=model_name,
+        messages=messages,
+        temperature=temperature,
+        timeout=timeout,
+        tools=tools,
+        other_options=other_options,
+    )
+
+    return _create_language_model_stream_response_with_references(
+        response=response,
+        content_chunks=content_chunks,
+        start_text=start_text,
+    )
+
+
+async def complete_with_references_async(
+    company_id: str,
+    messages: LanguageModelMessages,
+    model_name: LanguageModelName | str,
+    content_chunks: list[ContentChunk] | None = None,
+    debug_dict: dict = {},
+    temperature: float = DEFAULT_COMPLETE_TEMPERATURE,
+    timeout: int = DEFAULT_COMPLETE_TIMEOUT,
+    tools: list[LanguageModelTool | LanguageModelToolDescription] | None = None,
+    start_text: str | None = None,
+    other_options: dict[str, Any] | None = None,
+) -> LanguageModelStreamResponse:
+    # Use toolkit language model functions for chat completion
+    response = await complete_async(
+        company_id=company_id,
+        model_name=model_name,
+        messages=messages,
+        temperature=temperature,
+        timeout=timeout,
+        tools=tools,
+        other_options=other_options,
+    )
+
+    return _create_language_model_stream_response_with_references(
+        response=response,
+        content_chunks=content_chunks,
+        start_text=start_text,
+    )
+
+
+def _create_language_model_stream_response_with_references(
+    response: LanguageModelResponse,
+    content_chunks: list[ContentChunk] | None = None,
+    start_text: str | None = None,
+):
+    content = response.choices[0].message.content
+    content_chunks = content_chunks or []
+
+    if content is None:
+        raise ValueError("Content is None, which is not supported")
+    elif isinstance(content, list):
+        raise ValueError("Content is a list, which is not supported")
+    else:
+        content = start_text or "" + str(content)
+
+    message = ChatMessage(
+        id="msg_unknown",
+        text=copy.deepcopy(content),
+        role=ChatMessageRole.ASSISTANT,
+        created_at=datetime.now(timezone.utc),
+        chat_id="chat_unknown",
+    )
+
+    search_context = [
+        PotentialReference(
+            id=source.id,
+            chunk_id=source.id,
+            title=source.title,
+            key=source.key or "",
+            url=source.url,
+        )
+        for source in content_chunks
+    ]
+
+    message, __ = add_references_to_message(
+        message=message,
+        search_context=search_context,
+    )
+
+    stream_response_message = LanguageModelStreamResponseMessage(
+        id="stream_unknown",
+        previous_message_id=None,
+        role=LanguageModelMessageRole.ASSISTANT,
+        text=message.content or "",
+        original_text=content,
+        references=[u.model_dump() for u in message.references or []],
+    )
+
+    tool_calls = [r.function for r in response.choices[0].message.tool_calls or []]
+    tool_calls = tool_calls if len(tool_calls) > 0 else None
+
+    return LanguageModelStreamResponse(
+        message=stream_response_message,
+        tool_calls=tool_calls,
+    )