Skip to content

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

25.3 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.
//

// retrieval_nlp_test.go — NLPRetrievalAdapter tests.
//
// The adapter's Search method calls into the real
// nlp.RetrievalService, which requires a doc engine + document
// DAO. Those require network access and aren't worth standing up
// in a unit test. Instead we exercise the translation layer
// (translateChunk + helpers) and the rank-feature resolution
// (resolveRankFeature) directly — that's the surface that
// differs between the nlp chunk shape and the agent-tool chunk
// shape, and the only piece the adapter itself decides.

package tool

import (
	"context"
	"errors"
	"math"
	"testing"

	"ragflow/internal/agent/runtime"
	"ragflow/internal/entity"
	modelModule "ragflow/internal/entity/models"
	"ragflow/internal/permission"
	"ragflow/internal/permission/testsupport"
	"ragflow/internal/service/nlp"

	"github.com/glebarez/sqlite"
	"gorm.io/gorm"
)

// floatEqual compares two floats with a small epsilon so
// arithmetic like 0.4+0.8/2 == 0.6000000000000001 doesn't fail.
func floatEqual(a, b float64) bool { return math.Abs(a-b) < 1e-9 }

// TestTranslateChunk_FullFields: every chunk field is present and
// maps to the expected RetrievalChunk field.
func TestTranslateChunk_FullFields(t *testing.T) {
	raw := map[string]any{
		"chunk_id":            "ck-42",
		"doc_id":              "doc-7",
		"docnm_kwd":           "report.pdf",
		"kb_id":               "kb-1",
		"image_id":            "img-1",
		"position_int":        [][]float64{{1, 2, 3, 4}},
		"content_with_weight": "the answer is 42",
		"content_ltks":        "answer 42",
		"similarity":          0.87,
		"term_similarity":     0.5,
		"vector_similarity":   0.9,
	}
	got := translateChunk(raw)
	if got.ID != "ck-42" {
		t.Errorf("ID = %q, want \"ck-42\"", got.ID)
	}
	if got.Content != "the answer is 42" {
		t.Errorf("Content = %q, want content_with_weight", got.Content)
	}
	if got.DocumentID != "doc-7" {
		t.Errorf("DocumentID = %q, want \"doc-7\"", got.DocumentID)
	}
	if got.DocumentName != "report.pdf" {
		t.Errorf("DocumentName = %q, want \"report.pdf\"", got.DocumentName)
	}
	if got.DatasetID != "kb-1" {
		t.Errorf("DatasetID = %q, want \"kb-1\"", got.DatasetID)
	}
	if got.ImageID != "img-1" {
		t.Errorf("ImageID = %q, want \"img-1\"", got.ImageID)
	}
	if got.Positions == nil {
		t.Errorf("Positions is nil, want position_int payload")
	}
	if got.Score != 0.87 {
		t.Errorf("Score = %v, want 0.87 (similarity preferred)", got.Score)
	}
	if got.TermSimilarity != 0.5 {
		t.Errorf("TermSimilarity = %v, want 0.5", got.TermSimilarity)
	}
	if got.VectorSimilarity != 0.9 {
		t.Errorf("VectorSimilarity = %v, want 0.9", got.VectorSimilarity)
	}
}

// TestTranslateChunk_ContentFallback: when content_with_weight is
// empty, content_ltks is used.
func TestTranslateChunk_ContentFallback(t *testing.T) {
	raw := map[string]any{
		"chunk_id":     "ck-1",
		"content_ltks": "answer 42",
		"doc_id":       "doc-1",
		"similarity":   0.5,
	}
	got := translateChunk(raw)
	if got.Content != "answer 42" {
		t.Errorf("Content = %q, want content_ltks fallback", got.Content)
	}
}

// TestTranslateChunk_EmptyContent: both content fields empty →
// empty string (don't crash, don't synthesise).
func TestTranslateChunk_EmptyContent(t *testing.T) {
	raw := map[string]any{
		"chunk_id":   "ck-1",
		"doc_id":     "doc-1",
		"similarity": 0.5,
	}
	got := translateChunk(raw)
	if got.Content != "" {
		t.Errorf("Content = %q, want \"\"", got.Content)
	}
}

