Skip to content

RAGFlow is an agent-native database: a Retrieval-Augmented Generation (RAG) engine that grew into context infrastructure.

19.8 KB
Raw Blame
//
//  Copyright 2026 The InfiniFlow Authors. All Rights Reserved.
//
//  Licensed under the Apache License, Version 2.0 (the "License");
//  you may not use this file except in compliance with the License.
//  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//

package handler

import (
	"context"
	"encoding/json"
	"fmt"
	"io"
	"net/http"
	"strings"

	"github.com/gin-gonic/gin"

	"ragflow/internal/common"
	"ragflow/internal/entity"
	"ragflow/internal/permission"
	"ragflow/internal/service"

	"go.uber.org/zap"
)

// SearchBotAskRequest is the request body for POST /api/v1/searchbots/ask.
type SearchBotAskRequest struct {
	Query    string                   `json:"query,omitempty"`
	Messages []map[string]interface{} `json:"messages,omitempty"`
	Question string                   `json:"question"`
	KbIDs    common.StringSlice       `json:"kb_ids" binding:"required"`
	SearchID string                   `json:"search_id,omitempty"`
}

// SearchBotMindMapRequest is the request body for POST /api/v1/searchbots/mindmap.
type SearchBotMindMapRequest struct {
	Question string             `json:"question" binding:"required"`
	KbIDs    common.StringSlice `json:"kb_ids" binding:"required"`
	SearchID string             `json:"search_id,omitempty"`
}

// SearchBotRetrievalTestRequest is the request body for POST /api/v1/searchbots/retrieval.
type SearchBotRetrievalTestRequest struct {
	KbIDs                    common.StringSlice     `json:"kb_ids" binding:"required"`
	Question                 string                 `json:"question" binding:"required"`
	Page                     *int                   `json:"page,omitempty"`
	Size                     *int                   `json:"size,omitempty"`
	RerankCandidatesCount    *int                   `json:"rerank_candidates_count,omitempty"`
	DocIDs                   []string               `json:"doc_ids,omitempty"`
	UseKG                    *bool                  `json:"use_kg,omitempty"`
	TopK                     *int                   `json:"top_k,omitempty"`
	CrossLanguages           []string               `json:"cross_languages,omitempty"`
	SearchID                 *string                `json:"search_id,omitempty"`
	MetaDataFilter           map[string]interface{} `json:"meta_data_filter,omitempty"`
	TenantRerankID           *string                `json:"tenant_rerank_id,omitempty"`
	RerankID                 *string                `json:"rerank_id,omitempty"`
	Keyword                  *bool                  `json:"keyword,omitempty"`
	Highlight                *bool                  `json:"highlight,omitempty"`
	SimilarityThreshold      *float64               `json:"similarity_threshold,omitempty"`
	VectorSimilarityWeight   *float64               `json:"vector_similarity_weight,omitempty"`
	KeywordsSimilarityWeight *float64               `json:"keywords_similarity_weight,omitempty"`
}

// UnmarshalJSON accepts both kb_id (Python API) and kb_ids (Go compatibility).
func (r *SearchBotRetrievalTestRequest) UnmarshalJSON(data []byte) error {
	type Alias SearchBotRetrievalTestRequest
	aux := struct {
		*Alias
		KbID common.StringSlice `json:"kb_id"`
	}{
		Alias: (*Alias)(r),
	}
	if err := json.Unmarshal(data, &aux); err != nil {
		return err
	}
	if len(r.KbIDs) == 0 && len(aux.KbID) > 0 {
		r.KbIDs = aux.KbID
	}
	return nil
}

// SearchBotRequest is the request body for POST /api/v1/searchbots/related-questions.
// Question is validated manually below so the error message follows the
// established API contract instead of the Gin validator format.
type SearchBotRequest struct {
	Question string `json:"question"`
	SearchID string `json:"search_id,omitempty"`
}

// SearchBotHandler handles searchbot endpoints:
//
//	POST /api/v1/searchbots/related-questions
//	POST /api/v1/searchbots/retrieval
//	POST /api/v1/searchbots/ask
//	POST /api/v1/searchbots/mindmap
type SearchBotHandler struct {
	searchSvc    *service.SearchService
	tenantSvc    *service.TenantService
	modelFactory *service.ModelFactory
	chunkSvc     service.Retriever
	askSvc       *service.AskService
	sseWriter    SSEWriter
}

