truefoundry 0.5.0rc7__py3-none-any.whl → 0.5.1rc2__py3-none-any.whl

truefoundry/ml/autogen/client/models/model_version_manifest.py

@@ -40,11 +40,11 @@ class ModelVersionManifest(BaseModel):
 
     description: Optional[constr(strict=True, max_length=512)] = Field(
         default=None,
-        description="+label=Description +docs=Description of the artifact version",
+        description="+label=Description +usage=Description of the artifact or model version +docs=Description of the artifact or model version",
     )
     metadata: Dict[str, Any] = Field(
         default=...,
-        description="+label=Metadata +docs=Metadata for the model version +usage=Metadata for the model version +uiType=JsonInput",
+        description="+label=Metadata +docs=Metadata for the artifact or model version +usage=Metadata for the artifact or model version +uiType=JsonInput",
     )
     type: Optional[StrictStr] = "model-version"
     source: Source1 = Field(...)
@@ -55,7 +55,7 @@ class ModelVersionManifest(BaseModel):
     )
     model_schema: Optional[Dict[str, Any]] = Field(
         default=None,
-        description="+label=Model Schema +usage=Schema of the model +uiType=Hidden",
+        description="+label=Model Schema +usage=Schema of the model +uiType=JsonInput",
     )
     __properties = [
         "description",

truefoundry/ml/autogen/client/models/sklearn_framework.py

@@ -18,6 +18,7 @@ import pprint
 import re  # noqa: F401
 from typing import Optional
 
+from truefoundry.ml.autogen.client.models.infer_method_name import InferMethodName
 from truefoundry.ml.autogen.client.models.serialization_format import (
     SerializationFormat,
 )
@@ -37,7 +38,20 @@ class SklearnFramework(BaseModel):
         default=None,
         description="+label=Serialization format +usage=Serialization format used for the model",
     )
-    __properties = ["type", "serialization_format"]
+    model_filepath: Optional[StrictStr] = Field(
+        default=None,
+        description="+label=Model file path +usage=Relative path to the model file",
+    )
+    infer_method_name: Optional[InferMethodName] = Field(
+        default=None,
+        description="+label=Inference method name +usage=Name of the method used for inference",
+    )
+    __properties = [
+        "type",
+        "serialization_format",
+        "model_filepath",
+        "infer_method_name",
+    ]
 
     @validator("type")
     def type_validate_enum(cls, value):
@@ -83,6 +97,8 @@ class SklearnFramework(BaseModel):
             {
                 "type": obj.get("type"),
                 "serialization_format": obj.get("serialization_format"),
+                "model_filepath": obj.get("model_filepath"),
+                "infer_method_name": obj.get("infer_method_name"),
             }
         )
         return _obj

truefoundry/ml/autogen/client/models/transformers_framework.py

@@ -37,11 +37,11 @@ class TransformersFramework(BaseModel):
     )
     pipeline_tag: Optional[StrictStr] = Field(
         default=None,
-        description="+label=Pipeline Tag +usage=Pipeline tag +docs=Pipeline tag for the framework",
+        description="+label=Pipeline Tag +usage=The `pipeline()` task this model can be used with e.g. `text-generation`. See [huggingface docs](https://huggingface.co/docs/transformers/main/en/main_classes/pipelines#transformers.pipeline.task) for all possible values +docs=Pipeline tag for the framework",
     )
     base_model: Optional[StrictStr] = Field(
         default=None,
-        description="+label=Base Model +usage=Base model +docs=Base model Id. If this is a finetuned model, this points to the base model used for finetuning",
+        description="+label=Base Model +usage=Base model Id. If this is a finetuned model, this points to the base model used for finetuning +docs=Base model Id. If this is a finetuned model, this points to the base model used for finetuning",
     )
     __properties = ["type", "library_name", "pipeline_tag", "base_model"]
 

truefoundry/ml/autogen/client/models/xg_boost_framework.py

@@ -37,7 +37,11 @@ class XGBoostFramework(BaseModel):
         default=None,
         description="+label=Serialization format +usage=Serialization format used for the model",
     )
-    __properties = ["type", "serialization_format"]
+    model_filepath: Optional[StrictStr] = Field(
+        default=None,
+        description="+label=Model file path +usage=Relative path to the model file",
+    )
+    __properties = ["type", "serialization_format", "model_filepath"]
 
     @validator("type")
     def type_validate_enum(cls, value):