// TestTranslateChunk_ScoreFallback: when "similarity" is missing,
// the average of term_similarity + vector_similarity is used.
func TestTranslateChunk_ScoreFallback(t *testing.T) {
	raw := map[string]any{
		"chunk_id":          "ck-1",
		"term_similarity":   0.4,
		"vector_similarity": 0.8,
	}
	got := translateChunk(raw)
	if !floatEqual(got.Score, 0.6) {
		t.Errorf("Score = %v, want ~0.6 (avg of term+vec)", got.Score)
	}
}

// TestTranslateChunk_ScoreOnlyOneSub: only one of term_similarity
// or vector_similarity present → that one wins (not averaged
// against zero, which would be misleading).
func TestTranslateChunk_ScoreOnlyOneSub(t *testing.T) {
	cases := []struct {
		name string
		raw  map[string]any
		want float64
	}{
		{"term only", map[string]any{"term_similarity": 0.7}, 0.7},
		{"vector only", map[string]any{"vector_similarity": 0.3}, 0.3},
	}
	for _, tc := range cases {
		got := translateChunk(tc.raw)
		if !floatEqual(got.Score, tc.want) {
			t.Errorf("%s: Score = %v, want %v", tc.name, got.Score, tc.want)
		}
	}
}

// TestTranslateChunk_NumberTypesTolerated: numeric similarity
// fields may come back as float64, float32, int, or int64 depending
// on how the upstream serialised them. All should coerce.
func TestTranslateChunk_NumberTypesTolerated(t *testing.T) {
	cases := []struct {
		name string
		val  any
		want float64
	}{
		{"float64", float64(0.5), 0.5},
		{"float32", float32(0.5), 0.5},
		{"int", int(1), 1},
		{"int64", int64(1), 1},
	}
	for _, tc := range cases {
		raw := map[string]any{"similarity": tc.val}
		got := translateChunk(raw)
		if !floatEqual(got.Score, tc.want) {
			t.Errorf("%s: Score = %v, want %v", tc.name, got.Score, tc.want)
		}
	}
}

// TestTranslateChunk_WrongTypesIgnored: a similarity field that's
// a string or nil must not crash. We fall back to the sub-scores
// (which are also missing in this test → zero).
func TestTranslateChunk_WrongTypesIgnored(t *testing.T) {
	cases := []map[string]any{
		{"similarity": "0.5"},
		{"similarity": nil},
		{"similarity": []any{0.5}},
	}
	for _, raw := range cases {
		got := translateChunk(raw)
		if got.Score != 0 {
			t.Errorf("wrong-type similarity: Score = %v, want 0", got.Score)
		}
	}
}

// TestTranslateChunk_WrongStringTypesIgnored: a string field
// that's actually a number must not crash.
func TestTranslateChunk_WrongStringTypesIgnored(t *testing.T) {
	raw := map[string]any{
		"chunk_id": 42,  // int, not string
		"doc_id":   nil, // nil
	}
	got := translateChunk(raw)
	if got.ID != "" {
		t.Errorf("ID = %q, want \"\"", got.ID)
	}
	if got.DocumentID != "" {
		t.Errorf("DocumentID = %q, want \"\"", got.DocumentID)
	}
}

// TestTranslateChunk_MissingAllScores: a chunk with no score
// fields at all → score 0 (don't panic).
func TestTranslateChunk_MissingAllScores(t *testing.T) {
	raw := map[string]any{"chunk_id": "ck-1"}
	got := translateChunk(raw)
	if got.Score != 0 {
		t.Errorf("Score = %v, want 0", got.Score)
	}
}

