refactor: refactor python sdk (#28118)

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

sdks/python-client/dify_client/base_client.py

@@ -0,0 +1,228 @@
+"""Base client with common functionality for both sync and async clients."""
+
+import json
+import time
+import logging
+from typing import Dict, Callable, Optional
+
+try:
+    # Python 3.10+
+    from typing import ParamSpec
+except ImportError:
+    # Python < 3.10
+    from typing_extensions import ParamSpec
+
+from urllib.parse import urljoin
+
+import httpx
+
+P = ParamSpec("P")
+
+from .exceptions import (
+    DifyClientError,
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    NetworkError,
+    TimeoutError,
+)
+
+
+class BaseClientMixin:
+    """Mixin class providing common functionality for Dify clients."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.dify.ai/v1",
+        timeout: float = 60.0,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        enable_logging: bool = False,
+    ):
+        """Initialize the base client.
+
+        Args:
+            api_key: Your Dify API key
+            base_url: Base URL for the Dify API
+            timeout: Request timeout in seconds
+            max_retries: Maximum number of retry attempts
+            retry_delay: Delay between retries in seconds
+            enable_logging: Enable detailed logging
+        """
+        if not api_key:
+            raise ValidationError("API key is required")
+
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.retry_delay = retry_delay
+        self.enable_logging = enable_logging
+
+        # Setup logging
+        self.logger = logging.getLogger(f"dify_client.{self.__class__.__name__.lower()}")
+        if enable_logging and not self.logger.handlers:
+            # Create console handler with formatter
+            handler = logging.StreamHandler()
+            formatter = logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+            handler.setFormatter(formatter)
+            self.logger.addHandler(handler)
+            self.logger.setLevel(logging.INFO)
+            self.enable_logging = True
+        else:
+            self.enable_logging = enable_logging
+
+    def _get_headers(self, content_type: str = "application/json") -> Dict[str, str]:
+        """Get common request headers."""
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": content_type,
+            "User-Agent": "dify-client-python/0.1.12",
+        }
+
+    def _build_url(self, endpoint: str) -> str:
+        """Build full URL from endpoint."""
+        return urljoin(self.base_url + "/", endpoint.lstrip("/"))
+
+    def _handle_response(self, response: httpx.Response) -> httpx.Response:
+        """Handle HTTP response and raise appropriate exceptions."""
+        try:
+            if response.status_code == 401:
+                raise AuthenticationError(
+                    "Authentication failed. Check your API key.",
+                    status_code=response.status_code,
+                    response=response.json() if response.content else None,
+                )
+            elif response.status_code == 429:
+                retry_after = response.headers.get("Retry-After")
+                raise RateLimitError(
+                    "Rate limit exceeded. Please try again later.",
+                    retry_after=int(retry_after) if retry_after else None,
+                )
+            elif response.status_code >= 400:
+                try:
+                    error_data = response.json()
+                    message = error_data.get("message", f"HTTP {response.status_code}")
+                except:
+                    message = f"HTTP {response.status_code}: {response.text}"
+
+                raise APIError(
+                    message,
+                    status_code=response.status_code,
+                    response=response.json() if response.content else None,
+                )
+
+            return response
+
+        except json.JSONDecodeError:
+            raise APIError(
+                f"Invalid JSON response: {response.text}",
+                status_code=response.status_code,
+            )
+
+    def _retry_request(
+        self,
+        request_func: Callable[P, httpx.Response],
+        request_context: str | None = None,
+        *args: P.args,
+        **kwargs: P.kwargs,
+    ) -> httpx.Response:
+        """Retry a request with exponential backoff.
+
+        Args:
+            request_func: Function that performs the HTTP request
+            request_context: Context description for logging (e.g., "GET /v1/messages")
+            *args: Positional arguments to pass to request_func
+            **kwargs: Keyword arguments to pass to request_func
+
+        Returns:
+            httpx.Response: Successful response
+
+        Raises:
+            NetworkError: On network failures after retries
+            TimeoutError: On timeout failures after retries
+            APIError: On API errors (4xx/5xx responses)
+            DifyClientError: On unexpected failures
+        """
+        last_exception = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = request_func(*args, **kwargs)
+                return response  # Let caller handle response processing
+
+            except (httpx.NetworkError, httpx.TimeoutException) as e:
+                last_exception = e
+                context_msg = f" {request_context}" if request_context else ""
+
+                if attempt < self.max_retries:
+                    delay = self.retry_delay * (2**attempt)  # Exponential backoff
+                    self.logger.warning(
+                        f"Request failed{context_msg} (attempt {attempt + 1}/{self.max_retries + 1}): {e}. "
+                        f"Retrying in {delay:.2f} seconds..."
+                    )
+                    time.sleep(delay)
+                else:
+                    self.logger.error(f"Request failed{context_msg} after {self.max_retries + 1} attempts: {e}")
+                    # Convert to custom exceptions
+                    if isinstance(e, httpx.TimeoutException):
+                        from .exceptions import TimeoutError
+
+                        raise TimeoutError(f"Request timed out after {self.max_retries} retries{context_msg}") from e
+                    else:
+                        from .exceptions import NetworkError
+
+                        raise NetworkError(
+                            f"Network error after {self.max_retries} retries{context_msg}: {str(e)}"
+                        ) from e
+
+        if last_exception:
+            raise last_exception
+        raise DifyClientError("Request failed after retries")
+
+    def _validate_params(self, **params) -> None:
+        """Validate request parameters."""
+        for key, value in params.items():
+            if value is None:
+                continue
+
+            # String validations
+            if isinstance(value, str):
+                if not value.strip():
+                    raise ValidationError(f"Parameter '{key}' cannot be empty or whitespace only")
+                if len(value) > 10000:
+                    raise ValidationError(f"Parameter '{key}' exceeds maximum length of 10000 characters")
+
+            # List validations
+            elif isinstance(value, list):
+                if len(value) > 1000:
+                    raise ValidationError(f"Parameter '{key}' exceeds maximum size of 1000 items")
+
+            # Dictionary validations
+            elif isinstance(value, dict):
+                if len(value) > 100:
+                    raise ValidationError(f"Parameter '{key}' exceeds maximum size of 100 items")
+
+            # Type-specific validations
+            if key == "user" and not isinstance(value, str):
+                raise ValidationError(f"Parameter '{key}' must be a string")
+            elif key in ["page", "limit", "page_size"] and not isinstance(value, int):
+                raise ValidationError(f"Parameter '{key}' must be an integer")
+            elif key == "files" and not isinstance(value, (list, dict)):
+                raise ValidationError(f"Parameter '{key}' must be a list or dict")
+            elif key == "rating" and value not in ["like", "dislike"]:
+                raise ValidationError(f"Parameter '{key}' must be 'like' or 'dislike'")
+
+    def _log_request(self, method: str, url: str, **kwargs) -> None:
+        """Log request details."""
+        self.logger.info(f"Making {method} request to {url}")
+        if kwargs.get("json"):
+            self.logger.debug(f"Request body: {kwargs['json']}")
+        if kwargs.get("params"):
+            self.logger.debug(f"Query params: {kwargs['params']}")
+
+    def _log_response(self, response: httpx.Response) -> None:
+        """Log response details."""
+        self.logger.info(f"Received response: {response.status_code} ({len(response.content)} bytes)")

sdks/python-client/dify_client/client.py

@@ -1,11 +1,20 @@
 import json
+import logging
 import os
-from typing import Literal, Dict, List, Any, IO
+from typing import Literal, Dict, List, Any, IO, Optional, Union
 
 import httpx
+from .base_client import BaseClientMixin
+from .exceptions import (
+    APIError,
+    AuthenticationError,
+    RateLimitError,
+    ValidationError,
+    FileUploadError,
+)
 
 
-class DifyClient:
+class DifyClient(BaseClientMixin):
     """Synchronous Dify API client.
 
     This client uses httpx.Client for efficient connection pooling and resource management.
@@ -21,6 +30,9 @@ class DifyClient:
         api_key: str,
         base_url: str = "https://api.dify.ai/v1",
         timeout: float = 60.0,
+        max_retries: int = 3,
+        retry_delay: float = 1.0,
+        enable_logging: bool = False,
     ):
         """Initialize the Dify client.
 
@@ -28,9 +40,13 @@ class DifyClient:
             api_key: Your Dify API key
             base_url: Base URL for the Dify API
             timeout: Request timeout in seconds (default: 60.0)
+            max_retries: Maximum number of retry attempts (default: 3)
+            retry_delay: Delay between retries in seconds (default: 1.0)
+            enable_logging: Whether to enable request logging (default: True)
         """