// NewSearchBotHandler creates a new SearchBotHandler.
func NewSearchBotHandler(searchSvc *service.SearchService, tenantSvc *service.TenantService, modelFactory *service.ModelFactory, chunkSvc service.Retriever) *SearchBotHandler {
	return &SearchBotHandler{searchSvc: searchSvc, tenantSvc: tenantSvc, modelFactory: modelFactory, chunkSvc: chunkSvc, sseWriter: &ginSSEWriter{}}
}

// SetAskService sets the AskService used by the Ask endpoint.
func (h *SearchBotHandler) SetAskService(svc *service.AskService) { h.askSvc = svc }

// Handle generates related search questions based on a user query.
// @Summary Generate Related Questions
// @Description Generates 5-10 related search questions to expand the search scope.
// @Tags searchbots
// @Accept json
// @Produce json
// @Param request body SearchBotRequest true "Request body"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/searchbots/related-questions [post]
func (h *SearchBotHandler) Handle(c *gin.Context) {
	ctx := c.Request.Context()

	var req SearchBotRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		common.RespondError(c, common.CodeArgumentError, err.Error())
		return
	}

	if req.Question == "" {
		common.RespondError(c, common.CodeArgumentError, "question is required")
		return
	}

	questions, err := service.GenerateRelatedQuestions(ctx, req.Question, req.SearchID, h.searchSvc, h.modelFactory)
	if err != nil {
		if respondPermissionErrorIf(c, err, true) {
			return
		}
		common.Warn("searchbot related questions failed", zap.String("error", err.Error()))
		common.RespondError(c, common.CodeOperatingError, err.Error())
		return
	}

	common.RespondSuccessList(c, questions, "success")
}

// RetrievalTest performs a retrieval test against specified knowledge bases.
// @Summary Retrieval Test
// @Description Test document retrieval across knowledge bases with optional filters, reranking, and KG search.
// @Tags searchBots
// @Param request body SearchBotRetrievalTestRequest true "Retrieval test parameters"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/searchbots/retrieval [post]
func (h *SearchBotHandler) RetrievalTest(c *gin.Context) {

	var req SearchBotRetrievalTestRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
		return
	}

	// Filter out empty strings from KbIDs before validation.
	filtered := make(common.StringSlice, 0, len(req.KbIDs))
	for _, id := range req.KbIDs {
		if strings.TrimSpace(id) != "" {
			filtered = append(filtered, id)
		}
	}
	req.KbIDs = filtered

	if len(req.KbIDs) == 0 || req.Question == "" {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, "kb_id and question are required")
		return
	}

	vectorSimilarityWeight, err := service.ResolveVectorSimilarityWeight(req.KeywordsSimilarityWeight, req.VectorSimilarityWeight)
	if err != nil {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
		return
	}
	req.VectorSimilarityWeight = vectorSimilarityWeight

	if err := common.ValidatePagination(req.Page, nil, req.Size); err != nil {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
		return
	}
	applyRetrievalDefaults(&req)

	if req.TopK != nil && *req.TopK <= 0 {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, "top_k must be greater than 0")
		return
	}

	svcReq := toRetrievalServiceRequest(&req)
	ctx := c.Request.Context()
	result, err := h.chunkSvc.RetrievalTest(ctx, svcReq)
	if err != nil {
		if respondPermissionErrorIf(c, err, true) {
			return
		}
		common.Warn("search bot retrieval test failed", zap.String("error", err.Error()))
		common.RespondError(c, common.CodeDataError, err.Error())
		return
	}

	common.RespondSuccess(c, result, "success")
}

