Skip to content

armgit / dify

Public Imported from GitHub
0

Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.

20.7 KB
Raw Blame
from datetime import datetime
from http import HTTPStatus
from typing import Annotated, Any, Literal
from uuid import UUID

from flask_restx import Resource
from pydantic import BaseModel, Field, JsonValue, WithJsonSchema, field_validator

import services
from controllers.common.controller_schemas import ConversationRenamePayload
from controllers.common.errors import (
    ConversationCursorNotFoundHTTPError,
    ConversationFirstMessageNotFoundHTTPError,
    ConversationNotFoundHTTPError,
    ConversationVariableNotFoundHTTPError,
    ConversationVariableTypeMismatchHTTPError,
)
from controllers.common.schema import query_params_from_model, register_response_schema_models, register_schema_models
from controllers.console.wraps import model_validate
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import NotChatAppError
from controllers.service_api.flask_admission import service_api_end_user_admission
from controllers.service_api.schema import expect_user_json, expect_with_user
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg
from extensions.ext_application_services import application_services
from fields._value_type_serializer import serialize_value_type
from fields.base import ResponseModel
from fields.conversation_fields import (
    ConversationInfiniteScrollPagination,
    SimpleConversation,
)
from graphon.variables.types import SegmentType
from libs.external_api import error_responses
from libs.helper import UUIDStrOrEmpty, dump_response, to_timestamp
from machinery.context import ServiceApiEndUserContext
from models.model import AppMode
from services.entities.conversation_entities import EndUserConversationRef, EndUserConversationScope
from services.errors.message import MessageNotExistsError

UUIDString = Annotated[str, WithJsonSchema({"format": "uuid", "type": "string"})]
Int64 = Annotated[int, WithJsonSchema({"format": "int64", "type": "integer"})]


class ConversationListQuery(BaseModel):
    last_id: UUIDStrOrEmpty | None = Field(
        default=None,
        description="The ID of the last record on the current page. Used to fetch the next page.",
    )
    limit: int = Field(default=20, ge=1, le=100, description="Number of records to return.")
    sort_by: Literal["created_at", "-created_at", "updated_at", "-updated_at"] = Field(
        default="-updated_at",
        description="Sorting field. Use the `-` prefix for descending order.",
    )


class ConversationVariablesQuery(BaseModel):
    last_id: UUIDStrOrEmpty | None = Field(
        default=None,
        description="The ID of the last record on the current page. Used to fetch the next page.",
    )
    limit: int = Field(default=20, ge=1, le=100, description="Number of records to return.")
    variable_name: str | None = Field(
        default=None,
        description="Filter variables by a specific name.",
        min_length=1,
        max_length=255,
    )

    @field_validator("variable_name", mode="before")
    @classmethod
    def validate_variable_name(cls, v: str | None) -> str | None:
        """
        Validate variable_name to prevent injection attacks.
        """
        if v is None:
            return v

        # Only allow safe characters: alphanumeric, underscore, hyphen, period
        if not v.replace("-", "").replace("_", "").replace(".", "").isalnum():
            raise ValueError(
                "Variable name can only contain letters, numbers, hyphens (-), underscores (_), and periods (.)"
            )

        # Prevent SQL injection patterns
        dangerous_patterns = ["'", '"', ";", "--", "/*", "*/", "xp_", "sp_"]
        for pattern in dangerous_patterns:
            if pattern in v.lower():
                raise ValueError(f"Variable name contains invalid characters: {pattern}")

        return v


class ConversationVariableUpdatePayload(BaseModel):
    value: JsonValue = Field(description="The new value for the variable. Must match the variable's expected type.")


class ConversationVariableResponse(ResponseModel):
    id: UUIDString
    name: str
    value_type: str
    value: str | None = None
    description: str | None = None
    created_at: Int64 | None = None
    updated_at: Int64 | None = None

    @field_validator("value_type", mode="before")
    @classmethod
    def normalize_value_type(cls, value: Any) -> str:
        exposed_type = getattr(value, "exposed_type", None)
        if callable(exposed_type):
            return str(exposed_type())
        if isinstance(value, str):
            try:
                return str(SegmentType(value).exposed_type())
            except ValueError:
                return value
        try:
            return serialize_value_type(value)
        except (AttributeError, TypeError, ValueError):
            pass

        try:
            return serialize_value_type({"value_type": value})
        except (AttributeError, TypeError, ValueError):
            value_attr = getattr(value, "value", None)
            if value_attr is not None:
                return str(value_attr)
            return str(value)

    @field_validator("value", mode="before")
    @classmethod
    def normalize_value(cls, value: Any | None) -> str | None:
        if value is None:
            return None
        if isinstance(value, str):
            return value
        return str(value)

    @field_validator("created_at", "updated_at", mode="before")
    @classmethod
    def normalize_timestamp(cls, value: datetime | int | None) -> int | None:
        return to_timestamp(value)