-        self.api_key = api_key
-        self.base_url = base_url
+        # Initialize base client functionality
+        BaseClientMixin.__init__(self, api_key, base_url, timeout, max_retries, retry_delay, enable_logging)
+
         self._client = httpx.Client(
             base_url=base_url,
             timeout=httpx.Timeout(timeout, connect=5.0),
@@ -53,12 +69,12 @@ class DifyClient:
         self,
         method: str,
         endpoint: str,
-        json: dict | None = None,
-        params: dict | None = None,
+        json: Dict[str, Any] | None = None,
+        params: Dict[str, Any] | None = None,
         stream: bool = False,
         **kwargs,
     ):
-        """Send an HTTP request to the Dify API.
+        """Send an HTTP request to the Dify API with retry logic.
 
         Args:
             method: HTTP method (GET, POST, PUT, PATCH, DELETE)
@@ -71,23 +87,91 @@ class DifyClient:
         Returns:
             httpx.Response object
         """
+        # Validate parameters
+        if json:
+            self._validate_params(**json)
+        if params:
+            self._validate_params(**params)
+
         headers = {
             "Authorization": f"Bearer {self.api_key}",
             "Content-Type": "application/json",
         }
 
-        # httpx.Client automatically prepends base_url
-        response = self._client.request(
-            method,
-            endpoint,
-            json=json,
-            params=params,
-            headers=headers,
-            **kwargs,
-        )
+        def make_request():
+            """Inner function to perform the actual HTTP request."""
+            # Log request if logging is enabled
+            if self.enable_logging:
+                self.logger.info(f"Sending {method} request to {endpoint}")
+                # Debug logging for detailed information
+                if self.logger.isEnabledFor(logging.DEBUG):
+                    if json:
+                        self.logger.debug(f"Request body: {json}")
+                    if params:
+                        self.logger.debug(f"Request params: {params}")
+
+            # httpx.Client automatically prepends base_url
+            response = self._client.request(
+                method,
+                endpoint,
+                json=json,
+                params=params,
+                headers=headers,
+                **kwargs,
+            )
+
+            # Log response if logging is enabled
+            if self.enable_logging:
+                self.logger.info(f"Received response: {response.status_code}")
+
+            return response
+
+        # Use the retry mechanism from base client
+        request_context = f"{method} {endpoint}"
+        response = self._retry_request(make_request, request_context)
+
+        # Handle error responses (API errors don't retry)
+        self._handle_error_response(response)
 
         return response
 
+    def _handle_error_response(self, response, is_upload_request: bool = False) -> None:
+        """Handle HTTP error responses and raise appropriate exceptions."""
+
+        if response.status_code < 400:
+            return  # Success response
+
+        try:
+            error_data = response.json()
+            message = error_data.get("message", f"HTTP {response.status_code}")
+        except (ValueError, KeyError):
+            message = f"HTTP {response.status_code}"
+            error_data = None
+
+        # Log error response if logging is enabled
+        if self.enable_logging:
+            self.logger.error(f"API error: {response.status_code} - {message}")
+
+        if response.status_code == 401:
+            raise AuthenticationError(message, response.status_code, error_data)
+        elif response.status_code == 429:
+            retry_after = response.headers.get("Retry-After")
+            raise RateLimitError(message, retry_after)
+        elif response.status_code == 422:
+            raise ValidationError(message, response.status_code, error_data)
+        elif response.status_code == 400:
+            # Check if this is a file upload error based on the URL or context
+            current_url = getattr(response, "url", "") or ""
+            if is_upload_request or "upload" in str(current_url).lower() or "files" in str(current_url).lower():
+                raise FileUploadError(message, response.status_code, error_data)
+            else:
+                raise APIError(message, response.status_code, error_data)
+        elif response.status_code >= 500:
+            # Server errors should raise APIError
+            raise APIError(message, response.status_code, error_data)
+        elif response.status_code >= 400:
+            raise APIError(message, response.status_code, error_data)
+
     def _send_request_with_files(self, method: str, endpoint: str, data: dict, files: dict):
         """Send an HTTP request with file uploads.
 