// Ask performs a retrieval-augmented Q&A with streaming SSE response.
// @Summary Ask with Knowledge Bases
// @Description Retrieves chunks, builds prompt, and streams LLM answer with citations via SSE.
// @Tags searchbots
// @Accept json
// @Produce text/event-stream
// @Param request body SearchBotAskRequest true "Ask parameters"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/searchbots/ask [post]
func (h *SearchBotHandler) Ask(c *gin.Context) {

	var req SearchBotAskRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
		return
	}

	question, err := service.ResolveCompletionQuestion(req.Question, req.Query, req.Messages)
	if err != nil {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
		return
	}
	req.Question = question

	// Filter empty kb_ids.
	filtered := make(common.StringSlice, 0, len(req.KbIDs))
	for _, id := range req.KbIDs {
		if strings.TrimSpace(id) == "" {
			continue
		}
		filtered = append(filtered, id)
	}
	if len(filtered) == 0 || strings.TrimSpace(req.Question) == "" {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, "kb_ids and question are required")
		return
	}

	// Resolve chat model ID.
	modelID := ""
	options := service.AskStreamOptions{}
	modelTenantID := strings.TrimSpace(permission.TenantIDFromContext(c.Request.Context()))
	if modelTenantID == "" {
		modelTenantID = permission.UserIDFromContext(c.Request.Context())
	}
	if modelTenantID == "" {
		jsonInternalError(c, permission.ErrUnauthenticated)
		return
	}
	if req.SearchID != "" {
		if h.searchSvc == nil {
			jsonInternalError(c, fmt.Errorf("search service not configured"))
			return
		}
		ctx := c.Request.Context()
		detail, err := h.searchSvc.GetDetail(ctx, req.SearchID)
		if err != nil {
			if respondPermissionErrorIf(c, err, true) {
				return
			}
			common.RespondError(c, common.CodeDataError, err.Error())
			return
		}
		searchConfig := searchConfigFromDetail(detail)
		if tenantID, ok := detail["tenant_id"].(string); ok && strings.TrimSpace(tenantID) != "" {
			modelTenantID = strings.TrimSpace(tenantID)
		}
		options = service.BuildAskStreamOptions(req.SearchID, searchConfig)
		if chatID, ok := searchConfig["chat_id"].(string); ok && chatID != "" {
			modelID = chatID
		}
	}
	if modelID == "" && h.modelFactory != nil {
		ctx := c.Request.Context()
		if info, infoErr := h.modelFactory.ResolveDefaultInfo(permission.WithTenantID(ctx, modelTenantID), entity.ModelTypeChat); infoErr == nil {
			modelID = service.ModelReference(info)
		}
	}
	if modelID == "" {
		h.sseWriter.Write(c, sseError("chat model not configured"))
		return
	}

	clearResponseWriteDeadline(c)
	c.Header("Content-Type", "text/event-stream")
	c.Header("Cache-Control", "no-cache")
	c.Header("Connection", "keep-alive")

	if h.askSvc == nil {
		h.sseWriter.Write(c, sseError("ask service not configured"))
		return
	}
	if h.modelFactory == nil {
		h.sseWriter.Write(c, sseError("model factory not configured"))
		return
	}
	ctx, cancel := context.WithCancel(c.Request.Context())
	defer cancel()
	ctx = permission.WithTenantID(ctx, modelTenantID)
	c.Request = c.Request.WithContext(ctx)
	hadError := false
	adapter := &service.TenantStreamAdapter{Factory: h.modelFactory, ModelID: modelID}
	for delta := range h.askSvc.StreamWithOptions(ctx, adapter, req.Question, filtered, options) {
		var ok bool
		switch delta.Kind {
		case service.AskDeltaAnswer:
			ok = h.sseWriter.Write(c, sseAnswer(delta.Value, nil, false))
		case service.AskDeltaMarker:
			ok = h.sseWriter.Write(c, sseMarker(delta.Value))
		case service.AskDeltaError:
			hadError = true
			ok = h.sseWriter.Write(c, sseError(delta.Value))
		case service.AskDeltaFinal:
			ok = h.sseWriter.Write(c, sseAnswer(delta.Value, delta.Refs, true))
		}
		if !ok || ctx.Err() != nil {
			cancel()
			break
		}
	}
	if !hadError && ctx.Err() == nil {
		h.sseWriter.Write(c, "data: {\"code\": 0, \"message\": \"success\", \"data\": true}\n\n")
	}

}

