unique_toolkit 1.71.2__tar.gz → 1.72.0__tar.gz

{unique_toolkit-1.71.2 → unique_toolkit-1.72.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: unique-toolkit
-Version: 1.71.2
+Version: 1.72.0
 Summary: 
 Author: Cedric Klinkert, Martin Fadler, Sadique Sheik, Fabian Schläpfer, Pascal Hauri, Ejiroghene Oki-Peter, Rami Azouz, Ricardo Visini, Sanzio Monti
 Author-email: Cedric Klinkert <cedric.klinkert@unique.ch>, Martin Fadler <martin.fadler@unique.ch>, Sadique Sheik <sadique@unique.ch>, Fabian Schläpfer <fabian@unique.ch>, Pascal Hauri <pascal@unique.ch>, Ejiroghene Oki-Peter <oki-peter.ejiroghene@unique.ai>, Rami Azouz <rami.ext@unique.ch>, Ricardo Visini <ricardo.visini@unique.ch>, Sanzio Monti <sanzio.monti@unique.ai>

{unique_toolkit-1.71.2 → unique_toolkit-1.72.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "unique_toolkit"
-version = "1.71.2"
+version = "1.72.0"
 description = ""
 readme = "README.md"
 requires-python = ">=3.12"

{unique_toolkit-1.71.2 → unique_toolkit-1.72.0}/unique_toolkit/app/__init__.py

@@ -1,3 +1,5 @@
+from .find_env_file import EnvFileNotFoundError as EnvFileNotFoundError
+from .find_env_file import find_env_file as find_env_file
 from .init_logging import init_logging as init_logging
 from .init_sdk import get_endpoint_secret as get_endpoint_secret
 from .init_sdk import init_sdk as init_sdk

unique_toolkit-1.72.0/unique_toolkit/app/chat_event_filter_options_settings.py

@@ -0,0 +1,11 @@
+from pydantic_settings import SettingsConfigDict
+
+from unique_toolkit.app.find_env_file import find_env_file
+
+CHAT_EVENT_FILTER_OPTIONS_SETTINGS = SettingsConfigDict(
+    env_prefix="unique_chat_event_filter_options_",
+    env_file_encoding="utf-8",
+    case_sensitive=False,
+    extra="ignore",
+    env_file=find_env_file("unique.env", ".env", required=False),
+)

unique_toolkit-1.72.0/unique_toolkit/app/feature_flags.py

@@ -0,0 +1,100 @@
+from typing import Annotated
+
+from pydantic import BeforeValidator, Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class FeatureFlag:
+    """A feature flag that can be enabled globally or for specific company IDs.
+
+    Examples:
+        >>> flag = FeatureFlag(True)
+        >>> flag.is_enabled("any_company")
+        True
+
+        >>> flag = FeatureFlag(["company1", "company2"])
+        >>> flag.is_enabled("company1")
+        True
+        >>> flag.is_enabled("company3")
+        False
+    """
+
+    def __init__(self, *, value: list[str] | bool):
+        self._value = value
+
+    def is_enabled(self, *, company_id: str | None = None) -> bool:
+        """Check if the feature is enabled for the given company.
+
+        Args:
+            company_id: The company ID to check. Required if flag is a list.
+
+        Returns:
+            True if the feature is enabled, False otherwise.
+        """
+
+        if isinstance(self._value, bool):
+            return self._value
+
+        if isinstance(self._value, list):
+            return company_id in self._value if company_id else False
+
+        return False
+
+    def __repr__(self) -> str:
+        return f"FeatureFlag({self._value})"
+
+
+def parse_feature_flag(v: FeatureFlag | str | bool | list[str]) -> FeatureFlag:
+    """Parse all feature flag fields from environment variables.
+
+    Args:
+        v: Can be a string ("true", "false", or comma-separated IDs),
+           a boolean, a list of IDs, or already a FeatureFlag instance.
+
+    Returns:
+        A FeatureFlag instance.
+    """
+    if isinstance(v, FeatureFlag):
+        return v
+
+    if isinstance(v, str):
+        v_lower = v.lower().strip()
+        if v_lower in ("true", "1", "yes"):
+            return FeatureFlag(value=True)
+        elif v_lower in ("false", "0", "no", ""):
+            return FeatureFlag(value=False)
+        else:
+            # Comma-separated company IDs
+            return FeatureFlag(value=[id.strip() for id in v.split(",") if id.strip()])
+
+    if isinstance(v, bool):
+        return FeatureFlag(value=v)
+
+    if isinstance(v, list):
+        return FeatureFlag(value=v)
+
+    # Default to disabled (this handles default factory functions too)
+    return FeatureFlag(value=False)
+
+
+ValidatedFeatureFlag = Annotated[FeatureFlag, BeforeValidator(parse_feature_flag)]
+
+
+class _UniqueToolkitFeatureFlags(BaseSettings):
+    un_18894_freeze_unique_settings: ValidatedFeatureFlag = Field(
+        default=FeatureFlag(value=False),
+        frozen=True,
+        description="Freeze unique settings (UN-18894)",
+    )
+
+    model_config = SettingsConfigDict(
+        extra="ignore",
+        env_prefix="FEATURE_FLAG_",
+        case_sensitive=False,
+        env_file=".env",
+        env_file_encoding="utf-8",
+        frozen=True,
+    )
+
+
+UNIQUE_TOOLKIT_FEATURE_FLAGS = _UniqueToolkitFeatureFlags()

unique_toolkit-1.72.0/unique_toolkit/app/find_env_file.py

@@ -0,0 +1,70 @@
+import os
+from pathlib import Path
+
+from platformdirs import user_config_dir
+
+
+class EnvFileNotFoundError(FileNotFoundError):
+    """Raised when no environment file can be found in any of the expected locations."""
+
+
+def find_env_file(
+    *filenames: str,
+    app_name: str = "unique",
+    app_author: str = "unique",
+    required: bool = False,
+) -> Path | None:
+    """Find environment files using cross-platform fallback locations.
+
+    Search order for each filename:
+    1. ENVIRONMENT_FILE_PATH environment variable
+    2. Current working directory
+    3. User config directory (cross-platform via platformdirs)
+
+    If no filenames are given, defaults to ``".env"``.
+
+    Args:
+        *filenames: Names of the environment files to search for.
+        app_name: Application name for user config directory (default: 'unique')
+        app_author: Application author for user config directory (default: 'unique')
+        required: If True, raise EnvFileNotFoundError when file is not found.
+                  If False, return None when file is not found (default: True).
+
+    Returns:
+        Path to the environment file, or None if not found and required=False.
+
+    Raises:
+        EnvFileNotFoundError: If no environment file is found and required=True.
+    """
+    if not filenames:
+        filenames = (".env",)
+
+    locations = []
+    if env_path := os.environ.get("ENVIRONMENT_FILE_PATH"):
+        locations.append(Path(env_path))
+    else:
+        for filename in filenames:
+            locations.append(Path.cwd() / filename)
+            locations.append(
+                Path(user_config_dir(appname=app_name, appauthor=app_author)) / filename
+            )
+
+    for location in locations:
+        if location and location.exists() and location.is_file():
+            return location
+
+    # If no file found, either return None or raise error
+    if not required:
+        return None
+
+    # If required, provide helpful error message
+    searched_locations = [str(loc) for loc in locations if loc is not None]
+    raise EnvFileNotFoundError(
+        "\n".join(
+            [
+                f"Environment file '{filename}' not found. Searched locations:\n"
+                + "\n".join(f"  - {loc}" for loc in searched_locations)
+                for filename in filenames
+            ]
+        )
+    )

{unique_toolkit-1.71.2 → unique_toolkit-1.72.0}/unique_toolkit/app/schemas.py

@@ -12,6 +12,9 @@ from pydantic_settings import BaseSettings
 from typing_extensions import deprecated
 
 from unique_toolkit._common.exception import ConfigurationException
+from unique_toolkit.app.chat_event_filter_options_settings import (
+    CHAT_EVENT_FILTER_OPTIONS_SETTINGS,
+)
 from unique_toolkit.app.unique_settings import UniqueChatEventFilterOptions
 from unique_toolkit.smart_rules.compile import UniqueQL, parse_uniqueql
 
@@ -55,6 +58,9 @@ class BaseEvent(BaseModel, Generic[FilterOptionsT]):
             data = json.load(f)
         return cls.model_validate(data)
 
+    def filter(self) -> bool:
+        return False
+
     def filter_event(self, *, filter_options: FilterOptionsT | None = None) -> bool:
         """Determine if event should be filtered out and be neglected."""
         return False
@@ -284,6 +290,18 @@ class ChatEvent(BaseEvent):
     created_at: Optional[int] = None
     version: Optional[str] = None
 
+    class FilterOptions(BaseSettings):
+        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 = CHAT_EVENT_FILTER_OPTIONS_SETTINGS
+
     @classmethod
     def from_json_file(cls, file_path: Path) -> ChatEvent:
         if not file_path.exists():
@@ -303,6 +321,27 @@ class ChatEvent(BaseEvent):
             "assistant": {"id": self.payload.assistant_id},
         }
 
+    @override
+    def filter(self) -> bool:
+        """Filter the chat event based on the assistant id and reference in code."""
+
+        options = ChatEvent.FilterOptions()
+
+        # Empty lists mean "do not filter by this criterion" (same as filter_event).
+        if (
+            options.assistant_ids
+            and self.payload.assistant_id not in options.assistant_ids
+        ):
+            return True
+
+        if (
+            options.references_in_code
+            and self.payload.name not in options.references_in_code
+        ):
+            return True
+
+        return False
+
     @override
     def filter_event(
         self, *, filter_options: UniqueChatEventFilterOptions | None = None

{unique_toolkit-1.71.2 → unique_toolkit-1.72.0}/unique_toolkit/app/unique_settings.py

@@ -1,13 +1,11 @@
 from __future__ import annotations
 
-import os
 from logging import getLogger
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, Self, TypeVar
 from urllib.parse import ParseResult, urlparse, urlunparse
 
 import unique_sdk
-from platformdirs import user_config_dir
 from pydantic import (
     AliasChoices,
     BaseModel,
@@ -20,6 +18,11 @@ from pydantic_settings import BaseSettings, SettingsConfigDict
 from typing_extensions import Protocol, deprecated
 
 from unique_toolkit._common.config_checker import register_config
+from unique_toolkit.app.chat_event_filter_options_settings import (
+    CHAT_EVENT_FILTER_OPTIONS_SETTINGS,
+)
+from unique_toolkit.app.feature_flags import UNIQUE_TOOLKIT_FEATURE_FLAGS
+from unique_toolkit.app.find_env_file import EnvFileNotFoundError, find_env_file
 
 if TYPE_CHECKING:
     from unique_toolkit.app.schemas import BaseEvent, ChatEvent
@@ -61,8 +64,16 @@ class AuthContextProtocol(Protocol):
 
 
 class AuthContext(BaseModel):
-    company_id: SecretStr = Field(..., description="The company ID.")
-    user_id: SecretStr = Field(..., description="The user ID.")
+    company_id: SecretStr = Field(
+        ...,
+        description="The company ID.",
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
+    )
+    user_id: SecretStr = Field(
+        ...,
+        description="The user ID.",
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
+    )
 
     def get_confidential_company_id(self) -> str:
         return self.company_id.get_secret_value()
@@ -88,12 +99,14 @@ class UniqueAuth(BaseSettings):
             "UNIQUE_AUTH_COMPANY_ID",
             "COMPANY_ID",
         ),
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
     )
     user_id: SecretStr = Field(
         default=SecretStr("dummy_user_id"),
         validation_alias=AliasChoices(
             "unique_auth_user_id", "user_id", "UNIQUE_AUTH_USER_ID", "USER_ID"
         ),
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
     )
 
     model_config = SettingsConfigDict(
@@ -101,6 +114,8 @@ class UniqueAuth(BaseSettings):
         env_file_encoding="utf-8",
         case_sensitive=False,
         extra="ignore",
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
+        env_file=find_env_file("unique.env", ".env", required=False),
     )
 
     def get_confidential_company_id(self) -> str:
@@ -146,8 +161,16 @@ class ChatContextProtocol(Protocol):
 
 
 class ChatContext(BaseModel):
-    chat_id: str = Field(..., description="The chat ID.")
-    assistant_id: str = Field(..., description="The assistant ID.")
+    chat_id: str = Field(
+        ...,
+        description="The chat ID.",
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
+    )
+    assistant_id: str = Field(
+        ...,
+        description="The assistant ID.",
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
+    )
 
     _last_assistant_message_id: str | None = PrivateAttr(default=None)
     _last_user_message_id: str | None = PrivateAttr(default=None)
@@ -254,6 +277,7 @@ class UniqueApp(BaseSettings):
         default="http://localhost:8092/",
         deprecated="Use UniqueApi.base_url instead",
     )