@@ -102,6 +186,12 @@ class DifyClient:
         """
         headers = {"Authorization": f"Bearer {self.api_key}"}
 
+        # Log file upload request if logging is enabled
+        if self.enable_logging:
+            self.logger.info(f"Sending {method} file upload request to {endpoint}")
+            self.logger.debug(f"Form data: {data}")
+            self.logger.debug(f"Files: {files}")
+
         response = self._client.request(
             method,
             endpoint,
@@ -110,9 +200,17 @@ class DifyClient:
             files=files,
         )
 
+        # Log response if logging is enabled
+        if self.enable_logging:
+            self.logger.info(f"Received file upload response: {response.status_code}")
+
+        # Handle error responses
+        self._handle_error_response(response, is_upload_request=True)
+
         return response
 
     def message_feedback(self, message_id: str, rating: Literal["like", "dislike"], user: str):
+        self._validate_params(message_id=message_id, rating=rating, user=user)
         data = {"rating": rating, "user": user}
         return self._send_request("POST", f"/messages/{message_id}/feedbacks", data)
 
@@ -144,6 +242,72 @@ class DifyClient:
         """Get file preview by file ID."""
         return self._send_request("GET", f"/files/{file_id}/preview")
 
+    # App Configuration APIs
+    def get_app_site_config(self, app_id: str):
+        """Get app site configuration.
+
+        Args:
+            app_id: ID of the app
+
+        Returns:
+            App site configuration
+        """
+        url = f"/apps/{app_id}/site/config"
+        return self._send_request("GET", url)
+
+    def update_app_site_config(self, app_id: str, config_data: Dict[str, Any]):
+        """Update app site configuration.
+
+        Args:
+            app_id: ID of the app
+            config_data: Configuration data to update
+
+        Returns:
+            Updated app site configuration
+        """
+        url = f"/apps/{app_id}/site/config"
+        return self._send_request("PUT", url, json=config_data)
+
+    def get_app_api_tokens(self, app_id: str):
+        """Get API tokens for an app.
+
+        Args:
+            app_id: ID of the app
+
+        Returns:
+            List of API tokens
+        """
+        url = f"/apps/{app_id}/api-tokens"
+        return self._send_request("GET", url)
+
+    def create_app_api_token(self, app_id: str, name: str, description: str | None = None):
+        """Create a new API token for an app.
+
+        Args:
+            app_id: ID of the app
+            name: Name for the API token
+            description: Description for the API token (optional)
+
+        Returns:
+            Created API token information
+        """
+        data = {"name": name, "description": description}
+        url = f"/apps/{app_id}/api-tokens"
+        return self._send_request("POST", url, json=data)
+
+    def delete_app_api_token(self, app_id: str, token_id: str):
+        """Delete an API token.
+
+        Args:
+            app_id: ID of the app
+            token_id: ID of the token to delete
+
+        Returns:
+            Deletion result
+        """
+        url = f"/apps/{app_id}/api-tokens/{token_id}"
+        return self._send_request("DELETE", url)
+
 
 class CompletionClient(DifyClient):
     def create_completion_message(
@@ -151,8 +315,16 @@ class CompletionClient(DifyClient):
         inputs: dict,
         response_mode: Literal["blocking", "streaming"],
         user: str,
-        files: dict | None = None,
+        files: Dict[str, Any] | None = None,
     ):
+        # Validate parameters
+        if not isinstance(inputs, dict):
+            raise ValidationError("inputs must be a dictionary")
+        if response_mode not in ["blocking", "streaming"]:
+            raise ValidationError("response_mode must be 'blocking' or 'streaming'")
+
+        self._validate_params(inputs=inputs, response_mode=response_mode, user=user)
+
         data = {
             "inputs": inputs,
             "response_mode": response_mode,
@@ -175,8 +347,18 @@ class ChatClient(DifyClient):
         user: str,
         response_mode: Literal["blocking", "streaming"] = "blocking",
         conversation_id: str | None = None,
-        files: dict | None = None,
+        files: Dict[str, Any] | None = None,
     ):
+        # Validate parameters
+        if not isinstance(inputs, dict):
+            raise ValidationError("inputs must be a dictionary")
+        if not isinstance(query, str) or not query.strip():
+            raise ValidationError("query must be a non-empty string")
+        if response_mode not in ["blocking", "streaming"]:
+            raise ValidationError("response_mode must be 'blocking' or 'streaming'")
+
+        self._validate_params(inputs=inputs, query=query, user=user, response_mode=response_mode)
+
         data = {
             "inputs": inputs,
             "query": query,
@@ -238,7 +420,7 @@ class ChatClient(DifyClient):
         data = {"user": user}
         return self._send_request("DELETE", f"/conversations/{conversation_id}", data)
 
-    def audio_to_text(self, audio_file: IO[bytes] | tuple, user: str):
+    def audio_to_text(self, audio_file: Union[IO[bytes], tuple], user: str):
         data = {"user": user}
         files = {"file": audio_file}
         return self._send_request_with_files("POST", "/audio-to-text", data, files)
@@ -313,7 +495,48 @@ class ChatClient(DifyClient):
         """
         data = {"value": value, "user": user}
         url = f"/conversations/{conversation_id}/variables/{variable_id}"
