chore: 纳入本地 Dify 1.19.0 源码及品牌与免登改动

演示目录只保留可重建的源码。运行密钥、数据卷、依赖和带口令的本地配置不进入仓库。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
wuzilongandCursor committed 2026-11-18 13:59:25 +08:00
1 parent 60158935f4
commit 6519682885
15831 files changed
+3063428

No files matched your search

@@ -0,0 +1,141 @@
from types import ModuleType
from flask import Blueprint
from flask_restx import Namespace
from controllers.common.access_response import register_auth_error_response
from controllers.common.errors import (
InternalServerError,
InvalidArgumentError,
NotFoundError,
UnauthorizedError,
register_permission_error_handler,
)
from libs.external_api import ExternalApi
bp = Blueprint("service_api", __name__, url_prefix="/v1")
register_auth_error_response(bp, www_authenticate='Bearer realm="api"')
api = ExternalApi(
bp,
version="1.0",
title="Service API",
description="API for application services",
register_default_root=False,
)
register_permission_error_handler(api)
# ``invalid_param`` is what the surface's ValueError handler already emits on any operation;
# ``not_found``, ``unauthorized`` and ``internal_server_error`` are the codes Werkzeug's own
# exceptions already produce on every operation.
api.document_generic_errors(InvalidArgumentError, NotFoundError, UnauthorizedError, InternalServerError)
service_api_ns = Namespace("service_api", description="Service operations", path="/")
def _register_controllers() -> tuple[ModuleType, ...]:
"""Load route modules after their namespaces and schema models exist."""
from . import index
from .app import (
annotation,
app,
audio,
completion,
conversation,
file,
file_preview,
human_input_form,
message,
site,
workflow,
workflow_events,
)
from .dataset import (
dataset,
document,
hit_testing,
metadata,
segment,
)
from .dataset.rag_pipeline import rag_pipeline_workflow
from .end_user import end_user
from .knowledge_fs import resources as knowledge_fs_resources
from .workspace import models
return (
index,
annotation,
app,
audio,
completion,
conversation,
file,
file_preview,
human_input_form,
message,
site,
workflow,
workflow_events,
dataset,
document,
hit_testing,
metadata,
segment,
rag_pipeline_workflow,
end_user,
knowledge_fs_resources,
models,
)
(
index,
annotation,
app,
audio,
completion,
conversation,
file,
file_preview,
human_input_form,
message,
site,
workflow,
workflow_events,
dataset,
document,
hit_testing,
metadata,
segment,
rag_pipeline_workflow,
end_user,
knowledge_fs_resources,
models,
) = _register_controllers()
__all__ = [
"annotation",
"app",
"audio",
"completion",
"conversation",
"dataset",
"document",
"end_user",
"file",
"file_preview",
"hit_testing",
"human_input_form",
"index",
"knowledge_fs_resources",
"message",
"metadata",
"models",
"rag_pipeline_workflow",
"segment",
"site",
"workflow",
"workflow_events",
]
api.add_namespace(service_api_ns)
Whitespace-only changes.
@@ -0,0 +1,354 @@
from http import HTTPStatus
from uuid import UUID
from flask_restx import Resource
from pydantic import BaseModel, Field, TypeAdapter
from controllers.common.errors import NotFoundError
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.flask_admission import service_api_account_admission
from extensions.ext_application_services import application_services
from fields.annotation_fields import (
Annotation,
AnnotationJobStatusDetailResponse,
AnnotationJobStatusResponse,
AnnotationList,
)
from libs.helper import dump_response
from machinery.context import ServiceApiAccountRequestContext
from services.annotation_query import AnnotationAppNotFoundError, AnnotationNotFoundError
from services.annotation_reply_service import AnnotationReplyAction, AnnotationReplyJobNotFoundError
class AnnotationCreatePayload(BaseModel):
question: str = Field(description="Annotation question.")
answer: str = Field(description="Annotation answer.")
class AnnotationReplyActionPayload(BaseModel):
score_threshold: float = Field(
description=(
"Minimum similarity score for an annotation to be considered a match. Higher values require closer matches."
),
json_schema_extra={"format": "float"},
)
embedding_provider_name: str = Field(description="Name of the embedding model provider.")
embedding_model_name: str = Field(description="Name of the embedding model to use for annotation matching.")
class AnnotationListQuery(BaseModel):
page: int = Field(default=1, ge=1, description="Page number for pagination.")
limit: int = Field(default=20, ge=1, description="Number of items per page.")
keyword: str = Field(default="", description="Keyword to filter annotations by question or answer content.")
ANNOTATION_REPLY_ACTION_PARAM = {
"description": "Action to perform: `enable` or `disable`.",
"enum": ["enable", "disable"],
"type": "string",
}
register_schema_models(
service_api_ns,
AnnotationCreatePayload,
AnnotationReplyActionPayload,
AnnotationListQuery,
)
register_response_schema_models(
service_api_ns,
Annotation,
AnnotationList,
AnnotationJobStatusResponse,
AnnotationJobStatusDetailResponse,
)
@service_api_ns.route("/apps/annotation-reply/<string:action>")
class AnnotationReplyActionApi(Resource):
@service_api_ns.doc(
summary="Configure Annotation Reply",
description=(
"Enables or disables the annotation reply feature. Requires embedding model configuration "
"when enabling. Executes asynchronously — use [Get Annotation Reply Job "
"Status](/api-reference/annotations/get-annotation-reply-job-status) to track progress."
),
tags=["Annotations"],
responses={
HTTPStatus.OK: "Annotation reply settings task initiated.",
},
)
@service_api_ns.expect(service_api_ns.models[AnnotationReplyActionPayload.__name__])
@service_api_ns.doc("annotation_reply_action")
@service_api_ns.doc(description="Enable or disable annotation reply feature")
@service_api_ns.doc(params={"action": ANNOTATION_REPLY_ACTION_PARAM})
@service_api_ns.doc(
responses={
HTTPStatus.OK: "Action completed successfully",
HTTPStatus.BAD_REQUEST: "`invalid_param` : Invalid action or app selection.",
HTTPStatus.UNAUTHORIZED: "`unauthorized` : Invalid API credential or workspace owner unavailable.",
HTTPStatus.NOT_FOUND: "`not_found` : App no longer exists.",
HTTPStatus.UNPROCESSABLE_ENTITY: "`unprocessable_entity` : Invalid annotation reply payload.",
}
)
@service_api_ns.response(
HTTPStatus.OK,
"Action completed successfully",
service_api_ns.models[AnnotationJobStatusResponse.__name__],
)
@service_api_account_admission
@model_validate(AnnotationReplyActionPayload)
def post(
self, payload: AnnotationReplyActionPayload, context: ServiceApiAccountRequestContext, action: str
) -> tuple[dict[str, object], HTTPStatus]:
"""Enable or disable annotation reply feature."""
validated_action = TypeAdapter(AnnotationReplyAction).validate_python(action)
service = application_services().annotation_reply
try:
if validated_action == "enable":
result = service.enable(
tenant_id=context.tenant_id,
app_id=context.app_id,
account_id=context.account_id,
score_threshold=payload.score_threshold,
embedding_provider_name=payload.embedding_provider_name,
embedding_model_name=payload.embedding_model_name,
)
else:
result = service.disable(tenant_id=context.tenant_id, app_id=context.app_id)
except AnnotationAppNotFoundError as exc:
raise NotFoundError("App not found") from exc
return dump_response(AnnotationJobStatusResponse, result), HTTPStatus.OK
@service_api_ns.route("/apps/annotation-reply/<string:action>/status/<uuid:job_id>")
class AnnotationReplyActionStatusApi(Resource):
@service_api_ns.doc(
summary="Get Annotation Reply Job Status",
description=(
"Retrieves the status of an asynchronous annotation reply configuration job started by "
"[Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply)."
),
tags=["Annotations"],
responses={
HTTPStatus.OK: "Successfully retrieved task status.",
HTTPStatus.BAD_REQUEST: "`invalid_param` : Invalid action or app selection.",
HTTPStatus.NOT_FOUND: "`not_found` : The specified job does not belong to this app or no longer exists.",
},
)
@service_api_ns.doc("get_annotation_reply_action_status")
@service_api_ns.doc(description="Get the status of an annotation reply action job")
@service_api_ns.doc(
params={
"action": ANNOTATION_REPLY_ACTION_PARAM,
"job_id": (
"Job ID returned by "
"[Configure Annotation Reply](/api-reference/annotations/configure-annotation-reply)."
),
}
)
@service_api_ns.doc(
responses={
HTTPStatus.OK: "Job status retrieved successfully",
HTTPStatus.UNAUTHORIZED: "`unauthorized` : Invalid API credential or workspace owner unavailable.",
}
)
@service_api_ns.response(
HTTPStatus.OK,
"Job status retrieved successfully",
service_api_ns.models[AnnotationJobStatusDetailResponse.__name__],
)
@service_api_account_admission
def get(
self, context: ServiceApiAccountRequestContext, job_id: UUID, action: str
) -> tuple[dict[str, object], HTTPStatus]:
"""Get the status of an annotation reply action job."""
validated_action = TypeAdapter(AnnotationReplyAction).validate_python(action)
try:
result = application_services().annotation_reply.get_status(
tenant_id=context.tenant_id, app_id=context.app_id, action=validated_action, job_id=str(job_id)
)
except AnnotationAppNotFoundError as exc:
raise NotFoundError("App not found") from exc
except AnnotationReplyJobNotFoundError as exc:
raise NotFoundError("The job does not exist.") from exc
return dump_response(AnnotationJobStatusDetailResponse, result), HTTPStatus.OK
@service_api_ns.route("/apps/annotations")
class AnnotationListApi(Resource):
@service_api_ns.doc(
summary="List Annotations",
description="Retrieves a paginated list of annotations for the application. Supports keyword search filtering.",
tags=["Annotations"],
responses={
HTTPStatus.OK: "Successfully retrieved annotation list.",
},
)
@service_api_ns.doc("list_annotations")
@service_api_ns.doc(description="List annotations for the application")
@service_api_ns.doc(params=query_params_from_model(AnnotationListQuery))
@service_api_ns.doc(
responses={
HTTPStatus.OK: "Annotations retrieved successfully",
HTTPStatus.BAD_REQUEST: "`invalid_param` : Invalid app selection.",
HTTPStatus.UNAUTHORIZED: "`unauthorized` : Invalid API credential or workspace owner unavailable.",
HTTPStatus.NOT_FOUND: "`not_found` : App no longer exists.",
HTTPStatus.UNPROCESSABLE_ENTITY: "`unprocessable_entity` : Invalid pagination query.",
}
)
@service_api_ns.response(
HTTPStatus.OK,
"Annotations retrieved successfully",
service_api_ns.models[AnnotationList.__name__],
)
@service_api_account_admission
@model_validate(AnnotationListQuery)
def get(self, query: AnnotationListQuery, context: ServiceApiAccountRequestContext) -> dict[str, object]:
"""List annotations for the application."""
try:
result = application_services().annotation_queries.get_page(
tenant_id=context.tenant_id,
app_id=context.app_id,
page=query.page,
limit=query.limit,
keyword=query.keyword,
)
except AnnotationAppNotFoundError as exc:
raise NotFoundError("App not found") from exc
return dump_response(AnnotationList, result)
@service_api_ns.doc(
summary="Create Annotation",
description=(
"Creates a new annotation. Annotations provide predefined question-answer pairs that the app "
"can match and return directly instead of generating a response."
),
tags=["Annotations"],
responses={
HTTPStatus.CREATED: "Annotation created successfully.",
},
)
@service_api_ns.expect(service_api_ns.models[AnnotationCreatePayload.__name__])
@service_api_ns.doc("create_annotation")
@service_api_ns.doc(description="Create a new annotation")
@service_api_ns.doc(
responses={
HTTPStatus.CREATED: "Annotation created successfully",
HTTPStatus.BAD_REQUEST: "`invalid_param` : Invalid app selection.",
HTTPStatus.UNAUTHORIZED: "`unauthorized` : Invalid API credential or workspace owner unavailable.",
HTTPStatus.NOT_FOUND: "`not_found` : App no longer exists.",
HTTPStatus.UNPROCESSABLE_ENTITY: "`unprocessable_entity` : Invalid annotation payload.",
}
)
@service_api_ns.response(
HTTPStatus.CREATED,
"Annotation created successfully",
service_api_ns.models[Annotation.__name__],
)
@service_api_account_admission
@model_validate(AnnotationCreatePayload)
def post(
self, payload: AnnotationCreatePayload, context: ServiceApiAccountRequestContext
) -> tuple[dict[str, object], HTTPStatus]:
"""Create a new annotation."""
try:
annotation = application_services().annotation_commands.create(
tenant_id=context.tenant_id,
app_id=context.app_id,
account_id=context.account_id,
question=payload.question,
answer=payload.answer,
)
except AnnotationAppNotFoundError as exc:
raise NotFoundError("App not found") from exc
return dump_response(Annotation, annotation), HTTPStatus.CREATED
@service_api_ns.route("/apps/annotations/<uuid:annotation_id>")
class AnnotationUpdateDeleteApi(Resource):
@service_api_ns.doc(
summary="Update Annotation",
description="Updates the question and answer of an existing annotation.",
tags=["Annotations"],
responses={
HTTPStatus.OK: "Annotation updated successfully.",
HTTPStatus.FORBIDDEN: "`forbidden` : API credential scope, app, or workspace access denied.",
HTTPStatus.NOT_FOUND: "`not_found` : App or annotation no longer exists.",
},
)
@service_api_ns.expect(service_api_ns.models[AnnotationCreatePayload.__name__])
@service_api_ns.doc("update_annotation")
@service_api_ns.doc(description="Update an existing annotation")
@service_api_ns.doc(params={"annotation_id": "The unique identifier of the annotation to update."})
@service_api_ns.doc(
responses={
HTTPStatus.OK: "Annotation updated successfully",
HTTPStatus.BAD_REQUEST: "`invalid_param` : Invalid app selection.",
HTTPStatus.UNAUTHORIZED: "`unauthorized` : Invalid API credential or workspace owner unavailable.",
HTTPStatus.FORBIDDEN: "`forbidden` : API credential scope, app, or workspace access denied.",
HTTPStatus.NOT_FOUND: "Annotation not found",
HTTPStatus.UNPROCESSABLE_ENTITY: "`unprocessable_entity` : Invalid annotation payload.",
}
)
@service_api_ns.response(
HTTPStatus.OK,
"Annotation updated successfully",
service_api_ns.models[Annotation.__name__],
)
@service_api_account_admission
@model_validate(AnnotationCreatePayload)
def put(
self, payload: AnnotationCreatePayload, context: ServiceApiAccountRequestContext, annotation_id: UUID
) -> dict[str, object]:
"""Update an existing annotation."""
try:
annotation = application_services().annotation_commands.update(
tenant_id=context.tenant_id,
app_id=context.app_id,
annotation_id=str(annotation_id),
question=payload.question,
answer=payload.answer,
)
except AnnotationAppNotFoundError as exc:
raise NotFoundError("App not found") from exc
except AnnotationNotFoundError as exc:
raise NotFoundError("Annotation not found") from exc
return dump_response(Annotation, annotation)
@service_api_ns.doc(
summary="Delete Annotation",
description="Deletes an annotation and its associated hit history.",
tags=["Annotations"],
responses={
HTTPStatus.NO_CONTENT: "Annotation deleted successfully.",
HTTPStatus.FORBIDDEN: "`forbidden` : API credential scope, app, or workspace access denied.",
HTTPStatus.NOT_FOUND: "`not_found` : App or annotation no longer exists.",
},
)
@service_api_ns.doc("delete_annotation")
@service_api_ns.doc(description="Delete an annotation")
@service_api_ns.doc(params={"annotation_id": "The unique identifier of the annotation to delete."})
@service_api_ns.doc(
responses={
HTTPStatus.NO_CONTENT: "Annotation deleted successfully",
HTTPStatus.BAD_REQUEST: "`invalid_param` : Invalid app selection.",
HTTPStatus.UNAUTHORIZED: "`unauthorized` : Invalid API credential or workspace owner unavailable.",
HTTPStatus.FORBIDDEN: "`forbidden` : API credential scope, app, or workspace access denied.",
HTTPStatus.NOT_FOUND: "Annotation not found",
}
)
@service_api_account_admission
def delete(self, context: ServiceApiAccountRequestContext, annotation_id: UUID) -> tuple[str, HTTPStatus]:
"""Delete an annotation."""
try:
application_services().annotation_commands.delete(
tenant_id=context.tenant_id, app_id=context.app_id, annotation_id=str(annotation_id)
)
except AnnotationAppNotFoundError as exc:
raise NotFoundError("App not found") from exc
except AnnotationNotFoundError as exc:
raise NotFoundError("Annotation not found") from exc
return "", HTTPStatus.NO_CONTENT
@@ -0,0 +1,154 @@
from typing import Annotated
from flask_restx import Resource
from pydantic import Field, WithJsonSchema
from controllers.common.fields import Parameters
from controllers.common.schema import register_response_schema_models
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import AgentNotPublishedError, AppUnavailableError
from controllers.service_api.wraps import validate_app_token
from extensions.ext_application_services import application_services
from fields.base import ResponseModel
from libs.external_api import error_responses
from libs.helper import dump_response
from models.model import App
from services.app_definition_query_service import AppDefinitionNotPublishedError, AppDefinitionUnavailableError
class AppInfoResponse(ResponseModel):
name: str
description: str | None
tags: list[str]
mode: str
author_name: str | None
URLString = Annotated[str, WithJsonSchema({"format": "url", "type": "string"})]
class ToolIcon(ResponseModel):
background: str
content: str
class AppMetaResponse(ResponseModel):
tool_icons: dict[str, URLString | ToolIcon] = Field(default_factory=dict)
register_response_schema_models(service_api_ns, Parameters, AppMetaResponse, AppInfoResponse)
@service_api_ns.route("/parameters")
class AppParameterApi(Resource):
"""Resource for app variables."""
@error_responses(AgentNotPublishedError, AppUnavailableError)
@service_api_ns.doc(
summary="Get App Parameters",
description=(
"Retrieve the application's input form configuration, including feature switches, input "
"parameter names, types, and default values."
),
tags=["Applications"],
responses={
200: "Application parameters information.",
400: "`app_unavailable` : App unavailable or misconfigured.",
},
)
@service_api_ns.doc("get_app_parameters")
@service_api_ns.doc(description="Retrieve application input parameters and configuration")
@service_api_ns.doc(
responses={
200: "Parameters retrieved successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(200, "Parameters retrieved successfully", service_api_ns.models[Parameters.__name__])
@validate_app_token
def get(self, app_model: App):
"""Retrieve app parameters.
Returns the input form parameters and configuration for the application.
"""
try:
parameters = application_services().app_definitions.get_public_parameters(app_model.id)
except AppDefinitionNotPublishedError:
raise AgentNotPublishedError() from None
except AppDefinitionUnavailableError:
raise AppUnavailableError() from None
return dump_response(Parameters, parameters)
@service_api_ns.route("/meta")
class AppMetaApi(Resource):
@error_responses(AppUnavailableError)
@service_api_ns.doc(
summary="Get App Meta",
description="Retrieve metadata about this application, including tool icons and other configuration details.",
tags=["Applications"],
responses={
200: "Successfully retrieved application meta information.",
400: "`app_unavailable` : App unavailable or misconfigured.",
},
)
@service_api_ns.doc("get_app_meta")
@service_api_ns.doc(description="Get application metadata")
@service_api_ns.doc(
responses={
200: "Metadata retrieved successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(200, "Metadata retrieved successfully", service_api_ns.models[AppMetaResponse.__name__])
@validate_app_token
def get(self, app_model: App):
"""Get app metadata.
Returns metadata about the application including configuration and settings.
"""
try:
tool_icons = application_services().app_definitions.get_tool_icons(app_model.id)
except AppDefinitionUnavailableError:
raise AppUnavailableError() from None
return dump_response(AppMetaResponse, {"tool_icons": tool_icons})
@service_api_ns.route("/info")
class AppInfoApi(Resource):
@error_responses(AppUnavailableError)
@service_api_ns.doc(
summary="Get App Info",
description="Retrieve basic information about this application, including name, description, tags, and mode.",
tags=["Applications"],
responses={
200: "Basic information of the application.",
400: "`app_unavailable` : App unavailable or misconfigured.",
},
)
@service_api_ns.doc("get_app_info")
@service_api_ns.doc(description="Get basic application information")
@service_api_ns.doc(
responses={
200: "Application info retrieved successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(
200,
"Application info retrieved successfully",
service_api_ns.models[AppInfoResponse.__name__],
)
@validate_app_token
def get(self, app_model: App):
"""Get app information.
Returns basic information about the application including name, description, tags, and mode.
"""
try:
summary = application_services().app_definitions.get_summary(app_model.id)
except AppDefinitionUnavailableError:
raise AppUnavailableError() from None
return dump_response(AppInfoResponse, summary)
@@ -0,0 +1,249 @@
import logging
from flask import request
from flask_restx import Resource
from sqlalchemy.orm import Session
from werkzeug.exceptions import InternalServerError
import services
from controllers.common.controller_schemas import TextToAudioPayload
from controllers.common.fields import AudioBinaryResponse, AudioTranscriptResponse
from controllers.common.schema import register_response_schema_models, register_schema_model
from controllers.common.session import with_session
from controllers.console.wraps import model_validate
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import (
AppUnavailableError,
AudioTooLargeError,
CompletionRequestError,
NoAudioUploadedError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderNotSupportSpeechToTextError,
ProviderQuotaExceededError,
SpeechToTextDisabledError,
UnsupportedAudioTypeError,
)
from controllers.service_api.schema import binary_response, expect_with_user, multipart_file_params
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
from core.base.tts.audio_mime import SUPPORTED_TTS_AUDIO_MIME_TYPES
from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
from graphon.model_runtime.errors.invoke import InvokeError
from libs.external_api import error_responses
from libs.helper import dump_response
from models.model import App, EndUser
from services.app_ref_service import AppRefService
from services.audio_service import AudioService
from services.errors.audio import (
AudioTooLargeServiceError,
NoAudioUploadedServiceError,
ProviderNotSupportSpeechToTextServiceError,
SpeechToTextDisabledServiceError,
UnsupportedAudioTypeServiceError,
)
logger = logging.getLogger(__name__)
register_response_schema_models(service_api_ns, AudioBinaryResponse, AudioTranscriptResponse)
@service_api_ns.route("/audio-to-text")
class AudioApi(Resource):
@error_responses(
AppUnavailableError,
AudioTooLargeError,
CompletionRequestError,
NoAudioUploadedError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderNotSupportSpeechToTextError,
ProviderQuotaExceededError,
SpeechToTextDisabledError,
UnsupportedAudioTypeError,
)
@service_api_ns.doc(
summary="Convert Audio to Text",
description=(
"Convert audio file to text. Supported MIME types: `audio/mp3`, `audio/mpga`, `audio/m4a`, "
"`audio/x-m4a`, `audio/wav`, and `audio/amr`. File size limit is `30 MB`."
),
tags=["TTS"],
responses={
200: "Successfully converted audio to text.",
400: (
"- `app_unavailable` : App unavailable or misconfigured.\n"
"- `speech_to_text_disabled` : Speech-to-text is disabled for this app.\n"
"- `provider_not_support_speech_to_text` : Model provider does not support speech-to-text.\n"
"- `provider_not_initialize` : No valid model provider credentials found.\n"
"- `provider_quota_exceeded` : Model provider quota exhausted.\n"
"- `model_currently_not_support` : Current model does not support this operation.\n"
"- `completion_request_error` : Speech recognition request failed."
),
413: "`audio_too_large` : Audio file size exceeded the limit.",
415: "`unsupported_audio_type` : Audio type is not allowed.",
500: "`internal_server_error` : Internal server error.",
},
)
@service_api_ns.doc("audio_to_text")
@service_api_ns.doc(description="Convert audio to text using speech-to-text")
@service_api_ns.doc(
consumes=["multipart/form-data"],
params=multipart_file_params(
include_user=True,
file_description=(
"Audio file to transcribe. Supported MIME types: `audio/mp3`, `audio/mpga`, `audio/m4a`, "
"`audio/x-m4a`, `audio/wav`, and `audio/amr`. File size limit is `30 MB`."
),
),
)
@service_api_ns.doc(
responses={
200: "Audio successfully transcribed",
400: "Bad request - no audio or invalid audio",
401: "Unauthorized - invalid API token",
413: "Audio file too large",
415: "Unsupported audio type",
500: "Internal server error",
}
)
@service_api_ns.response(
200,
"Audio successfully transcribed",
service_api_ns.models[AudioTranscriptResponse.__name__],
)
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.FORM))
@with_session(write=False)
def post(self, session: Session, app_model: App, end_user: EndUser):
"""Convert audio to text using speech-to-text.
Accepts an audio file upload and returns the transcribed text.
"""
file = request.files.get("file")
try:
response = AudioService.transcript_asr(
app_model=app_model,
file=file,
session=session,
end_user=end_user.id,
)
return dump_response(AudioTranscriptResponse, response)
except services.errors.app_model_config.AppModelConfigBrokenError as caught_error:
logger.exception("App model config broken.")
raise AppUnavailableError() from caught_error
except NoAudioUploadedServiceError as caught_error:
raise NoAudioUploadedError() from caught_error
except AudioTooLargeServiceError as e:
raise AudioTooLargeError(str(e)) from e
except UnsupportedAudioTypeServiceError as caught_error:
raise UnsupportedAudioTypeError() from caught_error
except ProviderNotSupportSpeechToTextServiceError as caught_error:
raise ProviderNotSupportSpeechToTextError() from caught_error
except SpeechToTextDisabledServiceError as caught_error:
raise SpeechToTextDisabledError() from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
except QuotaExceededError as caught_error:
raise ProviderQuotaExceededError() from caught_error
except ModelCurrentlyNotSupportError as caught_error:
raise ProviderModelCurrentlyNotSupportError() from caught_error
except InvokeError as e:
raise CompletionRequestError(e.description) from e
except ValueError as e:
raise e
except Exception as e:
logger.exception("internal server error.")
raise InternalServerError() from e
register_schema_model(service_api_ns, TextToAudioPayload)
@service_api_ns.route("/text-to-audio")
class TextApi(Resource):
@error_responses(
AppUnavailableError,
CompletionRequestError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
)
@service_api_ns.doc(
summary="Convert Text to Audio",
description="Convert text to speech.",
tags=["TTS"],
responses={
200: (
"Returns the generated audio. The `Content-Type` header reflects the provider audio container, "
"verified from the response bytes when recognizable. The binary response can be AAC, FLAC, MP4, "
"MP3, Ogg, WAV, or WebM."
),
400: (
"- `app_unavailable` : App unavailable or misconfigured.\n"
"- `provider_not_initialize` : No valid model provider credentials found.\n"
"- `provider_quota_exceeded` : Model provider quota exhausted.\n"
"- `model_currently_not_support` : Current model does not support this operation.\n"
"- `completion_request_error` : Text-to-speech request failed."
),
500: "`internal_server_error` : Internal server error.",
},
)
@expect_with_user(service_api_ns, TextToAudioPayload)
@binary_response(service_api_ns, SUPPORTED_TTS_AUDIO_MIME_TYPES)
@service_api_ns.doc("text_to_audio")
@service_api_ns.doc(description="Convert text to audio using text-to-speech")
@service_api_ns.doc(
responses={
200: "Text successfully converted to audio",
400: "Bad request - invalid parameters",
401: "Unauthorized - invalid API token",
500: "Internal server error",
}
)
# TTS returns provider audio bytes, so the success response is intentionally schema-less.
@service_api_ns.response(200, "Text successfully converted to audio")
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON))
@with_session(write=False)
@model_validate(TextToAudioPayload)
def post(self, payload: TextToAudioPayload, session: Session, app_model: App, end_user: EndUser):
"""Convert text to audio using text-to-speech.
Converts the provided text to audio using the specified voice.
"""
try:
message_id = payload.message_id
text = payload.text
voice = payload.voice
message_ref = None
if message_id:
app_ref = AppRefService.create_app_ref(app_model)
message_ref = AppRefService.create_message_ref(
app_ref,
message_id,
end_user_id=end_user.id,
)
return AudioService.transcript_tts(
app_model=app_model,
session=session,
text=text,
voice=voice,
end_user=end_user.external_user_id,
message_ref=message_ref,
)
except services.errors.app_model_config.AppModelConfigBrokenError as caught_error:
logger.exception("App model config broken.")
raise AppUnavailableError() from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
except QuotaExceededError as caught_error:
raise ProviderQuotaExceededError() from caught_error
except ModelCurrentlyNotSupportError as caught_error:
raise ProviderModelCurrentlyNotSupportError() from caught_error
except InvokeError as e:
raise CompletionRequestError(e.description) from e
except ValueError as e:
raise e
except Exception as e:
logger.exception("internal server error.")
raise InternalServerError() from e
@@ -0,0 +1,533 @@
import logging
from typing import Any, Literal
from uuid import UUID
from flask import request
from flask_restx import Resource
from pydantic import BaseModel, Field, field_validator
from pydantic.json_schema import SkipJsonSchema
from sqlalchemy.orm import Session
from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
import services
from configs import dify_config
from controllers.common.fields import ChatBlockingResponse, CompletionBlockingResponse, SimpleResultResponse
from controllers.common.schema import register_response_schema_models, register_schema_models
from controllers.console.app.wraps import with_session
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import (
AgentNotPublishedError,
AppUnavailableError,
CompletionRequestError,
ConversationCompletedError,
NotChatAppError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
WorkflowVersionExecutionNotAllowedError,
)
from controllers.service_api.schema import (
SCOPED_TASK_STOP_USER_DESCRIPTION,
InputFileList,
expect_user_json,
expect_with_user,
json_or_event_stream_response,
)
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
from core.app.apps.agent_app.errors import AgentAppNotPublishedError
from core.app.entities.app_invoke_entities import InvokeFrom
from core.errors.error import (
ModelCurrentlyNotSupportError,
ProviderTokenNotInitError,
QuotaExceededError,
)
from core.helper.trace_id_helper import get_external_trace_id, get_trace_session_id, omit_trace_session_id_from_payload
from enums import CloudPlan, DeploymentEdition
from graphon.model_runtime.errors.invoke import InvokeError
from libs import helper
from libs.external_api import error_responses
from libs.helper import UUIDStrOrEmpty
from models.model import App, AppMode, EndUser
from services.app_generate_service import AppGenerateService
from services.app_task_service import AppTaskService
from services.billing_service import BillingService
from services.conversation_service import ConversationService
from services.errors.app import IsDraftWorkflowError, WorkflowIdFormatError, WorkflowNotFoundError
from services.errors.llm import InvokeRateLimitError
logger = logging.getLogger(__name__)
def _resolve_agent_app_streaming(*, app_mode: AppMode, response_mode: str | None) -> bool:
"""Agent App runtime is SSE-only until backend blocking runs are supported."""
if app_mode != AppMode.AGENT:
return response_mode == "streaming"
if response_mode == "blocking":
raise BadRequest("Agent App only supports streaming response mode.")
return True
class CompletionRequestPayload(BaseModel):
inputs: dict[str, Any] = Field(
description=(
"Values for app-defined variables. Refer to the `user_input_form` field in the "
"[Get App Parameters](/api-reference/applications/get-app-parameters) response to discover expected "
"variable names and types."
)
)
query: str = Field(default="", description="User input or prompt content.")
files: InputFileList = Field(
default=None,
description=(
"File list for multimodal understanding, including images, documents, audio, and video. To attach a "
"local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned "
"`id` as `upload_file_id` with `transfer_method: local_file`."
),
)
response_mode: Literal["blocking", "streaming"] | None = Field(
default=None,
description=(
"Response mode. `streaming` uses Server-Sent Events; `blocking` returns after completion. When omitted, "
"the request runs in blocking mode."
),
)
retriever_from: SkipJsonSchema[str] = Field(default="dev")
trace_session_id: SkipJsonSchema[str | None] = Field(
default=None, description="Trace session ID for observability grouping"
)
class ChatRequestPayload(BaseModel):
inputs: dict[str, Any] = Field(
description=(
"Values for app-defined variables. Refer to the `user_input_form` field in the "
"[Get App Parameters](/api-reference/applications/get-app-parameters) response to discover expected "
"variable names and types."
)
)
query: str = Field(description="User input or question content.")
files: InputFileList = Field(
default=None,
description=(
"File list for multimodal understanding, including images, documents, audio, and video. To attach a "
"local file, first upload it via [Upload File](/api-reference/files/upload-file) and use the returned "
"`id` as `upload_file_id` with `transfer_method: local_file`."
),
)
response_mode: Literal["blocking", "streaming"] | None = Field(
default=None,
description=(
"Response mode. `streaming` uses Server-Sent Events; `blocking` returns after completion. New Agent app "
"mode supports streaming only. When omitted, non-Agent apps run in blocking mode and new Agent apps stream."
),
)
conversation_id: UUIDStrOrEmpty | None = Field(
default=None,
description=(
"Conversation ID to continue a conversation. Omit this field or pass an empty string to start a new "
"conversation, then pass the returned `conversation_id` in subsequent requests."
),
)
retriever_from: SkipJsonSchema[str] = Field(default="dev")
auto_generate_name: bool = Field(
default=True,
description=(
"Auto-generate the conversation title. If `false`, use the Rename Conversation API with "
"`auto_generate: true` to generate the title asynchronously."
),
)
workflow_id: str | None = Field(
default=None,
description=(
"Published workflow version ID to execute for advanced chat. If omitted, the app's current published "
"workflow is used."
),
)
trace_session_id: SkipJsonSchema[str | None] = Field(
default=None, description="Trace session ID for observability grouping"
)
@field_validator("conversation_id", mode="before")
@classmethod
def normalize_conversation_id(cls, value: str | UUID | None) -> str | None:
"""Allow missing or blank conversation IDs; enforce UUID format when provided."""
if isinstance(value, str):
value = value.strip()
if not value:
return None
try:
return helper.uuid_value(value)
except ValueError as exc:
raise ValueError("conversation_id must be a valid UUID") from exc
register_schema_models(service_api_ns, CompletionRequestPayload, ChatRequestPayload)
register_response_schema_models(
service_api_ns,
SimpleResultResponse,
ChatBlockingResponse,
CompletionBlockingResponse,
)
@service_api_ns.route("/completion-messages")
class CompletionApi(Resource):
@error_responses(
AppUnavailableError,
CompletionRequestError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
)
@service_api_ns.doc(
summary="Send Completion Message",
description="Send a request to the text generation application.",
tags=["Completions"],
responses={
200: (
"Successful response. The content type and structure depend on the `response_mode` parameter "
"in the request.\n"
"\n"
"- If `response_mode` is `blocking`, returns `application/json` with a `CompletionResponse` "
"object.\n"
"- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of "
"`ChunkCompletionEvent` objects."
),
400: (
"- `app_unavailable` : App unavailable or misconfigured.\n"
"- `provider_not_initialize` : No valid model provider credentials found.\n"
"- `provider_quota_exceeded` : Model provider quota exhausted.\n"
"- `model_currently_not_support` : Current model unavailable.\n"
"- `completion_request_error` : Text generation failed."
),
429: "`too_many_requests` : Too many concurrent requests for this app.",
500: "`internal_server_error` : Internal server error.",
},
)
@expect_with_user(service_api_ns, CompletionRequestPayload)
@json_or_event_stream_response(service_api_ns)
@service_api_ns.doc("create_completion")
@service_api_ns.doc(description="Create a completion for the given prompt")
@service_api_ns.doc(
responses={
200: "Completion created successfully",
400: "Bad request - invalid parameters",
401: "Unauthorized - invalid API token",
500: "Internal server error",
}
)
@service_api_ns.response(
200,
"Completion created successfully",
service_api_ns.models[CompletionBlockingResponse.__name__],
)
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
@with_session
def post(self, session: Session, app_model: App, end_user: EndUser):
"""Create a completion for the given prompt.
This endpoint generates a completion based on the provided inputs and query.
Supports both blocking and streaming response modes.
"""
if app_model.mode != AppMode.COMPLETION:
raise AppUnavailableError()
payload = CompletionRequestPayload.model_validate(
omit_trace_session_id_from_payload(service_api_ns.payload) or {}
)
external_trace_id = get_external_trace_id(request)
args = payload.model_dump(exclude_none=True)
trace_session_id = get_trace_session_id(request)
if trace_session_id:
args["trace_session_id"] = trace_session_id
if external_trace_id:
args["external_trace_id"] = external_trace_id
streaming = payload.response_mode == "streaming"
args["auto_generate_name"] = False
try:
response = AppGenerateService.generate(
session=session,
app_model=app_model,
user=end_user,
args=args,
invoke_from=InvokeFrom.SERVICE_API,
streaming=streaming,
)
# response-contract:ignore compact_generate_response
return helper.compact_generate_response(response)
except services.errors.conversation.ConversationNotExistsError as caught_error:
raise NotFound("Conversation Not Exists.") from caught_error
except services.errors.conversation.ConversationCompletedError as caught_error:
raise ConversationCompletedError() from caught_error
except services.errors.app_model_config.AppModelConfigBrokenError as caught_error:
logger.exception("App model config broken.")
raise AppUnavailableError() from caught_error
except AgentAppNotPublishedError as caught_error:
raise AgentNotPublishedError() from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
except QuotaExceededError as caught_error:
raise ProviderQuotaExceededError() from caught_error
except ModelCurrentlyNotSupportError as caught_error:
raise ProviderModelCurrentlyNotSupportError() from caught_error
except InvokeError as e:
raise CompletionRequestError(e.description) from e
except ValueError as e:
raise e
except Exception as caught_error:
logger.exception("internal server error.")
raise InternalServerError() from caught_error
@service_api_ns.route("/completion-messages/<string:task_id>/stop")
class CompletionStopApi(Resource):
@error_responses(AppUnavailableError)
@service_api_ns.doc(
summary="Stop Completion Message Generation",
description="Stops a completion message generation task. Only supported in `streaming` mode.",
tags=["Completions"],
responses={
400: "`app_unavailable` : App unavailable or misconfigured.",
},
)
@expect_user_json(
service_api_ns,
model_name="ScopedTaskStopPayload",
user_description=SCOPED_TASK_STOP_USER_DESCRIPTION,
)
@service_api_ns.doc("stop_completion")
@service_api_ns.doc(description="Stop a running completion task")
@service_api_ns.doc(
params={"task_id": ("Task ID, obtained from a streaming chunk returned by the Send Completion Message API.")}
)
@service_api_ns.doc(
responses={
200: "Task stopped successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(200, "Task stopped successfully", service_api_ns.models[SimpleResultResponse.__name__])
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
def post(self, app_model: App, end_user: EndUser, task_id: str):
"""Stop a running completion task."""
if app_model.mode != AppMode.COMPLETION:
raise AppUnavailableError()
AppTaskService.stop_task(
tenant_id=app_model.tenant_id,
app_id=app_model.id,
task_id=task_id,
invoke_from=InvokeFrom.SERVICE_API,
user_id=end_user.id,
app_mode=AppMode.value_of(app_model.mode),
)
return SimpleResultResponse(result="success").model_dump(mode="json"), 200
@service_api_ns.route("/chat-messages")
class ChatApi(Resource):
@error_responses(
AgentNotPublishedError,
AppUnavailableError,
CompletionRequestError,
InvokeRateLimitHttpError,
NotChatAppError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
WorkflowVersionExecutionNotAllowedError,
)
@service_api_ns.doc(
summary="Send Chat Message",
description="Send a request to the chat application.",
tags=["Chats", "Chatflows"],
responses={
200: (
"Successful response. The content type and structure depend on the `response_mode` parameter "
"in the request.\n"
"\n"
"- If `response_mode` is `blocking`, returns `application/json` with a "
"`ChatCompletionResponse` object.\n"
"- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of "
"Server-Sent Events."
),
400: (
"- `app_unavailable` : App unavailable or misconfigured.\n"
"- `not_chat_app` : App mode does not match the API route.\n"
"- `conversation_completed` : The conversation has ended.\n"
"- `provider_not_initialize` : No valid model provider credentials found.\n"
"- `provider_quota_exceeded` : Model provider quota exhausted.\n"
"- `model_currently_not_support` : Current model unavailable.\n"
"- `completion_request_error` : Text generation failed."
),
403: (
"`workflow_version_execution_not_allowed` : Workflow version execution is unavailable on the "
"current plan. Upgrade to a paid plan."
),
404: "`not_found` : Conversation does not exist.",
429: (
"- `too_many_requests` : Too many concurrent requests for this app.\n"
"- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached."
),
500: "`internal_server_error` : Internal server error.",
},
)
@expect_with_user(service_api_ns, ChatRequestPayload)
@json_or_event_stream_response(service_api_ns)
@service_api_ns.doc("create_chat_message")
@service_api_ns.doc(description="Send a message in a chat conversation")
@service_api_ns.doc(
responses={
200: "Message sent successfully",
400: "Bad request - invalid parameters or workflow issues",
401: "Unauthorized - invalid API token",
403: "Forbidden - upgrade to a paid plan to execute a specific workflow version",
404: "Conversation or workflow not found",
429: "Rate limit exceeded",
500: "Internal server error",
}
)
@service_api_ns.response(
200,
"Message sent successfully",
service_api_ns.models[ChatBlockingResponse.__name__],
)
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
@with_session
def post(self, session: Session, app_model: App, end_user: EndUser):
"""Send a message in a chat conversation.
This endpoint handles chat messages for chat, agent chat, and advanced chat applications.
Supports conversation management and both blocking and streaming response modes.
"""
app_mode = AppMode.value_of(app_model.mode)
if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
raise NotChatAppError()
payload = ChatRequestPayload.model_validate(omit_trace_session_id_from_payload(service_api_ns.payload) or {})
if (
app_mode == AppMode.ADVANCED_CHAT
and payload.workflow_id
and dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD
):
billing_info = BillingService.get_info(app_model.tenant_id, exclude_vector_space=True)
if billing_info.subscription.plan == CloudPlan.SANDBOX:
raise WorkflowVersionExecutionNotAllowedError()
external_trace_id = get_external_trace_id(request)
args = payload.model_dump(exclude_none=True)
trace_session_id = get_trace_session_id(request)
if trace_session_id:
args["trace_session_id"] = trace_session_id
if external_trace_id:
args["external_trace_id"] = external_trace_id
streaming = _resolve_agent_app_streaming(app_mode=app_mode, response_mode=payload.response_mode)
try:
# Eagerly validate conversation to avoid hanging on invalid conversation_id
if payload.conversation_id:
ConversationService.get_conversation(
app_model=app_model,
conversation_id=payload.conversation_id,
user=end_user,
session=session,
)
response = AppGenerateService.generate(
session=session,
app_model=app_model,
user=end_user,
args=args,
invoke_from=InvokeFrom.SERVICE_API,
streaming=streaming,
)
# response-contract:ignore compact_generate_response
return helper.compact_generate_response(response)
except WorkflowNotFoundError as ex:
raise NotFound(str(ex)) from ex
except IsDraftWorkflowError as ex:
raise BadRequest(str(ex)) from ex
except WorkflowIdFormatError as ex:
raise BadRequest(str(ex)) from ex
except services.errors.conversation.ConversationNotExistsError as caught_error:
raise NotFound("Conversation Not Exists.") from caught_error
except services.errors.conversation.ConversationCompletedError as caught_error:
raise ConversationCompletedError() from caught_error
except services.errors.app_model_config.AppModelConfigBrokenError as caught_error:
logger.exception("App model config broken.")
raise AppUnavailableError() from caught_error
except AgentAppNotPublishedError as caught_error:
raise AgentNotPublishedError() from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
except QuotaExceededError as caught_error:
raise ProviderQuotaExceededError() from caught_error
except ModelCurrentlyNotSupportError as caught_error:
raise ProviderModelCurrentlyNotSupportError() from caught_error
except InvokeRateLimitError as ex:
raise InvokeRateLimitHttpError(ex.description) from ex
except InvokeError as e:
raise CompletionRequestError(e.description) from e
except ValueError as e:
raise e
except Exception as caught_error:
logger.exception("internal server error.")
raise InternalServerError() from caught_error
@service_api_ns.route("/chat-messages/<string:task_id>/stop")
class ChatStopApi(Resource):
@error_responses(NotChatAppError)
@service_api_ns.doc(
summary="Stop Chat Message Generation",
description="Stops a chat message generation task. Only supported in `streaming` mode.",
tags=["Chats", "Chatflows"],
responses={
400: "`not_chat_app` : App mode does not match the API route.",
},
)
@expect_user_json(
service_api_ns,
model_name="ScopedTaskStopPayload",
user_description=SCOPED_TASK_STOP_USER_DESCRIPTION,
)
@service_api_ns.doc("stop_chat_message")
@service_api_ns.doc(description="Stop a running chat message generation")
@service_api_ns.doc(
params={"task_id": "Task ID, obtained from a streaming chunk returned by the Send Chat Message API."}
)
@service_api_ns.doc(
responses={
200: "Task stopped successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(200, "Task stopped successfully", service_api_ns.models[SimpleResultResponse.__name__])
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
def post(self, app_model: App, end_user: EndUser, task_id: str):
"""Stop a running chat message generation."""
app_mode = AppMode.value_of(app_model.mode)
if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
raise NotChatAppError()
AppTaskService.stop_task(
tenant_id=app_model.tenant_id,
app_id=app_model.id,
task_id=task_id,
invoke_from=InvokeFrom.SERVICE_API,
user_id=end_user.id,
app_mode=app_mode,
)
return SimpleResultResponse(result="success").model_dump(mode="json"), 200
@@ -0,0 +1,469 @@
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
@@ -0,0 +1,163 @@
from http import HTTPStatus
from libs.exception import BaseHTTPException
from services.errors.app import (
TRIGGER_WORKFLOW_SERVICE_MODE_UNAVAILABLE_CODE,
TRIGGER_WORKFLOW_SERVICE_MODE_UNAVAILABLE_MESSAGE,
)
class AppNotFoundError(BaseHTTPException):
error_code = "app_not_found"
description = "The app no longer exists."
code = HTTPStatus.FORBIDDEN
class AppAbnormalStatusError(BaseHTTPException):
error_code = "app_abnormal_status"
description = "The app's status is abnormal."
code = HTTPStatus.FORBIDDEN
class AppApiDisabledError(BaseHTTPException):
error_code = "app_api_disabled"
description = "The app's API service has been disabled."
code = HTTPStatus.FORBIDDEN
class WorkspaceNotFoundError(BaseHTTPException):
error_code = "workspace_not_found"
description = "Tenant does not exist."
code = HTTPStatus.FORBIDDEN
class WorkspaceArchivedError(BaseHTTPException):
error_code = "workspace_archived"
description = "The workspace's status is archived."
code = HTTPStatus.FORBIDDEN
class AppUnavailableError(BaseHTTPException):
error_code = "app_unavailable"
description = "App unavailable, please check your app configurations."
code = 400
class AgentNotPublishedError(BaseHTTPException):
error_code = "agent_not_published"
description = "Agent has not been published. Please publish the Agent before using the API."
code = 400
class NotCompletionAppError(BaseHTTPException):
error_code = "not_completion_app"
description = "Please check if your Completion app mode matches the right API route."
code = 400
class NotChatAppError(BaseHTTPException):
error_code = "not_chat_app"
description = "Please check if your app mode matches the right API route."
code = 400
class NotWorkflowAppError(BaseHTTPException):
error_code = "not_workflow_app"
description = "Please check if your app mode matches the right API route."
code = 400
class WorkflowVersionExecutionNotAllowedError(BaseHTTPException):
error_code = "workflow_version_execution_not_allowed"
description = "Workflow version execution is not available on your current plan. Please upgrade to a paid plan."
code = 403
class TriggerWorkflowServiceModeUnavailableError(BaseHTTPException):
error_code = TRIGGER_WORKFLOW_SERVICE_MODE_UNAVAILABLE_CODE
description = TRIGGER_WORKFLOW_SERVICE_MODE_UNAVAILABLE_MESSAGE
code = 403
class ConversationCompletedError(BaseHTTPException):
error_code = "conversation_completed"
description = "The conversation has ended. Please start a new conversation."
code = 400
class ProviderNotInitializeError(BaseHTTPException):
error_code = "provider_not_initialize"
description = (
"No valid model provider credentials found. "
"Please go to Settings -> Model Provider to complete your provider credentials."
)
code = 400
class ProviderQuotaExceededError(BaseHTTPException):
error_code = "provider_quota_exceeded"
description = (
"Your quota for Dify Hosted OpenAI has been exhausted. "
"Please go to Settings -> Model Provider to complete your own provider credentials."
)
code = 400
class ProviderModelCurrentlyNotSupportError(BaseHTTPException):
error_code = "model_currently_not_support"
description = "Dify Hosted OpenAI trial currently not support the GPT-4 model."
code = 400
class CompletionRequestError(BaseHTTPException):
error_code = "completion_request_error"
description = "Completion request failed."
code = 400
class AppSuggestedQuestionsAfterAnswerDisabledError(BaseHTTPException):
error_code = "app_suggested_questions_after_answer_disabled"
description = "The 'Suggested Questions After Answer' feature is disabled."
code = 403
class NoAudioUploadedError(BaseHTTPException):
error_code = "no_audio_uploaded"
description = "Please upload your audio."
code = 400
class AudioTooLargeError(BaseHTTPException):
error_code = "audio_too_large"
description = "Audio size exceeded. {message}"
code = 413
class UnsupportedAudioTypeError(BaseHTTPException):
error_code = "unsupported_audio_type"
description = "Audio type not allowed."
code = 415
class ProviderNotSupportSpeechToTextError(BaseHTTPException):
error_code = "provider_not_support_speech_to_text"
description = "Provider not support speech to text."
code = 400
class SpeechToTextDisabledError(BaseHTTPException):
error_code = "speech_to_text_disabled"
description = "Speech to text is disabled."
code = 400
class FileNotFoundError(BaseHTTPException):
error_code = "file_not_found"
description = "The requested file was not found."
code = 404
class FileAccessDeniedError(BaseHTTPException):
error_code = "file_access_denied"
description = "Access to the requested file is denied."
code = 403
@@ -0,0 +1,103 @@
from flask import request
from flask_restx import Resource
from flask_restx.api import HTTPStatus
import services
from controllers.common.errors import (
BlockedFileExtensionError,
FilenameNotExistsError,
FileTooLargeError,
NoFileUploadedError,
TooManyFilesError,
UnsupportedFileTypeError,
)
from controllers.common.schema import JsonResponseWithStatus, register_response_schema_models
from controllers.service_api import service_api_ns
from controllers.service_api.schema import multipart_file_params
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
from extensions.ext_application_services import application_services
from fields.file_fields import FileResponse
from libs.external_api import error_responses
from libs.helper import dump_response
from models import App, EndUser
register_response_schema_models(service_api_ns, FileResponse)
@service_api_ns.route("/files/upload")
class FileApi(Resource):
@error_responses(
BlockedFileExtensionError,
FilenameNotExistsError,
FileTooLargeError,
NoFileUploadedError,
TooManyFilesError,
UnsupportedFileTypeError,
)
@service_api_ns.doc(
summary="Upload File",
description=(
"Upload a file for use when sending messages, enabling multimodal understanding of images, "
"documents, audio, and video. Uploaded files are for use by the current end-user only."
),
tags=["Files"],
responses={
201: "File uploaded successfully.",
400: (
"- `no_file_uploaded` : No file was provided in the request.\n"
"- `too_many_files` : Only one file is allowed per request.\n"
"- `filename_not_exists_error` : The uploaded file has no filename.\n"
"- `file_extension_blocked` : The file extension is blocked for security reasons."
),
413: "`file_too_large` : File size exceeded.",
415: "`unsupported_file_type` : File type not allowed.",
},
)
@service_api_ns.doc("upload_file")
@service_api_ns.doc(description="Upload a file for use in conversations")
@service_api_ns.doc(consumes=["multipart/form-data"], params=multipart_file_params(include_user=True))
@service_api_ns.doc(
responses={
201: "File uploaded successfully",
400: "Bad request - no file or invalid file",
401: "Unauthorized - invalid API token",
413: "File too large",
415: "Unsupported file type",
}
)
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.FORM)) # type: ignore
@service_api_ns.response(HTTPStatus.CREATED, "File uploaded", service_api_ns.models[FileResponse.__name__])
def post(self, app_model: App, end_user: EndUser) -> JsonResponseWithStatus:
"""Upload a file for use in conversations.
Accepts a single file upload via multipart/form-data.
"""
# check file
if "file" not in request.files:
raise NoFileUploadedError()
if len(request.files) > 1:
raise TooManyFilesError()
file = request.files["file"]
if not file.mimetype:
raise UnsupportedFileTypeError()
if not file.filename:
raise FilenameNotExistsError()
try:
upload_file = application_services().files.upload_file(
filename=file.filename,
content=file.stream.read(),
mimetype=file.mimetype,
user=end_user,
)
except services.errors.file.FileTooLargeError as file_too_large_error:
raise FileTooLargeError(file_too_large_error.description) from file_too_large_error
except services.errors.file.UnsupportedFileTypeError as unsupported_file_type_error:
raise UnsupportedFileTypeError() from unsupported_file_type_error
except services.errors.file.BlockedFileExtensionError as blocked_file_extension_error:
raise BlockedFileExtensionError() from blocked_file_extension_error
return dump_response(FileResponse, upload_file), 201
@@ -0,0 +1,171 @@
from urllib.parse import quote
from uuid import UUID
from flask import Response
from flask_restx import Resource
from pydantic import BaseModel, Field
from controllers.common.fields import BinaryFileResponse
from controllers.common.file_response import enforce_download_for_html
from controllers.common.schema import query_params_from_model, register_response_schema_model, register_schema_model
from controllers.console.wraps import model_validate
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import (
FileAccessDeniedError,
FileNotFoundError,
)
from controllers.service_api.schema import binary_response
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
from extensions.ext_application_services import application_services
from libs.external_api import error_responses
from models.model import App, EndUser
from services.message_file_preview_service import (
MessageFilePreview,
MessageFilePreviewAccessDeniedError,
MessageFilePreviewNotFoundError,
)
class FilePreviewQuery(BaseModel):
as_attachment: bool = Field(
default=False,
description="If `true`, forces the file to download as an attachment instead of previewing in browser.",
)
register_schema_model(service_api_ns, FilePreviewQuery)
register_response_schema_model(service_api_ns, BinaryFileResponse)
FILE_PREVIEW_RESPONSE_MEDIA_TYPE = "*/*"
_RANGE_MEDIA_TYPES = frozenset(
{
"audio/aac",
"audio/flac",
"audio/mp4",
"audio/mpeg",
"audio/ogg",
"audio/wav",
"audio/x-m4a",
"video/mp4",
"video/quicktime",
"video/webm",
}
)
@service_api_ns.route("/files/<uuid:file_id>/preview")
class FilePreviewApi(Resource):
"""
Service API File Preview endpoint
Provides secure file preview/download functionality for external API users.
Files can only be accessed if they belong to messages within the requesting app's context.
"""
@error_responses(FileAccessDeniedError, FileNotFoundError)
@service_api_ns.doc(
summary="Download File",
description=(
"Preview or download uploaded files previously uploaded via the [Upload "
"File](/api-reference/files/upload-file) API. Files can only be accessed if they belong to "
"messages within the requesting application."
),
tags=["Files"],
responses={
200: (
"Returns the raw file content. The `Content-Type` header is set to the file's MIME type. If "
"`as_attachment` is `true`, the file is returned as a download with `Content-Disposition: "
"attachment`."
),
403: "`file_access_denied` : Access to the requested file is denied.",
404: "`file_not_found` : The requested file was not found.",
},
)
@service_api_ns.doc(params=query_params_from_model(FilePreviewQuery))
@binary_response(service_api_ns, FILE_PREVIEW_RESPONSE_MEDIA_TYPE)
@service_api_ns.doc("preview_file")
@service_api_ns.doc(description="Preview or download a file uploaded via Service API")
@service_api_ns.doc(
params={
"file_id": (
"The unique identifier of the file to preview, obtained from the "
"[Upload File](/api-reference/files/upload-file) API response."
)
}
)
@service_api_ns.doc(
responses={
200: "File retrieved successfully",
401: "Unauthorized - invalid API token",
403: "Forbidden - file access denied",
404: "File not found",
}
)
@service_api_ns.response(200, "File retrieved successfully")
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
@model_validate(FilePreviewQuery)
def get(self, args: FilePreviewQuery, app_model: App, end_user: EndUser, file_id: UUID) -> Response:
"""
Preview/Download a file that was uploaded via Service API.
Provides secure file preview/download functionality.
Files can only be accessed if they belong to messages within the requesting app's context.
"""
try:
preview = application_services().message_file_previews.get_preview(
file_id=str(file_id),
app_id=app_model.id,
tenant_id=app_model.tenant_id,
)
except MessageFilePreviewNotFoundError as error:
raise FileNotFoundError() from error
except MessageFilePreviewAccessDeniedError as error:
raise FileAccessDeniedError() from error
return self._build_file_response(preview=preview, as_attachment=args.as_attachment)
def _build_file_response(self, *, preview: MessageFilePreview, as_attachment: bool = False) -> Response:
"""
Build Flask Response object with appropriate headers for file streaming
Args:
preview: App-scoped file metadata and content stream
as_attachment: Whether to set Content-Disposition as attachment
Returns:
Flask Response object with streaming file content
"""
file = preview.file
response = Response(
preview.content,
mimetype=file.mime_type,
direct_passthrough=True,
headers={},
)
# Add Content-Length if known
if file.size > 0:
response.headers["Content-Length"] = str(file.size)
# Add Accept-Ranges header for audio/video files to support seeking
if file.mime_type in _RANGE_MEDIA_TYPES:
response.headers["Accept-Ranges"] = "bytes"
# Set Content-Disposition for downloads
if as_attachment and file.name:
encoded_filename = quote(file.name)
response.headers["Content-Disposition"] = f"attachment; filename*=UTF-8''{encoded_filename}"
# Override content-type for downloads to force download
response.headers["Content-Type"] = "application/octet-stream"
enforce_download_for_html(
response,
mime_type=file.mime_type,
filename=file.name,
extension=file.extension,
)
# Add caching headers for performance
response.headers["Cache-Control"] = "public, max-age=3600" # Cache for 1 hour
return response
@@ -0,0 +1,268 @@
"""
Service API human input form endpoints.
This module exposes app-token authenticated APIs for fetching and submitting
paused human input forms in workflow/chatflow runs.
"""
import json
import logging
from collections.abc import Sequence
from typing import Annotated, NoReturn
from flask import Response, request
from flask_restx import Resource
from pydantic import ConfigDict, WithJsonSchema
from werkzeug.exceptions import BadRequest, NotFound
from controllers.common.human_input import HumanInputFormSubmitPayload, stringify_form_default_values
from controllers.common.schema import 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.schema import expect_with_user
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
from core.db.session_factory import session_factory
from core.human_input_v2.shared.values import TenantId
from core.workflow.human_input_policy import HumanInputSurface, is_recipient_type_allowed_for_surface
from core.workflow.nodes.human_input.entities import FormInputConfig, UserActionConfig
from extensions.ext_database import db
from factories.human_input_v2_form_presentation import build_form_presentation
from fields.base import ResponseModel
from libs.external_api import error_responses
from libs.helper import extract_remote_ip, to_timestamp
from models.model import App, EndUser
from repositories.human_input_v2.form_repository import Form as V2Form
from services.human_input_service import (
Form,
FormExpiredError,
FormNotFoundError,
FormSubmittedError,
InvalidFormDataError,
ServiceAPIHumanInputService,
)
from services.human_input_v2.submission_service import (
HumanInputFormError,
HumanInputFormErrorCode,
HumanInputSubmissionService,
ServiceAPIFormActor,
)
logger = logging.getLogger(__name__)
Int64 = Annotated[int, WithJsonSchema({"format": "int64", "type": "integer"})]
class HumanInputFormDefinitionResponse(ResponseModel):
form_content: str
inputs: list[FormInputConfig]
resolved_default_values: dict[str, str]
user_actions: list[UserActionConfig]
expiration_time: Int64 | None = None
class HumanInputFormSubmitResponse(ResponseModel):
model_config = ConfigDict(extra="forbid")
register_schema_models(service_api_ns, HumanInputFormSubmitPayload)
register_response_schema_models(
service_api_ns,
HumanInputFormDefinitionResponse,
HumanInputFormSubmitResponse,
)
def _jsonify_form_definition(form: Form, *, inputs: Sequence[FormInputConfig] = ()) -> Response:
definition_payload = form.get_definition().model_dump(mode="json")
payload = {
"form_content": definition_payload["rendered_content"],
"inputs": [form_input.model_dump(mode="json") for form_input in inputs],
"resolved_default_values": stringify_form_default_values(definition_payload["default_values"]),
"user_actions": definition_payload["user_actions"],
"expiration_time": to_timestamp(form.expiration_time),
}
return Response(json.dumps(payload, ensure_ascii=False), mimetype="application/json")
def _ensure_form_belongs_to_app(form: Form, app_model: App) -> None:
if form.app_id != app_model.id or form.tenant_id != app_model.tenant_id:
raise NotFound("Form not found")
def _ensure_form_is_allowed_for_service_api(form: Form) -> None:
# Keep app-token callers scoped to the public web-form surface; internal HITL
# routes must continue to flow through console-only authentication.
if not is_recipient_type_allowed_for_surface(form.recipient_type, HumanInputSurface.SERVICE_API):
raise NotFound("Form not found")
def _jsonify_v2_form_definition(form: V2Form) -> Response:
presentation = build_form_presentation(form.resolved_form)
response = HumanInputFormDefinitionResponse(
form_content=presentation.form_content,
inputs=presentation.inputs,
resolved_default_values=presentation.resolved_default_values,
user_actions=presentation.user_actions,
expiration_time=to_timestamp(min(form.expiration_time, form.global_timeout_deadline)),
)
return Response(response.model_dump_json(), mimetype="application/json")
def _raise_form_error(error: HumanInputFormError) -> NoReturn:
# Keep the existing Service API errors instead of leaking Web App v2's
# 409/410 statuses or its transport-specific error codes.
match error.code:
case HumanInputFormErrorCode.NOT_FOUND:
raise NotFound("Form not found") from error
case HumanInputFormErrorCode.ALREADY_SUBMITTED:
assert error.form_id is not None
raise FormSubmittedError(error.form_id) from error
case HumanInputFormErrorCode.EXPIRED:
assert error.form_id is not None
raise FormExpiredError(error.form_id) from error
case HumanInputFormErrorCode.INVALID_INPUT:
description = str(error.__cause__) if error.__cause__ is not None else "Invalid form data"
raise InvalidFormDataError(description) from error
case HumanInputFormErrorCode.WORKFLOW_NOT_ACTIVE:
raise BadRequest("The workflow is not paused with an active checkpoint.") from error
@service_api_ns.route("/form/human_input/<string:form_token>")
class WorkflowHumanInputFormApi(Resource):
@error_responses(FormExpiredError, FormSubmittedError)
@service_api_ns.doc(
summary="Get Human Input Form",
description=(
"Retrieve a paused Human Input form's contents using the `form_token` from a "
"`human_input_required` event. Requires **WebApp** delivery."
),
tags=["Human Input"],
responses={
200: "Form contents retrieved successfully.",
404: "`not_found` : Form not found.",
412: (
"- `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first "
"response wins regardless of which user submits it.\n"
"- `human_input_form_expired` : The form's expiration time passed before submission arrived."
),
},
)
@service_api_ns.doc("get_human_input_form")
@service_api_ns.doc(description="Get a paused human input form by token")
@service_api_ns.doc(params={"form_token": "Human input form token"})
@service_api_ns.doc(
responses={
200: "Form retrieved successfully",
401: "Unauthorized - invalid API token",
404: "Form not found",
412: "Form already submitted or expired",
}
)
@service_api_ns.response(
200,
"Form retrieved successfully",
service_api_ns.models[HumanInputFormDefinitionResponse.__name__],
)
@validate_app_token
def get(self, app_model: App, form_token: str):
service = ServiceAPIHumanInputService(db.engine)
form = service.get_form_by_token(form_token)
if form is None:
v2_service = HumanInputSubmissionService(session_factory=session_factory.get_session_maker())
try:
v2_form = v2_service.get_service_api_form(
actor=ServiceAPIFormActor(tenant_id=TenantId(app_model.tenant_id), app_id=app_model.id),
form_token=form_token,
ip_address=extract_remote_ip(request) or None,
)
except HumanInputFormError as error:
_raise_form_error(error)
return _jsonify_v2_form_definition(v2_form)
_ensure_form_belongs_to_app(form, app_model)
_ensure_form_is_allowed_for_service_api(form)
service.ensure_form_active(form)
inputs = service.resolve_form_inputs(form)
return _jsonify_form_definition(form, inputs=inputs)
@error_responses(FormExpiredError, FormSubmittedError, InvalidFormDataError)
@service_api_ns.doc(
summary="Submit Human Input Form",
description=(
"Submit the recipient's response to a paused Human Input form. The workflow resumes on "
"acceptance; use [Stream Workflow Events](/api-reference/chatflows/stream-workflow-events) "
"to follow subsequent events. Requires **WebApp** delivery."
),
tags=["Human Input"],
responses={
200: "Form submitted successfully. The response body is an empty object.",
400: (
"- `bad_request` : Form recipient type is invalid.\n"
"- `invalid_form_data` : Submission failed validation against the form definition."
),
404: "`not_found` : Form not found.",
412: (
"- `human_input_form_submitted` : Form already submitted. Forms are one-shot; the first "
"response wins regardless of which user submits it.\n"
"- `human_input_form_expired` : The form's expiration time passed before submission arrived."
),
},
)
@expect_with_user(service_api_ns, HumanInputFormSubmitPayload)
@service_api_ns.doc("submit_human_input_form")
@service_api_ns.doc(description="Submit a paused human input form by token")
@service_api_ns.doc(params={"form_token": "Human input form token"})
@service_api_ns.doc(
responses={
200: "Form submitted successfully",
400: "Bad request - invalid submission data",
401: "Unauthorized - invalid API token",
404: "Form not found",
412: "Form already submitted or expired",
}
)
@service_api_ns.response(
200,
"Form submitted successfully",
service_api_ns.models[HumanInputFormSubmitResponse.__name__],
)
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
@model_validate(HumanInputFormSubmitPayload)
def post(self, payload: HumanInputFormSubmitPayload, app_model: App, end_user: EndUser, form_token: str):
service = ServiceAPIHumanInputService(db.engine)
form = service.get_form_by_token(form_token)
if form is None:
v2_service = HumanInputSubmissionService(session_factory=session_factory.get_session_maker())
try:
v2_service.submit_service_api_form(
actor=ServiceAPIFormActor(tenant_id=TenantId(app_model.tenant_id), app_id=app_model.id),
end_user_id=end_user.id,
form_token=form_token,
action=payload.action,
inputs=payload.inputs,
)
except HumanInputFormError as error:
_raise_form_error(error)
return {}, 200
_ensure_form_belongs_to_app(form, app_model)
_ensure_form_is_allowed_for_service_api(form)
recipient_type = form.recipient_type
if recipient_type is None:
logger.warning("Recipient type is None for form, form_id=%s", form.id)
raise BadRequest("Form recipient type is invalid")
try:
service.submit_form_by_token(
recipient_type=recipient_type,
form_token=form_token,
selected_action_id=payload.action,
form_data=payload.inputs,
submission_end_user_id=end_user.id,
)
except FormNotFoundError as caught_error:
raise NotFound("Form not found") from caught_error
return {}, 200
@@ -0,0 +1,377 @@
import logging
from http import HTTPStatus
from typing import Annotated
from uuid import UUID
from flask_restx import Resource
from pydantic import BaseModel, Field, WithJsonSchema
from controllers.common.controller_schemas import MessageFeedbackPayload, MessageListQuery
from controllers.common.errors import InternalServerError, MessageFeedbackRatingRequiredError, NotFoundError
from controllers.common.fields import SimpleResultStringListResponse
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 (
AppSuggestedQuestionsAfterAnswerDisabledError,
AppUnavailableError,
CompletionRequestError,
NotChatAppError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
)
from controllers.service_api.flask_admission import service_api_app_admission, service_api_end_user_admission
from controllers.service_api.schema import expect_with_user
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg
from core.errors.error import ModelCurrentlyNotSupportError, ProviderTokenNotInitError, QuotaExceededError
from extensions.ext_application_services import application_services
from fields.base import ResponseModel
from fields.conversation_fields import ResultResponse
from fields.message_fields import MessageInfiniteScrollPagination, MessageListItem
from graphon.model_runtime.errors.invoke import InvokeError
from libs.external_api import error_responses
from libs.helper import dump_response
from machinery.context import AppRequestContext, ServiceApiEndUserContext
from models.enums import FeedbackRating
from models.model import AppMode
from services.agent.errors import AgentVersionNotFoundError
from services.app_definition_query_service import AppDefinitionUnavailableError
from services.entities.message_entities import MessageEndUser
from services.errors.conversation import ConversationNotExistsError
from services.errors.message import (
FeedbackRatingRequiredError,
FirstMessageNotExistsError,
MessageActorNotFoundError,
MessageNotExistsError,
SuggestedQuestionsAfterAnswerDisabledError,
)
logger = logging.getLogger(__name__)
UUIDString = Annotated[str, WithJsonSchema({"format": "uuid", "type": "string"})]
class FeedbackListQuery(BaseModel):
page: int = Field(default=1, ge=1, description="Page number for pagination.")
limit: int = Field(default=20, ge=1, le=101, description="Number of records per page.")
class AppFeedbackResponse(ResponseModel):
id: UUIDString
app_id: UUIDString
conversation_id: UUIDString
message_id: UUIDString
rating: str
content: str | None = None
from_source: str
from_end_user_id: UUIDString | None = None
from_account_id: UUIDString | None = None
created_at: str
updated_at: str
class AppFeedbackListResponse(ResponseModel):
data: list[AppFeedbackResponse]
register_schema_models(service_api_ns, MessageListQuery, MessageFeedbackPayload, FeedbackListQuery)
register_response_schema_models(
service_api_ns,
ResultResponse,
SimpleResultStringListResponse,
MessageInfiniteScrollPagination,
MessageListItem,
AppFeedbackListResponse,
)
@service_api_ns.route("/messages")
class MessageListApi(Resource):
@error_responses(AppUnavailableError, NotChatAppError)
@service_api_ns.doc("list_messages")
@service_api_ns.doc(
summary="List Conversation Messages",
description=(
"Returns historical chat records in a scrolling load format, with the first page returning "
"the latest `limit` messages, i.e., in reverse order."
),
tags=["Conversations"],
responses={
HTTPStatus.OK: "Successfully retrieved conversation history.",
HTTPStatus.BAD_REQUEST: (
"`not_chat_app` : App mode does not match the API route. "
"`app_unavailable` : App is no longer available."
),
HTTPStatus.NOT_FOUND: (
"- `not_found` : Conversation does not exist.\n- `not_found` : First message does not exist."
),
},
)
@service_api_ns.doc(params=query_params_from_model(MessageListQuery))
@service_api_ns.doc(description="List messages in a conversation")
@service_api_ns.doc(
responses={
HTTPStatus.OK: "Messages retrieved successfully",
HTTPStatus.BAD_REQUEST: (
"`not_chat_app` : App mode does not match the API route. "
"`app_unavailable` : App is no longer available."
),
HTTPStatus.UNAUTHORIZED: "Unauthorized - invalid API token",
HTTPStatus.NOT_FOUND: "Conversation or first message not found",
}
)
@service_api_ns.response(
HTTPStatus.OK,
"Messages retrieved successfully",
service_api_ns.models[MessageInfiniteScrollPagination.__name__],
)
@service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY))
@model_validate(MessageListQuery)
def get(self, query_args: MessageListQuery, context: ServiceApiEndUserContext) -> dict[str, object]:
"""List messages in a conversation.
Retrieves messages with pagination support using first_id.
"""
app_mode = context.app_mode
if app_mode not in {AppMode.CHAT, AppMode.AGENT_CHAT, AppMode.ADVANCED_CHAT, AppMode.AGENT}:
raise NotChatAppError()
try:
pagination = application_services().message_queries.get_page(
app_id=context.app_id,
app_owner_tenant_id=context.tenant_id,
actor=MessageEndUser(end_user_id=context.end_user_id),
conversation_id=query_args.conversation_id,
first_id=query_args.first_id or None,
limit=query_args.limit,
)
return dump_response(MessageInfiniteScrollPagination, pagination)
except AppDefinitionUnavailableError as error:
raise AppUnavailableError() from error
except MessageActorNotFoundError as error:
raise NotFoundError("End user not found") from error
except ConversationNotExistsError as error:
raise NotFoundError("Conversation Not Exists.") from error
except FirstMessageNotExistsError as error:
raise NotFoundError("First Message Not Exists.") from error
@service_api_ns.route("/messages/<uuid:message_id>/feedbacks")
class MessageFeedbackApi(Resource):
@error_responses(AppUnavailableError, MessageFeedbackRatingRequiredError)
@expect_with_user(service_api_ns, MessageFeedbackPayload)
@service_api_ns.response(
HTTPStatus.OK, "Feedback submitted successfully", service_api_ns.models[ResultResponse.__name__]
)
@service_api_ns.doc("create_message_feedback")
@service_api_ns.doc(
summary="Submit Message Feedback",
description=(
"Submit feedback for a message. End users can rate messages as `like` or `dislike`, and "
"optionally provide text feedback. Pass `null` for `rating` to revoke previously submitted feedback."
),
tags=["Feedback"],
responses={
HTTPStatus.NOT_FOUND: "`not_found` : Message does not exist.",
},
)
@service_api_ns.doc(description="Submit feedback for a message")
@service_api_ns.doc(params={"message_id": "Message ID."})
@service_api_ns.doc(
responses={
HTTPStatus.OK: "Feedback submitted successfully",
HTTPStatus.BAD_REQUEST: (
"`message_feedback_rating_required`: Cannot revoke feedback that does not exist. "
"`app_unavailable`: App is no longer available."
),
HTTPStatus.UNAUTHORIZED: "Unauthorized - invalid API token",
HTTPStatus.NOT_FOUND: "Message not found",
}
)
@service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
@model_validate(MessageFeedbackPayload)
def post(
self,
payload: MessageFeedbackPayload,
context: ServiceApiEndUserContext,
message_id: UUID,
) -> dict[str, object]:
"""Submit feedback for a message.
Allows users to rate messages as like/dislike and provide optional feedback content.
"""
message_id_str = str(message_id)
try:
application_services().message_feedbacks.set_feedback(
app_id=context.app_id,
app_owner_tenant_id=context.tenant_id,
message_id=message_id_str,
actor=MessageEndUser(end_user_id=context.end_user_id),
rating=FeedbackRating(payload.rating) if payload.rating else None,
content=payload.content,
)
except AppDefinitionUnavailableError as error:
raise AppUnavailableError() from error
except MessageActorNotFoundError as error:
raise NotFoundError("End user not found") from error
except MessageNotExistsError as error:
raise NotFoundError("Message Not Exists.") from error
except FeedbackRatingRequiredError as error:
raise MessageFeedbackRatingRequiredError() from error
return dump_response(ResultResponse, {"result": "success"})
@service_api_ns.route("/app/feedbacks")
class AppGetFeedbacksApi(Resource):
@error_responses(AppUnavailableError)
@service_api_ns.doc("get_app_feedbacks")
@service_api_ns.doc(
summary="List App Feedbacks",
description=(
"Retrieve a paginated list of all feedback submitted for messages in this application, including both "
"end-user and admin feedback."
),
tags=["Feedback"],
responses={
HTTPStatus.OK: "A list of application feedbacks.",
},
)
@service_api_ns.doc(params=query_params_from_model(FeedbackListQuery))
@service_api_ns.doc(description="Get all feedbacks for the application")
@service_api_ns.doc(
responses={
HTTPStatus.OK: "Feedbacks retrieved successfully",
HTTPStatus.BAD_REQUEST: "`app_unavailable`: App is no longer available.",
HTTPStatus.UNAUTHORIZED: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(
HTTPStatus.OK,
"Feedbacks retrieved successfully",
service_api_ns.models[AppFeedbackListResponse.__name__],
)
@service_api_app_admission
@model_validate(FeedbackListQuery)
def get(self, query_args: FeedbackListQuery, context: AppRequestContext) -> dict[str, object]:
"""Get all feedbacks for the application.
Returns paginated list of all feedback submitted for messages in this app.
"""
try:
feedbacks = application_services().message_feedbacks.get_feedbacks(
app_id=context.app_id,
app_owner_tenant_id=context.tenant_id,
page=query_args.page,
limit=query_args.limit,
)
except AppDefinitionUnavailableError as error:
raise AppUnavailableError() from error
return dump_response(AppFeedbackListResponse, {"data": feedbacks})
@service_api_ns.route("/messages/<uuid:message_id>/suggested")
class MessageSuggestedApi(Resource):
@error_responses(
AgentVersionNotFoundError,
AppSuggestedQuestionsAfterAnswerDisabledError,
AppUnavailableError,
CompletionRequestError,
NotChatAppError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
)
@service_api_ns.doc("get_suggested_questions")
@service_api_ns.doc(
summary="Get Next Suggested Questions",
description=(
"Get next question suggestions for the current message. "
"If no usable model can be resolved or the model call to generate questions fails, "
"the response is HTTP 200 with an empty data list. "
"Model invocation failures during history token counting instead return "
"HTTP 400 with `completion_request_error`."
),
tags=["Chats", "Chatflows"],
responses={
HTTPStatus.OK: "Suggested questions retrieved successfully",
HTTPStatus.BAD_REQUEST: (
"- `not_chat_app` : App mode does not match the API route.\n"
"- `app_unavailable` : App is no longer available.\n"
"- `completion_request_error` : Model invocation failed while counting history tokens."
),
HTTPStatus.UNAUTHORIZED: "Unauthorized - invalid API token",
HTTPStatus.FORBIDDEN: (
"- `forbidden` : Token scope does not allow access.\n"
"- `app_not_found` : The token's app no longer exists.\n"
"- `app_abnormal_status` : App status does not allow API access.\n"
"- `app_api_disabled` : The app's API service has been disabled.\n"
"- `workspace_not_found` : The app's workspace no longer exists.\n"
"- `workspace_archived` : The app's workspace is archived.\n"
"- `app_suggested_questions_after_answer_disabled` : Suggested questions feature is disabled."
),
HTTPStatus.NOT_FOUND: (
"- `not_found` : End user, message, or conversation does not exist.\n"
"- `agent_version_not_found_error` : Agent config version does not exist."
),
HTTPStatus.INTERNAL_SERVER_ERROR: "`internal_server_error` : Internal server error.",
},
)
@service_api_ns.response(
HTTPStatus.OK,
"Suggested questions retrieved successfully",
service_api_ns.models[SimpleResultStringListResponse.__name__],
)
@service_api_ns.doc(params={"message_id": "Message ID"})
@service_api_end_user_admission(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY, required=True))
def get(self, context: ServiceApiEndUserContext, message_id: UUID) -> dict[str, object]:
"""Get suggested follow-up questions for a message.
Returns an empty list when model resolution or the question-generation
model call fails. History token-counting invocation failures return
HTTP 400 with completion_request_error.
"""
message_id_str = str(message_id)
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:
questions = application_services().message_suggested_questions.get_suggested_questions(
app_id=context.app_id,
app_owner_tenant_id=context.tenant_id,
expected_app_mode=context.app_mode,
actor=MessageEndUser(end_user_id=context.end_user_id),
invoke_from="service-api",
message_id=message_id_str,
)
except AppDefinitionUnavailableError:
raise AppUnavailableError() from None
except MessageActorNotFoundError:
raise NotFoundError("End user not found") from None
except MessageNotExistsError as caught_error:
raise NotFoundError("Message Not Exists.") from caught_error
except ConversationNotExistsError:
raise NotFoundError("Conversation not found") from None
except SuggestedQuestionsAfterAnswerDisabledError:
raise AppSuggestedQuestionsAfterAnswerDisabledError() from None
except ProviderTokenNotInitError as error:
raise ProviderNotInitializeError(error.description) from error
except QuotaExceededError:
raise ProviderQuotaExceededError() from None
except ModelCurrentlyNotSupportError:
raise ProviderModelCurrentlyNotSupportError() from None
except InvokeError as error:
raise CompletionRequestError(error.description) from error
except AgentVersionNotFoundError:
# The legacy Agent config reader still owns this HTTP error.
# Remove this compatibility case when it exposes a domain error.
raise
except Exception as caught_error:
logger.exception("internal server error.")
raise InternalServerError() from caught_error
return dump_response(SimpleResultStringListResponse, {"result": "success", "data": questions})
@@ -0,0 +1,57 @@
from flask_restx import Resource
from werkzeug.exceptions import Forbidden
from controllers.common.fields import Site as SiteResponse
from controllers.common.schema import register_response_schema_models
from controllers.service_api import service_api_ns
from controllers.service_api.wraps import validate_app_token
from extensions.ext_application_services import application_services
from libs.helper import dump_response
from models.model import App
from services.app_definition_query_service import AppDefinitionUnavailableError
register_response_schema_models(service_api_ns, SiteResponse)
@service_api_ns.route("/site")
class AppSiteApi(Resource):
"""Resource for app sites."""
@service_api_ns.doc(
summary="Get App WebApp Settings",
description=(
"Retrieve the WebApp settings of this application, including site configuration, theme, and "
"customization options."
),
tags=["Applications"],
responses={
200: "WebApp settings of the application.",
403: "`forbidden` : Site not found for this application or the workspace has been archived.",
},
)
@service_api_ns.doc("get_app_site")
@service_api_ns.doc(description="Get application site configuration")
@service_api_ns.doc(
responses={
200: "Site configuration retrieved successfully",
401: "Unauthorized - invalid API token",
403: "Forbidden - site not found or tenant archived",
}
)
@service_api_ns.response(
200,
"Site configuration retrieved successfully",
service_api_ns.models[SiteResponse.__name__],
)
@validate_app_token
def get(self, app_model: App):
"""Retrieve app site info.
Returns the site configuration for the application including theme, icons, and text.
"""
try:
configuration = application_services().app_definitions.get_site_configuration(app_model.id)
except AppDefinitionUnavailableError:
raise Forbidden() from None
return dump_response(SiteResponse, configuration)
@@ -0,0 +1,649 @@
import logging
from collections.abc import Mapping
from datetime import datetime
from typing import Annotated, Literal
from dateutil.parser import isoparse
from flask import request
from flask_restx import Resource
from pydantic import BaseModel, Field, WithJsonSchema, field_validator, model_validator
from pydantic.json_schema import SkipJsonSchema
from sqlalchemy.orm import Session, sessionmaker
from werkzeug.exceptions import BadRequest, InternalServerError, NotFound
from configs import dify_config
from controllers.common.controller_schemas import WorkflowRunPayload as WorkflowRunPayloadBase
from controllers.common.fields import SimpleResultResponse, WorkflowBlockingResponse
from controllers.common.schema import (
query_params_from_model,
query_params_from_request,
register_response_schema_models,
register_schema_models,
)
from controllers.console.app.wraps import with_session
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import (
CompletionRequestError,
NotWorkflowAppError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
TriggerWorkflowServiceModeUnavailableError,
WorkflowVersionExecutionNotAllowedError,
)
from controllers.service_api.schema import (
WORKFLOW_TASK_STOP_USER_DESCRIPTION,
expect_user_json,
expect_with_user,
json_or_event_stream_response,
)
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
from controllers.web.error import InvokeRateLimitError as InvokeRateLimitHttpError
from core.app.entities.app_invoke_entities import InvokeFrom
from core.errors.error import (
ModelCurrentlyNotSupportError,
ProviderTokenNotInitError,
QuotaExceededError,
)
from core.helper.trace_id_helper import get_external_trace_id, get_trace_session_id, omit_trace_session_id_from_payload
from enums import CloudPlan, DeploymentEdition
from extensions.ext_application_services import application_services
from extensions.ext_database import db
from fields.base import ResponseModel
from fields.end_user_fields import SimpleEndUser
from fields.member_fields import SimpleAccountResponse
from graphon.enums import WorkflowExecutionStatus
from graphon.model_runtime.errors.invoke import InvokeError
from libs import helper
from libs.external_api import error_responses
from libs.helper import dump_response, to_timestamp
from models.model import App, AppMode, EndUser
from repositories.factory import DifyAPIRepositoryFactory
from services.app_generate_service import AppGenerateService
from services.app_task_service import AppTaskService
from services.billing_service import BillingService
from services.errors.app import (
IsDraftWorkflowError,
WorkflowIdFormatError,
WorkflowNotFoundError,
)
from services.errors.app import (
TriggerWorkflowServiceModeUnavailableError as TriggerWorkflowServiceModeUnavailableServiceError,
)
from services.errors.llm import InvokeRateLimitError
logger = logging.getLogger(__name__)
UUIDString = Annotated[str, WithJsonSchema({"format": "uuid", "type": "string"})]
Int64 = Annotated[int, WithJsonSchema({"format": "int64", "type": "integer"})]
FloatNumber = Annotated[float, WithJsonSchema({"format": "float", "type": "number"})]
class WorkflowRunPayload(WorkflowRunPayloadBase):
response_mode: Literal["blocking", "streaming"] | None = Field(
default=None,
description=(
"Response mode. Use `blocking` for synchronous responses or `streaming` for Server-Sent Events. "
"When omitted, the request runs in blocking mode."
),
)
trace_session_id: SkipJsonSchema[str | None] = Field(
default=None, description="Trace session ID for observability grouping"
)
class WorkflowLogQuery(BaseModel):
keyword: str | None = Field(default=None, description="Keyword to search in logs.")
status: Literal["succeeded", "failed", "stopped"] | None = Field(
default=None,
description="Filter by execution status.",
)
created_at__before: str | None = Field(
default=None,
description="Filter logs created before this ISO 8601 timestamp.",
json_schema_extra={"format": "date-time"},
)
created_at__after: str | None = Field(
default=None,
description="Filter logs created after this ISO 8601 timestamp.",
json_schema_extra={"format": "date-time"},
)
created_by_end_user_session_id: str | None = Field(
default=None,
description="Filter by end user session ID.",
)
created_by_account: str | None = Field(default=None, description="Filter by account ID.")
page: int = Field(default=1, ge=1, le=99999, description="Page number for pagination.")
limit: int = Field(default=20, ge=1, le=100, description="Number of items per page.")
register_schema_models(service_api_ns, WorkflowRunPayload, WorkflowLogQuery)
register_response_schema_models(service_api_ns, WorkflowBlockingResponse, SimpleResultResponse)
def _enum_value(value):
return getattr(value, "value", value)
class WorkflowRunResponse(ResponseModel):
id: UUIDString
workflow_id: UUIDString
status: str
inputs: dict | list | str | int | float | bool | None = Field(default=None)
outputs: dict = Field(default_factory=dict, validation_alias="outputs_dict")
error: str | None = None
total_steps: int | None = None
total_tokens: int | None = None
created_at: Int64 | None = None
finished_at: Int64 | None = None
elapsed_time: FloatNumber | int | None = None
@field_validator("status", mode="before")
@classmethod
def _normalize_enum(cls, value):
return _enum_value(value)
@field_validator("outputs", mode="before")
@classmethod
def _normalize_outputs(cls, value):
if value is None:
return {}
if isinstance(value, dict):
return value
if isinstance(value, Mapping):
return dict(value)
return {}
@field_validator("created_at", "finished_at", mode="before")
@classmethod
def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
return to_timestamp(value)
@model_validator(mode="after")
def _clear_paused_outputs(self):
if self.status == WorkflowExecutionStatus.PAUSED.value:
self.outputs = {}
return self
class WorkflowRunForLogResponse(ResponseModel):
id: UUIDString
version: str | None = None
status: str | None = None
triggered_from: str | None = None
error: str | None = None
elapsed_time: FloatNumber | int | None = None
total_tokens: int | None = None
total_steps: int | None = None
created_at: Int64 | None = None
finished_at: Int64 | None = None
exceptions_count: int | None = None
@field_validator("status", "triggered_from", mode="before")
@classmethod
def _normalize_enum(cls, value):
return _enum_value(value)
@field_validator("created_at", "finished_at", mode="before")
@classmethod
def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
return to_timestamp(value)
class WorkflowAppLogPartialResponse(ResponseModel):
id: UUIDString
workflow_run: WorkflowRunForLogResponse | None = None
details: dict | list | str | int | float | bool | None = Field(default=None)
created_from: str | None = None
created_by_role: str | None = None
created_by_account: SimpleAccountResponse | None = None
created_by_end_user: SimpleEndUser | None = None
created_at: Int64 | None = None
@field_validator("created_from", "created_by_role", mode="before")
@classmethod
def _normalize_enum(cls, value):
return _enum_value(value)
@field_validator("created_at", mode="before")
@classmethod
def _normalize_timestamp(cls, value: datetime | int | None) -> int | None:
return to_timestamp(value)
class WorkflowAppLogPaginationResponse(ResponseModel):
page: int
limit: int
total: int
has_more: bool
data: list[WorkflowAppLogPartialResponse]
register_response_schema_models(
service_api_ns,
WorkflowRunResponse,
WorkflowRunForLogResponse,
WorkflowAppLogPartialResponse,
WorkflowAppLogPaginationResponse,
)
@service_api_ns.route("/workflows/run/<string:workflow_run_id>")
class WorkflowRunDetailApi(Resource):
@error_responses(NotWorkflowAppError)
@service_api_ns.doc(
summary="Get Workflow Run Detail",
description="Retrieve the current execution results of a workflow task based on the workflow execution ID.",
tags=["Chatflows", "Workflows"],
responses={
200: "Successfully retrieved workflow run details.",
400: "`not_workflow_app` : App mode does not match the API route.",
404: "`not_found` : Workflow run not found.",
},
)
@service_api_ns.doc("get_workflow_run_detail")
@service_api_ns.doc(description="Get workflow run details")
@service_api_ns.doc(
params={
"workflow_run_id": "Workflow run ID, obtained from the workflow execution response or streaming events."
}
)
@service_api_ns.doc(
responses={
200: "Workflow run details retrieved successfully",
401: "Unauthorized - invalid API token",
404: "Workflow run not found",
}
)
@validate_app_token
@service_api_ns.response(
200,
"Workflow run details retrieved successfully",
service_api_ns.models[WorkflowRunResponse.__name__],
)
def get(self, app_model: App, workflow_run_id: str):
"""Get a workflow task running detail.
Returns detailed information about a specific workflow run.
"""
app_mode = AppMode.value_of(app_model.mode)
if app_mode not in [AppMode.WORKFLOW, AppMode.ADVANCED_CHAT]:
raise NotWorkflowAppError()
# Use repository to get workflow run
session_maker = sessionmaker(bind=db.engine, expire_on_commit=False)
workflow_run_repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_maker)
workflow_run = workflow_run_repo.get_workflow_run_by_id(
tenant_id=app_model.tenant_id,
app_id=app_model.id,
run_id=workflow_run_id,
)
if not workflow_run:
raise NotFound("Workflow run not found.")
return dump_response(WorkflowRunResponse, workflow_run)
@service_api_ns.route("/workflows/run")
class WorkflowRunApi(Resource):
@error_responses(
CompletionRequestError,
InvokeRateLimitHttpError,
NotWorkflowAppError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
TriggerWorkflowServiceModeUnavailableError,
)
@service_api_ns.doc(
summary="Run Workflow",
description="Execute a workflow. Cannot be executed without a published workflow.",
tags=["Workflows"],
responses={
200: (
"Successful response. The content type and structure depend on the `response_mode` parameter "
"in the request.\n"
"\n"
"- If `response_mode` is `blocking`, returns `application/json` with a "
"`WorkflowBlockingResponse` object.\n"
"- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of "
"`ChunkWorkflowEvent` objects."
),
400: (
"- `not_workflow_app` : App mode does not match the API route.\n"
"- `provider_not_initialize` : No valid model provider credentials found.\n"
"- `provider_quota_exceeded` : Model provider quota exhausted.\n"
"- `model_currently_not_support` : Current model unavailable.\n"
"- `completion_request_error` : Workflow execution request failed.\n"
"- `invalid_param` : Invalid parameter value."
),
403: (
"- `forbidden` : Token scope, app, or workspace access denied.\n"
"- `trigger_workflow_service_mode_unavailable` : Trigger-entry workflows cannot be invoked through "
"Web App, Service API, OpenAPI, or MCP."
),
429: (
"- `too_many_requests` : Too many concurrent requests for this app.\n"
"- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached."
),
500: "`internal_server_error` : Internal server error.",
},
)
@expect_with_user(service_api_ns, WorkflowRunPayload)
@json_or_event_stream_response(service_api_ns)
@service_api_ns.doc("run_workflow")
@service_api_ns.doc(description="Execute a workflow")
@service_api_ns.doc(
responses={
200: "Workflow executed successfully",
400: "Bad request - invalid parameters or workflow issues",
401: "Unauthorized - invalid API token",
429: "Rate limit exceeded",
500: "Internal server error",
}
)
@service_api_ns.response(
200,
"Workflow executed successfully",
service_api_ns.models[WorkflowBlockingResponse.__name__],
)
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
@with_session
def post(self, session: Session, app_model: App, end_user: EndUser):
"""Execute a workflow.
Runs a workflow with the provided inputs and returns the results.
Supports both blocking and streaming response modes.
"""
app_mode = AppMode.value_of(app_model.mode)
if app_mode != AppMode.WORKFLOW:
raise NotWorkflowAppError()
payload = WorkflowRunPayload.model_validate(omit_trace_session_id_from_payload(service_api_ns.payload) or {})
args = payload.model_dump(exclude_none=True)
trace_session_id = get_trace_session_id(request)
if trace_session_id:
args["trace_session_id"] = trace_session_id
external_trace_id = get_external_trace_id(request)
if external_trace_id:
args["external_trace_id"] = external_trace_id
streaming = payload.response_mode == "streaming"
try:
response = AppGenerateService.generate(
session=session,
app_model=app_model,
user=end_user,
args=args,
invoke_from=InvokeFrom.SERVICE_API,
streaming=streaming,
)
# response-contract:ignore compact_generate_response
return helper.compact_generate_response(response)
except TriggerWorkflowServiceModeUnavailableServiceError as caught_error:
raise TriggerWorkflowServiceModeUnavailableError() from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
except QuotaExceededError as caught_error:
raise ProviderQuotaExceededError() from caught_error
except ModelCurrentlyNotSupportError as caught_error:
raise ProviderModelCurrentlyNotSupportError() from caught_error
except InvokeRateLimitError as ex:
raise InvokeRateLimitHttpError(ex.description) from ex
except InvokeError as e:
raise CompletionRequestError(e.description) from e
except ValueError as e:
raise e
except Exception as caught_error:
logger.exception("internal server error.")
raise InternalServerError() from caught_error
@service_api_ns.route("/workflows/<string:workflow_id>/run")
class WorkflowRunByIdApi(Resource):
@error_responses(
CompletionRequestError,
InvokeRateLimitHttpError,
NotWorkflowAppError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
TriggerWorkflowServiceModeUnavailableError,
WorkflowVersionExecutionNotAllowedError,
)
@service_api_ns.doc(
summary="Run Workflow by ID",
description=(
"Execute a specific workflow version identified by its ID. Useful for running a particular "
"published version of the workflow."
),
tags=["Workflows"],
responses={
200: (
"Successful response. The content type and structure depend on the `response_mode` parameter "
"in the request.\n"
"\n"
"- If `response_mode` is `blocking`, returns `application/json` with a "
"`WorkflowBlockingResponse` object.\n"
"- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of "
"`ChunkWorkflowEvent` objects."
),
400: (
"- `not_workflow_app` : App mode does not match the API route.\n"
"- `bad_request` : Workflow is a draft or has an invalid ID format.\n"
"- `provider_not_initialize` : No valid model provider credentials found.\n"
"- `provider_quota_exceeded` : Model provider quota exhausted.\n"
"- `model_currently_not_support` : Current model unavailable.\n"
"- `completion_request_error` : Workflow execution request failed.\n"
"- `invalid_param` : Required parameter missing or invalid."
),
403: (
"- `forbidden` : Token scope, app, or workspace access denied.\n"
"- `workflow_version_execution_not_allowed` : Workflow version execution is unavailable on the "
"current plan. Upgrade to a paid plan.\n"
"- `trigger_workflow_service_mode_unavailable` : The selected workflow version uses a trigger entry "
"and cannot be invoked through Web App, Service API, OpenAPI, or MCP."
),
404: "`not_found` : Workflow not found.",
429: (
"- `too_many_requests` : Too many concurrent requests for this app.\n"
"- `rate_limit_error` : The Dify Cloud workflow execution quota for this workspace has been reached."
),
500: "`internal_server_error` : Internal server error.",
},
)
@expect_with_user(service_api_ns, WorkflowRunPayload)
@json_or_event_stream_response(service_api_ns)
@service_api_ns.doc("run_workflow_by_id")
@service_api_ns.doc(description="Execute a specific workflow by ID")
@service_api_ns.doc(
params={
"workflow_id": (
"Workflow ID of the specific version to execute. This value is returned in the `workflow_id` field "
"of workflow run responses."
)
}
)
@service_api_ns.doc(
responses={
200: "Workflow executed successfully",
400: "Bad request - invalid parameters or workflow issues",
401: "Unauthorized - invalid API token",
403: "Forbidden - upgrade to a paid plan to execute a specific workflow version",
404: "Workflow not found",
429: "Rate limit exceeded",
500: "Internal server error",
}
)
@service_api_ns.response(
200,
"Workflow executed successfully",
service_api_ns.models[WorkflowBlockingResponse.__name__],
)
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
@with_session
def post(self, session: Session, app_model: App, end_user: EndUser, workflow_id: str):
"""Run specific workflow by ID.
Executes a specific workflow version identified by its ID.
"""
app_mode = AppMode.value_of(app_model.mode)
if app_mode != AppMode.WORKFLOW:
raise NotWorkflowAppError()
if dify_config.DEPLOYMENT_EDITION == DeploymentEdition.CLOUD:
billing_info = BillingService.get_info(app_model.tenant_id, exclude_vector_space=True)
if billing_info.subscription.plan == CloudPlan.SANDBOX:
raise WorkflowVersionExecutionNotAllowedError()
payload = WorkflowRunPayload.model_validate(omit_trace_session_id_from_payload(service_api_ns.payload) or {})
args = payload.model_dump(exclude_none=True)
trace_session_id = get_trace_session_id(request)
if trace_session_id:
args["trace_session_id"] = trace_session_id
# Add workflow_id to args for AppGenerateService
args["workflow_id"] = workflow_id
external_trace_id = get_external_trace_id(request)
if external_trace_id:
args["external_trace_id"] = external_trace_id
streaming = payload.response_mode == "streaming"
try:
response = AppGenerateService.generate(
session=session,
app_model=app_model,
user=end_user,
args=args,
invoke_from=InvokeFrom.SERVICE_API,
streaming=streaming,
)
# response-contract:ignore compact_generate_response
return helper.compact_generate_response(response)
except TriggerWorkflowServiceModeUnavailableServiceError as caught_error:
raise TriggerWorkflowServiceModeUnavailableError() from caught_error
except WorkflowNotFoundError as ex:
raise NotFound(str(ex)) from ex
except IsDraftWorkflowError as ex:
raise BadRequest(str(ex)) from ex
except WorkflowIdFormatError as ex:
raise BadRequest(str(ex)) from ex
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
except QuotaExceededError as caught_error:
raise ProviderQuotaExceededError() from caught_error
except ModelCurrentlyNotSupportError as caught_error:
raise ProviderModelCurrentlyNotSupportError() from caught_error
except InvokeRateLimitError as ex:
raise InvokeRateLimitHttpError(ex.description) from ex
except InvokeError as e:
raise CompletionRequestError(e.description) from e
except ValueError as e:
raise e
except Exception as caught_error:
logger.exception("internal server error.")
raise InternalServerError() from caught_error
@service_api_ns.route("/workflows/tasks/<string:task_id>/stop")
class WorkflowTaskStopApi(Resource):
@error_responses(NotWorkflowAppError)
@service_api_ns.doc(
summary="Stop Workflow Task",
description="Stop a running workflow task. Only supported in `streaming` mode.",
tags=["Workflows"],
responses={
400: (
"- `not_workflow_app` : App mode does not match the API route.\n"
"- `invalid_param` : Required parameter missing or invalid."
),
},
)
@expect_user_json(
service_api_ns,
model_name="WorkflowTaskStopPayload",
user_description=WORKFLOW_TASK_STOP_USER_DESCRIPTION,
)
@service_api_ns.doc("stop_workflow_task")
@service_api_ns.doc(description="Stop a running workflow task")
@service_api_ns.doc(
params={"task_id": "Task ID, obtained from the streaming chunk returned by the Run Workflow API."}
)
@service_api_ns.doc(
responses={
200: "Task stopped successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(200, "Task stopped successfully", service_api_ns.models[SimpleResultResponse.__name__])
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.JSON, required=True))
def post(self, app_model: App, end_user: EndUser, task_id: str):
"""Stop a running workflow task."""
app_mode = AppMode.value_of(app_model.mode)
if app_mode != AppMode.WORKFLOW:
raise NotWorkflowAppError()
AppTaskService.stop_workflow_task(
tenant_id=app_model.tenant_id,
app_id=app_model.id,
task_id=task_id,
app_mode=app_mode,
owner=None,
)
return SimpleResultResponse(result="success").model_dump()
@service_api_ns.route("/workflows/logs")
class WorkflowAppLogApi(Resource):
@service_api_ns.doc(
summary="List Workflow Logs",
description="Retrieve paginated workflow execution logs with filtering options.",
tags=["Chatflows", "Workflows"],
responses={
200: "Successfully retrieved workflow logs.",
},
)
@service_api_ns.doc(params=query_params_from_model(WorkflowLogQuery))
@service_api_ns.doc("get_workflow_logs")
@service_api_ns.doc(description="Get workflow execution logs")
@service_api_ns.doc(
responses={
200: "Logs retrieved successfully",
400: "Bad request - invalid query parameters",
401: "Unauthorized - invalid API token",
}
)
@validate_app_token
@service_api_ns.response(
200,
"Logs retrieved successfully",
service_api_ns.models[WorkflowAppLogPaginationResponse.__name__],
)
def get(self, app_model: App):
"""Get workflow app logs.
Returns paginated workflow execution logs with filtering options.
"""
args = query_params_from_request(WorkflowLogQuery)
status = WorkflowExecutionStatus(args.status) if args.status else None
created_at_before = isoparse(args.created_at__before) if args.created_at__before else None
created_at_after = isoparse(args.created_at__after) if args.created_at__after else None
result = application_services().workflow_app_logs.list_logs(
tenant_id=app_model.tenant_id,
app_id=app_model.id,
keyword=args.keyword,
status=status,
created_at_before=created_at_before,
created_at_after=created_at_after,
page=args.page,
limit=args.limit,
created_by_end_user_session_id=args.created_by_end_user_session_id,
created_by_account=args.created_by_account,
)
return dump_response(WorkflowAppLogPaginationResponse, result)
@@ -0,0 +1,181 @@
"""
Service API workflow resume event stream endpoints.
"""
import json
from collections.abc import Generator
from flask import Response, request
from flask_restx import Resource
from pydantic import BaseModel, Field
from sqlalchemy.orm import sessionmaker
from werkzeug.exceptions import NotFound
from controllers.common.fields import EventStreamResponse
from controllers.common.schema import query_params_from_model, register_response_schema_model, register_schema_models
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import NotWorkflowAppError
from controllers.service_api.schema import event_stream_response
from controllers.service_api.wraps import FetchUserArg, WhereisUserArg, validate_app_token
from core.app.apps.advanced_chat.app_generator import AdvancedChatAppGenerator
from core.app.apps.base_app_generator import BaseAppGenerator
from core.app.apps.common.workflow_response_converter import WorkflowResponseConverter
from core.app.apps.message_generator import MessageGenerator
from core.app.apps.workflow.app_generator import WorkflowAppGenerator
from core.app.entities.task_entities import StreamEvent
from core.workflow.human_input_policy import HumanInputSurface
from extensions.ext_database import db
from libs.external_api import error_responses
from models.enums import CreatorUserRole
from models.model import App, AppMode, EndUser
from repositories.factory import DifyAPIRepositoryFactory
from services.workflow_event_snapshot_service import build_workflow_event_stream
class WorkflowEventsQuery(BaseModel):
user: str = Field(
...,
description="End-user identifier that originally triggered the run. Must match the creator of the run.",
)
include_state_snapshot: bool = Field(
default=False,
description=(
"When `true`, replay from the persisted state snapshot to include a status summary of already-executed "
"nodes before streaming new events."
),
)
continue_on_pause: bool = Field(
default=False,
description=(
"Set to `true` to keep the stream open across multiple `workflow_paused` events, which is useful when "
"the workflow has more than one Human Input node in sequence. By default, the stream closes after the "
"first pause."
),
)
register_schema_models(service_api_ns, WorkflowEventsQuery)
register_response_schema_model(service_api_ns, EventStreamResponse)
@service_api_ns.route("/workflow/<string:workflow_run_id>/events")
class WorkflowEventsApi(Resource):
"""Service API for getting workflow execution events after resume."""
@error_responses(NotWorkflowAppError)
@service_api_ns.doc(
summary="Stream Workflow Events",
description=(
"Resume the Server-Sent Events stream for a workflow run after a pause or a dropped SSE "
"connection. For runs that have already finished, the stream emits a single "
"`workflow_finished` event and closes."
),
tags=["Chatflows", "Workflows"],
responses={
200: (
"Server-Sent Events stream. Each event is delivered as `data: {JSON}\\n\\n`. Event payloads "
"follow the same schemas as the original streaming response."
),
400: "`not_workflow_app` : Please check if your app mode matches the right API route.",
404: "`not_found` : Workflow run not found.",
},
)
@event_stream_response(service_api_ns)
@service_api_ns.doc("get_workflow_events")
@service_api_ns.doc(description="Get workflow execution events stream after resume")
@service_api_ns.doc(params={"workflow_run_id": "Workflow run ID returned by the original workflow run request."})
@service_api_ns.doc(params=query_params_from_model(WorkflowEventsQuery))
@service_api_ns.doc(
responses={
200: "SSE event stream",
401: "Unauthorized - invalid API token",
404: "Workflow run not found",
}
)
@service_api_ns.response(200, "SSE event stream", service_api_ns.models[EventStreamResponse.__name__])
@validate_app_token(fetch_user_arg=FetchUserArg(fetch_from=WhereisUserArg.QUERY, required=True))
def get(self, app_model: App, end_user: EndUser, workflow_run_id: str):
app_mode = AppMode.value_of(app_model.mode)
if app_mode not in {AppMode.WORKFLOW, AppMode.ADVANCED_CHAT}:
raise NotWorkflowAppError()
session_maker = sessionmaker(db.engine)
repo = DifyAPIRepositoryFactory.create_api_workflow_run_repository(session_maker)
workflow_run = repo.get_workflow_run_by_id_and_tenant_id(
tenant_id=app_model.tenant_id,
run_id=workflow_run_id,
)
if workflow_run is None:
raise NotFound("Workflow run not found")
if workflow_run.app_id != app_model.id:
raise NotFound("Workflow run not found")
if workflow_run.created_by_role != CreatorUserRole.END_USER:
raise NotFound("Workflow run not found")
if workflow_run.created_by != end_user.id:
raise NotFound("Workflow run not found")
workflow_run_entity = workflow_run
if workflow_run_entity.finished_at is not None:
response = WorkflowResponseConverter.workflow_run_result_to_finish_response(
task_id=workflow_run_entity.id,
workflow_run=workflow_run_entity,
creator_user=end_user,
)
payload = response.model_dump(mode="json")
payload["event"] = response.event.value
def _generate_finished_events() -> Generator[str]:
yield f"data: {json.dumps(payload)}\n\n"
event_generator = _generate_finished_events
else:
msg_generator = MessageGenerator()
generator: type[BaseAppGenerator]
if app_mode == AppMode.ADVANCED_CHAT:
generator = AdvancedChatAppGenerator
elif app_mode == AppMode.WORKFLOW:
generator = WorkflowAppGenerator
else:
raise NotWorkflowAppError()
include_state_snapshot = request.args.get("include_state_snapshot", "false").lower() == "true"
continue_on_pause = request.args.get("continue_on_pause", "false").lower() == "true"
terminal_events: list[StreamEvent] | None = [] if continue_on_pause else None
def _generate_stream_events():
if include_state_snapshot:
return generator.convert_to_event_stream(
build_workflow_event_stream(
app_mode=app_mode,
workflow_run=workflow_run_entity,
tenant_id=app_model.tenant_id,
app_id=app_model.id,
session_maker=session_maker,
human_input_surface=HumanInputSurface.SERVICE_API,
close_on_pause=not continue_on_pause,
)
)
return generator.convert_to_event_stream(
msg_generator.retrieve_events(
app_mode,
workflow_run_entity.id,
terminal_events=terminal_events,
),
)
event_generator = _generate_stream_events
return Response(
event_generator(),
mimetype="text/event-stream",
headers={
"Cache-Control": "no-cache",
"Connection": "keep-alive",
},
)
Whitespace-only changes.
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,55 @@
from libs.exception import BaseHTTPException
class DatasetNotInitializedError(BaseHTTPException):
error_code = "dataset_not_initialized"
description = "The dataset is still being initialized or indexing. Please wait a moment."
code = 400
class ArchivedDocumentImmutableError(BaseHTTPException):
error_code = "archived_document_immutable"
description = "The archived document is not editable."
code = 403
class DatasetNameDuplicateError(BaseHTTPException):
error_code = "dataset_name_duplicate"
description = "The dataset name already exists. Please modify your dataset name."
code = 409
class InvalidActionError(BaseHTTPException):
error_code = "invalid_action"
description = "Invalid action."
code = 400
class DocumentAlreadyFinishedError(BaseHTTPException):
error_code = "document_already_finished"
description = "The document has been processed. Please refresh the page or go to the document details."
code = 400
class DocumentIndexingError(BaseHTTPException):
error_code = "document_indexing"
description = "The document is being processed and cannot be edited."
code = 400
class InvalidMetadataError(BaseHTTPException):
error_code = "invalid_metadata"
description = "The metadata content is incorrect. Please check and verify."
code = 400
class DatasetInUseError(BaseHTTPException):
error_code = "dataset_in_use"
description = "The dataset is being used by some apps. Please remove the dataset from the apps before deleting it."
code = 409
class PipelineRunError(BaseHTTPException):
error_code = "pipeline_run_error"
description = "An error occurred while running the pipeline."
code = 500
@@ -0,0 +1,85 @@
from uuid import UUID
from sqlalchemy.orm import Session
from controllers.common.schema import register_response_schema_models, register_schema_models
from controllers.console.app.error import (
CompletionRequestError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
)
from controllers.console.app.wraps import with_session
from controllers.console.datasets.hit_testing_base import DatasetsHitTestingBase, HitTestingPayload
from controllers.service_api import service_api_ns
from controllers.service_api.wraps import DatasetApiResource, cloud_edition_billing_rate_limit_check
from fields.hit_testing_fields import HitTestingResponse
from libs.external_api import error_responses
from libs.helper import dump_response
register_schema_models(service_api_ns, HitTestingPayload)
register_response_schema_models(service_api_ns, HitTestingResponse)
@service_api_ns.route(
"/datasets/<uuid:dataset_id>/hit-testing",
doc={"post": {"deprecated": True}},
)
@service_api_ns.route("/datasets/<uuid:dataset_id>/retrieve")
class HitTestingApi(DatasetApiResource, DatasetsHitTestingBase):
@error_responses(
CompletionRequestError,
ProviderModelCurrentlyNotSupportError,
ProviderNotInitializeError,
ProviderQuotaExceededError,
)
@service_api_ns.doc(
summary="Retrieve Chunks from a Knowledge Base / Test Retrieval",
description=(
"Performs a search query against a knowledge base to retrieve the most relevant chunks. This "
"endpoint can be used for both production retrieval and test retrieval."
),
tags=["Knowledge Bases"],
responses={
200: "Retrieval results.",
400: (
"- `dataset_not_initialized` : The dataset is still being initialized or indexing. Please "
"wait a moment.\n"
"- `provider_not_initialize` : No valid model provider credentials found. Please go to "
"Settings -> Model Provider to complete your provider credentials.\n"
"- `provider_quota_exceeded` : Your quota for Dify Hosted OpenAI has been exhausted. Please "
"go to Settings -> Model Provider to complete your own provider credentials.\n"
"- `model_currently_not_support` : Dify Hosted OpenAI trial currently not support the GPT-4 "
"model.\n"
"- `completion_request_error` : Completion request failed.\n"
"- `invalid_param` : Invalid parameter value."
),
403: "`forbidden` : Insufficient permissions.",
404: "`not_found` : Knowledge base not found.",
500: "`internal_server_error` : An internal error occurred during retrieval.",
},
)
@service_api_ns.doc("dataset_hit_testing")
@service_api_ns.doc(description="Perform hit testing on a dataset")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID."})
@service_api_ns.response(
200,
"Hit testing results",
model=service_api_ns.models[HitTestingResponse.__name__],
)
@service_api_ns.response(401, "Unauthorized - invalid API token")
@service_api_ns.response(404, "Dataset not found")
@service_api_ns.expect(service_api_ns.models[HitTestingPayload.__name__])
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
def post(self, session: Session, tenant_id: str, dataset_id: UUID) -> dict[str, object]:
"""Perform hit testing on a dataset.
Tests retrieval performance for the specified dataset.
"""
dataset_id_str = str(dataset_id)
dataset = self.get_and_validate_dataset(session, dataset_id_str)
args = self.parse_args(service_api_ns.payload)
self.hit_testing_args_check(args)
return dump_response(HitTestingResponse, self.perform_hit_testing(session, dataset, args))
@@ -0,0 +1,365 @@
from typing import Literal
from uuid import UUID
from flask_login import current_user
from sqlalchemy.orm import Session
from werkzeug.exceptions import NotFound
from controllers.common.controller_schemas import MetadataUpdatePayload
from controllers.common.schema import register_response_schema_models, register_schema_model, register_schema_models
from controllers.common.session import with_session
from controllers.console.wraps import model_validate
from controllers.service_api import service_api_ns
from controllers.service_api.wraps import DatasetApiResource, cloud_edition_billing_rate_limit_check
from extensions.ext_application_services import application_services
from fields.dataset_fields import (
DatasetMetadataActionResponse,
DatasetMetadataBuiltInFieldsResponse,
DatasetMetadataListResponse,
DatasetMetadataResponse,
)
from libs.helper import dump_response
from services.errors.metadata import MetadataResourceNotFoundError
from services.knowledge.dataset_service import DatasetService
from services.knowledge.entities.knowledge_entities import (
DocumentMetadataOperation,
MetadataArgs,
MetadataDetail,
MetadataOperationData,
)
from services.knowledge.resource_scope import DatasetRef
BUILT_IN_METADATA_ACTION_PARAM = {
"description": "`enable` to activate built-in metadata fields, `disable` to deactivate them.",
"enum": ["enable", "disable"],
"type": "string",
}
register_schema_model(service_api_ns, MetadataUpdatePayload)
register_schema_models(
service_api_ns,
MetadataArgs,
MetadataDetail,
DocumentMetadataOperation,
MetadataOperationData,
)
register_response_schema_models(
service_api_ns,
DatasetMetadataActionResponse,
DatasetMetadataBuiltInFieldsResponse,
DatasetMetadataListResponse,
DatasetMetadataResponse,
)
@service_api_ns.route("/datasets/<uuid:dataset_id>/metadata")
class DatasetMetadataCreateServiceApi(DatasetApiResource):
@service_api_ns.doc(
summary="Create Metadata Field",
description=(
"Create a custom metadata field for the knowledge base. Metadata fields can be used to "
"annotate documents with structured information."
),
tags=["Metadata"],
responses={
201: "Metadata field created successfully.",
},
)
@service_api_ns.expect(service_api_ns.models[MetadataArgs.__name__])
@service_api_ns.doc("create_dataset_metadata")
@service_api_ns.doc(description="Create metadata for a dataset")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID."})
@service_api_ns.doc(
responses={
201: "Metadata created successfully",
400: "Bad request - invalid or duplicate metadata name",
401: "Unauthorized - invalid API token",
404: "Dataset not found",
}
)
@service_api_ns.response(
201, "Metadata created successfully", service_api_ns.models[DatasetMetadataResponse.__name__]
)
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
@model_validate(MetadataArgs)
def post(self, metadata_args: MetadataArgs, session: Session, tenant_id, dataset_id: UUID):
"""Create metadata for a dataset."""
dataset_id_str = str(dataset_id)
dataset = DatasetService.get_dataset_for_tenant(dataset_id_str, str(tenant_id), session=session)
if dataset is None:
raise NotFound("Dataset not found.")
DatasetService.check_dataset_permission(dataset, current_user, session)
session.commit()
try:
metadata = application_services().knowledge.metadata.create_metadata(
DatasetRef(str(tenant_id), dataset_id_str), metadata_args, actor_id=current_user.id
)
except MetadataResourceNotFoundError as exc:
raise NotFound(str(exc)) from exc
return dump_response(DatasetMetadataResponse, metadata), 201
@service_api_ns.doc(
summary="List Metadata Fields",
description=(
"Returns the list of all metadata fields (both custom and built-in) for the knowledge base, "
"along with the count of documents using each field."
),
tags=["Metadata"],
responses={
200: "Metadata fields for the knowledge base.",
},
)
@service_api_ns.doc("get_dataset_metadata")
@service_api_ns.doc(description="Get all metadata for a dataset")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID."})
@service_api_ns.doc(
responses={
200: "Metadata retrieved successfully",
401: "Unauthorized - invalid API token",
404: "Dataset not found",
}
)
@service_api_ns.response(
200, "Metadata retrieved successfully", service_api_ns.models[DatasetMetadataListResponse.__name__]
)
@with_session(write=False)
def get(self, session: Session, tenant_id, dataset_id: UUID):
"""Get all metadata for a dataset."""
dataset_id_str = str(dataset_id)
dataset = DatasetService.get_dataset_for_tenant(dataset_id_str, str(tenant_id), session=session)
if dataset is None:
raise NotFound("Dataset not found.")
session.commit()
try:
metadata = application_services().knowledge.metadata.get_dataset_metadatas(
DatasetRef(str(tenant_id), dataset_id_str)
)
except MetadataResourceNotFoundError as exc:
raise NotFound(str(exc)) from exc
return dump_response(DatasetMetadataListResponse, metadata), 200
@service_api_ns.route("/datasets/<uuid:dataset_id>/metadata/<uuid:metadata_id>")
class DatasetMetadataServiceApi(DatasetApiResource):
@service_api_ns.doc(
summary="Update Metadata Field",
description="Rename a custom metadata field.",
tags=["Metadata"],
responses={
200: "Metadata field updated successfully.",
},
)
@service_api_ns.expect(service_api_ns.models[MetadataUpdatePayload.__name__])
@service_api_ns.doc("update_dataset_metadata")
@service_api_ns.doc(description="Update metadata name")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID.", "metadata_id": "Metadata field ID."})
@service_api_ns.doc(
responses={
200: "Metadata updated successfully",
400: "Bad request - invalid or duplicate metadata name",
401: "Unauthorized - invalid API token",
404: "Dataset or metadata not found",
}
)
@service_api_ns.response(
200, "Metadata updated successfully", service_api_ns.models[DatasetMetadataResponse.__name__]
)
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
@model_validate(MetadataUpdatePayload)
def patch(self, payload: MetadataUpdatePayload, session: Session, tenant_id, dataset_id: UUID, metadata_id: UUID):
"""Update metadata name."""
dataset_id_str = str(dataset_id)
metadata_id_str = str(metadata_id)
dataset = DatasetService.get_dataset_for_tenant(dataset_id_str, tenant_id, session=session)
if dataset is None:
raise NotFound("Dataset not found.")
DatasetService.check_dataset_permission(dataset, current_user, session)
session.commit()
try:
metadata = application_services().knowledge.metadata.update_metadata_name(
DatasetRef(str(tenant_id), dataset_id_str), metadata_id_str, payload.name, actor_id=current_user.id
)
except MetadataResourceNotFoundError as exc:
raise NotFound(str(exc)) from exc
return dump_response(DatasetMetadataResponse, metadata), 200
@service_api_ns.doc(
summary="Delete Metadata Field",
description=(
"Permanently delete a custom metadata field. Documents using this field will lose their "
"metadata values for it."
),
tags=["Metadata"],
responses={
204: "Success.",
},
)
@service_api_ns.doc("delete_dataset_metadata")
@service_api_ns.doc(description="Delete metadata")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID.", "metadata_id": "Metadata field ID."})
@service_api_ns.doc(
responses={
204: "Metadata deleted successfully",
401: "Unauthorized - invalid API token",
404: "Dataset or metadata not found",
}
)
@service_api_ns.response(204, "Metadata deleted successfully")
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
def delete(self, session: Session, tenant_id, dataset_id: UUID, metadata_id: UUID):
"""Delete metadata."""
dataset_id_str = str(dataset_id)
metadata_id_str = str(metadata_id)
dataset = DatasetService.get_dataset_for_tenant(dataset_id_str, tenant_id, session=session)
if dataset is None:
raise NotFound("Dataset not found.")
DatasetService.check_dataset_permission(dataset, current_user, session)
session.commit()
try:
application_services().knowledge.metadata.delete_metadata(
DatasetRef(str(tenant_id), dataset_id_str), metadata_id_str
)
except MetadataResourceNotFoundError as exc:
raise NotFound(str(exc)) from exc
return "", 204
@service_api_ns.route("/datasets/<uuid:dataset_id>/metadata/built-in")
class DatasetMetadataBuiltInFieldServiceApi(DatasetApiResource):
@service_api_ns.doc(
summary="Get Built-in Metadata Fields",
description=(
"Returns the list of built-in metadata fields provided by the system (e.g., document type, source URL)."
),
tags=["Metadata"],
responses={
200: "Built-in metadata fields.",
404: "`not_found` : Knowledge base not found.",
},
)
@service_api_ns.doc("get_built_in_fields")
@service_api_ns.doc(description="Get all built-in metadata fields")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID."})
@service_api_ns.doc(
responses={
200: "Built-in fields retrieved successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(
200,
"Built-in fields retrieved successfully",
service_api_ns.models[DatasetMetadataBuiltInFieldsResponse.__name__],
)
def get(self, tenant_id, dataset_id: UUID):
"""Get all built-in metadata fields."""
built_in_fields = application_services().knowledge.metadata.get_built_in_fields()
return dump_response(DatasetMetadataBuiltInFieldsResponse, {"fields": built_in_fields}), 200
@service_api_ns.route("/datasets/<uuid:dataset_id>/metadata/built-in/<string:action>")
class DatasetMetadataBuiltInFieldActionServiceApi(DatasetApiResource):
@service_api_ns.doc(
summary="Update Built-in Metadata Field",
description="Enable or disable built-in metadata fields for the knowledge base.",
tags=["Metadata"],
responses={
200: "Built-in metadata field toggled successfully.",
},
)
@service_api_ns.doc("toggle_built_in_field")
@service_api_ns.doc(description="Enable or disable built-in metadata field")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID.", "action": BUILT_IN_METADATA_ACTION_PARAM})
@service_api_ns.doc(
responses={
200: "Action completed successfully",
401: "Unauthorized - invalid API token",
404: "Dataset not found",
}
)
@service_api_ns.response(
200, "Action completed successfully", service_api_ns.models[DatasetMetadataActionResponse.__name__]
)
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
def post(self, session: Session, tenant_id, dataset_id: UUID, action: Literal["enable", "disable"]):
"""Enable or disable built-in metadata field."""
dataset_id_str = str(dataset_id)
dataset = DatasetService.get_dataset_for_tenant(dataset_id_str, str(tenant_id), session=session)
if dataset is None:
raise NotFound("Dataset not found.")
DatasetService.check_dataset_permission(dataset, current_user, session)
session.commit()
try:
match action:
case "enable":
application_services().knowledge.metadata.enable_built_in_field(
DatasetRef(str(tenant_id), dataset_id_str)
)
case "disable":
application_services().knowledge.metadata.disable_built_in_field(
DatasetRef(str(tenant_id), dataset_id_str)
)
except MetadataResourceNotFoundError as exc:
raise NotFound(str(exc)) from exc
return dump_response(DatasetMetadataActionResponse, {"result": "success"}), 200
@service_api_ns.route("/datasets/<uuid:dataset_id>/documents/metadata")
class DocumentMetadataEditServiceApi(DatasetApiResource):
@service_api_ns.doc(
summary="Update Document Metadata in Batch",
description=(
"Update metadata values for multiple documents at once. Each document in the request "
"receives the specified metadata key-value pairs."
),
tags=["Metadata"],
responses={
200: "Document metadata updated successfully.",
},
)
@service_api_ns.expect(service_api_ns.models[MetadataOperationData.__name__])
@service_api_ns.doc("update_documents_metadata")
@service_api_ns.doc(description="Update metadata for multiple documents")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID."})
@service_api_ns.doc(
responses={
200: "Documents metadata updated successfully",
400: "Bad request - invalid or conflicting document metadata operation",
401: "Unauthorized - invalid API token",
404: "Dataset, document, or metadata not found",
}
)
@service_api_ns.response(
200,
"Documents metadata updated successfully",
service_api_ns.models[DatasetMetadataActionResponse.__name__],
)
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
@model_validate(MetadataOperationData)
def post(self, metadata_args: MetadataOperationData, session: Session, tenant_id, dataset_id: UUID):
"""Update metadata for multiple documents."""
dataset = DatasetService.get_dataset_for_tenant(str(dataset_id), str(tenant_id), session=session)
if dataset is None:
raise NotFound("Dataset not found.")
DatasetService.check_dataset_permission(dataset, current_user, session)
session.commit()
try:
application_services().knowledge.metadata.update_documents_metadata(
DatasetRef(str(tenant_id), str(dataset_id)), metadata_args, actor_id=current_user.id
)
except MetadataResourceNotFoundError as exc:
raise NotFound(str(exc)) from exc
return dump_response(DatasetMetadataActionResponse, {"result": "success"}), 200
@@ -0,0 +1,410 @@
from collections.abc import Generator
from datetime import datetime
from typing import Any
from uuid import UUID
from flask import request
from pydantic import BaseModel, Field, RootModel, field_validator
from sqlalchemy import select
from sqlalchemy.orm import Session
from werkzeug.exceptions import Forbidden, NotFound
import services
from controllers.common.errors import (
FilenameNotExistsError,
FileTooLargeError,
NoFileUploadedError,
TooManyFilesError,
UnsupportedFileTypeError,
)
from controllers.common.fields import WorkflowBlockingResponse
from controllers.common.schema import (
query_params_from_model,
query_params_from_request,
register_response_schema_models,
register_schema_model,
)
from controllers.console.app.wraps import with_session
from controllers.console.wraps import model_validate
from controllers.service_api import service_api_ns
from controllers.service_api.dataset.error import PipelineRunError
from controllers.service_api.schema import event_stream_response, json_or_event_stream_response, multipart_file_params
from controllers.service_api.wraps import DatasetApiResource
from core.app.apps.pipeline.pipeline_generator import PipelineGenerator
from core.app.entities.app_invoke_entities import InvokeFrom
from core.entities.knowledge_entities import PipelineDataset, PipelineDocument
from extensions.ext_application_services import application_services
from fields.base import ResponseModel
from libs import helper
from libs.external_api import error_responses
from libs.helper import dump_response
from libs.login import current_user
from models import Account
from models.dataset import Dataset, Pipeline
from models.engine import db
from services.feature_service import FeatureService
from services.file_service import FileService
from services.rag_pipeline.entity.pipeline_service_api_entities import (
DatasourceNodeRunApiEntity,
DatasourceType,
PipelineRunApiEntity,
)
from services.rag_pipeline.pipeline_generate_service import PipelineGenerateService
from services.rag_pipeline.rag_pipeline import RagPipelineService
class DatasourceNodeRunPayload(BaseModel):
inputs: dict[str, Any] = Field(description="Input variables for the datasource node.")
datasource_type: DatasourceType = Field(description="Type of the datasource.")
credential_id: str | None = Field(
default=None, description="Datasource credential ID. Uses the default if omitted."
)
is_published: bool = Field(
description=(
"Whether to run the published or draft version of the node. `true` runs the published version, "
"`false` runs the draft."
)
)
class DatasourcePluginsQuery(BaseModel):
is_published: bool = Field(
default=True,
description=(
"Whether to retrieve nodes from the published or draft pipeline. `true` returns nodes from the published "
"version, `false` returns nodes from the draft."
),
)
class DatasourceCredentialInfoResponse(ResponseModel):
id: str | None = None
name: str | None = None
type: str | None = None
is_default: bool | None = None
class DatasourcePluginResponse(ResponseModel):
node_id: str | None = None
plugin_id: str | None = None
provider_name: str | None = None
datasource_type: str | None = None
title: str | None = None
user_input_variables: list[dict[str, Any]] = Field(default_factory=list)
credentials: list[DatasourceCredentialInfoResponse] = Field(default_factory=list)
class DatasourcePluginListResponse(RootModel[list[DatasourcePluginResponse]]):
pass
class PipelineUploadFileResponse(ResponseModel):
id: str
name: str
size: int
extension: str
mime_type: str | None = None
created_by: str
created_at: str | None = None
@field_validator("created_at", mode="before")
@classmethod
def _normalize_created_at(cls, value: datetime | str | None) -> str | None:
if isinstance(value, datetime):
return value.isoformat()
return value
class PublishedPipelineRunResponse(ResponseModel):
batch: str
dataset: PipelineDataset
documents: list[PipelineDocument]
class PipelineRunJsonResponse(RootModel[PublishedPipelineRunResponse | WorkflowBlockingResponse]):
"""JSON result for published runs and draft runs using `response_mode: blocking`."""
register_schema_model(service_api_ns, DatasourceNodeRunPayload)
register_schema_model(service_api_ns, DatasourcePluginsQuery)
register_schema_model(service_api_ns, PipelineRunApiEntity)
register_response_schema_models(
service_api_ns,
DatasourceCredentialInfoResponse,
DatasourcePluginResponse,
DatasourcePluginListResponse,
PipelineUploadFileResponse,
WorkflowBlockingResponse,
PublishedPipelineRunResponse,
PipelineRunJsonResponse,
)
@service_api_ns.route("/datasets/<uuid:dataset_id>/pipeline/datasource-plugins")
class DatasourcePluginsApi(DatasetApiResource):
"""Resource for datasource plugins."""
@service_api_ns.doc(
summary="List Datasource Plugins",
description=(
"List the datasource nodes configured in the knowledge pipeline. Each node includes the plugin it uses "
"plus the metadata needed to run it."
),
tags=["Knowledge Pipeline"],
responses={
200: "List of datasource nodes configured in the pipeline.",
404: "`not_found` : Dataset not found.",
},
)
@service_api_ns.doc(shortcut="list_rag_pipeline_datasource_plugins")
@service_api_ns.doc(description="List all datasource plugins for a rag pipeline")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID."})
@service_api_ns.doc(params=query_params_from_model(DatasourcePluginsQuery))
@service_api_ns.doc(
responses={
200: "Datasource plugins retrieved successfully",
400: "Bad request - pipeline is not configured",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(
200,
"Datasource plugins retrieved successfully",
service_api_ns.models[DatasourcePluginListResponse.__name__],
)
def get(self, tenant_id: str, dataset_id: UUID):
"""Resource for getting datasource plugins."""
dataset_id_str = str(dataset_id)
# Verify dataset ownership
stmt = select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str)
dataset = db.session.scalar(stmt)
if not dataset:
raise NotFound("Dataset not found.")
query = query_params_from_request(DatasourcePluginsQuery)
rag_pipeline_service = RagPipelineService(db.session())
datasource_plugins: list[dict[Any, Any]] = rag_pipeline_service.get_datasource_plugins(
tenant_id=tenant_id,
dataset_id=dataset_id_str,
is_published=query.is_published,
credential_query=application_services().credential_queries,
datasource_providers=application_services().data_sources.providers,
)
return dump_response(DatasourcePluginListResponse, datasource_plugins), 200
@service_api_ns.route("/datasets/<uuid:dataset_id>/pipeline/datasource/nodes/<string:node_id>/run")
class DatasourceNodeRunApi(DatasetApiResource):
"""Resource for datasource node run."""
@service_api_ns.doc(
summary="Run Datasource Node",
description=(
"Execute a single datasource node within the knowledge pipeline. Returns a streaming response with the "
"node execution results."
),
tags=["Knowledge Pipeline"],
responses={
200: "Streaming response with node execution events.",
404: "`not_found` : Dataset not found.",
},
)
@event_stream_response(service_api_ns)
@service_api_ns.doc(shortcut="run_datasource_node")
@service_api_ns.doc(description="Run a datasource node for a rag pipeline")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID.", "node_id": "ID of the datasource node to execute."})
@service_api_ns.doc(
responses={
200: "Datasource node run successfully",
400: "Bad request - invalid payload or pipeline is not configured",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.expect(service_api_ns.models[DatasourceNodeRunPayload.__name__])
@model_validate(DatasourceNodeRunPayload)
def post(self, payload: DatasourceNodeRunPayload, tenant_id: str, dataset_id: UUID, node_id: str):
"""Resource for getting datasource plugins."""
dataset_id_str = str(dataset_id)
# Verify dataset ownership
stmt = select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str)
dataset = db.session.scalar(stmt)
if not dataset:
raise NotFound("Dataset not found.")
assert isinstance(current_user, Account)
rag_pipeline_service: RagPipelineService = RagPipelineService(db.session())
pipeline: Pipeline = rag_pipeline_service.get_pipeline(tenant_id=tenant_id, dataset_id=dataset_id_str)
datasource_node_run_api_entity = DatasourceNodeRunApiEntity.model_validate(
{
**payload.model_dump(exclude_none=True),
"pipeline_id": pipeline.id,
"node_id": node_id,
}
)
# response-contract:ignore compact_generate_response
return helper.compact_generate_response(
PipelineGenerator.convert_to_event_stream(
rag_pipeline_service.run_datasource_workflow_node(
pipeline=pipeline,
node_id=node_id,
user_inputs=datasource_node_run_api_entity.inputs,
account=current_user,
datasource_type=datasource_node_run_api_entity.datasource_type,
is_published=datasource_node_run_api_entity.is_published,
credential_id=datasource_node_run_api_entity.credential_id,
datasource_providers=application_services().data_sources.providers,
)
)
)
@service_api_ns.route("/datasets/<uuid:dataset_id>/pipeline/run")
class PipelineRunApi(DatasetApiResource):
"""Resource for datasource node run."""
@error_responses(PipelineRunError)
@service_api_ns.doc(
summary="Run Pipeline",
description=(
"Execute the full knowledge pipeline for a knowledge base. Published runs are queued and return batch "
"metadata as JSON. Draft runs support blocking JSON and streaming Server-Sent Events."
),
tags=["Knowledge Pipeline"],
responses={
200: (
"Pipeline execution result. Published runs return a JSON object containing `batch`, `dataset`, and "
"`documents`. Draft runs return `text/event-stream` for streaming mode or a workflow result JSON "
"object for blocking mode."
),
403: "`forbidden` : Forbidden.",
404: "`not_found` : Dataset not found.",
500: "`pipeline_run_error` : Pipeline execution failed.",
},
)
@json_or_event_stream_response(service_api_ns)
@service_api_ns.doc(shortcut="run_pipeline")
@service_api_ns.doc(description="Run a datasource node for a rag pipeline")
@service_api_ns.doc(params={"dataset_id": "Knowledge base ID."})
@service_api_ns.doc(
responses={
200: "Pipeline run successfully",
400: "Bad request - invalid payload or pipeline is not configured",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.expect(service_api_ns.models[PipelineRunApiEntity.__name__])
@service_api_ns.response(
200,
"Pipeline run successfully",
service_api_ns.models[PipelineRunJsonResponse.__name__],
)
@with_session
def post(self, session: Session, tenant_id: str, dataset_id: UUID):
"""Resource for running a rag pipeline."""
dataset_id_str = str(dataset_id)
# Verify dataset ownership
stmt = select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str)
dataset = session.scalar(stmt)
if not dataset:
raise NotFound("Dataset not found.")
payload = PipelineRunApiEntity.model_validate(service_api_ns.payload or {})
if not isinstance(current_user, Account):
raise Forbidden()
rag_pipeline_service = RagPipelineService(session)
pipeline = rag_pipeline_service.get_pipeline(tenant_id=tenant_id, dataset_id=dataset_id_str)
try:
response: dict[Any, Any] | Generator[str, Any] = PipelineGenerateService.generate(
generator=application_services().knowledge.pipeline_generator,
session=session,
pipeline=pipeline,
user=current_user,
args=payload.model_dump(),
invoke_from=InvokeFrom.PUBLISHED_PIPELINE if payload.is_published else InvokeFrom.DEBUGGER,
streaming=payload.response_mode == "streaming",
)
# response-contract:ignore compact_generate_response
return helper.compact_generate_response(response)
except Exception as ex:
raise PipelineRunError(description=str(ex)) from ex
@service_api_ns.route("/datasets/pipeline/file-upload")
class KnowledgebasePipelineFileUploadApi(DatasetApiResource):
"""Resource for uploading a file to a knowledgebase pipeline."""
@error_responses(
FilenameNotExistsError, FileTooLargeError, NoFileUploadedError, TooManyFilesError, UnsupportedFileTypeError
)
@service_api_ns.doc(
summary="Upload Pipeline File",
description="Upload a file for use in a knowledge pipeline. Accepts a single file via `multipart/form-data`.",
tags=["Knowledge Pipeline"],
responses={
201: "File uploaded successfully.",
400: (
"- `no_file_uploaded` : Please upload your file.\n"
"- `filename_not_exists_error` : The specified filename does not exist.\n"
"- `too_many_files` : Only one file is allowed."
),
413: "`file_too_large` : File size exceeded.",
415: "`unsupported_file_type` : File type not allowed.",
},
)
@service_api_ns.doc(shortcut="knowledgebase_pipeline_file_upload")
@service_api_ns.doc(description="Upload a file to a knowledgebase pipeline")
@service_api_ns.doc(consumes=["multipart/form-data"], params=multipart_file_params(include_user=False))
@service_api_ns.doc(
responses={
201: "File uploaded successfully",
400: "Bad request - no file or invalid file",
401: "Unauthorized - invalid API token",
413: "File too large",
415: "Unsupported file type",
}
)
@service_api_ns.response(
201,
"File uploaded successfully",
service_api_ns.models[PipelineUploadFileResponse.__name__],
)
def post(self, tenant_id: str):
"""Upload a file for use in conversations.
Accepts a single file upload via multipart/form-data.
"""
# check file
if "file" not in request.files:
raise NoFileUploadedError()
if len(request.files) > 1:
raise TooManyFilesError()
file = request.files["file"]
if not file.mimetype:
raise UnsupportedFileTypeError()
if not file.filename:
raise FilenameNotExistsError
if not current_user:
raise ValueError("Invalid user account")
try:
upload_file = FileService(db.engine).upload_file(
filename=file.filename,
content=file.stream.read(),
mimetype=file.mimetype,
user=current_user,
default_file_size_limit=FeatureService.get_knowledge_file_size_limit(tenant_id),
)
except services.errors.file.FileTooLargeError as file_too_large_error:
raise FileTooLargeError(file_too_large_error.description) from file_too_large_error
except services.errors.file.UnsupportedFileTypeError as caught_error:
raise UnsupportedFileTypeError() from caught_error
return dump_response(PipelineUploadFileResponse, upload_file), 201
@@ -0,0 +1,866 @@
from typing import cast
from uuid import UUID
from pydantic import BaseModel, Field, ValidationError, field_validator
from sqlalchemy import select
from sqlalchemy.orm import Session
from werkzeug.exceptions import NotFound
from configs import dify_config
from controllers.common.controller_schemas import ChildChunkCreatePayload, ChildChunkUpdatePayload
from controllers.common.fields import ErrorMessageResponse
from controllers.common.schema import (
query_params_from_model,
query_params_from_request,
register_response_schema_models,
register_schema_models,
)
from controllers.common.session import with_session
from controllers.console.wraps import model_validate
from controllers.service_api import service_api_ns
from controllers.service_api.app.error import ProviderNotInitializeError
from controllers.service_api.wraps import (
DatasetApiResource,
cloud_edition_billing_knowledge_limit_check,
cloud_edition_billing_rate_limit_check,
cloud_edition_billing_resource_check,
)
from core.errors.error import LLMBadRequestError, ProviderTokenNotInitError
from core.model_manager import ModelManager
from core.rag.index_processor.constant.index_type import IndexTechniqueType
from extensions.ext_application_services import application_services
from fields.base import ResponseModel
from fields.segment_fields import (
ChildChunkDetailResponse,
ChildChunkListResponse,
SegmentDetailResponse,
SegmentResponse,
)
from graphon.model_runtime.entities.model_entities import ModelType
from libs.external_api import error_responses
from libs.helper import dump_response
from libs.login import current_account_with_tenant
from models.dataset import Dataset, Document, DocumentSegment
from services.errors.chunk import ChildChunkDeleteIndexError, ChildChunkIndexingError
from services.errors.chunk import ChildChunkDeleteIndexError as ChildChunkDeleteIndexServiceError
from services.errors.chunk import ChildChunkIndexingError as ChildChunkIndexingServiceError
from services.knowledge.dataset_read_service import load_segment_detail, load_segment_details
from services.knowledge.dataset_service import DatasetService, DocumentService, SegmentService
from services.knowledge.entities.segments import SegmentUpdateArgs
from services.knowledge.resource_scope import DatasetRef, SegmentRef
from services.knowledge.summaries.adapters import SummaryIndexAdapter
class SegmentCreateItemPayload(BaseModel):
content: str = Field(min_length=1, description="Chunk text content.")
answer: str | None = Field(default=None, description="Answer content for QA mode.")
keywords: list[str] | None = Field(default=None, description="Keywords for the chunk.")
attachment_ids: list[str] | None = Field(default=None, description="Attachment file IDs.")
@field_validator("content")
@classmethod
def validate_content(cls, value: str) -> str:
if not value.strip():
raise ValueError("Content is empty")
return value
class SegmentCreatePayload(BaseModel):
segments: list[SegmentCreateItemPayload] = Field(min_length=1, description="Array of chunk objects to create.")
class SegmentListQuery(BaseModel):
limit: int = Field(default=20, ge=1, description="Number of items per page. Server caps at `100`.")
page: int = Field(default=1, ge=1, description="Page number to retrieve.")
status: list[str] = Field(
default_factory=list,
description="Filter chunks by indexing status, such as `completed`, `indexing`, or `error`.",
)
keyword: str | None = Field(default=None, description="Search keyword.")
class SegmentUpdatePayload(BaseModel):
segment: SegmentUpdateArgs = Field(description="Chunk data to update.")
class ChildChunkListQuery(BaseModel):
limit: int = Field(default=20, ge=1, description="Number of items per page. Server caps at `100`.")
keyword: str | None = Field(default=None, description="Search keyword.")
page: int = Field(default=1, ge=1, description="Page number to retrieve.")
class SegmentDocParams:
DATASET_DOCUMENT = {"dataset_id": "Knowledge base ID.", "document_id": "Document ID."}
DATASET_DOCUMENT_SEGMENT = {**DATASET_DOCUMENT, "segment_id": "Chunk ID."}
DATASET_DOCUMENT_PARENT_SEGMENT = {**DATASET_DOCUMENT, "segment_id": "Chunk ID."}
DATASET_DOCUMENT_CHILD_CHUNK = {**DATASET_DOCUMENT_PARENT_SEGMENT, "child_chunk_id": "Child chunk ID."}
class SegmentCreateListResponse(ResponseModel):
data: list[SegmentResponse]
doc_form: str
class SegmentListResponse(ResponseModel):
data: list[SegmentResponse]
doc_form: str
total: int
has_more: bool
limit: int
page: int
register_schema_models(
service_api_ns,
SegmentCreatePayload,
SegmentCreateItemPayload,
SegmentListQuery,
SegmentUpdateArgs,
SegmentUpdatePayload,
ChildChunkCreatePayload,
ChildChunkListQuery,
ChildChunkUpdatePayload,
)
register_response_schema_models(
service_api_ns,
ErrorMessageResponse,
SegmentResponse,
SegmentCreateListResponse,
SegmentListResponse,
SegmentDetailResponse,
ChildChunkDetailResponse,
ChildChunkListResponse,
)
def _get_segment_for_document(
session: Session, dataset: Dataset, document: Document, segment_id: str
) -> tuple[SegmentRef, DocumentSegment]:
if document.tenant_id != dataset.tenant_id or document.dataset_id != dataset.id:
raise NotFound("Document not found.")
dataset_ref = DatasetRef(tenant_id=dataset.tenant_id, dataset_id=dataset.id)
segment_ref = dataset_ref.document(document.id).segment(segment_id)
segment = SegmentService.get_segment_by_ref(segment_ref, session=session)
if not segment:
raise NotFound("Segment not found.")
return segment_ref, segment
@service_api_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments")
class SegmentApi(DatasetApiResource):
"""Resource for segments."""
@error_responses(ProviderNotInitializeError)
@service_api_ns.doc(
summary="Create Chunks",
description=(
"Create one or more chunks within a document. Each chunk can include optional keywords and an "
"answer field (for QA-mode documents)."
),
tags=["Chunks"],
responses={
200: "Chunks created successfully.",
404: "`not_found` : Document is not completed or is disabled.",
},
)
@service_api_ns.expect(service_api_ns.models[SegmentCreatePayload.__name__])
@service_api_ns.doc("create_segments")
@service_api_ns.doc(description="Create segments in a document")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
@service_api_ns.doc(
responses={
200: "Segments created successfully",
400: "Bad request - segments data is missing",
401: "Unauthorized - invalid API token",
404: "Dataset or document not found",
}
)
@service_api_ns.response(
200,
"Segments created successfully",
service_api_ns.models[SegmentCreateListResponse.__name__],
)
@service_api_ns.response(
400,
"Bad request - segments data is missing",
service_api_ns.models[ErrorMessageResponse.__name__],
)
@cloud_edition_billing_resource_check("vector_space", "dataset")
@cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
def post(self, session: Session, tenant_id: str, dataset_id: UUID, document_id: UUID):
_, current_tenant_id = current_account_with_tenant()
"""Create single segment."""
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset.id, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
if document.indexing_status != "completed":
raise NotFound("Document is not completed.")
if not document.enabled:
raise NotFound("Document is disabled.")
# check embedding model setting
if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
try:
model_manager = ModelManager.for_tenant(tenant_id=current_tenant_id)
model_manager.get_model_instance(
tenant_id=current_tenant_id,
provider=dataset.embedding_model_provider,
model_type=ModelType.TEXT_EMBEDDING,
model=dataset.embedding_model,
)
except LLMBadRequestError as caught_error:
raise ProviderNotInitializeError(
"No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
) from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
# validate args
try:
payload = SegmentCreatePayload.model_validate(service_api_ns.payload or {})
except ValidationError as e:
return {"error": str(e)}, 400
segments_limit = dify_config.DATASET_MAX_SEGMENTS_PER_REQUEST
if segments_limit > 0 and len(payload.segments) > segments_limit:
raise ValueError(f"Exceeded maximum segments limit of {segments_limit}.")
segment_items = [segment.model_dump(exclude_none=True) for segment in payload.segments]
for args_item in segment_items:
SegmentService.segment_create_args_validate(args_item, document)
segments = cast(
list[DocumentSegment],
SegmentService.multi_create_segment(
segment_items,
document,
dataset,
session,
mutations=application_services().knowledge.segments.mutations,
),
)
segment_ids = [segment.id for segment in segments]
summaries: dict[str, str | None] = {}
if segment_ids:
summary_records = SummaryIndexAdapter.get_segments_summaries(
segment_ids=segment_ids, dataset_id=dataset_id_str, session=session
)
summaries = {chunk_id: record.summary_content for chunk_id, record in summary_records.items()}
response = {
"data": load_segment_details(segments, summaries, session=session),
"doc_form": document.doc_form,
}
return dump_response(SegmentCreateListResponse, response), 200
@error_responses(ProviderNotInitializeError)
@service_api_ns.doc(
summary="List Chunks",
description="Returns a paginated list of chunks within a document. Supports filtering by keyword and status.",
tags=["Chunks"],
responses={
200: "List of chunks.",
},
)
@service_api_ns.doc("list_segments")
@service_api_ns.doc(description="List segments in a document")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT)
@service_api_ns.doc(params=query_params_from_model(SegmentListQuery))
@service_api_ns.doc(
responses={
200: "Segments retrieved successfully",
400: "Bad request - embedding model is not configured",
401: "Unauthorized - invalid API token",
404: "Dataset or document not found",
}
)
@service_api_ns.response(
200,
"Segments retrieved successfully",
service_api_ns.models[SegmentListResponse.__name__],
)
@with_session
def get(self, session: Session, tenant_id: str, dataset_id: UUID, document_id: UUID):
_, current_tenant_id = current_account_with_tenant()
"""Get segments."""
# check dataset
args = query_params_from_request(
SegmentListQuery,
list_fields=("status",),
use_defaults_for_malformed_ints=True,
)
page = args.page
limit = min(args.limit, 100)
dataset_id_str = str(dataset_id)
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset.id, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
# check embedding model setting
if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
try:
model_manager = ModelManager.for_tenant(tenant_id=current_tenant_id)
model_manager.get_model_instance(
tenant_id=current_tenant_id,
provider=dataset.embedding_model_provider,
model_type=ModelType.TEXT_EMBEDDING,
model=dataset.embedding_model,
)
except LLMBadRequestError as caught_error:
raise ProviderNotInitializeError(
"No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
) from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
segments, total = SegmentService.get_segments(
session=session,
document_id=document_id_str,
tenant_id=current_tenant_id,
status_list=args.status,
keyword=args.keyword,
page=page,
limit=limit,
)
segment_ids = [segment.id for segment in segments]
summaries: dict[str, str | None] = {}
if segment_ids:
summary_records = SummaryIndexAdapter.get_segments_summaries(
segment_ids=segment_ids, dataset_id=dataset_id_str, session=session
)
summaries = {chunk_id: record.summary_content for chunk_id, record in summary_records.items()}
response = {
"data": load_segment_details(segments, summaries, session=session),
"doc_form": document.doc_form,
"total": total,
"has_more": page * limit < total,
"limit": limit,
"page": page,
}
return dump_response(SegmentListResponse, response), 200
@service_api_ns.route("/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>")
class DatasetSegmentApi(DatasetApiResource):
@service_api_ns.doc(
summary="Delete Chunk",
description="Permanently delete a chunk from the document.",
tags=["Chunks"],
responses={
204: "Success.",
},
)
@service_api_ns.doc("delete_segment")
@service_api_ns.doc(description="Delete a specific segment")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
@service_api_ns.doc(
responses={
204: "Segment deleted successfully",
400: "Bad request - invalid dataset model state or concurrent deletion",
401: "Unauthorized - invalid API token",
404: "Dataset, document, or segment not found",
}
)
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
def delete(self, session: Session, tenant_id: str, dataset_id: UUID, document_id: UUID, segment_id: UUID):
current_account_with_tenant()
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
# check user's model setting
DatasetService.check_dataset_model_setting(dataset)
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset_id_str, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
segment_id_str = str(segment_id)
_, segment = _get_segment_for_document(session, dataset, document, segment_id_str)
SegmentService.delete_segment(
segment, document, dataset, session, mutations=application_services().knowledge.segments.mutations
)
return "", 204
@error_responses(ProviderNotInitializeError)
@service_api_ns.doc(
summary="Update Chunk",
description="Update a chunk's content, keywords, or answer. Re-triggers indexing for the modified chunk.",
tags=["Chunks"],
responses={
200: "Chunk updated successfully.",
},
)
@service_api_ns.expect(service_api_ns.models[SegmentUpdatePayload.__name__])
@service_api_ns.doc("update_segment")
@service_api_ns.doc(description="Update a specific segment")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
@service_api_ns.doc(
responses={
200: "Segment updated successfully",
400: "Bad request - invalid segment or embedding model configuration",
401: "Unauthorized - invalid API token",
404: "Dataset, document, or segment not found",
}
)
@service_api_ns.response(200, "Segment updated successfully", service_api_ns.models[SegmentDetailResponse.__name__])
@cloud_edition_billing_resource_check("vector_space", "dataset")
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
@model_validate(SegmentUpdatePayload)
def post(
self,
payload: SegmentUpdatePayload,
session: Session,
tenant_id: str,
dataset_id: UUID,
document_id: UUID,
segment_id: UUID,
):
current_account, current_tenant_id = current_account_with_tenant()
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
# check user's model setting
DatasetService.check_dataset_model_setting(dataset)
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset_id_str, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
# check embedding model setting
try:
model_manager = ModelManager.for_tenant(tenant_id=current_tenant_id)
model_manager.get_model_instance(
tenant_id=current_tenant_id,
provider=dataset.embedding_model_provider,
model_type=ModelType.TEXT_EMBEDDING,
model=dataset.embedding_model,
)
except LLMBadRequestError as caught_error:
raise ProviderNotInitializeError(
"No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
) from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
segment_id_str = str(segment_id)
_, segment = _get_segment_for_document(session, dataset, document, segment_id_str)
updated_segment = SegmentService.update_segment(
payload.segment,
segment,
document,
dataset,
session,
actor_id=current_account.id,
mutations=application_services().knowledge.segments.mutations,
)
summary = SummaryIndexAdapter.get_segment_summary(
segment_id=updated_segment.id, dataset_id=dataset_id_str, session=session
)
response = {
"data": load_segment_detail(updated_segment, summary.summary_content if summary else None, session=session),
"doc_form": document.doc_form,
}
return dump_response(SegmentDetailResponse, response), 200
@service_api_ns.doc(
summary="Get Chunk",
description=(
"Retrieve detailed information about a specific chunk, including its content, keywords, and "
"indexing status."
),
tags=["Chunks"],
responses={
200: "Chunk details.",
},
)
@service_api_ns.doc("get_segment")
@service_api_ns.doc(description="Get a specific segment by ID")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_SEGMENT)
@service_api_ns.doc(
responses={
200: "Segment retrieved successfully",
400: "Bad request - invalid dataset model configuration",
401: "Unauthorized - invalid API token",
404: "Dataset, document, or segment not found",
}
)
@service_api_ns.response(
200,
"Segment retrieved successfully",
service_api_ns.models[SegmentDetailResponse.__name__],
)
@with_session
def get(self, session: Session, tenant_id: str, dataset_id: UUID, document_id: UUID, segment_id: UUID):
current_account_with_tenant()
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
# check user's model setting
DatasetService.check_dataset_model_setting(dataset)
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset_id_str, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
segment_id_str = str(segment_id)
_, segment = _get_segment_for_document(session, dataset, document, segment_id_str)
summary = SummaryIndexAdapter.get_segment_summary(
segment_id=segment.id, dataset_id=dataset_id_str, session=session
)
response = {
"data": load_segment_detail(segment, summary.summary_content if summary else None, session=session),
"doc_form": document.doc_form,
}
return dump_response(SegmentDetailResponse, response), 200
@service_api_ns.route(
"/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks"
)
class ChildChunkApi(DatasetApiResource):
"""Resource for child chunks."""
@error_responses(ProviderNotInitializeError)
@service_api_ns.doc(
summary="Create Child Chunk",
description="Create a child chunk under the specified segment.",
tags=["Chunks"],
responses={
200: "Child chunk created successfully.",
400: "`invalid_param` : Create child chunk index failed.",
},
)
@service_api_ns.expect(service_api_ns.models[ChildChunkCreatePayload.__name__])
@service_api_ns.doc("create_child_chunk")
@service_api_ns.doc(description="Create a new child chunk for a segment")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT)
@service_api_ns.doc(
responses={
200: "Child chunk created successfully",
401: "Unauthorized - invalid API token",
404: "Dataset, document, or segment not found",
}
)
@service_api_ns.response(
200,
"Child chunk created successfully",
service_api_ns.models[ChildChunkDetailResponse.__name__],
)
@cloud_edition_billing_resource_check("vector_space", "dataset")
@cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
@model_validate(ChildChunkCreatePayload)
def post(
self,
payload: ChildChunkCreatePayload,
session: Session,
tenant_id: str,
dataset_id: UUID,
document_id: UUID,
segment_id: UUID,
):
current_account, current_tenant_id = current_account_with_tenant()
"""Create child chunk."""
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset.id, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
segment_id_str = str(segment_id)
_, segment = _get_segment_for_document(session, dataset, document, segment_id_str)
# check embedding model setting
if dataset.indexing_technique == IndexTechniqueType.HIGH_QUALITY:
try:
model_manager = ModelManager.for_tenant(tenant_id=current_tenant_id)
model_manager.get_model_instance(
tenant_id=current_tenant_id,
provider=dataset.embedding_model_provider,
model_type=ModelType.TEXT_EMBEDDING,
model=dataset.embedding_model,
)
except LLMBadRequestError as caught_error:
raise ProviderNotInitializeError(
"No Embedding Model available. Please configure a valid provider in the Settings -> Model Provider."
) from caught_error
except ProviderTokenNotInitError as ex:
raise ProviderNotInitializeError(ex.description) from ex
try:
child_chunk = SegmentService.create_child_chunk(
payload.content,
segment,
document,
dataset,
session,
actor_id=current_account.id,
mutations=application_services().knowledge.segments.mutations,
)
except ChildChunkIndexingServiceError as e:
raise ChildChunkIndexingError(str(e)) from e
return dump_response(ChildChunkDetailResponse, {"data": child_chunk}), 200
@service_api_ns.doc(
summary="List Child Chunks",
description="Returns a paginated list of child chunks under a specific parent chunk.",
tags=["Chunks"],
responses={
200: "List of child chunks.",
},
)
@service_api_ns.doc("list_child_chunks")
@service_api_ns.doc(description="List child chunks for a segment")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_PARENT_SEGMENT)
@service_api_ns.doc(params=query_params_from_model(ChildChunkListQuery))
@service_api_ns.doc(
responses={
200: "Child chunks retrieved successfully",
401: "Unauthorized - invalid API token",
404: "Dataset, document, or segment not found",
}
)
@service_api_ns.response(
200,
"Child chunks retrieved successfully",
service_api_ns.models[ChildChunkListResponse.__name__],
)
@with_session
def get(self, session: Session, tenant_id: str, dataset_id: UUID, document_id: UUID, segment_id: UUID):
current_account_with_tenant()
"""Get child chunks."""
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset.id, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
segment_id_str = str(segment_id)
_get_segment_for_document(session, dataset, document, segment_id_str)
args = query_params_from_request(ChildChunkListQuery, use_defaults_for_malformed_ints=True)
page = args.page
limit = min(args.limit, 100)
keyword = args.keyword
child_chunks = SegmentService.get_child_chunks(
segment_id_str,
document_id_str,
dataset_id_str,
page,
limit,
keyword,
session=session,
)
response = {
"data": child_chunks.items,
"total": child_chunks.total,
"total_pages": child_chunks.pages,
"page": page,
"limit": limit,
}
return dump_response(ChildChunkListResponse, response), 200
@service_api_ns.route(
"/datasets/<uuid:dataset_id>/documents/<uuid:document_id>/segments/<uuid:segment_id>/child_chunks/<uuid:child_chunk_id>"
)
class DatasetChildChunkApi(DatasetApiResource):
"""Resource for updating child chunks."""
@service_api_ns.doc(
summary="Delete Child Chunk",
description="Permanently delete a child chunk from its parent chunk.",
tags=["Chunks"],
responses={
204: "Success.",
400: "`invalid_param` : Delete child chunk index failed.",
},
)
@service_api_ns.doc("delete_child_chunk")
@service_api_ns.doc(description="Delete a specific child chunk")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_CHILD_CHUNK)
@service_api_ns.doc(
responses={
204: "Child chunk deleted successfully",
401: "Unauthorized - invalid API token",
404: "Dataset, document, segment, or child chunk not found",
}
)
@cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
def delete(
self,
session: Session,
tenant_id: str,
dataset_id: UUID,
document_id: UUID,
segment_id: UUID,
child_chunk_id: UUID,
):
current_account_with_tenant()
"""Delete child chunk."""
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
document_id_str = str(document_id)
# check document
document = DocumentService.get_document(dataset.id, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
segment_id_str = str(segment_id)
segment_ref, _ = _get_segment_for_document(session, dataset, document, segment_id_str)
child_chunk_id_str = str(child_chunk_id)
# check child chunk
child_chunk = SegmentService.get_child_chunk_by_segment_ref(child_chunk_id_str, segment_ref, session=session)
if not child_chunk:
raise NotFound("Child chunk not found.")
try:
SegmentService.delete_child_chunk(
child_chunk, dataset, session, mutations=application_services().knowledge.segments.mutations
)
except ChildChunkDeleteIndexServiceError as e:
raise ChildChunkDeleteIndexError(str(e)) from e
return "", 204
@service_api_ns.doc(
summary="Update Child Chunk",
description="Update the content of an existing child chunk.",
tags=["Chunks"],
responses={
200: "Child chunk updated successfully.",
400: "`invalid_param` : Update child chunk index failed.",
},
)
@service_api_ns.expect(service_api_ns.models[ChildChunkUpdatePayload.__name__])
@service_api_ns.doc("update_child_chunk")
@service_api_ns.doc(description="Update a specific child chunk")
@service_api_ns.doc(params=SegmentDocParams.DATASET_DOCUMENT_CHILD_CHUNK)
@service_api_ns.doc(
responses={
200: "Child chunk updated successfully",
401: "Unauthorized - invalid API token",
404: "Dataset, document, segment, or child chunk not found",
}
)
@service_api_ns.response(
200,
"Child chunk updated successfully",
service_api_ns.models[ChildChunkDetailResponse.__name__],
)
@cloud_edition_billing_resource_check("vector_space", "dataset")
@cloud_edition_billing_knowledge_limit_check("add_segment", "dataset")
@cloud_edition_billing_rate_limit_check("knowledge", "dataset")
@with_session
@model_validate(ChildChunkUpdatePayload)
def patch(
self,
payload: ChildChunkUpdatePayload,
session: Session,
tenant_id: str,
dataset_id: UUID,
document_id: UUID,
segment_id: UUID,
child_chunk_id: UUID,
):
current_account, _ = current_account_with_tenant()
"""Update child chunk."""
dataset_id_str = str(dataset_id)
# check dataset
dataset = session.scalar(
select(Dataset).where(Dataset.tenant_id == tenant_id, Dataset.id == dataset_id_str).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
document_id_str = str(document_id)
# get document
document = DocumentService.get_document(dataset_id_str, document_id_str, session=session)
if not document:
raise NotFound("Document not found.")
segment_id_str = str(segment_id)
segment_ref, segment = _get_segment_for_document(session, dataset, document, segment_id_str)
child_chunk_id_str = str(child_chunk_id)
# get child chunk
child_chunk = SegmentService.get_child_chunk_by_segment_ref(child_chunk_id_str, segment_ref, session=session)
if not child_chunk:
raise NotFound("Child chunk not found.")
try:
child_chunk = SegmentService.update_child_chunk(
payload.content,
child_chunk,
segment,
document,
dataset,
session,
actor_id=current_account.id,
mutations=application_services().knowledge.segments.mutations,
)
except ChildChunkIndexingServiceError as e:
raise ChildChunkIndexingError(str(e)) from e
return dump_response(ChildChunkDetailResponse, {"data": child_chunk}), 200
@@ -0,0 +1,3 @@
from . import end_user
__all__ = ["end_user"]
@@ -0,0 +1,65 @@
from uuid import UUID
from flask_restx import Resource
from controllers.common.schema import register_response_schema_models
from controllers.service_api import service_api_ns
from controllers.service_api.end_user.error import EndUserNotFoundError
from controllers.service_api.wraps import validate_app_token
from extensions.ext_application_services import application_services
from fields.end_user_fields import EndUserDetail
from libs.external_api import error_responses
from libs.helper import dump_response
from machinery.context import AppRequestContext
from models.model import App
from services.app_scoped_end_user_query_service import AppScopedEndUserNotFoundError
register_response_schema_models(service_api_ns, EndUserDetail)
@service_api_ns.route("/end-users/<uuid:end_user_id>")
class EndUserApi(Resource):
"""Resource for retrieving end user details by ID."""
@error_responses(EndUserNotFoundError)
@service_api_ns.doc(
summary="Get End User Info",
description=(
"Retrieve an end user by ID. Useful when other APIs return an end-user ID (e.g., "
"`created_by` from [Upload File](/api-reference/files/upload-file))."
),
tags=["End Users"],
responses={
200: "End user retrieved successfully.",
404: "`end_user_not_found` : End user not found.",
},
)
@service_api_ns.doc("get_end_user")
@service_api_ns.doc(description="Get an end user by ID")
@service_api_ns.doc(
params={"end_user_id": "End user ID"},
responses={
200: "End user retrieved successfully",
401: "Unauthorized - invalid API token",
404: "End user not found",
},
)
@service_api_ns.response(200, "End user retrieved successfully", service_api_ns.models[EndUserDetail.__name__])
@validate_app_token
def get(self, app_model: App, end_user_id: UUID):
"""Get end user detail.
This endpoint is scoped to the current app token's tenant/app to prevent
cross-tenant/app access when an end-user ID is known.
"""
request_context = AppRequestContext(
tenant_id=app_model.tenant_id,
app_id=app_model.id,
)
try:
end_user = application_services().app_scoped_end_users.queries.get_by_id(request_context, str(end_user_id))
except AppScopedEndUserNotFoundError as error:
raise EndUserNotFoundError() from error
return dump_response(EndUserDetail, end_user)
@@ -0,0 +1,7 @@
from libs.exception import BaseHTTPException
class EndUserNotFoundError(BaseHTTPException):
error_code = "end_user_not_found"
description = "End user not found."
code = 404
@@ -0,0 +1,168 @@
"""Service API admission for handlers that consume stable app and actor identities."""
from collections.abc import Callable
from functools import wraps
from typing import Concatenate
from flask import request
from controllers.common.errors import ForbiddenError, InvalidArgumentError, NotFoundError, UnauthorizedError
from controllers.service_api.app import error as http_errors
from controllers.service_api.wraps import (
FetchUserArg,
document_app_token_contract,
peek_service_api_bearer_token,
resolve_service_api_end_user,
validate_and_get_api_token,
)
from core.logging.context import set_identity_context
from extensions.ext_application_services import application_services
from extensions.otel.runtime import set_identity_span_attributes
from libs.external_api import document_errors
from machinery.context import AppRequestContext, ServiceApiAccountRequestContext, ServiceApiEndUserContext
from services.app_definition_query_service import AppDefinitionUnavailableError, ServiceApiAppRecord
from services.auth.resource_access_token_contracts import (
ResourceAccessTokenForbiddenError,
ResourceAccessTokenInputError,
ResourceAccessTokenInvalidError,
ResourceAccessTokenNotFoundError,
is_resource_access_token,
)
from services.errors.app import AppAbnormalStatusError, AppApiDisabledError
from services.errors.workspace import WorkspaceArchivedError, WorkspaceNotFoundError
_APP_ADMISSION_ERRORS = (
ForbiddenError,
http_errors.AppNotFoundError,
http_errors.AppAbnormalStatusError,
http_errors.AppApiDisabledError,
http_errors.WorkspaceNotFoundError,
http_errors.WorkspaceArchivedError,
)
def service_api_end_user_admission[T, **P, R](
*,
fetch_user_arg: FetchUserArg,
) -> Callable[
[Callable[Concatenate[T, ServiceApiEndUserContext, P], R]],
Callable[Concatenate[T, P], R],
]:
"""Validate API access before provisioning an end user and injecting scalar identity.
App/workspace reads finish before user provisioning or the handler runs. The
shared login helper retains Flask's request identity for legacy dependencies;
neither an ORM object nor its session is passed to the handler.
"""
def decorator(
view: Callable[Concatenate[T, ServiceApiEndUserContext, P], R],
) -> Callable[Concatenate[T, P], R]:
@wraps(view)
def admitted(self: T, /, *args: P.args, **kwargs: P.kwargs) -> R:
app = _admit_service_api_app()
end_user = resolve_service_api_end_user(
tenant_id=app.tenant_id, app_id=app.app_id, fetch_user_arg=fetch_user_arg
)
context = ServiceApiEndUserContext(
tenant_id=app.tenant_id,
app_id=app.app_id,
app_mode=app.mode,
end_user_id=end_user.id,
)
return view(self, context, *args, **kwargs)
document_app_token_contract(admitted, fetch_user_arg)
document_errors(admitted, *_APP_ADMISSION_ERRORS)
return admitted
return decorator
def service_api_app_admission[T, **P, R](
view: Callable[Concatenate[T, AppRequestContext, P], R],
) -> Callable[Concatenate[T, P], R]:
"""Admit app-token queries without an end user or request-scoped ORM session.
Retain the legacy active-workspace/owner requirement without logging in that
owner: handlers consume only the token's app scope, not an Account identity.
"""
@wraps(view)
def admitted(self: T, /, *args: P.args, **kwargs: P.kwargs) -> R:
app = _admit_service_api_app()
_require_service_api_owner(app.tenant_id)
return view(self, AppRequestContext(tenant_id=app.tenant_id, app_id=app.app_id), *args, **kwargs)
document_app_token_contract(admitted, None)
document_errors(admitted, *_APP_ADMISSION_ERRORS)
return admitted
def service_api_account_admission[T, **P, R](
view: Callable[Concatenate[T, ServiceApiAccountRequestContext, P], R],
) -> Callable[Concatenate[T, P], R]:
"""Admit app access and use its workspace owner for account-backed operations.
This owner is the legacy attribution identity, not a user authenticated by the token.
"""
@wraps(view)
def admitted(self: T, /, *args: P.args, **kwargs: P.kwargs) -> R:
app = _admit_service_api_app()
context = ServiceApiAccountRequestContext(
tenant_id=app.tenant_id,
app_id=app.app_id,
account_id=_require_service_api_owner(app.tenant_id),
)
set_identity_context(tenant_id=context.tenant_id, user_id=context.account_id, user_type="account")
set_identity_span_attributes(tenant_id=context.tenant_id, user_id=context.account_id)
return view(self, context, *args, **kwargs)
document_app_token_contract(admitted, None)
document_errors(admitted, *_APP_ADMISSION_ERRORS)
return admitted
def _require_service_api_owner(tenant_id: str) -> str:
account_id = application_services().app_definitions.get_service_api_owner_id(tenant_id)
if account_id is None:
raise UnauthorizedError("Tenant owner account not found or tenant is not active.")
return account_id
def _admit_service_api_app() -> ServiceApiAppRecord:
auth_token = peek_service_api_bearer_token()
if auth_token and is_resource_access_token(auth_token):
try:
grant = application_services().resource_access_tokens.resolve_app_for_service_api(
token=auth_token,
requested_app_id=request.headers.get("X-Dify-App-ID"),
)
except ResourceAccessTokenInputError as error:
raise InvalidArgumentError(str(error)) from error
except ResourceAccessTokenForbiddenError as error:
raise ForbiddenError(str(error)) from error
except ResourceAccessTokenNotFoundError as error:
raise NotFoundError(str(error)) from error
except ResourceAccessTokenInvalidError as error:
raise UnauthorizedError(str(error)) from error
app_id = next(iter(grant.app_ids))
tenant_id = grant.tenant_id
else:
token = validate_and_get_api_token("app")
app_id = token.app_id
tenant_id = token.tenant_id
try:
return application_services().app_definitions.get_service_api_app(app_id, tenant_id=tenant_id)
except AppDefinitionUnavailableError as error:
raise http_errors.AppNotFoundError() from error
except AppAbnormalStatusError as error:
raise http_errors.AppAbnormalStatusError() from error
except AppApiDisabledError as error:
raise http_errors.AppApiDisabledError() from error
except WorkspaceNotFoundError as error:
raise http_errors.WorkspaceNotFoundError() from error
except WorkspaceArchivedError as error:
raise http_errors.WorkspaceArchivedError() from error
@@ -0,0 +1,28 @@
from flask_restx import Resource
from configs import dify_config
from controllers.common.schema import register_response_schema_models
from controllers.service_api import service_api_ns
from fields.base import ResponseModel
class IndexInfoResponse(ResponseModel):
welcome: str
api_version: str
server_version: str
register_response_schema_models(service_api_ns, IndexInfoResponse)
@service_api_ns.route("/", endpoint="root")
class IndexApi(Resource):
@service_api_ns.doc("get_index_api", security=[])
@service_api_ns.response(200, "Success", service_api_ns.models[IndexInfoResponse.__name__])
def get(self) -> dict[str, str]:
"""Return public Service API metadata without requiring an API key."""
return IndexInfoResponse(
welcome="Dify OpenAPI",
api_version="v1",
server_version=dify_config.project.version,
).model_dump(mode="json")
@@ -0,0 +1,5 @@
"""KnowledgeFS-specific Service API authenticated by resource credentials."""
from . import resources
__all__ = ["resources"]
@@ -0,0 +1,92 @@
"""Stable KnowledgeFS Service API error contract."""
from libs.exception import BaseHTTPException
from services.knowledge_fs.product_dto import KnowledgeFSPublicFailureResponse
class _KnowledgeFSServiceFailureHTTPError(BaseHTTPException):
def __init__(self, failure: KnowledgeFSPublicFailureResponse | None = None) -> None:
super().__init__(failure.message if failure else None)
if failure is not None and self.data is not None:
self.data["failure"] = failure.model_dump(by_alias=True, exclude_none=True)
class KnowledgeFSInvalidCredentialHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_invalid_credential"
description = "Invalid Agent Knowledge Base service credential."
code = 401
class KnowledgeFSServiceOperationUnavailableHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_operation_unavailable"
description = "Agent Knowledge Base operation is not available."
code = 503
class KnowledgeFSServiceUpstreamUnavailableHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_upstream_unavailable"
description = "Agent Knowledge Base is unavailable."
code = 502
class KnowledgeFSServiceTimeoutHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_timeout"
description = "Agent Knowledge Base request timed out."
code = 504
class KnowledgeFSServiceInvalidRequestHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_invalid_request"
description = "Agent Knowledge Base request is invalid."
code = 400
class KnowledgeFSServiceAccessDeniedHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_access_denied"
description = "Agent Knowledge Base operation is not allowed."
code = 403
class KnowledgeFSServiceResourceNotFoundHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_resource_not_found"
description = "Agent Knowledge Base resource was not found."
code = 404
class KnowledgeFSServiceConflictHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_conflict"
description = "Agent Knowledge Base operation conflicts with the current resource state."
code = 409
class KnowledgeFSServiceRequestTooLargeHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_request_too_large"
description = "Agent Knowledge Base request is too large."
code = 413
class KnowledgeFSServiceRequestRejectedHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_request_rejected"
description = "Agent Knowledge Base request was rejected."
code = 422
class KnowledgeFSServiceRateLimitHTTPError(_KnowledgeFSServiceFailureHTTPError):
error_code = "knowledge_fs_rate_limit_exceeded"
description = "Agent Knowledge Base request rate limit exceeded."
code = 429
__all__ = [
"KnowledgeFSInvalidCredentialHTTPError",
"KnowledgeFSServiceAccessDeniedHTTPError",
"KnowledgeFSServiceConflictHTTPError",
"KnowledgeFSServiceInvalidRequestHTTPError",
"KnowledgeFSServiceOperationUnavailableHTTPError",
"KnowledgeFSServiceRateLimitHTTPError",
"KnowledgeFSServiceRequestRejectedHTTPError",
"KnowledgeFSServiceRequestTooLargeHTTPError",
"KnowledgeFSServiceResourceNotFoundHTTPError",
"KnowledgeFSServiceTimeoutHTTPError",
"KnowledgeFSServiceUpstreamUnavailableHTTPError",
]
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,211 @@
"""Service API OpenAPI documentation helpers.
These helpers keep documentation-only request shapes next to controller
definitions without changing the Pydantic models used for runtime validation.
"""
from __future__ import annotations
from collections.abc import Sequence
from copy import deepcopy
from typing import Annotated, Any, cast
from flask_restx import Namespace
from pydantic import BaseModel, WithJsonSchema
from libs.flask_restx_compat import BINARY_RESPONSE_MEDIA_TYPES_VENDOR_KEY
USER_DESCRIPTION = (
"End-user identifier, defined by your app and unique within it. Identifies the end user for this request. "
"See [End User Identity](/api-reference/guides/end-user-identity) for endpoint-specific access rules."
)
SCOPED_TASK_STOP_USER_DESCRIPTION = (
"End-user identifier, defined by your app and unique within it. Send the same `user` value used for the original "
"generation request. See "
"[End User Identity](/api-reference/guides/end-user-identity)."
)
WORKFLOW_TASK_STOP_USER_DESCRIPTION = (
"End-user identifier, defined by your app and unique within it. It does not need to match the `user` that "
"started the run; the stop applies to the task regardless of `user`. See "
"[End User Identity](/api-reference/guides/end-user-identity)."
)
USER_PROPERTY_SCHEMA: dict[str, object] = {"description": USER_DESCRIPTION, "type": "string"}
USER_QUERY_PARAM: dict[str, object] = {
"description": "User identifier, used for end-user context.",
"in": "query",
"type": "string",
}
USER_FORM_PARAM: dict[str, object] = {
"description": USER_DESCRIPTION,
"in": "formData",
"type": "string",
}
FILE_FORM_PARAM: dict[str, object] = {
"description": "The file to upload.",
"in": "formData",
"required": True,
"type": "file",
}
USER_FETCH_FROM_ATTR = "_dify_service_api_user_fetch_from"
USER_REQUIRED_ATTR = "_dify_service_api_user_required"
JSON_USER_FETCH_FROM = "JSON"
def _input_file_variant(transfer_method: str, source: str) -> dict[str, object]:
return {
"type": "object",
"properties": {
"type": {
"description": "File type.",
"enum": ["document", "image", "audio", "video", "custom"],
"type": "string",
},
"transfer_method": {
"description": (
"Transfer method: `remote_url` for a file URL or persisted uploaded-file reference, "
"`local_file` for an uploaded file."
),
"enum": [transfer_method],
"type": "string",
},
"url": {
"description": "File URL when `transfer_method` is `remote_url`.",
"format": "url",
"type": "string",
},
"remote_url": {
"description": "Legacy alias of `url` when `transfer_method` is `remote_url`.",
"format": "url",
"type": "string",
},
"upload_file_id": {
"description": (
"Uploaded file ID obtained from the [Upload File](/api-reference/files/upload-file) API. "
"Required for `local_file`; also accepted with `remote_url` for compatibility with persisted "
"file references."
),
"type": "string",
},
},
"required": ["type", "transfer_method", source],
}
INPUT_FILE_ITEM_SCHEMA: dict[str, object] = {
"type": "object",
"anyOf": [
_input_file_variant("remote_url", "url"),
_input_file_variant("remote_url", "remote_url"),
_input_file_variant("remote_url", "upload_file_id"),
_input_file_variant("local_file", "upload_file_id"),
],
}
INPUT_FILE_LIST_SCHEMA: dict[str, object] = {
"anyOf": [{"items": INPUT_FILE_ITEM_SCHEMA, "type": "array"}, {"type": "null"}]
}
InputFileList = Annotated[list[dict[str, Any]] | None, WithJsonSchema(INPUT_FILE_LIST_SCHEMA)]
def expect_with_user(namespace: Namespace, model: type[BaseModel]):
"""Document a JSON request body as ``model`` plus Service API ``user``."""
source_model = namespace.models[model.__name__]
model_name = f"{model.__name__}WithUser"
def decorator(view_func):
required = _json_user_required(view_func)
schema = cast(dict[str, object], deepcopy(source_model.__schema__))
_add_user_property(schema, required=required)
if model_name not in namespace.models:
namespace.schema_model(model_name, schema)
return namespace.expect(namespace.models[model_name], validate=False)(view_func)
return decorator
def expect_user_json(
namespace: Namespace,
*,
model_name: str | None = None,
user_description: str = USER_DESCRIPTION,
):
"""Document a JSON request body that only carries the Service API ``user``."""
def decorator(view_func):
required = _json_user_required(view_func)
schema: dict[str, object] = {"properties": {}, "title": "ServiceApiUserPayload", "type": "object"}
_add_user_property(schema, required=required, description=user_description)
resolved_model_name = model_name or (
"RequiredServiceApiUserPayload" if required else "OptionalServiceApiUserPayload"
)
if resolved_model_name not in namespace.models:
namespace.schema_model(resolved_model_name, schema)
return namespace.expect(namespace.models[resolved_model_name], validate=False)(view_func)
return decorator
def multipart_file_params(*, include_user: bool, file_description: str | None = None) -> dict[str, dict[str, object]]:
file_param = deepcopy(FILE_FORM_PARAM)
if file_description is not None:
file_param["description"] = file_description
params: dict[str, dict[str, object]] = {"file": file_param}
if include_user:
params["user"] = USER_FORM_PARAM
return deepcopy(params)
def json_or_event_stream_response(namespace: Namespace):
return namespace.doc(produces=["application/json", "text/event-stream"])
def event_stream_response(namespace: Namespace):
return namespace.doc(produces=["text/event-stream"])
def binary_response(namespace: Namespace, media_type: str | Sequence[str]):
media_types = [media_type] if isinstance(media_type, str) else list(media_type)
return namespace.doc(
produces=media_types,
vendor={BINARY_RESPONSE_MEDIA_TYPES_VENDOR_KEY: media_types},
)
def _json_user_required(view_func) -> bool:
fetch_from = getattr(view_func, USER_FETCH_FROM_ATTR, None)
if fetch_from != JSON_USER_FETCH_FROM:
raise ValueError("JSON user documentation must match validate_app_token(fetch_user_arg=WhereisUserArg.JSON)")
return bool(getattr(view_func, USER_REQUIRED_ATTR, False))
def _add_user_property(schema: dict[str, object], *, required: bool, description: str = USER_DESCRIPTION) -> None:
variants: list[dict[str, object]] = []
for keyword in ("anyOf", "oneOf"):
candidates = schema.get(keyword)
if isinstance(candidates, list):
variants.extend(candidate for candidate in candidates if isinstance(candidate, dict))
if variants:
for variant in variants:
_add_user_property_to_object_schema(variant, required=required, description=description)
_add_user_property_to_object_schema(schema, required=required, description=description)
def _add_user_property_to_object_schema(schema: dict[str, object], *, required: bool, description: str) -> None:
properties = schema.setdefault("properties", {})
if isinstance(properties, dict):
cast(dict[str, object], properties)["user"] = {"description": description, "type": "string"}
if required:
required_fields = schema.setdefault("required", [])
if isinstance(required_fields, list) and "user" not in required_fields:
required_fields.append("user")
else:
required_fields = schema.get("required")
if isinstance(required_fields, list) and "user" in required_fields:
required_fields.remove("user")
if required_fields == []:
schema.pop("required", None)
@@ -0,0 +1,64 @@
from flask_login import current_user
from flask_restx import Resource
from controllers.common.schema import register_response_schema_models
from controllers.service_api import service_api_ns
from controllers.service_api.wraps import validate_dataset_token
from fields.base import ResponseModel
from graphon.model_runtime.utils.encoders import jsonable_encoder
from services.entities.model_provider_entities import ProviderWithModelsResponse
from services.model_provider.service import ModelProviderService
MODEL_TYPE_PARAM = {
"description": "Type of model to retrieve.",
"enum": ["text-embedding", "rerank", "llm", "tts", "speech2text", "moderation"],
"type": "string",
}
class ProviderWithModelsListResponse(ResponseModel):
data: list[ProviderWithModelsResponse]
register_response_schema_models(service_api_ns, ProviderWithModelsListResponse)
@service_api_ns.route("/workspaces/current/models/model-types/<string:model_type>")
class ModelProviderAvailableModelApi(Resource):
@service_api_ns.doc(
summary="Get Available Models",
description=(
"Retrieve the list of available models by type. Primarily used to query `text-embedding` and "
"`rerank` models for knowledge base configuration."
),
tags=["Models"],
responses={
200: "Available models for the specified type.",
},
)
@service_api_ns.doc("get_available_models")
@service_api_ns.doc(description="Get available models by model type")
@service_api_ns.doc(params={"model_type": MODEL_TYPE_PARAM})
@service_api_ns.doc(
responses={
200: "Models retrieved successfully",
401: "Unauthorized - invalid API token",
}
)
@service_api_ns.response(
200,
"Models retrieved successfully",
service_api_ns.models[ProviderWithModelsListResponse.__name__],
)
@validate_dataset_token
def get(self, _, model_type: str):
"""Get available models by model type.
Returns a list of available models for the specified model type.
"""
tenant_id = current_user.current_tenant_id
model_provider_service = ModelProviderService()
models = model_provider_service.get_models_by_model_type(tenant_id=tenant_id, model_type=model_type)
return jsonable_encoder({"data": models})
@@ -0,0 +1,502 @@
import inspect
import logging
from collections.abc import Callable
from enum import StrEnum, auto
from functools import wraps
from typing import Protocol, cast, overload
from flask import current_app, request
from flask_login import user_logged_in
from flask_restx import Resource
from flask_restx.utils import merge
from pydantic import BaseModel
from sqlalchemy import select
from sqlalchemy.orm import Session
from werkzeug.exceptions import Forbidden, NotFound, ServiceUnavailable, Unauthorized
from configs import dify_config
from controllers.common.access_response import MISSING_BEARER_MESSAGE
from controllers.common.errors import UnauthorizedError
from controllers.common.resource_access_token_errors import resource_access_token_errors
from controllers.service_api.schema import (
USER_FETCH_FROM_ATTR,
USER_FORM_PARAM,
USER_QUERY_PARAM,
USER_REQUIRED_ATTR,
)
from enums import CloudPlan, DeploymentEdition
from extensions.ext_application_services import application_services
from extensions.ext_database import db
from libs.login import current_user
from models import Account, Tenant, TenantAccountJoin, TenantStatus
from models.dataset import Dataset
from models.model import ApiToken, EndUser
from repositories.knowledge import dataset_api_key_bindings
from services.api_token_service import (
ApiTokenCache,
ApiTokenInvalidError,
CachedApiToken,
fetch_token_with_single_flight,
record_token_usage,
)
from services.app_service import AppService
from services.auth.resource_access_token_contracts import DatasetServiceApiGrant, is_resource_access_token
from services.feature_service import FeatureService
from services.knowledge_rate_limit_service import KnowledgeRateLimitExceededError, enforce_knowledge_rate_limit
logger = logging.getLogger(__name__)
class _RestxDocumentedView(Protocol):
"""Callable view object carrying Flask-RESTX documentation metadata."""
__apidoc__: dict[str, object]
class WhereisUserArg(StrEnum):
"""
Enum for whereis_user_arg.
"""
QUERY = auto()
JSON = auto()
FORM = auto()
class FetchUserArg(BaseModel):
fetch_from: WhereisUserArg
required: bool = False
APP_TOKEN_FORBIDDEN_RESPONSE = {
403: "Forbidden - token scope, app, dataset, or workspace access denied",
}
DATASET_TOKEN_AUTH_RESPONSES = {
401: "Unauthorized - invalid API token",
403: "Forbidden - dataset API access or workspace access denied",
}
VECTOR_SPACE_UNAVAILABLE_RESPONSE = {
503: (
"`service_unavailable` : Vector space usage could not be verified. Returned on the Dify Cloud Sandbox "
"plan only; retry the request later."
),
}
def document_app_token_contract(view_func: Callable[..., object], fetch_user_arg: FetchUserArg | None) -> None:
doc: dict[str, object] = {"responses": APP_TOKEN_FORBIDDEN_RESPONSE}
if fetch_user_arg is not None:
setattr(view_func, USER_FETCH_FROM_ATTR, fetch_user_arg.fetch_from.name)
setattr(view_func, USER_REQUIRED_ATTR, fetch_user_arg.required)
match fetch_user_arg.fetch_from:
case WhereisUserArg.QUERY:
doc["params"] = {"user": {**USER_QUERY_PARAM, "required": fetch_user_arg.required}}
case WhereisUserArg.FORM:
doc["params"] = {"user": {**USER_FORM_PARAM, "required": fetch_user_arg.required}}
case WhereisUserArg.JSON:
pass
cast(_RestxDocumentedView, view_func).__apidoc__ = cast(
dict[str, object],
merge(getattr(view_func, "__apidoc__", {}), doc),
)
@overload
def validate_app_token[**P, R](view: Callable[P, R]) -> Callable[P, R]: ...
@overload
def validate_app_token[**P, R](
view: None = None, *, fetch_user_arg: FetchUserArg | None = None
) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
def validate_app_token[**P, R](
view: Callable[P, R] | None = None, *, fetch_user_arg: FetchUserArg | None = None
) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
def decorator(view_func: Callable[P, R]) -> Callable[P, R]:
@wraps(view_func)
def decorated_view(*args: P.args, **kwargs: P.kwargs) -> R:
# TODO: Remove these duplicate app/workspace checks when all legacy
# ORM App/EndUser handlers (including account-only endpoints) migrate
# to scalar admission. Keep resource-token routing and app policy aligned
# with service_api_end_user_admission until then.
auth_token = peek_service_api_bearer_token()
if auth_token and is_resource_access_token(auth_token):
with resource_access_token_errors():
grant = application_services().resource_access_tokens.resolve_app_for_service_api(
token=auth_token,
requested_app_id=request.headers.get("X-Dify-App-ID"),
)
app_model = AppService.get_app_in_workspace(
tenant_id=grant.tenant_id,
app_id=next(iter(grant.app_ids)),
session=db.session(),
)
else:
api_token = validate_and_get_api_token("app")
app_model = AppService.get_app_by_id(api_token.app_id, session=db.session())
if not app_model:
raise Forbidden("The app no longer exists.")
if app_model.status != "normal":
raise Forbidden("The app's status is abnormal.")
if not app_model.enable_api:
raise Forbidden("The app's API service has been disabled.")
tenant = db.session.get(Tenant, app_model.tenant_id)
if tenant is None:
raise ValueError("Tenant does not exist.")
if tenant.status == TenantStatus.ARCHIVE:
raise Forbidden("The workspace's status is archived.")
kwargs["app_model"] = app_model
# If caller needs end-user context, attach EndUser to current_user
if fetch_user_arg:
kwargs["end_user"] = resolve_service_api_end_user(
tenant_id=app_model.tenant_id, app_id=app_model.id, fetch_user_arg=fetch_user_arg
)
else:
# For service API without end-user context, ensure an Account is logged in
# so services relying on current_account_with_tenant() work correctly.
tenant_owner_info = db.session.execute(
select(Tenant, Account)
.join(TenantAccountJoin, Tenant.id == TenantAccountJoin.tenant_id)
.join(Account, TenantAccountJoin.account_id == Account.id)
.where(
Tenant.id == app_model.tenant_id,
TenantAccountJoin.role == "owner",
Tenant.status == TenantStatus.NORMAL,
)
).one_or_none()
if tenant_owner_info:
tenant_model, account = tenant_owner_info
account.set_current_tenant_with_session(tenant_model, session=db.session())
current_app.login_manager._update_request_context_with_user(account) # type: ignore
user_logged_in.send(current_app._get_current_object(), user=current_user) # type: ignore
else:
raise Unauthorized("Tenant owner account not found or tenant is not active.")
return view_func(*args, **kwargs)
document_app_token_contract(decorated_view, fetch_user_arg)
return decorated_view
if view is None:
return decorator
else:
return decorator(view)
def resolve_service_api_end_user(*, tenant_id: str, app_id: str, fetch_user_arg: FetchUserArg) -> EndUser:
"""Share user parsing, provisioning and Flask login identity across API admission paths."""
user_id = None
match fetch_user_arg.fetch_from:
case WhereisUserArg.QUERY:
user_id = request.args.get("user")
case WhereisUserArg.JSON:
user_id = request.get_json().get("user")
case WhereisUserArg.FORM:
user_id = request.form.get("user")
if not user_id and fetch_user_arg.required:
raise ValueError("Arg user must be provided.")
if user_id:
user_id = str(user_id)
end_user = application_services().app_scoped_end_users.commands.get_or_create_end_user(tenant_id, app_id, user_id)
current_app.login_manager._update_request_context_with_user(end_user) # type: ignore
user_logged_in.send(current_app._get_current_object(), user=end_user) # type: ignore
return end_user
def cloud_edition_billing_resource_check[**P, R](
resource: str,
api_token_type: str,
) -> Callable[[Callable[P, R]], Callable[P, R]]:
def interceptor(view: Callable[P, R]):
@wraps(view)
def decorated(*args: P.args, **kwargs: P.kwargs):
api_token = validate_and_get_api_token(api_token_type)
if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD:
return view(*args, **kwargs)
tenant_id = api_token.tenant_id
if tenant_id is None:
raise Unauthorized("Tenant id is required for this token.")
if resource == "vector_space":
vector_space = application_services().feature_queries.get_workspace_vector_space(tenant_id)
if vector_space.usage_unknown:
features = FeatureService.get_features(tenant_id, exclude_vector_space=True)
if features.billing.subscription.plan == CloudPlan.SANDBOX:
raise ServiceUnavailable(
"Unable to verify vector space usage right now. Please try again later."
)
if 0 < vector_space.limit <= vector_space.size:
raise Forbidden("The capacity of the vector space has reached the limit of your subscription.")
return view(*args, **kwargs)
features = FeatureService.get_features(tenant_id, exclude_vector_space=True)
members = features.members
apps = features.apps
documents_upload_quota = features.documents_upload_quota
if resource == "members" and 0 < members.limit <= members.size:
raise Forbidden("The number of members has reached the limit of your subscription.")
elif resource == "apps" and 0 < apps.limit <= apps.size:
raise Forbidden("The number of apps has reached the limit of your subscription.")
elif resource == "documents" and 0 < documents_upload_quota.limit <= documents_upload_quota.size:
raise Forbidden("The number of documents has reached the limit of your subscription.")
return view(*args, **kwargs)
if resource == "vector_space":
cast(_RestxDocumentedView, decorated).__apidoc__ = cast(
dict[str, object],
merge(decorated.__dict__.get("__apidoc__", {}), {"responses": VECTOR_SPACE_UNAVAILABLE_RESPONSE}),
)
return decorated
return interceptor
def cloud_edition_billing_knowledge_limit_check[**P, R](
resource: str,
api_token_type: str,
) -> Callable[[Callable[P, R]], Callable[P, R]]:
def interceptor(view: Callable[P, R]):
@wraps(view)
def decorated(*args: P.args, **kwargs: P.kwargs):
api_token = validate_and_get_api_token(api_token_type)
if dify_config.DEPLOYMENT_EDITION != DeploymentEdition.CLOUD or resource != "add_segment":
return view(*args, **kwargs)
tenant_id = api_token.tenant_id
if tenant_id is None:
raise Unauthorized("Tenant id is required for this token.")
features = FeatureService.get_features(tenant_id, exclude_vector_space=True)
if features.billing.subscription.plan == CloudPlan.SANDBOX:
raise Forbidden(
"To unlock this feature and elevate your Dify experience, please upgrade to a paid plan."
)
return view(*args, **kwargs)
return decorated
return interceptor
def check_knowledge_rate_limit(api_token: ApiToken | CachedApiToken) -> None:
"""Enforce the cloud knowledge base request rate limit for a dataset API key's workspace.
Shared by the ``cloud_edition_billing_rate_limit_check`` decorator and the KnowledgeFS
service routes, which authenticate inside their own profile helper rather than through
a decorator. No-op unless the workspace has a knowledge rate limit (cloud billing).
"""
if api_token.tenant_id is None:
raise Unauthorized("Tenant id is required for this token.")
try:
enforce_knowledge_rate_limit(api_token.tenant_id)
except KnowledgeRateLimitExceededError as error:
raise Forbidden(str(error)) from error
def cloud_edition_billing_rate_limit_check[**P, R](
resource: str,
api_token_type: str,
) -> Callable[[Callable[P, R]], Callable[P, R]]:
def interceptor(view: Callable[P, R]):
@wraps(view)
def decorated(*args: P.args, **kwargs: P.kwargs):
api_token = validate_and_get_api_token(api_token_type)
if api_token.tenant_id is None:
raise Forbidden("API token is not associated with a workspace")
if resource == "knowledge":
check_knowledge_rate_limit(api_token)
return view(*args, **kwargs)
return decorated
return interceptor
def validate_dataset_token[R](view: Callable[..., R]) -> Callable[..., R]:
view_parameters = inspect.signature(view).parameters
positional_parameters = [
parameter
for parameter in view_parameters.values()
if parameter.kind in (inspect.Parameter.POSITIONAL_ONLY, inspect.Parameter.POSITIONAL_OR_KEYWORD)
]
expects_bound_instance = bool(positional_parameters and positional_parameters[0].name in {"self", "cls"})
accepts_dataset_grant = "dataset_grant" in view_parameters
@wraps(view)
def decorated(*args: object, **kwargs: object) -> R:
# Flask may pass URL path parameters positionally, so inspect both kwargs and args.
dataset_id = kwargs.get("dataset_id")
if not dataset_id and args:
potential_id = args[0]
try:
str_id = str(potential_id)
if len(str_id) == 36 and str_id.count("-") == 4:
dataset_id = str_id
except Exception:
logger.exception("Failed to parse dataset_id from positional args")
auth_token = peek_service_api_bearer_token()
if auth_token and is_resource_access_token(auth_token):
with resource_access_token_errors():
dataset_grant = application_services().resource_access_tokens.resolve_datasets_for_service_api(
token=auth_token,
dataset_id=str(dataset_id) if dataset_id else None,
)
tenant_id = dataset_grant.tenant_id
else:
api_token = validate_and_get_api_token("dataset")
tenant_id = api_token.tenant_id
# Per-knowledge-base scoping is expressed by DatasetApiTokenBinding rows:
# no rows -> the key can reach every dataset in its tenant (default / back-compat)
# N rows -> the key is limited to exactly those resources
# Only legacy-dataset bindings count here: a key bound solely to KnowledgeFS spaces
# is restricted but has no reachable legacy dataset, so it is rejected. A bound key
# may only call endpoints carrying one of its dataset ids; endpoints without a
# dataset id (e.g. list/create datasets) are rejected. The scope is queried per
# request (not cached) so changes take effect immediately.
# db.session is Flask-SQLAlchemy's scoped_session proxy; cast so the plain-Session
# typed helper accepts it (runtime proxies every Session method through unchanged).
if tenant_id is None:
raise Unauthorized("Tenant id is required for this token.")
scope = dataset_api_key_bindings.get_active_key_scope(
cast(Session, db.session), api_token_id=api_token.id, tenant_id=tenant_id
)
if scope is None:
raise Unauthorized("API key is no longer valid.")
if not scope.allows_dataset(str(dataset_id) if dataset_id else None):
raise Forbidden("The API key is not authorized to access this knowledge base.")
dataset_grant = DatasetServiceApiGrant(
token_id=str(api_token.id),
tenant_id=tenant_id,
dataset_ids=None,
)
if dataset_id:
dataset_id = str(dataset_id)
dataset = db.session.scalar(
select(Dataset)
.where(
Dataset.id == dataset_id,
Dataset.tenant_id == tenant_id,
)
.limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
if not dataset.enable_api:
raise Forbidden("Dataset api access is not enabled.")
tenant_account_join = db.session.execute(
select(Tenant, TenantAccountJoin).where(
Tenant.id == tenant_id,
TenantAccountJoin.tenant_id == Tenant.id,
TenantAccountJoin.role.in_(["owner"]),
Tenant.status == TenantStatus.NORMAL,
)
).one_or_none() # TODO: only owner information is required, so only one is returned.
if tenant_account_join:
tenant, ta = tenant_account_join
account = db.session.get(Account, ta.account_id)
# Login admin
if account:
account.set_current_tenant_with_session(tenant, session=db.session())
current_app.login_manager._update_request_context_with_user(account) # type: ignore
user_logged_in.send(current_app._get_current_object(), user=current_user) # type: ignore
else:
raise Unauthorized("Tenant owner account does not exist.")
else:
raise Unauthorized("Tenant does not exist.")
if accepts_dataset_grant:
kwargs["dataset_grant"] = dataset_grant
if expects_bound_instance:
if not args:
raise TypeError("validate_dataset_token expected a bound resource instance.")
return view(args[0], tenant_id, *args[1:], **kwargs)
return view(tenant_id, *args, **kwargs)
return decorated
def validate_and_get_api_token(scope: str | None = None) -> ApiToken | CachedApiToken:
"""
Validate and get API token with Redis caching.
This function uses a two-tier approach:
1. First checks Redis cache for the token
2. If not cached, queries database and caches the result
The last_used_at field is updated asynchronously via Celery task
to avoid blocking the request.
"""
auth_token = extract_service_api_bearer_token()
# Try to get token from cache first
# Returns a CachedApiToken (plain Python object), not a SQLAlchemy model
cached_token = ApiTokenCache.get(auth_token, scope)
if cached_token is not None:
logger.debug("Token validation served from cache for scope: %s", scope)
# Record usage in Redis for later batch update (no Celery task per request)
record_token_usage(auth_token, scope)
return cached_token
# Cache miss - use Redis lock for single-flight mode
# This ensures only one request queries DB for the same token concurrently
try:
return fetch_token_with_single_flight(auth_token, scope)
except ApiTokenInvalidError as error:
raise UnauthorizedError(str(error)) from error
def extract_service_api_bearer_token() -> str:
auth_token = peek_service_api_bearer_token()
if auth_token is None:
raise UnauthorizedError(MISSING_BEARER_MESSAGE)
return auth_token
def peek_service_api_bearer_token() -> str | None:
# Match the Gateway's HTTP SP/HTAB parser for both API keys and resource
# access tokens. Unicode whitespace must not bypass policy identity lookup.
auth_header = request.headers.get("Authorization") or ""
auth_parts = [part for part in auth_header.replace("\t", " ").split(" ") if part]
if len(auth_parts) != 2 or auth_parts[0].lower() != "bearer":
return None
return auth_parts[1]
class DatasetApiResource(Resource):
__apidoc__ = {"responses": DATASET_TOKEN_AUTH_RESPONSES}
method_decorators = [validate_dataset_token]
def get_dataset(self, dataset_id: str, tenant_id: str) -> Dataset:
dataset = db.session.scalar(
select(Dataset).where(Dataset.id == dataset_id, Dataset.tenant_id == tenant_id).limit(1)
)
if not dataset:
raise NotFound("Dataset not found.")
return dataset