@@ -83,6 +87,7 @@ class XGBoostFramework(BaseModel):
             {
                 "type": obj.get("type"),
                 "serialization_format": obj.get("serialization_format"),
+                "model_filepath": obj.get("model_filepath"),
             }
         )
         return _obj

truefoundry/ml/autogen/client_README.md

@@ -102,6 +102,7 @@ Class | Method | HTTP request | Description
 *MlfoundryArtifactsApi* | [**delete_dataset_post**](truefoundry/ml/autogen/client/docs/MlfoundryArtifactsApi.md#delete_dataset_post) | **POST** /api/2.0/mlflow/mlfoundry-artifacts/datasets/delete | Delete Dataset
 *MlfoundryArtifactsApi* | [**delete_files_for_dataset_delete**](truefoundry/ml/autogen/client/docs/MlfoundryArtifactsApi.md#delete_files_for_dataset_delete) | **DELETE** /api/2.0/mlflow/mlfoundry-artifacts/datasets/files/ | Delete Files For Dataset
 *MlfoundryArtifactsApi* | [**delete_model_version_post**](truefoundry/ml/autogen/client/docs/MlfoundryArtifactsApi.md#delete_model_version_post) | **POST** /api/2.0/mlflow/mlfoundry-artifacts/model-versions/delete | Delete Model Version
+*MlfoundryArtifactsApi* | [**export_deployment_files_by_fqn_post**](truefoundry/ml/autogen/client/docs/MlfoundryArtifactsApi.md#export_deployment_files_by_fqn_post) | **POST** /api/2.0/mlflow/mlfoundry-artifacts/model-versions/export-deployment-files-by-fqn | Export Deployment Files By Fqn
 *MlfoundryArtifactsApi* | [**finalize_artifact_version_post**](truefoundry/ml/autogen/client/docs/MlfoundryArtifactsApi.md#finalize_artifact_version_post) | **POST** /api/2.0/mlflow/mlfoundry-artifacts/artifact-versions/finalize | Finalize Artifact Version
 *MlfoundryArtifactsApi* | [**get_artifact_by_fqn_get**](truefoundry/ml/autogen/client/docs/MlfoundryArtifactsApi.md#get_artifact_by_fqn_get) | **GET** /api/2.0/mlflow/mlfoundry-artifacts/artifacts/get-by-fqn | Get Artifact By Fqn
 *MlfoundryArtifactsApi* | [**get_artifact_by_id_get**](truefoundry/ml/autogen/client/docs/MlfoundryArtifactsApi.md#get_artifact_by_id_get) | **GET** /api/2.0/mlflow/mlfoundry-artifacts/artifacts/get | Get Artifact By Id
@@ -211,6 +212,7 @@ Class | Method | HTTP request | Description
  - [ExperimentIdRequestDto](truefoundry/ml/autogen/client/docs/ExperimentIdRequestDto.md)
  - [ExperimentResponseDto](truefoundry/ml/autogen/client/docs/ExperimentResponseDto.md)
  - [ExperimentTagDto](truefoundry/ml/autogen/client/docs/ExperimentTagDto.md)
+ - [ExportDeploymentFilesRequestDto](truefoundry/ml/autogen/client/docs/ExportDeploymentFilesRequestDto.md)
  - [ExternalArtifactSource](truefoundry/ml/autogen/client/docs/ExternalArtifactSource.md)
  - [FastAIFramework](truefoundry/ml/autogen/client/docs/FastAIFramework.md)
  - [FileInfoDto](truefoundry/ml/autogen/client/docs/FileInfoDto.md)
@@ -233,6 +235,7 @@ Class | Method | HTTP request | Description
  - [HTTPValidationError](truefoundry/ml/autogen/client/docs/HTTPValidationError.md)
  - [ImageContentPart](truefoundry/ml/autogen/client/docs/ImageContentPart.md)
  - [ImageUrl](truefoundry/ml/autogen/client/docs/ImageUrl.md)
+ - [InferMethodName](truefoundry/ml/autogen/client/docs/InferMethodName.md)
  - [InternalMetadata](truefoundry/ml/autogen/client/docs/InternalMetadata.md)
  - [KerasFramework](truefoundry/ml/autogen/client/docs/KerasFramework.md)
  - [LatestRunLogDto](truefoundry/ml/autogen/client/docs/LatestRunLogDto.md)
@@ -270,6 +273,7 @@ Class | Method | HTTP request | Description
  - [ModelConfiguration](truefoundry/ml/autogen/client/docs/ModelConfiguration.md)
  - [ModelDto](truefoundry/ml/autogen/client/docs/ModelDto.md)
  - [ModelResponseDto](truefoundry/ml/autogen/client/docs/ModelResponseDto.md)
+ - [ModelServer](truefoundry/ml/autogen/client/docs/ModelServer.md)
  - [ModelVersionDto](truefoundry/ml/autogen/client/docs/ModelVersionDto.md)
  - [ModelVersionEnvironment](truefoundry/ml/autogen/client/docs/ModelVersionEnvironment.md)
  - [ModelVersionManifest](truefoundry/ml/autogen/client/docs/ModelVersionManifest.md)

truefoundry/ml/autogen/entities/artifacts.py

@@ -1,6 +1,6 @@
 # generated by datamodel-codegen:
 #   filename:  artifacts.json
-#   timestamp: 2024-11-28T08:27:16+00:00
+#   timestamp: 2024-12-04T12:00:28+00:00
 
 from __future__ import annotations
 
@@ -52,11 +52,11 @@ class AgentWithFQN(Agent):
 class BaseArtifactVersion(BaseModel):
     description: Optional[constr(max_length=512)] = Field(
         None,
-        description="+label=Description\n+docs=Description of the artifact version",
+        description="+label=Description\n+usage=Description of the artifact or model version\n+docs=Description of the artifact or model version",
     )
     metadata: Dict[str, Any] = Field(
         ...,
-        description="+label=Metadata\n+docs=Metadata for the model version\n+usage=Metadata for the model version\n+uiType=JsonInput",
+        description="+label=Metadata\n+docs=Metadata for the artifact or model version\n+usage=Metadata for the artifact or model version\n+uiType=JsonInput",
     )
 
 
@@ -228,7 +228,7 @@ class ModelConfiguration(BaseModel):
 
 class ModelVersionEnvironment(BaseModel):
     """
-    +label=ModelVersionEnvironment
+    +label=Environment
     """
 
     python_version: Optional[constr(regex=r"^\d+(\.\d+){1,2}([\-\.a-z0-9]+)?$")] = (
@@ -287,6 +287,16 @@ class SerializationFormat(str, Enum):
     pickle = "pickle"
 
 
+class InferMethodName(str, Enum):
+    """
+    +label=Inference method name
+    +usage=Name of the method used for inference
+    """
+
+    predict = "predict"
+    predict_proba = "predict_proba"
+
+
 class SklearnFramework(BaseModel):
     """
     +docs=Scikit-learn framework for the model version
@@ -300,6 +310,14 @@ class SklearnFramework(BaseModel):
         None,
         description="+label=Serialization format\n+usage=Serialization format used for the model",
     )
+    model_filepath: Optional[str] = Field(
+        None,
+        description="+label=Model file path\n+usage=Relative path to the model file",
+    )
+    infer_method_name: Optional[InferMethodName] = Field(
+        None,
+        description="+label=Inference method name\n+usage=Name of the method used for inference",
+    )
 
 
 class SpaCyFramework(BaseModel):
@@ -389,11 +407,11 @@ class TransformersFramework(BaseModel):
     )
     pipeline_tag: Optional[str] = Field(
         None,
-        description="+label=Pipeline Tag\n+usage=Pipeline tag\n+docs=Pipeline tag for the framework",
+        description="+label=Pipeline Tag\n+usage=The `pipeline()` task this model can be used with e.g. `text-generation`. See [huggingface docs](https://huggingface.co/docs/transformers/main/en/main_classes/pipelines#transformers.pipeline.task) for all possible values\n+docs=Pipeline tag for the framework",
     )
     base_model: Optional[str] = Field(
         None,
-        description="+label=Base Model\n+usage=Base model\n+docs=Base model Id. If this is a finetuned model, this points to the base model used for finetuning",
+        description="+label=Base Model\n+usage=Base model Id. If this is a finetuned model, this points to the base model used for finetuning\n+docs=Base model Id. If this is a finetuned model, this points to the base model used for finetuning",
     )
 
 
@@ -446,6 +464,10 @@ class XGBoostFramework(BaseModel):
         None,
         description="+label=Serialization format\n+usage=Serialization format used for the model",
     )
+    model_filepath: Optional[str] = Field(
+        None,
+        description="+label=Model file path\n+usage=Relative path to the model file",
+    )
 
 
 class AgentOpenAPITool(BaseModel):
@@ -573,7 +595,7 @@ class ModelVersion(BaseArtifactVersion):
     step: conint(ge=0) = Field(0, description="+label=Step")
     model_schema: Optional[Dict[str, Any]] = Field(
         None,
-        description="+label=Model Schema\n+usage=Schema of the model\n+uiType=Hidden",
+        description="+label=Model Schema\n+usage=Schema of the model\n+uiType=JsonInput",
     )
 
 

truefoundry/ml/cli/commands/model_init.py

@@ -0,0 +1,97 @@
+import os
+from typing import Optional
+
+import rich_click as click
+
+from truefoundry.deploy.cli.console import console
+from truefoundry.deploy.cli.const import COMMAND_CLS
+from truefoundry.deploy.cli.util import handle_exception_wrapper
+from truefoundry.ml.autogen.client.models import ModelServer
+from truefoundry.ml.cli.utils import (
+    AppName,
+    NonEmptyString,
+)
+from truefoundry.ml.mlfoundry_api import get_client
+
+
+@click.command(
+    name="model",
+    cls=COMMAND_CLS,
+    help="Generating application code for the specified model version.",
+)
+@click.option(
+    "--name",
+    required=True,
+    type=AppName(),
+    help="Name for the model server deployment",
+    show_default=True,
+)
+@click.option(
+    "--model-version-fqn",
+    "--model_version_fqn",
+    type=NonEmptyString(),
+    required=True,
+    show_default=True,
+    help="Fully Qualified Name (FQN) of the model version to deploy, e.g., 'model:tenant_name/my-model/linear-regression:2'",
+)
+@click.option(
+    "-w",
+    "--workspace-fqn",
+    "--workspace_fqn",
+    type=NonEmptyString(),
+    required=True,
+    show_default=True,
+    help="Fully Qualified Name (FQN) of the workspace to deploy",
+)
+@click.option(
+    "--model-server",
+    "--model_server",
+    type=click.Choice(ModelServer, case_sensitive=False),
+    default=ModelServer.FASTAPI.value,
+    show_default=True,
+    help="Specify the model server (Case Insensitive).",
+)
+@click.option(
+    "--output-dir",
+    "--output_dir",
+    type=click.Path(exists=True, file_okay=False, writable=True),
+    help="Output directory for the model server code",
+    required=False,
+    show_default=True,
+    default=os.getcwd(),
+)
+@handle_exception_wrapper
+def model_init_command(
+    name: str,
+    model_version_fqn: str,
+    workspace_fqn: str,
+    model_server: ModelServer,
+    output_dir: Optional[str],
+):
+    """
+    Generates application code for the specified model version.
+    """
+    ml_client = get_client()
+    console.print(f"Generating application code for {model_version_fqn!r}")
+    output_dir = ml_client._initialize_model_server(
+        name=name,
+        model_version_fqn=model_version_fqn,
+        workspace_fqn=workspace_fqn,
+        model_server=ModelServer[model_server.upper()],
+        output_dir=output_dir,
+    )
+    message = f"""
+[bold green]Model Server code initialized successfully![/bold green]
+
+[bold]Code Location:[/bold] {output_dir}
+
+[bold]Next Steps:[/bold]
+- Navigate to the model server directory:
+[green]cd {output_dir}[/green]
+- Refer to the README file in the directory for further instructions.
+"""
+    console.print(message)
+
+
+def get_model_init_command():
+    return model_init_command

truefoundry/ml/cli/utils.py

@@ -0,0 +1,34 @@
+import rich_click as click
+
+from truefoundry.ml import MlFoundryException
+from truefoundry.ml.validation_utils import (
+    _APP_NAME_REGEX,
+)
+
+
+class AppName(click.ParamType):
+    """
+    Custom ParamType to validate application names.
+    """
+
+    name = "application-name"
+
+    def convert(self, value, param, ctx):
+        try:
+            if not value or not _APP_NAME_REGEX.match(value):
+                raise MlFoundryException(
+                    f"{value!r} must be lowercase and cannot contain spaces. It can only contain alphanumeric characters and hyphens. "
+                    f"Length must be between 1 and 30 characters."
+                )
+        except MlFoundryException as e:
+            self.fail(str(e), param, ctx)
+        return value
+
+
+class NonEmptyString(click.ParamType):
+    name = "non-empty-string"
+
+    def convert(self, value, param, ctx):
+        if isinstance(value, str) and not value.strip():
+            self.fail("Value cannot be empty or contain only spaces.", param, ctx)
+        return value

truefoundry/ml/log_types/artifacts/model.py

@@ -8,7 +8,7 @@ import typing
 import uuid
 import warnings
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, Optional, Sequence, Tuple, Union
+from typing import TYPE_CHECKING, Any, Dict, Optional, Union
 
 from truefoundry.ml.artifact.truefoundry_artifact_repo import (
     ArtifactIdentifier,
@@ -44,11 +44,19 @@ from truefoundry.ml.log_types.artifacts.utils import (
     _validate_description,
     calculate_total_size,
 )
-from truefoundry.ml.model_framework import ModelFrameworkType, _ModelFramework
+from truefoundry.ml.model_framework import (
+    ModelFrameworkType,
+    _ModelFramework,
+    auto_update_environment_details,
+    auto_update_model_framework_details,
+)
 from truefoundry.ml.session import _get_api_client
 from truefoundry.pydantic_v1 import BaseModel, Extra
 
 if TYPE_CHECKING:
+    import numpy as np
+    import pandas as pd
+
     from truefoundry.ml.mlfoundry_run import MlFoundryRun
 
 
@@ -98,6 +106,7 @@ class ModelVersion:
         self._description: str = ""
         self._metadata: Dict[str, Any] = {}
         self._model_schema: Optional[Dict[str, Any]] = None
+        self._environment: Optional[ModelVersionEnvironment] = None
         self._framework: Optional[ModelFrameworkType] = None
         self._set_mutable_attrs()
 
@@ -143,19 +152,20 @@ class ModelVersion:
             self._model_schema = copy.deepcopy(
                 self._model_version.manifest.model_schema
             )
-            if self._model_version.manifest.framework:
-                self._framework = copy.deepcopy(
-                    self._model_version.manifest.framework.actual_instance
-                )
-            else:
-                self._framework = None
+            self._environment = copy.deepcopy(self._model_version.manifest.environment)
+            self._framework = (
+                copy.deepcopy(self._model_version.manifest.framework.actual_instance)
+                if self._model_version.manifest.framework
+                else None
+            )
         else:
             self._description = self._model_version.description or ""
             self._metadata = copy.deepcopy(self._model_version.artifact_metadata)
+            self._model_schema = None
+            self._environment = None
             self._framework = _ModelFramework.to_model_framework_type(
                 self._model_version.model_framework
             )
-            self._model_schema = None
 
     def _refetch_model_version(self, reset_mutable_attrs: bool = True):
         _model_version = self._mlfoundry_artifacts_api.get_model_version_get(
@@ -242,6 +252,23 @@ class ModelVersion:
             return
         self._model_schema = copy.deepcopy(value)
 
+    @property
+    def environment(self) -> Optional[ModelVersionEnvironment]:
+        """Get the environment details for the model"""
+        return self._environment
+
+    @environment.setter
+    def environment(self, value: Optional[Dict[str, Any]]):
+        """set the environment details for the model"""
+        if not self._model_version.manifest:
+            warnings.warn(
+                message="This model version was created using an older serialization format. Environment will not be updated",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            return
+        self._environment = copy.deepcopy(value)
+
     @property
     def framework(self) -> Optional["ModelFrameworkType"]:
         """Get the framework of the model"""
@@ -440,6 +467,7 @@ class ModelVersion:
             self._model_version.manifest.description = self.description
             self._model_version.manifest.metadata = self.metadata
             self._model_version.manifest.model_schema = self.model_schema
+            self._model_version.manifest.environment = self.environment
             self._model_version.manifest.framework = (
                 Framework.from_dict(self.framework.dict()) if self.framework else None
             )
@@ -467,7 +495,6 @@ def _log_model_version(  # noqa: C901
     model_file_or_folder: Union[str, BlobStorageDirectory],
     mlfoundry_artifacts_api: Optional[MlfoundryArtifactsApi] = None,
     ml_repo_id: Optional[str] = None,
-    additional_files: Sequence[Tuple[Union[str, Path], Optional[str]]] = (),
     description: Optional[str] = None,
     metadata: Optional[Dict[str, Any]] = None,
     step: Optional[int] = 0,
@@ -498,7 +525,6 @@ def _log_model_version(  # noqa: C901
     step = step or 0
     total_size = None
     metadata = metadata or {}
-    additional_files = additional_files or {}
 
     _validate_description(description)
     _validate_artifact_metadata(metadata)
@@ -516,17 +542,6 @@ def _log_model_version(  # noqa: C901
                 ignore_model_dir_dest_conflict=True,
             )
 
-            # verify additional files and paths, copy additional files
-            if additional_files:
-                logger.info("Adding `additional_files` to model version contents")
-                temp_dest_to_src_map = _copy_additional_files(
-                    root_dir=temp_dir.name,
-                    files_dir="",
-                    model_dir=None,
-                    additional_files=additional_files,
-                    ignore_model_dir_dest_conflict=False,
-                    existing_dest_to_src_map=temp_dest_to_src_map,
-                )
         except Exception as e:
             temp_dir.cleanup()
             raise MlFoundryException("Failed to log model") from e
@@ -580,13 +595,22 @@ def _log_model_version(  # noqa: C901
     else:
         raise MlFoundryException("Invalid model_file_or_folder provided")
 
-    _framework = _ModelFramework.to_model_framework_type(framework)
     _source_cls = typing.get_type_hints(ModelVersionManifest)["source"]
+
+    # Auto fetch the framework & environment details if not provided
+    framework = _ModelFramework.to_model_framework_type(framework)
+    if framework and isinstance(model_file_or_folder, str):
+        auto_update_model_framework_details(
+            framework=framework, model_file_or_folder=model_file_or_folder
+        )
+    environment = environment or ModelVersionEnvironment()
+    auto_update_environment_details(environment=environment, framework=framework)
+
     model_manifest = ModelVersionManifest(
         description=description,
         metadata=metadata,
         source=_source_cls.from_dict(source.dict()),
-        framework=Framework.from_dict(_framework.dict()) if _framework else None,
+        framework=Framework.from_dict(framework.dict()) if framework else None,
         environment=environment,
         step=step,
         model_schema=model_schema,
@@ -603,3 +627,18 @@ def _log_model_version(  # noqa: C901
         )
     )
     return ModelVersion.from_fqn(fqn=artifact_version_response.artifact_version.fqn)
+
+
+def infer_signature(
+    model_input: Any = None,
+    model_output: Optional[
+        Union["pd.DataFrame", "np.ndarray", Dict[str, "np.ndarray"]]
+    ] = None,
+    params: Optional[Dict[str, Any]] = None,
+):
+    # TODO: Importing this globally causes hard dependencies on some libraries like pandas
+    from truefoundry.ml.autogen.models import infer_signature as _infer_signature
+
+    return _infer_signature(
+        model_input=model_input, model_output=model_output, params=params
+    )

truefoundry/ml/log_types/artifacts/utils.py

@@ -2,7 +2,7 @@ import json
 import logging
 import os
 import posixpath
-from pathlib import Path
+from pathlib import Path, PureWindowsPath
 from typing import Any, Dict, Optional, Sequence, Tuple, Union
 
 from truefoundry.ml.exceptions import MlFoundryException
@@ -11,6 +11,13 @@ from truefoundry.ml.log_types.artifacts.constants import DESCRIPTION_MAX_LENGTH
 logger = logging.getLogger(__name__)
 
 
+def to_unix_path(path):
+    path = os.path.normpath(path)
+    if os.path.sep == "\\":
+        path = PureWindowsPath(path).as_posix()
+    return path
+
+
 def _copy_tree(
     root_dir: str, src_path: str, dest_path: str, dest_to_src: Dict[str, str]
 ):
@@ -42,6 +49,35 @@ def is_destination_path_dirlike(dest_path) -> bool:
     return False
 
 
+def get_single_file_path_if_only_one_in_directory(path: str) -> Optional[str]:
+    """
+    Get the filename from a path, or return a filename from a directory if a single file exists.
+    Args:
+        path: The file or folder path.
+    Returns:
+        Optional[str]: The filename or None if no files are found or multiple files are found.
+    """
+    # If it's already a file, return it as-is
+    if os.path.isfile(path):
+        return path
+
+    # If it's a directory, check if it contains a single file
+    if is_destination_path_dirlike(path):
+        all_files = []
+        for root, _, files in os.walk(path):
+            # Collect all files found in any subdirectory
+            all_files.extend(os.path.join(root, f) for f in files)
+            # If more than one file is found, stop early
+            if len(all_files) > 1:
+                return None
+
+        # If only one file is found, return it
+        if len(all_files) == 1:
+            return all_files[0]
+
+    return None  # No file found or Multiple files found
+
+
 def _copy_additional_files(
     root_dir: str,
     files_dir: str,  # relative to root dir e.g. "files/"