unique_toolkit 0.7.7__py3-none-any.whl → 1.23.0__py3-none-any.whl

unique_toolkit/app/schemas.py

@@ -1,23 +1,43 @@
+import json
 from enum import StrEnum
-from typing import Any, Optional
+from logging import getLogger
+from pathlib import Path
+from typing import Any, Generic, Optional, TypeVar, override
 
 from humps import camelize
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic_settings import BaseSettings
 from typing_extensions import deprecated
 
+from unique_toolkit._common.exception import ConfigurationException
+from unique_toolkit.app.unique_settings import UniqueChatEventFilterOptions
+from unique_toolkit.smart_rules.compile import UniqueQL, parse_uniqueql
+
+FilterOptionsT = TypeVar("FilterOptionsT", bound=BaseSettings)
+
 # set config to convert camelCase to snake_case
 model_config = ConfigDict(
     alias_generator=camelize,
     populate_by_name=True,
     arbitrary_types_allowed=True,
 )
+_logger = getLogger(__name__)
 
 
 class EventName(StrEnum):
     EXTERNAL_MODULE_CHOSEN = "unique.chat.external-module.chosen"
-
-
-class BaseEvent(BaseModel):
+    USER_MESSAGE_CREATED = "unique.chat.user-message.created"
+    INGESTION_CONTENT_UPLOADED = "unique.ingestion.content.uploaded"
+    INGESTION_CONTENT_FINISHED = "unique.ingestion.content.finished"
+    MAGIC_TABLE_IMPORT_COLUMNS = "unique.magic-table.import-columns"
+    MAGIC_TABLE_ADD_META_DATA = "unique.magic-table.add-meta-data"
+    MAGIC_TABLE_ADD_DOCUMENT = "unique.magic-table.add-document"
+    MAGIC_TABLE_DELETE_ROW = "unique.magic-table.delete-row"
+    MAGIC_TABLE_DELETE_COLUMN = "unique.magic-table.delete-column"
+    MAGIC_TABLE_UPDATE_CELL = "unique.magic-table.update-cell"
+
+
+class BaseEvent(BaseModel, Generic[FilterOptionsT]):
     model_config = model_config
 
     id: str
@@ -25,6 +45,68 @@ 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)
+
+    def filter_event(self, *, filter_options: FilterOptionsT | None = None) -> bool:
+        """Determine if event should be filtered out and be neglected."""
+        return False
+
+
+###
+# MCP schemas
+###
+
+
+class McpTool(BaseModel):
+    model_config = model_config
+
+    name: str
+    description: Optional[str] = None
+    input_schema: dict[str, Any]
+    output_schema: Optional[dict[str, Any]] = None
+    annotations: Optional[dict[str, Any]] = None
+    title: Optional[str] = Field(
+        default=None,
+        description="The display title for a tool. This is a Unique specific field.",
+    )
+    icon: Optional[str] = Field(
+        default=None,
+        description="An icon name from the Lucide icon set for the tool. This is a Unique specific field.",
+    )
+    system_prompt: Optional[str] = Field(
+        default=None,
+        description="An optional system prompt for the tool. This is a Unique specific field.",
+    )
+    user_prompt: Optional[str] = Field(
+        default=None,
+        description="An optional user prompt for the tool. This is a Unique specific field.",
+    )
+    is_connected: bool = Field(
+        description="Whether the tool is connected to the MCP server. This is a Unique specific field.",
+    )
+
+
+class McpServer(BaseModel):
+    model_config = model_config
+
+    id: str
+    name: str
+    system_prompt: Optional[str] = Field(
+        default=None,
+        description="An optional system prompt for the MCP server.",
+    )
+    user_prompt: Optional[str] = Field(
+        default=None,
+        description="An optional user prompt for the MCP server.",
+    )
+    tools: list[McpTool] = []
+
 
 ###
 # ChatEvent schemas