+
     endpoint: str = Field(default="dummy")
 
     endpoint_secret: SecretStr = Field(
@@ -273,8 +297,12 @@ class UniqueApp(BaseSettings):
     model_config = SettingsConfigDict(
         env_prefix="unique_app_",
         env_file_encoding="utf-8",
+        env_file=find_env_file("unique.env", ".env", required=False),
         case_sensitive=False,
         extra="ignore",
+        validate_by_name=True,
+        validate_by_alias=True,
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
     )
 
 
@@ -305,8 +333,10 @@ class UniqueApi(BaseSettings):
     model_config = SettingsConfigDict(
         env_prefix="unique_api_",
         env_file_encoding="utf-8",
+        env_file=find_env_file("unique.env", ".env", required=False),
         case_sensitive=False,
         extra="ignore",
+        frozen=UNIQUE_TOOLKIT_FEATURE_FLAGS.un_18894_freeze_unique_settings.is_enabled(),
     )
 
     @model_validator(mode="after")
@@ -366,22 +396,13 @@ class UniqueChatEventFilterOptions(BaseSettings):
         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_config = CHAT_EVENT_FILTER_OPTIONS_SETTINGS
 
     @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 UniqueEnvironment:
     """
     Contains all settings that come exclusively from the environment.
@@ -474,47 +495,6 @@ class UniqueSettings:
             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,
@@ -563,7 +543,7 @@ class UniqueSettings:
             UniqueSettings instance with values loaded from found env file or environment variables.
         """
         try:
-            env_file = cls._find_env_file(filename)
+            env_file = find_env_file(filename)
             logger.info(f"Environment file found at {env_file}")
             return cls.from_env(env_file=env_file)
         except EnvFileNotFoundError:

{unique_toolkit-1.71.2 → unique_toolkit-1.72.0}/unique_toolkit/content/functions.py

@@ -876,17 +876,17 @@ def get_content_info(
     skip: int | None = None,
     take: int | None = None,
     file_path: str | None = None,
-):
+) -> PaginatedContentInfos:
     """Gets the info of a content."""
 
     get_info_params = unique_sdk.Content.ContentInfoParams(
         metadataFilter=metadata_filter or None,  # Dict cannot be empty
     )