// TestNewNLPRetrievalAdapter_NilService: nil constructor inputs
// must produce an adapter whose Search returns the missing-service
// error, not a panic.
func TestNewNLPRetrievalAdapter_NilService(t *testing.T) {
	a := NewNLPRetrievalAdapter(nil, RetrievalModelConstructors{}, nil)
	_, err := a.Search(context.TODO(), nil, RetrievalRequest{Query: "hi"})
	if err == nil {
		t.Fatal("expected error from nil-service adapter")
	}
	if !errors.Is(err, ErrRetrievalServiceMissing) {
		t.Errorf("err = %v, want ErrRetrievalServiceMissing", err)
	}
}

func TestNLPRequestFromRetrieval_ThreadsSearchControls(t *testing.T) {
	keywordWeight := 0.25
	similarityThreshold := 0.42
	embeddingModel := &modelModule.EmbeddingModel{}
	got := nlpRequestFromRetrieval(RetrievalRequest{
		Query:                    "hi",
		DatasetIDs:               []string{"kb-1"},
		TopN:                     3,
		TopK:                     99,
		KeywordsSimilarityWeight: &keywordWeight,
		SimilarityThreshold:      &similarityThreshold,
		AllowDenseFallback:       new(false),
	}, []string{"tenant-a"}, 3, embeddingModel, false)

	if got.Question != "hi" {
		t.Fatalf("Question=%q want hi", got.Question)
	}
	if got.AllowDenseFallback == nil || *got.AllowDenseFallback {
		t.Fatal("dense fallback opt-out was not passed to nlp retrieval")
	}
	if len(got.TenantIDs) != 1 || got.TenantIDs[0] != "tenant-a" {
		t.Fatalf("TenantIDs=%v want [tenant-a]", got.TenantIDs)
	}
	if len(got.KbIDs) != 1 || got.KbIDs[0] != "kb-1" {
		t.Fatalf("KbIDs=%v want [kb-1]", got.KbIDs)
	}
	if got.Page != 1 || got.PageSize != 3 {
		t.Fatalf("Page/PageSize=%d/%d want 1/3", got.Page, got.PageSize)
	}
	if got.KNNTopK == nil || *got.KNNTopK != 99 {
		t.Fatalf("KNNTopK=%v want 99", got.KNNTopK)
	}
	if got.SimilarityThreshold == nil || *got.SimilarityThreshold != 0.42 {
		t.Fatalf("SimilarityThreshold=%v want 0.42", got.SimilarityThreshold)
	}
	if got.VectorSimilarityWeight == nil || !floatEqual(*got.VectorSimilarityWeight, 0.75) {
		t.Fatalf("VectorSimilarityWeight=%v want 0.75", got.VectorSimilarityWeight)
	}
	if got.EmbeddingModel != embeddingModel {
		t.Fatal("EmbeddingModel was not passed to nlp retrieval request")
	}
	if got.VectorOnly {
		t.Fatal("mixed retrieval must not be vector-only")
	}
}

func TestNLPRequestFromRetrieval_DerivesPureModesFromKeywordWeight(t *testing.T) {
	embeddingModel := &modelModule.EmbeddingModel{}
	vectorOnlyWeight := 0.0
	vectorOnly := nlpRequestFromRetrieval(RetrievalRequest{
		Query:                    "hi",
		DatasetIDs:               []string{"kb-1"},
		KeywordsSimilarityWeight: &vectorOnlyWeight,
	}, []string{"tenant-a"}, 3, embeddingModel, false)
	if !vectorOnly.VectorOnly {
		t.Fatal("keywords weight 0 must derive vector-only search")
	}
	if vectorOnly.EmbeddingModel != embeddingModel {
		t.Fatal("vector-only search must retain the embedding model")
	}
	if vectorOnly.VectorSimilarityWeight == nil || *vectorOnly.VectorSimilarityWeight != 1 {
		t.Fatalf("vector-only vector weight = %v, want 1", vectorOnly.VectorSimilarityWeight)
	}

	keywordOnlyWeight := 1.0
	keywordOnly := nlpRequestFromRetrieval(RetrievalRequest{
		Query:                    "hi",
		DatasetIDs:               []string{"kb-1"},
		KeywordsSimilarityWeight: &keywordOnlyWeight,
	}, []string{"tenant-a"}, 3, embeddingModel, false)
	if keywordOnly.VectorOnly {
		t.Fatal("keywords weight 1 must not derive vector-only search")
	}
	if keywordOnly.EmbeddingModel != nil {
		t.Fatal("keywords weight 1 must disable the vector leg")
	}
	if keywordOnly.VectorSimilarityWeight == nil || *keywordOnly.VectorSimilarityWeight != 0 {
		t.Fatalf("keyword-only vector weight = %v, want 0", keywordOnly.VectorSimilarityWeight)
	}
}