class ConversationVariableInfiniteScrollPaginationResponse(ResponseModel):
    limit: int
    has_more: bool
    data: list[ConversationVariableResponse]


register_schema_models(
    service_api_ns,
    ConversationListQuery,
    ConversationRenamePayload,
    ConversationVariablesQuery,
    ConversationVariableUpdatePayload,
)
register_response_schema_models(
    service_api_ns,
    ConversationVariableResponse,
    ConversationVariableInfiniteScrollPaginationResponse,
    ConversationInfiniteScrollPagination,
    SimpleConversation,
)


@service_api_ns.route("/conversations")
class ConversationApi(Resource):
    @error_responses(NotChatAppError, ConversationCursorNotFoundHTTPError, ConversationNotFoundHTTPError)
    @service_api_ns.doc(
        summary="List Conversations",
        description="Retrieve the conversation list for the current user, ordered by most recently active.",
        tags=["Conversations"],
        responses={
            HTTPStatus.OK: "Conversations retrieved successfully.",
            HTTPStatus.BAD_REQUEST: "Invalid app selection or app mode does not match the API route.",
            HTTPStatus.UNAUTHORIZED: "Invalid API credentials.",
            HTTPStatus.FORBIDDEN: "API credential, app or workspace access is unavailable.",
            HTTPStatus.NOT_FOUND: (
                "`conversation_cursor_not_found`: Cursor is outside the current list. "
                "`conversation_not_found`: The app or user is no longer available."
            ),
            HTTPStatus.UNPROCESSABLE_ENTITY: "Invalid conversation list query.",
        },
    )
    @service_api_ns.doc("list_conversations")
    @service_api_ns.doc(params=query_params_from_model(ConversationListQuery))
    @service_api_ns.response(
        HTTPStatus.OK,
        "Conversations retrieved successfully",
        service_api_ns.models[ConversationInfiniteScrollPagination.__name__],
    )
    @service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
    @model_validate(ConversationListQuery)
    def get(self, query_args: ConversationListQuery, context: ServiceApiEndUserContext) -> dict[str, object]:
        """List the current user's conversations, optionally continuing from a cursor."""
        app_mode = AppMode.value_of(context.app_mode)
        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
            raise NotChatAppError()

        try:
            pagination = application_services().conversation_queries.get_page(
                scope=EndUserConversationScope(
                    app_id=context.app_id,
                    tenant_id=context.tenant_id,
                    end_user_id=context.end_user_id,
                ),
                invoke_from="service-api",
                last_id=query_args.last_id or None,
                limit=query_args.limit,
                pinned=None,
                sort_by=query_args.sort_by,
            )
            return dump_response(ConversationInfiniteScrollPagination, pagination)
        except services.errors.conversation.LastConversationNotExistsError as error:
            raise ConversationCursorNotFoundHTTPError() from error
        except services.errors.conversation.ConversationNotExistsError as error:
            raise ConversationNotFoundHTTPError() from error


@service_api_ns.route("/conversations/<uuid:conversation_id>")
class ConversationDetailApi(Resource):
    @error_responses(NotChatAppError, ConversationNotFoundHTTPError)
    @service_api_ns.doc(
        summary="Delete Conversation",
        description="Delete a conversation.",
        tags=["Conversations"],
        responses={
            HTTPStatus.NO_CONTENT: "Conversation deleted successfully.",
            HTTPStatus.BAD_REQUEST: "Invalid app selection or app mode does not match the API route.",
            HTTPStatus.UNAUTHORIZED: "Invalid API credentials.",
            HTTPStatus.FORBIDDEN: "API credential, app or workspace access is unavailable.",
            HTTPStatus.NOT_FOUND: "`conversation_not_found`: Conversation does not exist for this user and app.",
        },
    )
    @expect_user_json(service_api_ns)
    @service_api_ns.doc("delete_conversation")
    @service_api_ns.doc(params={"conversation_id": "Conversation ID."})
    @service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
    def delete(self, context: ServiceApiEndUserContext, conversation_id: UUID) -> tuple[str, HTTPStatus]:
        """Delete a specific conversation."""
        app_mode = AppMode.value_of(context.app_mode)
        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
            raise NotChatAppError()

        try:
            application_services().conversation_commands.delete(
                ref=EndUserConversationRef(
                    app_id=context.app_id,
                    tenant_id=context.tenant_id,
                    end_user_id=context.end_user_id,
                    conversation_id=str(conversation_id),
                )
            )
        except services.errors.conversation.ConversationNotExistsError as error:
            raise ConversationNotFoundHTTPError() from error
        return "", HTTPStatus.NO_CONTENT