-    if skip:
+    if skip is not None:
         get_info_params["skip"] = skip
-    if take:
+    if take is not None:
         get_info_params["take"] = take
-    if file_path:
+    if file_path is not None:
         get_info_params["filePath"] = file_path
 
     content_info = unique_sdk.Content.get_infos(
@@ -897,6 +897,35 @@ def get_content_info(
     )
 
 
+async def get_content_info_async(
+    user_id: str,
+    company_id: str,
+    *,
+    metadata_filter: dict[str, Any] | None = None,
+    skip: int | None = None,
+    take: int | None = None,
+    file_path: str | None = None,
+) -> PaginatedContentInfos:
+    """Gets the info of a content."""
+
+    get_info_params = unique_sdk.Content.ContentInfoParams(
+        metadataFilter=metadata_filter or None,  # Dict cannot be empty
+    )
+    if skip is not None:
+        get_info_params["skip"] = skip
+    if take is not None:
+        get_info_params["take"] = take
+    if file_path is not None:
+        get_info_params["filePath"] = file_path
+
+    content_info = unique_sdk.Content.get_infos_async(
+        user_id=user_id, company_id=company_id, **get_info_params
+    )
+    return PaginatedContentInfos.model_validate(
+        await content_info, by_alias=True, by_name=True
+    )
+
+
 def get_folder_info(user_id: str, company_id: str, *, scope_id: str) -> FolderInfo:
     info = unique_sdk.Folder.get_info(
         user_id=user_id, company_id=company_id, scopeId=scope_id
@@ -905,6 +934,16 @@ def get_folder_info(user_id: str, company_id: str, *, scope_id: str) -> FolderIn
     return FolderInfo.model_validate(info, by_alias=True, by_name=True)
 
 
+async def get_folder_info_async(
+    user_id: str, company_id: str, *, scope_id: str
+) -> FolderInfo:
+    info = unique_sdk.Folder.get_info_async(
+        user_id=user_id, company_id=company_id, scopeId=scope_id
+    )
+
+    return FolderInfo.model_validate(await info, by_alias=True, by_name=True)
+
+
 def update_content(
     user_id: str,
     company_id: str,