func TestNLPRequestFromRetrieval_FallsBackToTopNHeadroom(t *testing.T) {
	got := nlpRequestFromRetrieval(RetrievalRequest{
		Query:      "hi",
		DatasetIDs: []string{"kb-1"},
		TopN:       3,
	}, []string{"tenant-a"}, 3, &modelModule.EmbeddingModel{}, false)

	if got.KNNTopK == nil || *got.KNNTopK != 12 {
		t.Fatalf("KNNTopK=%v want 12", got.KNNTopK)
	}
	if got.VectorSimilarityWeight != nil {
		t.Fatalf("VectorSimilarityWeight=%v want nil", got.VectorSimilarityWeight)
	}
	if got.AllowDenseFallback != nil {
		t.Fatal("ordinary retrieval must preserve default dense fallback policy")
	}
}

func TestNLPRequestFromRetrieval_PreservesExplicitZeroSimilarityThreshold(t *testing.T) {
	similarityThreshold := 0.0
	got := nlpRequestFromRetrieval(RetrievalRequest{
		Query:               "hi",
		DatasetIDs:          []string{"kb-1"},
		SimilarityThreshold: &similarityThreshold,
	}, []string{"tenant-a"}, 3, &modelModule.EmbeddingModel{}, false)

	if got.SimilarityThreshold == nil || *got.SimilarityThreshold != 0 {
		t.Fatalf("SimilarityThreshold = %v; want explicit zero", got.SimilarityThreshold)
	}
}

// TestNLPRequestFromRetrieval_ExcludeCompiled verifies the compiled-product
// exclusion reaches the nlp request as must_not={"exists":"compile_kwd"},
// mirroring Python hybrid_search (search.py:171).
func TestNLPRequestFromRetrieval_ExcludeCompiled(t *testing.T) {
	// excludeCompiled=false leaves Filter nil (no exclusion).
	got := nlpRequestFromRetrieval(RetrievalRequest{
		Query:      "hi",
		DatasetIDs: []string{"kb-1"},
	}, []string{"tenant-a"}, 3, &modelModule.EmbeddingModel{}, false)
	if got.Filter != nil {
		t.Fatalf("Filter = %v; want nil when not excluding compiled", got.Filter)
	}
	// excludeCompiled=true sets must_not exists compile_kwd.
	got = nlpRequestFromRetrieval(RetrievalRequest{
		Query:      "hi",
		DatasetIDs: []string{"kb-1"},
	}, []string{"tenant-a"}, 3, &modelModule.EmbeddingModel{}, true)
	mustNot, ok := got.Filter["must_not"].(map[string]interface{})
	if !ok {
		t.Fatalf("Filter.must_not = %v; want map", got.Filter["must_not"])
	}
	// Python hybrid_search: must_not={"exists":"compile_kwd"} — the exists
	// clause names the compile_kwd field, mirroring dataset/search.go:292.
	if exists, ok := mustNot["exists"].(string); !ok || exists != "compile_kwd" {
		t.Fatalf("must_not.exists = %v; want \"compile_kwd\"", mustNot["exists"])
	}
}