-        return self._send_request("PATCH", url, json=data)
+        return self._send_request("PUT", url, json=data)
+
+    def delete_annotation_with_response(self, annotation_id: str):
+        """Delete an annotation with full response handling."""
+        url = f"/apps/annotations/{annotation_id}"
+        return self._send_request("DELETE", url)
+
+    def list_conversation_variables_with_pagination(
+        self, conversation_id: str, user: str, page: int = 1, limit: int = 20
+    ):
+        """List conversation variables with pagination."""
+        params = {"page": page, "limit": limit, "user": user}
+        url = f"/conversations/{conversation_id}/variables"
+        return self._send_request("GET", url, params=params)
+
+    def update_conversation_variable_with_response(self, conversation_id: str, variable_id: str, user: str, value: Any):
+        """Update a conversation variable with full response handling."""
+        data = {"value": value, "user": user}
+        url = f"/conversations/{conversation_id}/variables/{variable_id}"
+        return self._send_request("PUT", url, json=data)
+
+    # Enhanced Annotation APIs
+    def get_annotation_reply_job_status(self, action: str, job_id: str):
+        """Get status of an annotation reply action job."""
+        url = f"/apps/annotation-reply/{action}/status/{job_id}"
+        return self._send_request("GET", url)
+
+    def list_annotations_with_pagination(self, page: int = 1, limit: int = 20, keyword: str | None = None):
+        """List annotations with pagination."""
+        params = {"page": page, "limit": limit, "keyword": keyword}
+        return self._send_request("GET", "/apps/annotations", params=params)
+
+    def create_annotation_with_response(self, question: str, answer: str):
+        """Create an annotation with full response handling."""
+        data = {"question": question, "answer": answer}
+        return self._send_request("POST", "/apps/annotations", json=data)
+
+    def update_annotation_with_response(self, annotation_id: str, question: str, answer: str):
+        """Update an annotation with full response handling."""
+        data = {"question": question, "answer": answer}
+        url = f"/apps/annotations/{annotation_id}"
+        return self._send_request("PUT", url, json=data)
 
 
 class WorkflowClient(DifyClient):
