dify_plugin 0.3.4__tar.gz → 0.4.0__tar.gz

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: dify_plugin
-Version: 0.3.4
+Version: 0.4.0
 Summary: Dify Plugin SDK
 Keywords: dify,plugin,sdk
 Author-Email: langgenius <hello@dify.ai>
@@ -10,7 +10,7 @@ Requires-Python: >=3.11
 Requires-Dist: Flask~=3.0.3
 Requires-Dist: Werkzeug~=3.0.3
 Requires-Dist: dpkt~=1.9.8
-Requires-Dist: gevent~=24.11.1
+Requires-Dist: gevent~=25.5.1
 Requires-Dist: httpx~=0.28.1
 Requires-Dist: pydantic_settings<3.0.0,>=2.5.0
 Requires-Dist: pydantic>=2.8.2
@@ -37,12 +37,12 @@ This SDK follows Semantic Versioning (a.b.c):
 ### For SDK Users
 
 When depending on this SDK, it's recommended to specify version constraints that:
+
 - Allow patch and minor updates for bug fixes and new features
 - Prevent major version updates to avoid breaking changes
 
 Example in your project's dependency management:
 
-```
+```python
 dify_plugin>=0.3.0,<0.4.0
 ```
-

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/README.md

@@ -13,12 +13,12 @@ This SDK follows Semantic Versioning (a.b.c):
 ### For SDK Users
 
 When depending on this SDK, it's recommended to specify version constraints that:
+
 - Allow patch and minor updates for bug fixes and new features
 - Prevent major version updates to avoid breaking changes
 
 Example in your project's dependency management:
 
-```
+```python
 dify_plugin>=0.3.0,<0.4.0
 ```
-

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/core/entities/invocation.py

@@ -4,6 +4,7 @@ from enum import Enum
 class InvokeType(Enum):
     Tool = "tool"
     LLM = "llm"
+    LLMStructuredOutput = "llm_structured_output"
     TextEmbedding = "text_embedding"
     Rerank = "rerank"
     TTS = "tts"

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/core/entities/plugin/request.py

@@ -22,6 +22,7 @@ class PluginInvokeType(StrEnum):
     Endpoint = "endpoint"
     Agent = "agent_strategy"
     OAuth = "oauth"
+    DynamicParameter = "dynamic_parameter"
 
 
 class AgentActions(StrEnum):
@@ -58,8 +59,12 @@ class OAuthActions(StrEnum):
     GetCredentials = "get_credentials"
 
 
+class DynamicParameterActions(StrEnum):
+    FetchParameterOptions = "fetch_parameter_options"
+
+
 # merge all the access actions
-PluginAccessAction = AgentActions | ToolActions | ModelActions | EndpointActions
+PluginAccessAction = AgentActions | ToolActions | ModelActions | EndpointActions | DynamicParameterActions
 
 
 class PluginAccessRequest(BaseModel):
@@ -249,3 +254,15 @@ class OAuthGetCredentialsRequest(BaseModel):
     provider: str
     system_credentials: Mapping[str, Any]
     raw_http_request: str
+
+
+class DynamicParameterFetchParameterOptionsRequest(BaseModel):
+    type: PluginInvokeType = PluginInvokeType.DynamicParameter
+    action: DynamicParameterActions = DynamicParameterActions.FetchParameterOptions
+    credentials: dict
+    provider: str
+    provider_action: str
+    user_id: str
+    parameter: str
+
+    model_config = ConfigDict(protected_namespaces=())

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/core/entities/plugin/setup.py

@@ -137,10 +137,21 @@ class PluginConfiguration(BaseModel):
             version: str
             entrypoint: str
 
-        version: str
+        version: str = Field(
+            ...,
+            description="The version of the manifest specification, designed for backward compatibility,"
+            "when installing an older plugin to a newer Dify, it's hard to ensure breaking changes never happen,"
+            " but at least, Dify can detect it by this field, it knows which version of the manifest is supported.",
+        )
         arch: list[PluginArch]
         runner: PluginRunner