func TestNLPRetrievalAdapter_ResolveDatasetsRequiresEveryDataset(t *testing.T) {
	a := &NLPRetrievalAdapter{
		kbDAO: fakeKnowledgebaseLookup{
			kbs: []*entity.Knowledgebase{
				{ID: "kb-1", TenantID: "tenant-a"},
				{ID: "kb-2", TenantID: "tenant-a"},
			},
		},
	}
	_, err := a.resolveDatasets(nil, nil, RetrievalRequest{
		TenantID:   "tenant-a",
		DatasetIDs: []string{"kb-1", "kb-2", "kb-missing"},
	})
	if err == nil {
		t.Fatal("resolveDatasets: expected missing dataset error")
	}
}

func TestNLPRetrievalAdapter_SearchRejectsDatasetsFromMultipleTenants(t *testing.T) {
	a := &NLPRetrievalAdapter{
		svc: &nlp.RetrievalService{},
		kbDAO: fakeKnowledgebaseLookup{
			kbs: []*entity.Knowledgebase{
				{ID: "kb-1", TenantID: "tenant-a", EmbdID: "embedding@provider"},
				{ID: "kb-2", TenantID: "tenant-b", EmbdID: "embedding@provider"},
			},
		},
	}
	_, err := a.Search(t.Context(), nil, RetrievalRequest{
		Query:      "hi",
		DatasetIDs: []string{"kb-1", "kb-2"},
	})
	if err == nil || err.Error() != "retrieval: datasets span multiple tenants" {
		t.Fatalf("Search error = %v, want multiple-tenant rejection", err)
	}
}

func TestNLPRetrievalAdapter_SearchRequiresDatasetUsePermission(t *testing.T) {
	db, err := gorm.Open(sqlite.Open("file:"+t.Name()+"?mode=memory&cache=shared"), &gorm.Config{})
	if err != nil {
		t.Fatalf("open sqlite: %v", err)
	}
	if err := db.AutoMigrate(&entity.Knowledgebase{}, &entity.UserTenant{}); err != nil {
		t.Fatalf("migrate permission tables: %v", err)
	}
	status := string(entity.StatusValid)
	dataset := entity.Knowledgebase{
		ID: "kb-private", TenantID: "tenant-1", Name: "private", EmbdID: "embedding@provider",
		Permission: string(entity.TenantPermissionMe), CreatedBy: "owner", Status: &status,
	}
	if err := db.Create(&dataset).Error; err != nil {
		t.Fatalf("create dataset: %v", err)
	}
	memberships := []entity.UserTenant{
		{ID: "owner-membership", UserID: "owner", TenantID: "tenant-1", Role: string(permission.RoleOwner), InvitedBy: "owner", Status: &status},
		{ID: "member-membership", UserID: "member", TenantID: "tenant-1", Role: string(permission.RoleNormal), InvitedBy: "owner", Status: &status},
	}
	if err := db.Create(&memberships).Error; err != nil {
		t.Fatalf("create memberships: %v", err)
	}
	if err := testsupport.PrepareEnterprisePermissionFixture(db, "tenant-1", "owner", "member"); err != nil {
		t.Fatalf("prepare permission fixture: %v", err)
	}

	adapter := &NLPRetrievalAdapter{
		svc:   &nlp.RetrievalService{},
		kbDAO: fakeKnowledgebaseLookup{kbs: []*entity.Knowledgebase{&dataset}},
	}
	state := runtime.NewCanvasState("run-1", "session-1")
	state.Sys["user_id"] = "member"
	state.Sys["tenant_id"] = "tenant-1"
	ctx := permission.WithIdentity(runtime.WithState(t.Context(), state), "member", "tenant-1")
	_, err = adapter.Search(ctx, db, RetrievalRequest{
		Query: "hello", DatasetIDs: []string{dataset.ID}, UserID: "owner",
	})
	if !errors.Is(err, permission.ErrPermissionDenied) {
		t.Fatalf("Search error = %v, want permission denial for runtime caller despite req.UserID=owner", err)
	}
}