@@ -376,6 +599,68 @@ class WorkflowClient(DifyClient):
             stream=(response_mode == "streaming"),
         )
 
+    # Enhanced Workflow APIs
+    def get_workflow_draft(self, app_id: str):
+        """Get workflow draft configuration.
+
+        Args:
+            app_id: ID of the workflow app
+
+        Returns:
+            Workflow draft configuration
+        """
+        url = f"/apps/{app_id}/workflow/draft"
+        return self._send_request("GET", url)
+
+    def update_workflow_draft(self, app_id: str, workflow_data: Dict[str, Any]):
+        """Update workflow draft configuration.
+
+        Args:
+            app_id: ID of the workflow app
+            workflow_data: Workflow configuration data
+
+        Returns:
+            Updated workflow draft
+        """
+        url = f"/apps/{app_id}/workflow/draft"
+        return self._send_request("PUT", url, json=workflow_data)
+
+    def publish_workflow(self, app_id: str):
+        """Publish workflow from draft.
+
+        Args:
+            app_id: ID of the workflow app
+
+        Returns:
+            Published workflow information
+        """
+        url = f"/apps/{app_id}/workflow/publish"
+        return self._send_request("POST", url)
+
+    def get_workflow_run_history(
+        self,
+        app_id: str,
+        page: int = 1,
+        limit: int = 20,
+        status: Literal["succeeded", "failed", "stopped"] | None = None,
+    ):
+        """Get workflow run history.
+
+        Args:
+            app_id: ID of the workflow app
+            page: Page number (default: 1)
+            limit: Number of items per page (default: 20)
+            status: Filter by status (optional)
+
+        Returns:
+            Paginated workflow run history
+        """
+        params = {"page": page, "limit": limit}
+        if status:
+            params["status"] = status
+        url = f"/apps/{app_id}/workflow/runs"
+        return self._send_request("GET", url, params=params)
+
 
 class WorkspaceClient(DifyClient):
     """Client for workspace-related operations."""
@@ -385,6 +670,41 @@ class WorkspaceClient(DifyClient):
         url = f"/workspaces/current/models/model-types/{model_type}"
         return self._send_request("GET", url)
 
+    def get_available_models_by_type(self, model_type: str):
+        """Get available models by model type (enhanced version)."""
+        url = f"/workspaces/current/models/model-types/{model_type}"
+        return self._send_request("GET", url)
+
+    def get_model_providers(self):
+        """Get all model providers."""
+        return self._send_request("GET", "/workspaces/current/model-providers")
+
+    def get_model_provider_models(self, provider_name: str):
+        """Get models for a specific provider."""
+        url = f"/workspaces/current/model-providers/{provider_name}/models"
+        return self._send_request("GET", url)
+
+    def validate_model_provider_credentials(self, provider_name: str, credentials: Dict[str, Any]):
+        """Validate model provider credentials."""
+        url = f"/workspaces/current/model-providers/{provider_name}/credentials/validate"
+        return self._send_request("POST", url, json=credentials)
+
+    # File Management APIs
+    def get_file_info(self, file_id: str):
+        """Get information about a specific file."""
+        url = f"/files/{file_id}/info"
+        return self._send_request("GET", url)
+
+    def get_file_download_url(self, file_id: str):
+        """Get download URL for a file."""
+        url = f"/files/{file_id}/download-url"
+        return self._send_request("GET", url)
+
+    def delete_file(self, file_id: str):
+        """Delete a file."""
+        url = f"/files/{file_id}"
+        return self._send_request("DELETE", url)
+
 
 class KnowledgeBaseClient(DifyClient):
     def __init__(
@@ -416,7 +736,7 @@ class KnowledgeBaseClient(DifyClient):
     def list_datasets(self, page: int = 1, page_size: int = 20, **kwargs):
         return self._send_request("GET", "/datasets", params={"page": page, "limit": page_size}, **kwargs)
 
-    def create_document_by_text(self, name, text, extra_params: dict | None = None, **kwargs):
+    def create_document_by_text(self, name, text, extra_params: Dict[str, Any] | None = None, **kwargs):
         """
         Create a document by text.
 
@@ -458,7 +778,7 @@ class KnowledgeBaseClient(DifyClient):
         document_id: str,
         name: str,
         text: str,
-        extra_params: dict | None = None,
+        extra_params: Dict[str, Any] | None = None,
         **kwargs,
     ):
         """
@@ -497,7 +817,7 @@ class KnowledgeBaseClient(DifyClient):
         self,
         file_path: str,
         original_document_id: str | None = None,
-        extra_params: dict | None = None,
+        extra_params: Dict[str, Any] | None = None,
     ):
         """
         Create a document by file.
@@ -537,7 +857,12 @@ class KnowledgeBaseClient(DifyClient):
             url = f"/datasets/{self._get_dataset_id()}/document/create_by_file"
             return self._send_request_with_files("POST", url, {"data": json.dumps(data)}, files)
 
-    def update_document_by_file(self, document_id: str, file_path: str, extra_params: dict | None = None):
+    def update_document_by_file(
+        self,
+        document_id: str,
+        file_path: str,
+        extra_params: Dict[str, Any] | None = None,
+    ):
         """
         Update a document by file.
 