-        minimum_dify_version: Optional[str] = Field(None, pattern=r"^\d{1,4}(\.\d{1,4}){1,3}(-\w{1,16})?$")
+        minimum_dify_version: Optional[str] = Field(
+            None,
+            description="The minimum version of Dify, designed for forward compatibility."
+            "When installing a newer plugin to an older Dify, many new features may not be available,"
+            "but showing the minimum Dify version helps users understand how to upgrade.",
+            pattern=r"^\d{1,4}(\.\d{1,4}){1,3}(-\w{1,16})?$",
+        )
 
     version: str = Field(..., pattern=r"^\d{1,4}(\.\d{1,4}){1,3}(-\w{1,16})?$")
     type: PluginType

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/core/plugin_executor.py

@@ -7,6 +7,7 @@ from werkzeug import Response
 from dify_plugin.config.config import DifyPluginEnv
 from dify_plugin.core.entities.plugin.request import (
     AgentInvokeRequest,
+    DynamicParameterFetchParameterOptionsRequest,
     EndpointInvokeRequest,
     ModelGetAIModelSchemas,
     ModelGetLLMNumTokens,
@@ -40,6 +41,7 @@ from dify_plugin.interfaces.model.speech2text_model import Speech2TextModel
 from dify_plugin.interfaces.model.text_embedding_model import TextEmbeddingModel
 from dify_plugin.interfaces.model.tts_model import TTSModel
 from dify_plugin.interfaces.tool import ToolProvider
+from dify_plugin.protocol.dynamic_select import DynamicSelectProtocol
 from dify_plugin.protocol.oauth import OAuthProviderProtocol
 
 
@@ -351,3 +353,32 @@ class PluginExecutor:
         return {
             "credentials": provider_instance.oauth_get_credentials(data.system_credentials, request),
         }
+
+    def _get_dynamic_parameter_action(
+        self, session: Session, data: DynamicParameterFetchParameterOptionsRequest
+    ) -> DynamicSelectProtocol | None:
+        """
+        get the dynamic parameter provider class by provider name
+
+        :param session: session
+        :param data: data
+        :return: dynamic parameter provider class
+        """
+        # get tool
+        tool_cls = self.registration.get_tool_cls(data.provider, data.provider_action)
+        if tool_cls is not None:
+            return tool_cls(
+                runtime=ToolRuntime(credentials=data.credentials, user_id=data.user_id, session_id=session.session_id),
+                session=session,
+            )
+
+        # TODO: trigger
+
+    def fetch_parameter_options(self, session: Session, data: DynamicParameterFetchParameterOptionsRequest):
+        action_instance = self._get_dynamic_parameter_action(session, data)
+        if action_instance is None:
+            raise ValueError(f"Provider `{data.provider}` not found")
+
+        return {
+            "options": action_instance.fetch_parameter_options(data.parameter),
+        }

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/core/runtime.py

@@ -28,6 +28,7 @@ from dify_plugin.core.server.tcp.request_reader import TCPReaderWriter
 class ModelInvocations:
     def __init__(self, session: "Session") -> None:
         from dify_plugin.invocations.model.llm import LLMInvocation, SummaryInvocation
+        from dify_plugin.invocations.model.llm_structured_output import LLMStructuredOutputInvocation
         from dify_plugin.invocations.model.moderation import ModerationInvocation
         from dify_plugin.invocations.model.rerank import RerankInvocation
         from dify_plugin.invocations.model.speech2text import Speech2TextInvocation
@@ -35,6 +36,7 @@ class ModelInvocations:
         from dify_plugin.invocations.model.tts import TTSInvocation
 
         self.llm = LLMInvocation(session)
+        self.llm_structured_output = LLMStructuredOutputInvocation(session)
         self.text_embedding = TextEmbeddingInvocation(session)
         self.rerank = RerankInvocation(session)
         self.speech2text = Speech2TextInvocation(session)

dify_plugin-0.4.0/dify_plugin/entities/__init__.py

@@ -0,0 +1,47 @@
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+from dify_plugin.core.documentation.schema_doc import docs
+
+
+@docs(
+    description="Common i18n object",
+)
+class I18nObject(BaseModel):
+    """
+    Model class for i18n object.
+    """
+
+    zh_Hans: Optional[str] = None
+    pt_BR: Optional[str] = None
+    en_US: str
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        if not self.zh_Hans:
+            self.zh_Hans = self.en_US
+        if not self.pt_BR:
+            self.pt_BR = self.en_US
+
+    def to_dict(self) -> dict:
+        return {"zh_Hans": self.zh_Hans, "en_US": self.en_US, "pt_BR": self.pt_BR}
+
+
+@docs(
+    description="The option of the parameter",
+)
+class ParameterOption(BaseModel):
+    value: str = Field(..., description="The value of the option")
+    label: I18nObject = Field(..., description="The label of the option")
+    icon: Optional[str] = Field(
+        default=None, description="The icon of the option, can be a URL or a base64 encoded string"
+    )
+
+    @field_validator("value", mode="before")
+    @classmethod
+    def transform_id_to_str(cls, value) -> str:
+        if not isinstance(value, str):
+            return str(value)
+        else:
+            return value

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/entities/model/llm.py

@@ -1,3 +1,4 @@
+from collections.abc import Mapping
 from decimal import Decimal
 from enum import Enum
 from typing import Optional
@@ -106,6 +107,22 @@ class LLMResultChunk(BaseModel):
         return []
 
 
+class LLMStructuredOutput(BaseModel):
+    """
+    Model class for llm structured output.
+    """
+
+    structured_output: Optional[Mapping] = None
+
+
+class LLMResultChunkWithStructuredOutput(LLMResultChunk, LLMStructuredOutput):
+    """
+    Model class for llm result chunk with structured output.
+    """
+
+    pass
+
+
 class LLMResult(BaseModel):
     """
     Model class for llm result.
@@ -145,6 +162,25 @@ class LLMResult(BaseModel):
         )
 
 
+class LLMResultWithStructuredOutput(LLMResult, LLMStructuredOutput):
+    """
+    Model class for llm result with structured output.
+    """
+
+    def to_llm_result_chunk_with_structured_output(self) -> "LLMResultChunkWithStructuredOutput":
+        return LLMResultChunkWithStructuredOutput(
+            model=self.model,
+            system_fingerprint=self.system_fingerprint,
+            delta=LLMResultChunkDelta(
+                index=0,
+                message=self.message,
+                usage=self.usage,
+                finish_reason=None,
+            ),
+            structured_output=self.structured_output,
+        )
+
+
 class SummaryResult(BaseModel):
     """
     Model class for summary result.

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/entities/provider_config.py

@@ -37,6 +37,7 @@ class CommonParameterType(Enum):
     # MCP object and array type parameters
     OBJECT = "object"
     ARRAY = "array"
+    DYNAMIC_SELECT = "dynamic-select"
 
 
 @docs(

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/entities/tool.py

@@ -15,7 +15,7 @@ from pydantic import (
 
 from dify_plugin.core.documentation.schema_doc import docs
 from dify_plugin.core.utils.yaml_loader import load_yaml_file
-from dify_plugin.entities import I18nObject
+from dify_plugin.entities import I18nObject, ParameterOption
 from dify_plugin.entities.model.message import PromptMessageTool
 from dify_plugin.entities.oauth import OAuthSchema
 from dify_plugin.entities.provider_config import CommonParameterType, LogMetadata, ProviderConfig
@@ -172,17 +172,8 @@ class ToolIdentity(BaseModel):
 @docs(
     description="The option of the tool parameter",
 )
-class ToolParameterOption(BaseModel):
-    value: str = Field(..., description="The value of the option")
-    label: I18nObject = Field(..., description="The label of the option")
-
-    @field_validator("value", mode="before")
-    @classmethod
-    def transform_id_to_str(cls, value) -> str:
-        if not isinstance(value, str):
-            return str(value)
-        else:
-            return value
+class ToolParameterOption(ParameterOption):
+    pass
 
 
 @docs(
@@ -219,8 +210,9 @@ class ToolParameter(BaseModel):
         # TOOL_SELECTOR = CommonParameterType.TOOL_SELECTOR.value
         ANY = CommonParameterType.ANY.value
         # MCP object and array type parameters
-        OBJECT = "object"
-        ARRAY = "array"
+        OBJECT = CommonParameterType.OBJECT.value
+        ARRAY = CommonParameterType.ARRAY.value
+        DYNAMIC_SELECT = CommonParameterType.DYNAMIC_SELECT.value
 
     class ToolParameterForm(Enum):
         SCHEMA = "schema"  # should be set while adding tool

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/interfaces/agent/__init__.py

@@ -338,10 +338,14 @@ class AgentStrategy(ToolLike[AgentInvokeMessage]):
             if parameter.type == ToolParameter.ToolParameterType.SELECT:
                 enum = [option.value for option in parameter.options] if parameter.options else []
 
-            prompt_tool.parameters["properties"][parameter.name] = {
-                "type": parameter_type,
-                "description": parameter.llm_description or "",
-            }
+            prompt_tool.parameters["properties"][parameter.name] = (
+                {
+                    "type": parameter_type,
+                    "description": parameter.llm_description or "",
+                }
+                if parameter.input_schema is None
+                else parameter.input_schema
+            )
 
             if len(enum) > 0:
                 prompt_tool.parameters["properties"][parameter.name]["enum"] = enum

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/interfaces/model/openai_compatible/llm.py

@@ -203,7 +203,8 @@ class OAICompatLargeLanguageModel(_CommonOaiApiCompat, LargeLanguageModel):
                 response = requests.post(endpoint_url, headers=headers, json=data, timeout=(10, 300), stream=True)
                 if response.status_code != 200:
                     raise CredentialsValidateFailedError(
-                        f"Credentials validation failed with status code {response.status_code}"
+                        f"Credentials validation failed with status code {response.status_code} "
+                        f"and response body {response.text}"
                     )
                 return
 
@@ -212,13 +213,16 @@ class OAICompatLargeLanguageModel(_CommonOaiApiCompat, LargeLanguageModel):
 
             if response.status_code != 200:
                 raise CredentialsValidateFailedError(
-                    f"Credentials validation failed with status code {response.status_code}"
+                    f"Credentials validation failed with status code {response.status_code} "
+                    f"and response body {response.text}"
                 )
 
             try:
                 json_result = response.json()
             except json.JSONDecodeError:
-                raise CredentialsValidateFailedError("Credentials validation failed: JSON decode error") from None
+                raise CredentialsValidateFailedError(
+                    f"Credentials validation failed: JSON decode error, response body {response.text}"
+                ) from None
 
             if completion_type is LLMMode.CHAT and json_result.get("object", "") == "":
                 json_result["object"] = "chat.completion"
@@ -229,18 +233,22 @@ class OAICompatLargeLanguageModel(_CommonOaiApiCompat, LargeLanguageModel):
                 "object" not in json_result or json_result["object"] != "chat.completion"
             ):
                 raise CredentialsValidateFailedError(
-                    "Credentials validation failed: invalid response object, must be 'chat.completion'"
+                    f"Credentials validation failed: invalid response object, "
+                    f"must be 'chat.completion', response body {response.text}"
                 )
             elif completion_type is LLMMode.COMPLETION and (
                 "object" not in json_result or json_result["object"] != "text_completion"
             ):
                 raise CredentialsValidateFailedError(
-                    "Credentials validation failed: invalid response object, must be 'text_completion'"
+                    f"Credentials validation failed: invalid response object, "
+                    f"must be 'text_completion', response body {response.text}"
                 )
         except CredentialsValidateFailedError:
             raise
         except Exception as ex:
-            raise CredentialsValidateFailedError(f"An error occurred during credentials validation: {ex!s}") from ex
+            raise CredentialsValidateFailedError(
+                f"An error occurred during credentials validation: {ex!s}, response body {response.text}"
+            ) from ex
 
     def get_customizable_model_schema(self, model: str, credentials: dict) -> AIModelEntity:
         """

{dify_plugin-0.3.4 → dify_plugin-0.4.0}/dify_plugin/interfaces/tool/__init__.py

@@ -2,9 +2,11 @@ from abc import ABC, abstractmethod
 from collections.abc import Generator, Mapping
 from typing import Any, Generic, Optional, TypeVar, final
 
+from typing_extensions import deprecated
 from werkzeug import Request
 
 from dify_plugin.core.runtime import Session
+from dify_plugin.entities import ParameterOption
 from dify_plugin.entities.agent import AgentInvokeMessage
 from dify_plugin.entities.tool import LogMetadata, ToolInvokeMessage, ToolParameter, ToolRuntime, ToolSelector
 from dify_plugin.file.constants import DIFY_FILE_IDENTITY, DIFY_TOOL_SELECTOR_IDENTITY
@@ -167,6 +169,7 @@ class ToolLike(ABC, Generic[T]):
             ),
         )
 
+    @deprecated("This feature is deprecated, will soon be replaced by dynamic select parameter")
     def _get_runtime_parameters(self) -> list[ToolParameter]:
         """
         get the runtime parameters of the tool
@@ -229,19 +232,21 @@ class ToolProvider:
         return self._validate_credentials(credentials)
 
     def _validate_credentials(self, credentials: dict):
-        raise NotImplementedError("This method should be implemented by a subclass")
+        raise NotImplementedError(
+            "This plugin should implement `_validate_credentials` method to enable credentials validation"
+        )
 
     def oauth_get_authorization_url(self, system_credentials: Mapping[str, Any]) -> str:
         return self._oauth_get_authorization_url(system_credentials)
 
     def _oauth_get_authorization_url(self, system_credentials: Mapping[str, Any]) -> str:
-        raise NotImplementedError("This method should be implemented by a subclass")
+        raise NotImplementedError("This plugin should implement `_oauth_get_authorization_url` method to enable oauth")
 
     def oauth_get_credentials(self, system_credentials: Mapping[str, Any], request: Request) -> Mapping[str, Any]:
         return self._oauth_get_credentials(system_credentials, request)
 
     def _oauth_get_credentials(self, system_credentials: Mapping[str, Any], request: Request) -> Mapping[str, Any]:
-        raise NotImplementedError("This method should be implemented by a subclass")
+        raise NotImplementedError("This plugin should implement `_oauth_get_credentials` method to enable oauth")
 
 
 class Tool(ToolLike[ToolInvokeMessage]):
@@ -283,6 +288,18 @@ class Tool(ToolLike[ToolInvokeMessage]):
     def _invoke(self, tool_parameters: dict) -> Generator[ToolInvokeMessage, None, None]:
         pass
 
+    def _fetch_parameter_options(self, parameter: str) -> list[ParameterOption]:
+        """
+        Fetch the parameter options of the tool.
+
+        To be implemented by subclasses.
+
+        Also, it's optional to implement, that's why it's not an abstract method.
+        """
+        raise NotImplementedError(
+            "This plugin should implement `_fetch_parameter_options` method to enable dynamic select parameter"
+        )
+
     ############################################################
     #                 For executor use only                    #
     ############################################################
@@ -292,5 +309,15 @@ class Tool(ToolLike[ToolInvokeMessage]):
         tool_parameters = self._convert_parameters(tool_parameters)
         return self._invoke(tool_parameters)
 
+    @deprecated("This feature is deprecated, will soon be replaced by dynamic select parameter")
     def get_runtime_parameters(self) -> list[ToolParameter]:
         return self._get_runtime_parameters()
+
+    def fetch_parameter_options(self, parameter: str) -> list[ParameterOption]:
+        """
+        Fetch the parameter options of the tool.
+
+        To be implemented by subclasses.
+
+        """
+        return self._fetch_parameter_options(parameter)

dify_plugin-0.4.0/dify_plugin/interfaces/trigger/__init__.py

@@ -0,0 +1,99 @@
+from abc import ABC, abstractmethod
+from collections.abc import Mapping
+from typing import Any, final
+
+from werkzeug import Request
+
+from dify_plugin.core.runtime import Session
+from dify_plugin.entities import ParameterOption
+from dify_plugin.entities.trigger import TriggerResponse, TriggerRuntime
+
+
+class TriggerProvider:
+    """
+    The provider of a trigger
+    """
+
+    def validate_credentials(self, credentials: dict):
+        return self._validate_credentials(credentials)
+
+    def _validate_credentials(self, credentials: dict):
+        raise NotImplementedError(
+            "This plugin should implement `_validate_credentials` method to enable credentials validation"
+        )
+
+    def oauth_get_authorization_url(self, system_credentials: Mapping[str, Any]) -> str:
+        return self._oauth_get_authorization_url(system_credentials)
+
+    def _oauth_get_authorization_url(self, system_credentials: Mapping[str, Any]) -> str:
+        raise NotImplementedError("This plugin should implement `_oauth_get_authorization_url` method to enable oauth")
+
+    def oauth_get_credentials(self, system_credentials: Mapping[str, Any], request: Request) -> Mapping[str, Any]:
+        return self._oauth_get_credentials(system_credentials, request)
+
+    def _oauth_get_credentials(self, system_credentials: Mapping[str, Any], request: Request) -> Mapping[str, Any]:
+        raise NotImplementedError("This plugin should implement `_oauth_get_credentials` method to enable oauth")
+
+
+class Trigger(ABC):
+    """
+    The trigger interface
+    """
+
+    runtime: TriggerRuntime
+    session: Session
+
+    @final
+    def __init__(
+        self,
+        runtime: TriggerRuntime,
+        session: Session,
+    ):
+        """
+        Initialize the trigger
+
+        NOTE:
+        - This method has been marked as final, DO NOT OVERRIDE IT.
+        """
+        self.runtime = runtime
+        self.session = session
+
+    ############################################################
+    #        Methods that can be implemented by plugin         #
+    ############################################################
+
+    @abstractmethod
+    def _trigger(self, request: Request, values: Mapping, parameters: Mapping) -> TriggerResponse:
+        """
+        Trigger the trigger with the given request.
+
+        To be implemented by subclasses.
+        """
+
+    def _fetch_parameter_options(self, parameter: str) -> list[ParameterOption]:
+        """
+        Fetch the parameter options of the trigger.
+
+        To be implemented by subclasses.
+
+        Also, it's optional to implement, that's why it's not an abstract method.
+        """
+        raise NotImplementedError(
+            "This plugin should implement `_fetch_parameter_options` method to enable dynamic select parameter"
+        )
+
+    ############################################################
+    #                 For executor use only                    #
+    ############################################################
+
+    def trigger(self, request: Request, values: Mapping, parameters: Mapping) -> TriggerResponse:
+        """
+        Trigger the trigger with the given request.
+        """
+        return self._trigger(request, values, parameters)
+
+    def fetch_parameter_options(self, parameter: str) -> list[ParameterOption]:
+        """
+        Fetch the parameter options of the trigger.
+        """
+        return self._fetch_parameter_options(parameter)