func TestNLPRetrievalAdapter_ResolveDatasetsFromDatasetIDs(t *testing.T) {
	a := &NLPRetrievalAdapter{
		kbDAO: fakeKnowledgebaseLookup{
			kbs: []*entity.Knowledgebase{
				{ID: "kb-1", TenantID: "tenant-a"},
				{ID: "kb-2", TenantID: "tenant-b"},
				{ID: "kb-3", TenantID: "tenant-a"},
			},
		},
	}
	got, err := a.resolveDatasets(nil, nil, RetrievalRequest{
		DatasetIDs: []string{"kb-1", "kb-2", "kb-3", " "},
	})
	if err != nil {
		t.Fatalf("resolveDatasets: %v", err)
	}
	if len(got.tenantIDs) != 2 || got.tenantIDs[0] != "tenant-a" || got.tenantIDs[1] != "tenant-b" {
		t.Fatalf("tenantIDs=%v want [tenant-a tenant-b]", got.tenantIDs)
	}
}

func TestNLPRetrievalAdapter_ResolveDatasetsUsesDatasetTenants(t *testing.T) {
	a := &NLPRetrievalAdapter{
		kbDAO: fakeKnowledgebaseLookup{
			kbs: []*entity.Knowledgebase{
				{ID: "kb-1", TenantID: "tenant-b"},
			},
		},
	}
	got, err := a.resolveDatasets(nil, nil, RetrievalRequest{
		TenantID:   "tenant-a",
		DatasetIDs: []string{"kb-1"},
	})
	if err != nil {
		t.Fatalf("resolveDatasets: %v", err)
	}
	if len(got.tenantIDs) != 1 || got.tenantIDs[0] != "tenant-b" {
		t.Fatalf("tenantIDs=%v want [tenant-b]", got.tenantIDs)
	}
}

func TestNLPRetrievalAdapter_ResolveEmbeddingModelPriority(t *testing.T) {
	tenantEmbeddingID := "tenant-embedding-1"
	tests := []struct {
		name     string
		kb       *entity.Knowledgebase
		wantCall string
	}{
		{
			name: "tenant embedding id",
			kb: &entity.Knowledgebase{
				ID:           "kb-1",
				TenantID:     "tenant-1",
				EmbdID:       "embedding@provider",
				TenantEmbdID: &tenantEmbeddingID,
			},
			wantCall: "resolve:tenant-embedding-1",
		},
		{
			name: "knowledge base embedding reference",
			kb: &entity.Knowledgebase{
				ID:       "kb-1",
				TenantID: "tenant-1",
				EmbdID:   "embedding@provider",
			},
			wantCall: "resolve:embedding@provider",
		},
		{
			name: "tenant default only when knowledge base has no model",
			kb: &entity.Knowledgebase{
				ID:       "kb-1",
				TenantID: "tenant-1",
			},
			wantCall: "resolve:",
		},
	}

	for _, test := range tests {
		t.Run(test.name, func(t *testing.T) {
			var gotRef string
			adapter := &NLPRetrievalAdapter{
				modelConstructors: RetrievalModelConstructors{
					Embedding: func(_ context.Context, _ string, modelRef string) (*modelModule.EmbeddingModel, error) {
						gotRef = modelRef
						modelName := "resolved-model"
						return modelModule.NewEmbeddingModel(&modelModule.DummyModel{}, &modelName, &modelModule.APIConfig{}, 512), nil
					},
				},
			}
			model, err := adapter.resolveEmbeddingModel(t.Context(), test.kb)
			if err != nil {
				t.Fatalf("resolveEmbeddingModel: %v", err)
			}
			if got := "resolve:" + gotRef; got != test.wantCall {
				t.Fatalf("constructor model ref = %q, want %q", got, test.wantCall)
			}
			if model == nil || model.ModelName == nil || *model.ModelName != "resolved-model" {
				t.Fatalf("resolved model = %#v", model)
			}
		})
	}
}

func TestValidateEmbeddingModelsRejectsDifferentTenantModels(t *testing.T) {
	firstID := "tenant-embedding-1"
	secondID := "tenant-embedding-2"
	err := validateEmbeddingModels(t.Context(), nil, []*entity.Knowledgebase{
		{ID: "kb-1", TenantID: "tenant-1", TenantEmbdID: &firstID},
		{ID: "kb-2", TenantID: "tenant-1", TenantEmbdID: &secondID},
	})
	if err == nil {
		t.Fatal("expected different tenant embedding models to be rejected")
	}
}