@service_api_ns.route("/conversations/<uuid:conversation_id>/name")
class ConversationRenameApi(Resource):
    @error_responses(NotChatAppError, ConversationNotFoundHTTPError, ConversationFirstMessageNotFoundHTTPError)
    @service_api_ns.doc(
        summary="Rename Conversation",
        description=(
            "Rename a conversation or auto-generate a name. The conversation name is used for display on "
            "clients that support multiple conversations."
        ),
        tags=["Conversations"],
        responses={
            HTTPStatus.OK: "Conversation renamed successfully; model failure preserves the existing name.",
            HTTPStatus.BAD_REQUEST: "Invalid app selection or app mode does not match the API route.",
            HTTPStatus.UNAUTHORIZED: "Invalid API credentials.",
            HTTPStatus.FORBIDDEN: "API credential, app or workspace access is unavailable.",
            HTTPStatus.NOT_FOUND: (
                "`conversation_not_found`: Conversation does not exist. "
                "`conversation_first_message_not_found`: No first message is available for automatic naming."
            ),
            HTTPStatus.UNPROCESSABLE_ENTITY: "Invalid conversation rename payload.",
        },
    )
    @expect_with_user(service_api_ns, ConversationRenamePayload)
    @service_api_ns.doc("rename_conversation")
    @service_api_ns.doc(description="Rename a conversation or auto-generate a name")
    @service_api_ns.doc(params={"conversation_id": "Conversation ID."})
    @service_api_ns.response(
        HTTPStatus.OK,
        "Conversation renamed successfully",
        service_api_ns.models[SimpleConversation.__name__],
    )
    @service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
    @model_validate(ConversationRenamePayload)
    def post(
        self, payload: ConversationRenamePayload, context: ServiceApiEndUserContext, conversation_id: UUID
    ) -> dict[str, object]:
        """Rename a conversation or auto-generate a name."""
        app_mode = AppMode.value_of(context.app_mode)
        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
            raise NotChatAppError()

        conversation_id_str = str(conversation_id)

        try:
            conversation = application_services().conversation_names.rename(
                ref=EndUserConversationRef(
                    app_id=context.app_id,
                    tenant_id=context.tenant_id,
                    end_user_id=context.end_user_id,
                    conversation_id=conversation_id_str,
                ),
                app_mode=context.app_mode,
                name=payload.name,
                auto_generate=payload.auto_generate,
            )
            return dump_response(SimpleConversation, conversation)
        except services.errors.conversation.ConversationNotExistsError as error:
            raise ConversationNotFoundHTTPError() from error
        except MessageNotExistsError as error:
            raise ConversationFirstMessageNotFoundHTTPError() from error


@service_api_ns.route("/conversations/<uuid:conversation_id>/variables")
class ConversationVariablesApi(Resource):
    @error_responses(NotChatAppError, ConversationNotFoundHTTPError, ConversationVariableNotFoundHTTPError)
    @service_api_ns.doc(
        summary="List Conversation Variables",
        description="Retrieve variables from a specific conversation.",
        tags=["Conversations"],
        responses={
            HTTPStatus.OK: "Conversation variables retrieved successfully.",
            HTTPStatus.BAD_REQUEST: "Invalid app selection or app mode does not match the API route.",
            HTTPStatus.UNAUTHORIZED: "Invalid API credentials.",
            HTTPStatus.FORBIDDEN: "API credential, app or workspace access is unavailable.",
            HTTPStatus.NOT_FOUND: (
                "`conversation_not_found`: Conversation does not exist for this user and app. "
                "`conversation_variable_not_found`: Cursor variable is outside the current list."
            ),
            HTTPStatus.UNPROCESSABLE_ENTITY: "Invalid conversation variables query.",
        },
    )
    @service_api_ns.doc("list_conversation_variables")
    @service_api_ns.doc(
        params={"conversation_id": "Conversation ID.", **query_params_from_model(ConversationVariablesQuery)}
    )
    @service_api_ns.response(
        HTTPStatus.OK,
        "Variables retrieved successfully",
        service_api_ns.models[ConversationVariableInfiniteScrollPaginationResponse.__name__],
    )
    @service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
    @model_validate(ConversationVariablesQuery)
    def get(
        self, query_args: ConversationVariablesQuery, context: ServiceApiEndUserContext, conversation_id: UUID
    ) -> dict[str, object]:
        """List the current user's conversation variables."""
        app_mode = AppMode.value_of(context.app_mode)
        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
            raise NotChatAppError()

        try:
            pagination = application_services().conversation_variables.get_page(
                ref=EndUserConversationRef(
                    app_id=context.app_id,
                    tenant_id=context.tenant_id,
                    end_user_id=context.end_user_id,
                    conversation_id=str(conversation_id),
                ),
                last_id=query_args.last_id or None,
                limit=query_args.limit,
                variable_name=query_args.variable_name,
            )
            return dump_response(
                ConversationVariableInfiniteScrollPaginationResponse,
                {
                    "limit": pagination.limit,
                    "has_more": pagination.has_more,
                    "data": [
                        {
                            "created_at": row.created_at,
                            "updated_at": row.updated_at,
                            **row.variable.model_dump(),
                            "id": row.id,
                        }
                        for row in pagination.data
                    ],
                },
            )
        except services.errors.conversation.ConversationNotExistsError as error:
            raise ConversationNotFoundHTTPError() from error
        except services.errors.conversation.ConversationVariableNotExistsError as error:
            raise ConversationVariableNotFoundHTTPError() from error