@@ -95,45 +177,130 @@ 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
+    disabled_tools: list[str] = Field(
+        default_factory=list,
+        description="A list containing the tool names of tools that are disabled at the company level",
+    )
+    tool_parameters: dict[str, Any] = Field(
+        default_factory=dict,
+        description="Parameters extracted from module selection function calling the tool.",
+    )
+    # Default is None as empty dict triggers error in `backend-ingestion`
+    metadata_filter: dict[str, Any] | None = Field(
+        default=None,
+        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.",
+    )
+    mcp_servers: list[McpServer] = Field(
+        default_factory=list,
+        description="A list of MCP servers with tools available for the chat session.",
+    )
+    message_execution_id: str | None = Field(
+        default=None,
+        description="The message execution id for triggering the chat event. Originates from the message execution service.",
+    )
+
+    @field_validator("raw_scope_rules", mode="before")
+    def validate_scope_rules(cls, value: dict[str, Any] | None) -> UniqueQL | None:
+        if value:
+            return parse_uniqueql(value)
 
 
 @deprecated("""Use `ChatEventPayload` instead.
             This class will be removed in the next major version.""")
 class EventPayload(ChatEventPayload):
-    user_message: EventUserMessage
-    assistant_message: EventAssistantMessage
-    additional_parameters: Optional[EventAdditionalParameters] = None
+    pass
+    # user_message: EventUserMessage
+    # assistant_message: EventAssistantMessage
+    # additional_parameters: Optional[EventAdditionalParameters] = None
 
 
-@deprecated(
-    """Use the more specific `ChatEvent` instead that has the same properties. \
-This class will be removed in the next major version."""
-)
-class Event(BaseModel):
+class ChatEvent(BaseEvent):
     model_config = model_config
 
-    id: str
-    event: EventName
-    user_id: str
-    company_id: str
-    payload: EventPayload
+    payload: ChatEventPayload
     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)
+
+    def get_initial_debug_info(self) -> dict[str, Any]:
+        """Get the debug information for the chat event"""
+
+        # TODO: Make sure this coincides with what is shown in the first user message
+        return {
+            "user_metadata": self.payload.user_metadata,
+            "tool_parameters": self.payload.tool_parameters,
+            "chosen_module": self.payload.name,
+            "assistant": {"id": self.payload.assistant_id},
+        }
+
+    @override
+    def filter_event(
+        self, *, filter_options: UniqueChatEventFilterOptions | None = None
+    ) -> bool:
+        # Empty string evals to False
+
+        if filter_options is None:
+            return False  # Don't filter when no options provided
+
+        if not filter_options.assistant_ids and not filter_options.references_in_code:
+            raise ConfigurationException(
+                "No filter options provided, all events will be filtered! \n"
+                "Please define: \n"
+                " - 'UNIQUE_CHAT_EVENT_FILTER_OPTIONS_ASSISTANT_IDS' \n"
+                " - 'UNIQUE_CHAT_EVENT_FILTER_OPTIONS_REFERENCES_IN_CODE' \n"
+                "in your environment variables."
+            )
+
+        # Per reference in code there can be multiple assistants
+        if (
+            filter_options.assistant_ids
+            and self.payload.assistant_id not in filter_options.assistant_ids
+        ):
+            return True
+
+        if (
+            filter_options.references_in_code
+            and self.payload.name not in filter_options.references_in_code
+        ):
+            return True
+
+        return super().filter_event(filter_options=filter_options)
 
-class ChatEvent(BaseEvent):
-    model_config = model_config
 
-    event: EventName
-    payload: ChatEventPayload
-    created_at: Optional[int] = None
-    version: Optional[str] = None
+@deprecated(
+    """Use the more specific `ChatEvent` instead that has the same properties. \
+This class will be removed in the next major version."""
+)
+class Event(ChatEvent):
+    pass
+    # 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/app/unique_settings.py