func TestValidateEmbeddingModelsAllowsSameBaseAcrossInstances(t *testing.T) {
	// Datasets using the same base embedding model through different provider
	// instances must validate together, matching the chat/dataset-search rule.
	err := validateEmbeddingModels(t.Context(), nil, []*entity.Knowledgebase{
		{ID: "kb-1", TenantID: "tenant-1", EmbdID: "BAAI/bge-m3@renew@SILICONFLOW"},
		{ID: "kb-2", TenantID: "tenant-1", EmbdID: "BAAI/bge-m3@COPY@SILICONFLOW"},
	})
	if err != nil {
		t.Fatalf("expected same-base composites to be accepted, got %v", err)
	}
}

func TestValidateEmbeddingModelsRejectsDifferentBases(t *testing.T) {
	err := validateEmbeddingModels(t.Context(), nil, []*entity.Knowledgebase{
		{ID: "kb-1", TenantID: "tenant-1", EmbdID: "BAAI/bge-m3@renew@SILICONFLOW"},
		{ID: "kb-2", TenantID: "tenant-1", EmbdID: "Qwen/Qwen3-Embedding-0.6B@renew@SILICONFLOW"},
	})
	if err == nil {
		t.Fatal("expected different base embedding models to be rejected")
	}
}

type fakeKnowledgebaseLookup struct {
	kbs []*entity.Knowledgebase
	err error
}

func (f fakeKnowledgebaseLookup) GetByIDs(ctx context.Context, db *gorm.DB, ids []string) ([]*entity.Knowledgebase, error) {
	requested := make(map[string]struct{}, len(ids))
	for _, id := range ids {
		requested[id] = struct{}{}
	}
	kbs := make([]*entity.Knowledgebase, 0, len(f.kbs))
	for _, kb := range f.kbs {
		if kb == nil {
			continue
		}
		if _, ok := requested[kb.ID]; ok {
			kbs = append(kbs, kb)
		}
	}
	return kbs, f.err
}

func (f fakeKnowledgebaseLookup) GetByName(_ context.Context, _ *gorm.DB, name, tenantID string) (*entity.Knowledgebase, error) {
	for _, kb := range f.kbs {
		if kb != nil && kb.Name == name && kb.TenantID == tenantID {
			return kb, nil
		}
	}
	return nil, gorm.ErrRecordNotFound
}

// stubRankFeatureEnhancer records whether the question was labelled.
type stubRankFeatureEnhancer struct {
	labels map[string]float64
	calls  int
}

func (s *stubRankFeatureEnhancer) CrossLanguages(context.Context, string, string, []string) (string, error) {
	return "", nil
}

func (s *stubRankFeatureEnhancer) FilterDocuments(
	context.Context, map[string]any, string, *modelModule.ChatModel, []string, []string,
) ([]string, error) {
	return nil, nil
}

func (s *stubRankFeatureEnhancer) LabelQuestion(
	context.Context, string, []*entity.Knowledgebase,
) map[string]float64 {
	s.calls++
	return s.labels
}

func (s *stubRankFeatureEnhancer) RetrieveByChildren(
	context.Context, []map[string]any, []string,
) []map[string]any {
	return nil
}

func testRankFeatureKBs() []*entity.Knowledgebase {
	return []*entity.Knowledgebase{{ID: "kb-1", TenantID: "tenant-1"}}
}

// No tag source: labelling yields nil, which must still reach the request as an
// empty map instead of letting the nlp layer apply its default.
func TestResolveRankFeature_NoTagSourceReturnsEmptyMap(t *testing.T) {
	enhancer := &stubRankFeatureEnhancer{labels: nil}

	got := resolveRankFeature(context.Background(), nil, enhancer, "q", testRankFeatureKBs(), false)

	if got == nil {
		t.Fatal("rankFeature = nil, want an empty (non-nil) map")
	}
	if len(got) != 0 {
		t.Fatalf("rankFeature = %v, want empty", got)
	}
	if enhancer.calls != 1 {
		t.Fatalf("LabelQuestion calls = %d, want 1", enhancer.calls)
	}
}