@@ -893,3 +1218,50 @@ class KnowledgeBaseClient(DifyClient):
         url = f"/datasets/{ds_id}/documents/status/{action}"
         data = {"document_ids": document_ids}
         return self._send_request("PATCH", url, json=data)
+
+    # Enhanced Dataset APIs
+    def create_dataset_from_template(self, template_name: str, name: str, description: str | None = None):
+        """Create a dataset from a predefined template.
+
+        Args:
+            template_name: Name of the template to use
+            name: Name for the new dataset
+            description: Description for the dataset (optional)
+
+        Returns:
+            Created dataset information
+        """
+        data = {
+            "template_name": template_name,
+            "name": name,
+            "description": description,
+        }
+        return self._send_request("POST", "/datasets/from-template", json=data)
+
+    def duplicate_dataset(self, dataset_id: str, name: str):
+        """Duplicate an existing dataset.
+
+        Args:
+            dataset_id: ID of dataset to duplicate
+            name: Name for duplicated dataset
+
+        Returns:
+            New dataset information
+        """
+        data = {"name": name}
+        url = f"/datasets/{dataset_id}/duplicate"
+        return self._send_request("POST", url, json=data)
+
+    def list_conversation_variables_with_pagination(
+        self, conversation_id: str, user: str, page: int = 1, limit: int = 20
+    ):
+        """List conversation variables with pagination."""
+        params = {"page": page, "limit": limit, "user": user}
+        url = f"/conversations/{conversation_id}/variables"
+        return self._send_request("GET", url, params=params)
+
+    def update_conversation_variable_with_response(self, conversation_id: str, variable_id: str, user: str, value: Any):
+        """Update a conversation variable with full response handling."""
+        data = {"value": value, "user": user}
+        url = f"/conversations/{conversation_id}/variables/{variable_id}"
+        return self._send_request("PUT", url, json=data)

sdks/python-client/dify_client/exceptions.py