// MindMap generates a query mind map for a shared search bot.
// @Summary Generate Mind Map
// @Description Retrieves related chunks and asks the configured chat model to summarize them into a mind map.
// @Tags searchbots
// @Accept json
// @Produce json
// @Param request body SearchBotMindMapRequest true "Mind map parameters"
// @Success 200 {object} map[string]interface{}
// @Router /api/v1/searchbots/mindmap [post]
func (h *SearchBotHandler) MindMap(c *gin.Context) {

	var req SearchBotMindMapRequest
	if err := c.ShouldBindJSON(&req); err != nil {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, err.Error())
		return
	}

	filtered := make(common.StringSlice, 0, len(req.KbIDs))
	for _, id := range req.KbIDs {
		if strings.TrimSpace(id) != "" {
			filtered = append(filtered, id)
		}
	}
	if len(filtered) == 0 || strings.TrimSpace(req.Question) == "" {
		common.Respond(c, http.StatusBadRequest, common.CodeArgumentError, nil, "kb_ids and question are required")
		return
	}
	if h.chunkSvc == nil {
		jsonInternalError(c, fmt.Errorf("chunk service not configured"))
		return
	}
	if h.modelFactory == nil {
		jsonInternalError(c, fmt.Errorf("LLM not configured"))
		return
	}

	searchConfig := map[string]interface{}{}
	modelTenantID := strings.TrimSpace(permission.TenantIDFromContext(c.Request.Context()))
	if modelTenantID == "" {
		modelTenantID = permission.UserIDFromContext(c.Request.Context())
	}
	if req.SearchID != "" {
		if h.searchSvc == nil {
			jsonInternalError(c, fmt.Errorf("search service not configured"))
			return
		}
		ctx := c.Request.Context()
		detail, err := h.searchSvc.GetDetail(ctx, req.SearchID)
		if err != nil {
			if respondPermissionErrorIf(c, err, true) {
				return
			}
			jsonInternalError(c, err)
			return
		}
		searchConfig = searchConfigFromDetail(detail)
		if tenantID, ok := detail["tenant_id"].(string); ok && strings.TrimSpace(tenantID) != "" {
			modelTenantID = strings.TrimSpace(tenantID)
		}
	}

	ctx := c.Request.Context()
	mindMap, err := runMindMap(ctx, mindMapRunConfig{
		Question:      req.Question,
		KbIDs:         filtered,
		SearchID:      req.SearchID,
		SearchConfig:  searchConfig,
		ModelTenantID: modelTenantID,
		ChunkSvc:      h.chunkSvc,
		LLM:           h.modelFactory,
		TenantSvc:     h.tenantSvc,
	})
	if err != nil {
		if respondPermissionErrorIf(c, err, true) {
			return
		}
		common.Warn("searchbot mindmap failed", zap.String("error", err.Error()))
		common.RespondError(c, common.CodeOperatingError, err.Error())
		return
	}
	common.RespondSuccess(c, mindMap, "success")
}

// SearchBotDetail returns the public share-page bootstrap payload for a
// search app. The route is mounted under apiNoAuth but still requires a beta
// token, matching Python's AUTH_BETA flow.
func (h *SearchBotHandler) SearchBotDetail(c *gin.Context) {
	ctx := c.Request.Context()
	searchID := strings.TrimSpace(c.Query("search_id"))
	if searchID == "" {
		common.RespondError(c, common.CodeArgumentError, "search_id is required")
		return
	}

	userSvc := service.NewUserService()
	identity, code, err := userSvc.ResolveBetaAPIToken(ctx, c.GetHeader("Authorization"))
	if err != nil {
		common.RespondError(c, code, "Authentication error: API key is invalid!")
		return
	}
	setAuthIdentity(c, identity)
	ctx = c.Request.Context()
	c.Set("auth_via_beta_token", true)
	if h.searchSvc == nil {
		jsonInternalError(c, fmt.Errorf("search service not configured"))
		return
	}
	detail, err := h.searchSvc.GetSearchShareDetail(ctx, searchID)
	if err != nil {
		if respondPermissionErrorIf(c, err, true) {
			return
		}
		jsonInternalError(c, err)
		return
	}

	common.RespondSuccess(c, detail, "success")
}

// ---- SSE helpers ----

type ssePayload struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data"`
}