func TestResolveRankFeature_TagMatchIsForwarded(t *testing.T) {
	enhancer := &stubRankFeatureEnhancer{labels: map[string]float64{"tag_1": 0.8}}

	got := resolveRankFeature(context.Background(), nil, enhancer, "q", testRankFeatureKBs(), false)

	if got["tag_1"] != 0.8 {
		t.Fatalf("rankFeature = %v, want tag_1=0.8", got)
	}
}

// A caller-supplied feature wins over the enhancer and must not trigger a label
// lookup.
func TestResolveRankFeature_PrefersRequestSuppliedFeature(t *testing.T) {
	enhancer := &stubRankFeatureEnhancer{labels: map[string]float64{"from_enhancer": 0.1}}
	requested := map[string]float64{"from_request": 0.5}

	got := resolveRankFeature(context.Background(), &requested, enhancer, "q", testRankFeatureKBs(), false)

	if got["from_request"] != 0.5 || len(got) != 1 {
		t.Fatalf("rankFeature = %v, want only from_request=0.5", got)
	}
	if enhancer.calls != 0 {
		t.Fatalf("LabelQuestion calls = %d, want 0", enhancer.calls)
	}
}

// A vector-only request skips the label lookup; the map must still be non-nil.
func TestResolveRankFeature_VectorOnlySkipsLabelling(t *testing.T) {
	enhancer := &stubRankFeatureEnhancer{labels: map[string]float64{"tag_1": 0.8}}

	got := resolveRankFeature(context.Background(), nil, enhancer, "q", testRankFeatureKBs(), true)

	if got == nil {
		t.Fatal("rankFeature = nil, want an empty (non-nil) map")
	}
	if len(got) != 0 {
		t.Fatalf("rankFeature = %v, want empty", got)
	}
	if enhancer.calls != 0 {
		t.Fatalf("LabelQuestion calls = %d, want 0", enhancer.calls)
	}
}

func TestResolveRankFeature_NilEnhancerReturnsEmptyMap(t *testing.T) {
	got := resolveRankFeature(context.Background(), nil, nil, "q", testRankFeatureKBs(), false)

	if got == nil {
		t.Fatal("rankFeature = nil, want an empty (non-nil) map")
	}
	if len(got) != 0 {
		t.Fatalf("rankFeature = %v, want empty", got)
	}
}

// nil and {} are distinct: nil asks for labelling, {} means there are none.
func TestResolveRankFeature_ExplicitEmptyMapSuppressesLabelling(t *testing.T) {
	enhancer := &stubRankFeatureEnhancer{labels: map[string]float64{"tag_1": 0.8}}
	requested := map[string]float64{}

	got := resolveRankFeature(context.Background(), &requested, enhancer, "q", testRankFeatureKBs(), false)

	if got == nil {
		t.Fatal("rankFeature = nil, want an empty (non-nil) map")
	}
	if len(got) != 0 {
		t.Fatalf("rankFeature = %v, want empty", got)
	}
	if enhancer.calls != 0 {
		t.Fatalf("LabelQuestion calls = %d, want 0", enhancer.calls)
	}
}

// The result must not alias the caller's map.
func TestResolveRankFeature_ReturnsDetachedCopy(t *testing.T) {
	requested := map[string]float64{"tag_1": 0.4}

	got := resolveRankFeature(context.Background(), &requested, nil, "q", testRankFeatureKBs(), false)
	got["tag_1"] = 0.9
	got["injected"] = 1.0

	if requested["tag_1"] != 0.4 {
		t.Fatalf("caller map mutated through the result: %v", requested)
	}
	if _, ok := requested["injected"]; ok {
		t.Fatalf("caller map gained a key through the result: %v", requested)
	}
}