@@ -0,0 +1,71 @@
+"""Custom exceptions for the Dify client."""
+
+from typing import Optional, Dict, Any
+
+
+class DifyClientError(Exception):
+    """Base exception for all Dify client errors."""
+
+    def __init__(self, message: str, status_code: int | None = None, response: Dict[str, Any] | None = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response
+
+
+class APIError(DifyClientError):
+    """Raised when the API returns an error response."""
+
+    def __init__(self, message: str, status_code: int, response: Dict[str, Any] | None = None):
+        super().__init__(message, status_code, response)
+        self.status_code = status_code
+
+
+class AuthenticationError(DifyClientError):
+    """Raised when authentication fails."""
+
+    pass
+
+
+class RateLimitError(DifyClientError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded", retry_after: int | None = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+
+
+class ValidationError(DifyClientError):
+    """Raised when request validation fails."""
+
+    pass
+
+
+class NetworkError(DifyClientError):
+    """Raised when network-related errors occur."""
+
+    pass
+
+
+class TimeoutError(DifyClientError):
+    """Raised when request times out."""
+
+    pass
+
+
+class FileUploadError(DifyClientError):
+    """Raised when file upload fails."""
+
+    pass
+
+
+class DatasetError(DifyClientError):
+    """Raised when dataset operations fail."""
+
+    pass
+
+
+class WorkflowError(DifyClientError):
+    """Raised when workflow operations fail."""
+
+    pass

sdks/python-client/dify_client/models.py

@@ -0,0 +1,396 @@
+"""Response models for the Dify client with proper type hints."""
+
+from typing import Optional, List, Dict, Any, Literal, Union
+from dataclasses import dataclass, field
+from datetime import datetime
+
+
+@dataclass
+class BaseResponse:
+    """Base response model."""
+
+    success: bool = True
+    message: str | None = None
+
+
+@dataclass
+class ErrorResponse(BaseResponse):
+    """Error response model."""
+
+    error_code: str | None = None
+    details: Dict[str, Any] | None = None
+    success: bool = False
+
+
+@dataclass
+class FileInfo:
+    """File information model."""
+
+    id: str
+    name: str
+    size: int
+    mime_type: str
+    url: str | None = None
+    created_at: datetime | None = None
+
+
+@dataclass
+class MessageResponse(BaseResponse):
+    """Message response model."""
+
+    id: str = ""
+    answer: str = ""
+    conversation_id: str | None = None
+    created_at: int | None = None
+    metadata: Dict[str, Any] | None = None
+    files: List[Dict[str, Any]] | None = None
+
+
+@dataclass
+class ConversationResponse(BaseResponse):
+    """Conversation response model."""
+
+    id: str = ""
+    name: str = ""
+    inputs: Dict[str, Any] | None = None
+    status: str | None = None
+    created_at: int | None = None
+    updated_at: int | None = None
+
+
+@dataclass
+class DatasetResponse(BaseResponse):
+    """Dataset response model."""
+
+    id: str = ""
+    name: str = ""
+    description: str | None = None
+    permission: str | None = None
+    indexing_technique: str | None = None
+    embedding_model: str | None = None
+    embedding_model_provider: str | None = None
+    retrieval_model: Dict[str, Any] | None = None
+    document_count: int | None = None
+    word_count: int | None = None
+    app_count: int | None = None
+    created_at: int | None = None
+    updated_at: int | None = None
+
+
+@dataclass
+class DocumentResponse(BaseResponse):
+    """Document response model."""
+
+    id: str = ""
+    name: str = ""
+    data_source_type: str | None = None
+    data_source_info: Dict[str, Any] | None = None
+    dataset_process_rule_id: str | None = None
+    batch: str | None = None
+    position: int | None = None
+    enabled: bool | None = None
+    disabled_at: float | None = None
+    disabled_by: str | None = None
+    archived: bool | None = None
+    archived_reason: str | None = None
+    archived_at: float | None = None
+    archived_by: str | None = None
+    word_count: int | None = None
+    hit_count: int | None = None
+    doc_form: str | None = None
+    doc_metadata: Dict[str, Any] | None = None
+    created_at: float | None = None
+    updated_at: float | None = None
+    indexing_status: str | None = None
+    completed_at: float | None = None
+    paused_at: float | None = None
+    error: str | None = None
+    stopped_at: float | None = None
+
+
+@dataclass
+class DocumentSegmentResponse(BaseResponse):
+    """Document segment response model."""
+
+    id: str = ""
+    position: int | None = None
+    document_id: str | None = None
+    content: str | None = None
+    answer: str | None = None
+    word_count: int | None = None
+    tokens: int | None = None
+    keywords: List[str] | None = None
+    index_node_id: str | None = None
+    index_node_hash: str | None = None
+    hit_count: int | None = None
+    enabled: bool | None = None
+    disabled_at: float | None = None
+    disabled_by: str | None = None
+    status: str | None = None
+    created_by: str | None = None
+    created_at: float | None = None
+    indexing_at: float | None = None
+    completed_at: float | None = None
+    error: str | None = None
+    stopped_at: float | None = None
+
+
+@dataclass
+class WorkflowRunResponse(BaseResponse):
+    """Workflow run response model."""
+
+    id: str = ""
+    workflow_id: str | None = None
+    status: Literal["running", "succeeded", "failed", "stopped"] | None = None
+    inputs: Dict[str, Any] | None = None
+    outputs: Dict[str, Any] | None = None
+    error: str | None = None
+    elapsed_time: float | None = None
+    total_tokens: int | None = None
+    total_steps: int | None = None
+    created_at: float | None = None
+    finished_at: float | None = None
+
+
+@dataclass
+class ApplicationParametersResponse(BaseResponse):
+    """Application parameters response model."""
+
+    opening_statement: str | None = None
+    suggested_questions: List[str] | None = None
+    speech_to_text: Dict[str, Any] | None = None
+    text_to_speech: Dict[str, Any] | None = None
+    retriever_resource: Dict[str, Any] | None = None
+    sensitive_word_avoidance: Dict[str, Any] | None = None
+    file_upload: Dict[str, Any] | None = None
+    system_parameters: Dict[str, Any] | None = None
+    user_input_form: List[Dict[str, Any]] | None = None
+
+
+@dataclass
+class AnnotationResponse(BaseResponse):
+    """Annotation response model."""
+
+    id: str = ""
+    question: str = ""
+    answer: str = ""
+    content: str | None = None
+    created_at: float | None = None
+    updated_at: float | None = None
+    created_by: str | None = None
+    updated_by: str | None = None
+    hit_count: int | None = None
+
+
+@dataclass
+class PaginatedResponse(BaseResponse):
+    """Paginated response model."""
+
+    data: List[Any] = field(default_factory=list)
+    has_more: bool = False
+    limit: int = 0
+    total: int = 0
+    page: int | None = None
+
+
+@dataclass
+class ConversationVariableResponse(BaseResponse):
+    """Conversation variable response model."""
+
+    conversation_id: str = ""
+    variables: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class FileUploadResponse(BaseResponse):
+    """File upload response model."""
+
+    id: str = ""
+    name: str = ""
+    size: int = 0
+    mime_type: str = ""
+    url: str | None = None
+    created_at: float | None = None
+
+
+@dataclass
+class AudioResponse(BaseResponse):
+    """Audio generation/response model."""
+
+    audio: str | None = None  # Base64 encoded audio data or URL
+    audio_url: str | None = None
+    duration: float | None = None
+    sample_rate: int | None = None
+
+
+@dataclass
+class SuggestedQuestionsResponse(BaseResponse):
+    """Suggested questions response model."""
+
+    message_id: str = ""
+    questions: List[str] = field(default_factory=list)
+
+
+@dataclass
+class AppInfoResponse(BaseResponse):
+    """App info response model."""
+
+    id: str = ""
+    name: str = ""
+    description: str | None = None
+    icon: str | None = None
+    icon_background: str | None = None
+    mode: str | None = None
+    tags: List[str] | None = None
+    enable_site: bool | None = None
+    enable_api: bool | None = None
+    api_token: str | None = None
+
+
+@dataclass
+class WorkspaceModelsResponse(BaseResponse):
+    """Workspace models response model."""
+
+    models: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class HitTestingResponse(BaseResponse):
+    """Hit testing response model."""
+
+    query: str = ""
+    records: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class DatasetTagsResponse(BaseResponse):
+    """Dataset tags response model."""
+
+    tags: List[Dict[str, Any]] = field(default_factory=list)
+
+
+@dataclass
+class WorkflowLogsResponse(BaseResponse):
+    """Workflow logs response model."""
+
+    logs: List[Dict[str, Any]] = field(default_factory=list)
+    total: int = 0
+    page: int = 0
+    limit: int = 0
+    has_more: bool = False
+
+
+@dataclass
+class ModelProviderResponse(BaseResponse):
+    """Model provider response model."""
+
+    provider_name: str = ""
+    provider_type: str = ""
+    models: List[Dict[str, Any]] = field(default_factory=list)
+    is_enabled: bool = False
+    credentials: Dict[str, Any] | None = None
+
+
+@dataclass
+class FileInfoResponse(BaseResponse):
+    """File info response model."""
+
+    id: str = ""
+    name: str = ""
+    size: int = 0
+    mime_type: str = ""
+    url: str | None = None
+    created_at: int | None = None
+    metadata: Dict[str, Any] | None = None
+
+
+@dataclass
+class WorkflowDraftResponse(BaseResponse):
+    """Workflow draft response model."""
+
+    id: str = ""
+    app_id: str = ""
+    draft_data: Dict[str, Any] = field(default_factory=dict)
+    version: int = 0
+    created_at: int | None = None
+    updated_at: int | None = None
+
+
+@dataclass
+class ApiTokenResponse(BaseResponse):
+    """API token response model."""
+
+    id: str = ""
+    name: str = ""
+    token: str = ""
+    description: str | None = None
+    created_at: int | None = None
+    last_used_at: int | None = None
+    is_active: bool = True
+
+
+@dataclass
+class JobStatusResponse(BaseResponse):
+    """Job status response model."""
+
+    job_id: str = ""
+    job_status: str = ""
+    error_msg: str | None = None
+    progress: float | None = None
+    created_at: int | None = None
+    updated_at: int | None = None
+
+
+@dataclass
+class DatasetQueryResponse(BaseResponse):
+    """Dataset query response model."""
+
+    query: str = ""
+    records: List[Dict[str, Any]] = field(default_factory=list)
+    total: int = 0
+    search_time: float | None = None
+    retrieval_model: Dict[str, Any] | None = None
+
+
+@dataclass
+class DatasetTemplateResponse(BaseResponse):
+    """Dataset template response model."""
+
+    template_name: str = ""
+    display_name: str = ""
+    description: str = ""
+    category: str = ""
+    icon: str | None = None
+    config_schema: Dict[str, Any] = field(default_factory=dict)
+
+
+# Type aliases for common response types
+ResponseType = Union[
+    BaseResponse,
+    ErrorResponse,
+    MessageResponse,
+    ConversationResponse,
+    DatasetResponse,
+    DocumentResponse,
+    DocumentSegmentResponse,
+    WorkflowRunResponse,
+    ApplicationParametersResponse,
+    AnnotationResponse,
+    PaginatedResponse,
+    ConversationVariableResponse,
+    FileUploadResponse,
+    AudioResponse,
+    SuggestedQuestionsResponse,
+    AppInfoResponse,
+    WorkspaceModelsResponse,
+    HitTestingResponse,
+    DatasetTagsResponse,
+    WorkflowLogsResponse,
+    ModelProviderResponse,
+    FileInfoResponse,
+    WorkflowDraftResponse,
+    ApiTokenResponse,
+    JobStatusResponse,
+    DatasetQueryResponse,
+    DatasetTemplateResponse,
+]