@service_api_ns.route("/conversations/<uuid:conversation_id>/variables/<uuid:variable_id>")
class ConversationVariableDetailApi(Resource):
    @error_responses(
        NotChatAppError,
        ConversationNotFoundHTTPError,
        ConversationVariableNotFoundHTTPError,
        ConversationVariableTypeMismatchHTTPError,
    )
    @service_api_ns.doc(
        summary="Update Conversation Variable",
        description="Update the value of a specific conversation variable. The value must match the expected type.",
        tags=["Conversations"],
        responses={
            HTTPStatus.OK: "Variable updated successfully.",
            HTTPStatus.BAD_REQUEST: (
                "Invalid app selection or app mode does not match the API route. "
                "`conversation_variable_type_mismatch`: Value does not match the variable's expected type. "
                "`invalid_param`: Value violates variable constraints, including the size limit."
            ),
            HTTPStatus.UNAUTHORIZED: "Invalid API credentials.",
            HTTPStatus.FORBIDDEN: "API credential, app or workspace access is unavailable.",
            HTTPStatus.NOT_FOUND: (
                "`conversation_not_found`: Conversation does not exist for this user and app. "
                "`conversation_variable_not_found`: Variable does not exist for this conversation."
            ),
            HTTPStatus.UNPROCESSABLE_ENTITY: "Invalid conversation variable update payload.",
        },
    )
    @expect_with_user(service_api_ns, ConversationVariableUpdatePayload)
    @service_api_ns.doc("update_conversation_variable")
    @service_api_ns.doc(params={"conversation_id": "Conversation ID.", "variable_id": "Variable ID."})
    @service_api_ns.response(
        HTTPStatus.OK,
        "Variable updated successfully",
        service_api_ns.models[ConversationVariableResponse.__name__],
    )
    @service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
    @model_validate(ConversationVariableUpdatePayload)
    def put(
        self,
        payload: ConversationVariableUpdatePayload,
        context: ServiceApiEndUserContext,
        conversation_id: UUID,
        variable_id: UUID,
    ) -> dict[str, object]:
        """Update a value without changing the variable's identity, type, or metadata."""
        app_mode = AppMode.value_of(context.app_mode)
        if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT}:
            raise NotChatAppError()

        try:
            row = application_services().conversation_variable_commands.update_value(
                ref=EndUserConversationRef(
                    app_id=context.app_id,
                    tenant_id=context.tenant_id,
                    end_user_id=context.end_user_id,
                    conversation_id=str(conversation_id),
                ),
                variable_id=str(variable_id),
                new_value=payload.value,
            )
            return dump_response(
                ConversationVariableResponse,
                {
                    "created_at": row.created_at,
                    "updated_at": row.updated_at,
                    **row.variable.model_dump(),
                    "id": row.id,
                },
            )
        except services.errors.conversation.ConversationNotExistsError as error:
            raise ConversationNotFoundHTTPError() from error
        except services.errors.conversation.ConversationVariableNotExistsError as error:
            raise ConversationVariableNotFoundHTTPError() from error
        except services.errors.conversation.ConversationVariableTypeMismatchError as error:
            raise ConversationVariableTypeMismatchHTTPError(str(error)) from error