@@ -0,0 +1,367 @@
+import os
+from logging import getLogger
+from pathlib import Path
+from typing import TYPE_CHECKING, Self, TypeVar
+from urllib.parse import ParseResult, urlparse, urlunparse
+
+import unique_sdk
+from platformdirs import user_config_dir
+from pydantic import AliasChoices, Field, SecretStr, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+if TYPE_CHECKING:
+    from unique_toolkit.app.schemas import BaseEvent
+
+
+logger = getLogger(__name__)
+
+T = TypeVar("T", bound=BaseSettings)
+
+
+def warn_about_defaults(instance: T) -> T:
+    """Log warnings for fields that are using default values."""
+    for field_name, model_field in instance.__class__.model_fields.items():
+        field_value = getattr(instance, field_name)
+        default_value = model_field.default
+
+        # Handle SecretStr comparison by comparing the secret values
+        if isinstance(field_value, SecretStr) and isinstance(default_value, SecretStr):
+            if field_value.get_secret_value() == default_value.get_secret_value():
+                logger.warning(
+                    f"Using default value for '{field_name}': {default_value.get_secret_value()}"
+                )
+        elif field_value == default_value:
+            logger.warning(f"Using default value for '{field_name}': {default_value}")
+    return instance
+
+
+class UniqueApp(BaseSettings):
+    id: SecretStr = Field(
+        default=SecretStr("dummy_id"),
+        validation_alias=AliasChoices(
+            "unique_app_id", "app_id", "UNIQUE_APP_ID", "APP_ID"
+        ),
+    )
+    key: SecretStr = Field(
+        default=SecretStr("dummy_key"),
+        validation_alias=AliasChoices(
+            "unique_app_key", "key", "UNIQUE_APP_KEY", "KEY", "API_KEY", "api_key"
+        ),
+    )
+    base_url: str = Field(
+        default="http://localhost:8092/",
+        deprecated="Use UniqueApi.base_url instead",
+    )
+    endpoint: str = Field(default="dummy")
+
+    endpoint_secret: SecretStr = Field(default=SecretStr("dummy_secret"))
+
+    @model_validator(mode="after")
+    def _warn_about_defaults(self) -> Self:
+        return warn_about_defaults(self)
+
+    model_config = SettingsConfigDict(
+        env_prefix="unique_app_",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+
+class UniqueApi(BaseSettings):
+    base_url: str = Field(
+        default="http://localhost:8092/",
+        description="The base URL of the Unique API. Ask your admin to provide you with the correct URL.",
+        validation_alias=AliasChoices(
+            "unique_api_base_url",
+            "base_url",
+            "UNIQUE_API_BASE_URL",
+            "BASE_URL",
+            "API_BASE",
+        ),
+    )
+    version: str = Field(
+        default="2023-12-06",
+        validation_alias=AliasChoices(
+            "unique_api_version", "version", "UNIQUE_API_VERSION", "VERSION"
+        ),
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="unique_api_",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    @model_validator(mode="after")
+    def _warn_about_defaults(self) -> Self:
+        return warn_about_defaults(self)
+
+    def sse_url(self, subscriptions: list[str]) -> str:
+        parsed = urlparse(self.base_url)
+        return urlunparse(
+            parsed._replace(
+                path="/public/event-socket/events/stream",
+                query=f"subscriptions={','.join(subscriptions)}",
+                fragment=None,
+            )
+        )
+
+    def base_path(self) -> tuple[ParseResult, str]:
+        parsed = urlparse(self.base_url)
+        base_path = "/public/chat/"
+
+        if parsed.hostname and (
+            "gateway.qa.unique" in parsed.hostname
+            or "gateway.unique" in parsed.hostname
+        ):
+            base_path = "/public/chat-gen2/"
+
+        if parsed.hostname and (
+            "localhost" in parsed.hostname or "svc.cluster.local" in parsed.hostname
+        ):
+            base_path = "/public/"
+
+        return parsed, base_path
+
+    def sdk_url(self) -> str:
+        parsed, base_path = self.base_path()
+        return urlunparse(parsed._replace(path=base_path, query=None, fragment=None))
+
+    def openai_proxy_url(self) -> str:
+        parsed, base_path = self.base_path()
+        path = base_path + "openai-proxy/"
+        return urlunparse(parsed._replace(path=path, query=None, fragment=None))
+
+
+class UniqueAuth(BaseSettings):
+    company_id: SecretStr = Field(
+        default=SecretStr("dummy_company_id"),
+        validation_alias=AliasChoices(
+            "unique_auth_company_id",
+            "company_id",
+            "UNIQUE_AUTH_COMPANY_ID",
+            "COMPANY_ID",
+        ),
+    )
+    user_id: SecretStr = Field(
+        default=SecretStr("dummy_user_id"),
+        validation_alias=AliasChoices(
+            "unique_auth_user_id", "user_id", "UNIQUE_AUTH_USER_ID", "USER_ID"
+        ),
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="unique_auth_",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    @model_validator(mode="after")
+    def _warn_about_defaults(self) -> Self:
+        return warn_about_defaults(self)
+
+    @classmethod
+    def from_event(cls, event: "BaseEvent") -> Self:
+        return cls(
+            company_id=SecretStr(event.company_id),
+            user_id=SecretStr(event.user_id),
+        )
+
+
+class UniqueChatEventFilterOptions(BaseSettings):
+    # Empty string evals to False
+    assistant_ids: list[str] = Field(
+        default=[],
+        description="The assistant ids (space) to filter by. Default is all assistants.",
+    )
+    references_in_code: list[str] = Field(
+        default=[],
+        description="The module (reference) names in code to filter by. Default is all modules.",
+    )
+
+    model_config = SettingsConfigDict(
+        env_prefix="unique_chat_event_filter_options_",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    @model_validator(mode="after")
+    def _warn_about_defaults(self) -> Self:
+        return warn_about_defaults(self)
+
+
+class EnvFileNotFoundError(FileNotFoundError):
+    """Raised when no environment file can be found in any of the expected locations."""
+
+
+class UniqueSettings:
+    def __init__(
+        self,
+        auth: UniqueAuth,
+        app: UniqueApp,
+        api: UniqueApi,
+        *,
+        chat_event_filter_options: UniqueChatEventFilterOptions | None = None,
+        env_file: Path | None = None,
+    ):
+        self._app = app
+        self._auth = auth
+        self._api = api
+        self._chat_event_filter_options = chat_event_filter_options
+        self._env_file: Path | None = (
+            env_file if (env_file and env_file.exists()) else None
+        )
+
+    @classmethod
+    def _find_env_file(cls, filename: str = "unique.env") -> Path:
+        """Find environment file using cross-platform fallback locations.
+
+        Search order:
+        1. UNIQUE_ENV_FILE environment variable
+        2. Current working directory
+        3. User config directory (cross-platform via platformdirs)
+
+        Args:
+            filename: Name of the environment file (default: 'unique.env')
+
+        Returns:
+            Path to the environment file.
+
+        Raises:
+            EnvFileNotFoundError: If no environment file is found in any location.
+        """
+        locations = [
+            # 1. Explicit environment variable
+            Path(env_path) if (env_path := os.environ.get("UNIQUE_ENV_FILE")) else None,
+            # 2. Current working directory
+            Path.cwd() / filename,
+            # 3. User config directory (cross-platform)
+            Path(user_config_dir("unique", "unique-toolkit")) / filename,
+        ]
+
+        for location in locations:
+            if location and location.exists() and location.is_file():
+                return location
+
+        # If no file found, provide helpful error message
+        searched_locations = [str(loc) for loc in locations if loc is not None]
+        raise EnvFileNotFoundError(
+            f"Environment file '{filename}' not found. Searched locations:\n"
+            + "\n".join(f"  - {loc}" for loc in searched_locations)
+            + "\n\nTo fix this:\n"
+            + f"  1. Create {filename} in one of the above locations, or\n"
+            + f"  2. Set UNIQUE_ENV_FILE environment variable to point to your {filename} file"
+        )
+
+    @classmethod
+    def from_env(
+        cls,
+        env_file: Path | None = None,
+    ) -> "UniqueSettings":
+        """Initialize settings from environment variables and/or env file.
+
+        Args:
+            env_file: Optional path to environment file. If provided, will load variables from this file.
+
+        Returns:
+            UniqueSettings instance with values loaded from environment/env file.
+
+        Raises:
+            FileNotFoundError: If env_file is provided but does not exist.
+            ValidationError: If required environment variables are missing.
+        """
+        if env_file and not env_file.exists():
+            raise FileNotFoundError(f"Environment file not found: {env_file}")
+
+        # Initialize settings with environment file if provided
+        env_file_str = str(env_file) if env_file else None
+        auth = UniqueAuth(_env_file=env_file_str)  # type: ignore[call-arg]
+        app = UniqueApp(_env_file=env_file_str)  # type: ignore[call-arg]
+        api = UniqueApi(_env_file=env_file_str)  # type: ignore[call-arg]
+        event_filter_options = UniqueChatEventFilterOptions(_env_file=env_file_str)  # type: ignore[call-arg]
+        return cls(
+            auth=auth,
+            app=app,
+            api=api,
+            chat_event_filter_options=event_filter_options,
+            env_file=env_file,
+        )
+
+    @classmethod
+    def from_env_auto(cls, filename: str = "unique.env") -> "UniqueSettings":
+        """Initialize settings by automatically finding environment file.
+
+        This method will automatically search for an environment file in standard locations
+        and fall back to environment variables only if no file is found.
+
+        Args:
+            filename: Name of the environment file to search for (default: '.env')
+
+        Returns:
+            UniqueSettings instance with values loaded from found env file or environment variables.
+        """
+        try:
+            env_file = cls._find_env_file(filename)
+            logger.info(f"Environment file found at {env_file}")
+            return cls.from_env(env_file=env_file)
+        except EnvFileNotFoundError:
+            logger.warning(
+                f"Environment file '{filename}' not found. Falling back to environment variables only."
+            )
+            # Fall back to environment variables only
+            return cls.from_env()
+
+    def init_sdk(self) -> None:
+        """Initialize the unique_sdk global configuration with these settings.
+
+        This method configures the global unique_sdk module with the API key,
+        app ID, and base URL from these settings.
+        """
+        unique_sdk.api_key = self._app.key.get_secret_value()
+        unique_sdk.app_id = self._app.id.get_secret_value()
+        unique_sdk.api_base = self._api.sdk_url()
+
+    @classmethod
+    def from_env_auto_with_sdk_init(
+        cls, filename: str = "unique.env"
+    ) -> "UniqueSettings":
+        """Initialize settings and SDK in one convenient call.
+
+        This method combines from_env_auto() and init_sdk() for the most common use case.
+
+        Args:
+            filename: Name of the environment file to search for (default: '.env')
+
+        Returns:
+            UniqueSettings instance with SDK already initialized.
+        """
+        settings = cls.from_env_auto(filename)
+        settings.init_sdk()
+        return settings
+
+    def update_from_event(self, event: "BaseEvent") -> None:
+        self._auth = UniqueAuth.from_event(event)
+
+    @property
+    def api(self) -> UniqueApi:
+        return self._api
+
+    @property
+    def app(self) -> UniqueApp:
+        return self._app
+
+    @property
+    def auth(self) -> UniqueAuth:
+        return self._auth
+
+    @auth.setter
+    def auth(self, value: UniqueAuth) -> None:
+        self._auth = value
+
+    @property
+    def chat_event_filter_options(self) -> UniqueChatEventFilterOptions | None:
+        return self._chat_event_filter_options

unique_toolkit/chat/__init__.py

@@ -1,3 +1,5 @@
+import warnings
+
 from .constants import DOMAIN_NAME as DOMAIN_NAME
 from .schemas import ChatMessage as ChatMessage
 from .schemas import ChatMessageAssessment as ChatMessageAssessment
@@ -5,7 +7,12 @@ from .schemas import ChatMessageAssessmentLabel as ChatMessageAssessmentLabel
 from .schemas import ChatMessageAssessmentStatus as ChatMessageAssessmentStatus
 from .schemas import ChatMessageAssessmentType as ChatMessageAssessmentType
 from .schemas import ChatMessageRole as ChatMessageRole
-from .service import ChatService as ChatService
+
+# Import ChatService with deprecation warning suppressed for internal use
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore", DeprecationWarning)
+    from .service import ChatService as ChatService
+
 from .utils import (
     convert_chat_history_to_injectable_string as convert_chat_history_to_injectable_string,
 )