// askSSEData is the inner data object for SSE events, matching Python bot_api.py.
// The Reference field is always present (non-nil) so the frontend can safely
// access .chunks or .reduce without a null guard.
type askSSEData struct {
	Answer       string      `json:"answer"`
	Reference    interface{} `json:"reference"`
	Final        bool        `json:"final"`
	StartToThink bool        `json:"start_to_think,omitempty"`
	EndToThink   bool        `json:"end_to_think,omitempty"`
}

func sseAnswer(answer string, refs interface{}, final bool) string {
	if refs == nil {
		refs = map[string]interface{}{}
	}
	payload := ssePayload{
		Code:    0,
		Message: "success",
		Data: askSSEData{
			Answer:    answer,
			Reference: refs,
			Final:     final,
		},
	}
	b, _ := json.Marshal(payload)
	return fmt.Sprintf("data: %s\n\n", string(b))
}

// sseError matches Python bot_api.py error format:
//
//	{"code": 500, "message": "...", "data": {"answer": "**ERROR**: ...", "reference": []}}
func sseError(message string) string {
	payload := ssePayload{
		Code:    int(common.CodeServerError),
		Message: message,
		Data: askSSEData{
			Answer:    "**ERROR**: " + message,
			Reference: []map[string]interface{}{},
		},
	}
	b, _ := json.Marshal(payload)
	return fmt.Sprintf("data: %s\n\n", string(b))
}

// sseMarker matches Python dialog_service.py think-tag marker format:
//
//	{"answer": "", "reference": {}, "final": false, "start_to_think": true}
func sseMarker(marker string) string {
	d := askSSEData{
		Answer:    "",
		Reference: map[string]interface{}{},
	}
	if marker == "<think>" {
		d.StartToThink = true
	} else {
		d.EndToThink = true
	}
	payload := ssePayload{Code: 0, Message: "success", Data: d}
	b, _ := json.Marshal(payload)
	return fmt.Sprintf("data: %s\n\n", string(b))
}

type SSEWriter interface {
	Write(c *gin.Context, data string) bool
}

// ginSSEWriter is the production SSEWriter backed by gin.Context.Stream.
type ginSSEWriter struct{}

func (w *ginSSEWriter) Write(c *gin.Context, data string) bool {
	if c.Request.Context().Err() != nil {
		return false
	}
	var writeErr error
	clientGone := c.Stream(func(w io.Writer) bool {
		_, writeErr = fmt.Fprint(w, data)
		return false
	})
	return !clientGone && writeErr == nil && c.Request.Context().Err() == nil
}

// toRetrievalServiceRequest maps the handler DTO to the service DTO.
// The two structs differ in KbIDs (StringSlice → []string) and
// MetaDataFilter (→ Filter) to maintain Python API compatibility.
func toRetrievalServiceRequest(h *SearchBotRetrievalTestRequest) *service.RetrievalTestRequest {
	return &service.RetrievalTestRequest{
		Datasets:               common.StringSlice(h.KbIDs),
		Question:               h.Question,
		Page:                   h.Page,
		Size:                   h.Size,
		RerankCandidatesCount:  h.RerankCandidatesCount,
		DocIDs:                 h.DocIDs,
		UseKG:                  h.UseKG,
		TopK:                   h.TopK,
		CrossLanguages:         h.CrossLanguages,
		SearchID:               h.SearchID,
		Filter:                 h.MetaDataFilter,
		TenantRerankID:         h.TenantRerankID,
		RerankID:               h.RerankID,
		Keyword:                h.Keyword,
		Highlight:              h.Highlight,
		SimilarityThreshold:    h.SimilarityThreshold,
		VectorSimilarityWeight: h.VectorSimilarityWeight,
	}
}

// applyRetrievalDefaults fills in default values for optional fields,
// matching the Python bot_api.py retrieval_test endpoint.
//
// similarity_threshold, vector_similarity_weight and top_k are left nil:
// ChunkService.RetrievalTest resolves them against the search app's saved
// search_config, which a default here would hide.
func applyRetrievalDefaults(req *SearchBotRetrievalTestRequest) {
	if req.Page == nil {
		v := common.DefaultPage
		req.Page = &v
	}
	if req.Size == nil {
		v := common.DefaultPageSize
		req.Size = &v
	}
	if req.UseKG == nil {
		v := false
		req.UseKG = &v
	}
	if req.Keyword == nil {
		v := false
		req.Keyword = &v
	}
}