Skip to content

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

13.7 KB
Raw Blame
package common

import (
	"context"
	"fmt"
	"sync"

	"gorm.io/gorm"

	"ragflow/internal/ingestion/component/progress"
)

// DefaultLLMContextLength is the fallback chat-model context window (tokens)
// used for per-cluster text truncation when the model's real max length is
// unknown (e.g. in tests). Mirrors Python's default llm_model.max_length.
const DefaultLLMContextLength = 8192

// ChatRequest is the minimal surface a variant needs to dispatch one LLM call.
type ChatRequest struct {
	LLMID        string
	SystemPrompt string
	UserPrompt   string
	JSONMode     bool
	// These fields are per-call defaults. Run-level ChatSettings override them
	// when the caller explicitly enables a setting in the compiler node.
	Temperature      *float64
	TopP             *float64
	PresencePenalty  *float64
	FrequencyPenalty *float64
	MaxTokens        *int
	// Thinking explicitly controls reasoning when non-nil. DisableThinking is a
	// call-site default retained for compiler steps that must avoid reasoning;
	// an explicit Thinking setting takes precedence.
	Thinking        *bool
	DisableThinking bool
	APIKey          string
	BaseURL         string
	// DisableRetry tells the production ChatInvoker that the caller owns
	// transient-error retries (GenJSON is such a caller). It is internal
	// plumbing and is not part of the user-facing model request.
	DisableRetry bool
}

// ChatSettings are caller-provided LLM overrides for every request in one
// knowledge-compilation run. Nil values leave each call site's defaults intact;
// ThinkingSet distinguishes an explicit "default" choice from no setting.
type ChatSettings struct {
	Temperature      *float64
	TopP             *float64
	PresencePenalty  *float64
	FrequencyPenalty *float64
	MaxTokens        *int
	Thinking         *bool
	ThinkingSet      bool
}

type chatSettingsInvoker struct {
	next     ChatInvoker
	settings ChatSettings
}

// WithChatSettings applies explicit run-level settings over each compiler
// call's defaults while preserving fields the caller did not configure.
func WithChatSettings(next ChatInvoker, settings ChatSettings) ChatInvoker {
	settingsEmpty := settings.Temperature == nil && settings.TopP == nil && settings.PresencePenalty == nil && settings.FrequencyPenalty == nil && settings.MaxTokens == nil && !settings.ThinkingSet
	if next == nil || settingsEmpty {
		return next
	}
	return chatSettingsInvoker{next: next, settings: settings}
}

func (c chatSettingsInvoker) Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error) {
	if c.settings.Temperature != nil {
		req.Temperature = c.settings.Temperature
	}
	if c.settings.TopP != nil {
		req.TopP = c.settings.TopP
	}
	if c.settings.PresencePenalty != nil {
		req.PresencePenalty = c.settings.PresencePenalty
	}
	if c.settings.FrequencyPenalty != nil {
		req.FrequencyPenalty = c.settings.FrequencyPenalty
	}
	if c.settings.MaxTokens != nil {
		req.MaxTokens = c.settings.MaxTokens
	}
	if c.settings.ThinkingSet {
		req.Thinking = c.settings.Thinking
		req.DisableThinking = false
	}
	return c.next.Chat(ctx, req)
}

// ChatResponse holds the LLM's text answer.
type ChatResponse struct {
	Content string
}

// ChatInvoker dispatches a single LLM chat call. The production path routes
// through internal/entity/models (same factory as other ingestion components);
// tests inject a canned responder.
type ChatInvoker interface {
	Chat(ctx context.Context, req ChatRequest) (*ChatResponse, error)
}

// Embedder wraps a text embedding model. Encode returns one vector per input.
type Embedder interface {
	Encode(ctx context.Context, texts []string) ([][]float32, error)
	Dimensions() int
}

// Tokenizer estimates token counts for budget packing.
type Tokenizer interface {
	NumTokens(text string) int
}

// HistoricalHit is one cross-run KNN candidate returned by HistoricalKNN.
type HistoricalHit struct {
	ID    string
	Score float64
}

// HistoricalKNN is the read-only ES KNN candidate lookup used by the wiki
// variant for cross-run dedup. nil in M1; wired in M5/M9.
type HistoricalKNN interface {
	TopKHistory(ctx context.Context, tenantID, datasetID, variant string, vec []float32, k int, threshold float64) ([]HistoricalHit, error)
}

// WikiPageCandidate is one existing wiki page returned from the backing store.
type WikiPageCandidate struct {
	ID           string
	Slug         string
	Title        string
	PageType     string
	Topic        string
	PlanGroup    string
	Summary      string
	ContentMD    string
	ContentMDRaw string
	EntityNames  []string
	// RoutedEntityNames is populated only when the topic route LLM explicitly
	// returns a new membership set. An empty value means preserve the existing
	// membership for backward-compatible direct-match routing.
	RoutedEntityNames []string
	// RoutedTopic is the topic selected by the topic route LLM. Empty means
	// preserve the existing topic value.
	RoutedTopic    string
	RelatedKBPages []string
	Outlinks       []string
	SourceChunkIDs []string
	Score          float64
}

// WikiPageStore is the read-only storage seam the wiki variant uses to
// reconcile against existing artifact_page rows and to load the current page
// body for UPDATE merges.
type WikiPageStore interface {
	FindSimilarPages(ctx context.Context, tenantID, datasetID string, queryVec []float32, k int) ([]WikiPageCandidate, error)
	GetPageBySlug(ctx context.Context, tenantID, datasetID, slug string) (*WikiPageCandidate, error)
}

// WikiPageCooccurrenceStore is an optional recall signal for topic routing.
// It returns pages whose source evidence contains one of the supplied chunks.
type WikiPageCooccurrenceStore interface {
	FindPagesBySourceChunks(ctx context.Context, tenantID, datasetID string, chunkIDs []string, k int) ([]WikiPageCandidate, error)
}

// WikiMapVersion identifies one immutable MAP extraction for a source chunk
// version. Key is a deterministic digest over the remaining identity fields;
// Payload is the variant-owned JSON representation of the extraction.
type WikiMapVersion struct {
	Key                 string
	TenantID            string
	DatasetID           string
	DocumentID          string
	ChunkID             string
	ContentHash         string
	TemplateFingerprint string
	LLMFingerprint      string
	Payload             []byte
}

// WikiMapVersionStore persists immutable, reusable Wiki MAP results. Removing
// or disabling a source chunk does not delete its historical versions; the
// dataset semantic compiler decides which versions are active.
type WikiMapVersionStore interface {
	GetWikiMapVersions(ctx context.Context, tenantID, datasetID string, keys []string) (map[string][]byte, error)
	PutWikiMapVersions(ctx context.Context, versions []WikiMapVersion) error
}

// WikiMapActiveState is the mutable pointer to the chunk/hash MAP versions and
// page plan used by the latest successful document Wiki compile. Payload is
// owned by the wiki variant so the storage layer remains schema-independent.
type WikiMapActiveState struct {
	Key        string
	TenantID   string
	DatasetID  string
	DocumentID string
	Payload    []byte
}

// WikiMapActiveStateStore persists the active MAP/plan snapshot separately
// from immutable WikiMapVersion history.
type WikiMapActiveStateStore interface {
	GetWikiMapActiveState(ctx context.Context, tenantID, datasetID, key string) ([]byte, error)
	PutWikiMapActiveState(ctx context.Context, state WikiMapActiveState) error
}

// RedisClient is injected only for the datasetnav variant (M8).
type RedisClient interface {
	// Minimal lock surface; full API added in M8.
}

// Deps bundles the runtime capabilities a variant needs. All fields are
// interfaces so tests inject stubs; production wiring lives in
// internal/ingestion/task (see PORT_PLAN.md §4 dependency injection seam).
type Deps struct {
	// Progress is the fraction budget allocated to this compilation template.
	Progress      progress.Window
	Chat          ChatInvoker
	Embed         Embedder
	Tokenizer     Tokenizer
	HistoricalKNN HistoricalKNN // optional (wiki)
	WikiPages     WikiPageStore // optional (wiki)
	// WikiMapVersions requires BOTH TenantID and DatasetID on every access:
	// the DocStore-backed store keys its rows ragflow_<tenant_id>/<kb_id> and
	// fails loudly on an empty scope. Runs missing either scope (canvas debug
	// dry-runs) take the cache-less MAP path instead of calling the store.
	WikiMapVersions WikiMapVersionStore // optional (wiki version cache)
	Redis           RedisClient         // optional (datasetnav)
	TenantID        string
	DatasetID       string
	// ModelContextLen is the chat model's context window in tokens
	// (content_length). Prompt-packing helpers use it to size input quotas.
	ModelContextLen int
	// ModelMaxOutput is the chat model's generation cap (max_output), the most
	// tokens one LLM response may emit. Cross-document merge judging packs many
	// pairs into a single call, so the caller must cap the batch by both the
	// input window (ModelContextLen) and this output cap; otherwise a large
	// candidate set can overflow the model's max_output and it returns a
	// truncated/non-JSON reply. Mirrors Python's max_tokens generation config.
	ModelMaxOutput int
}

// DepsResolver resolves the per-run Deps from the active task context and
// tenant/model references.
type DepsResolver func(ctx context.Context, tenantID, llmID, embeddingModel string) (Deps, error)

// DepsResolver / SetDepsResolver / ResolveDeps are the only injection seams the
// component exposes. The component is DB-independent: it compiles knowledge
// units into chunk-aligned docs (see conf/infinity_mapping.json) and returns
// them merged into the upstream chunk stream, so it owns the product schema but
// not the storage engine. Persistence (if any) is the caller's concern.

var (
	depsResolverMu sync.RWMutex
	depsResolver   DepsResolver
)

// SetDepsResolver installs the production (or test) DepsResolver. Tests call
// this to inject stubs; production wiring calls it from an init() in
// internal/ingestion/task.
func SetDepsResolver(r DepsResolver) {
	depsResolverMu.Lock()
	defer depsResolverMu.Unlock()
	depsResolver = r
}

// ResolveDeps resolves Deps via the installed resolver.
func ResolveDeps(ctx context.Context, tenantID, llmID, embeddingModel string) (Deps, error) {
	depsResolverMu.RLock()
	r := depsResolver
	depsResolverMu.RUnlock()
	if r == nil {
		return Deps{}, fmt.Errorf("knowledge_compiler: no DepsResolver registered (call common.SetDepsResolver in production wiring)")
	}
	return r(ctx, tenantID, llmID, embeddingModel)
}

// GroupResolver resolves compilation-template-group ids to the concrete
// compilation_template ids they contain. It is a DB-backed seam installed by
// production wiring in internal/ingestion/task; the knowledge_compiler package
// itself stays DB-independent. When a component is configured with
// compilation_template_group_id but no GroupResolver is installed, the
// component fails loudly instead of silently emitting rows that miss
// compilation_template_ids (a data-loss path).
type GroupResolver func(ctx context.Context, db *gorm.DB, tenantID string, groupIDs []string) ([]string, error)

var (
	groupResolverMu sync.RWMutex
	groupResolver   GroupResolver
)

// SetGroupResolver installs the production (or test) GroupResolver. Production
// wiring calls this from an init() in internal/ingestion/task; tests may inject
// a stub.
func SetGroupResolver(r GroupResolver) {
	groupResolverMu.Lock()
	defer groupResolverMu.Unlock()
	groupResolver = r
}

// ResolveGroupTemplateIDs resolves the given group ids to template ids via the
// installed resolver. Returns (nil, nil) when there are no group ids to
// resolve. Returns an error if group ids are requested but no resolver is
// installed, surfacing the misconfiguration instead of silently dropping the
// compilation_template_ids stamp.
func ResolveGroupTemplateIDs(ctx context.Context, db *gorm.DB, tenantID string, groupIDs []string) ([]string, error) {
	if len(groupIDs) == 0 {
		return nil, nil
	}
	groupResolverMu.RLock()
	r := groupResolver
	groupResolverMu.RUnlock()
	if r == nil {
		return nil, fmt.Errorf("knowledge_compiler: compilation_template_group_id provided but no GroupResolver installed (production wiring must call common.SetGroupResolver)")
	}
	return r(ctx, db, tenantID, groupIDs)
}

// TemplateResolver loads a single compilation template by id for the tenant.
type TemplateResolver func(ctx context.Context, db *gorm.DB, tenantID, templateID string) (TemplateInfo, error)

// TemplateInfo is a resolved compilation template: its id, the kind that
// selects the Go compiler variant (see KindToVariant), and its config blob (the
// template "content"). It is dependency-light so common can return it without
// importing entity/gorm — production wiring (internal/ingestion/task) converts
// the entity row into this shape.
type TemplateInfo struct {
	ID     string
	Kind   string
	Config map[string]any
}

var (
	templateResolverMu sync.RWMutex
	templateResolver   TemplateResolver
)

// SetTemplateResolver installs the production (or test) TemplateResolver.
// Production wiring calls this from an init() in internal/ingestion/task; tests
// may inject a stub.
func SetTemplateResolver(r TemplateResolver) {
	templateResolverMu.Lock()
	defer templateResolverMu.Unlock()
	templateResolver = r
}

// ResolveTemplate loads a single compilation template by id via the installed
// resolver. Returns an error when no resolver is installed (compilation_template_id
// provided but unwired) rather than silently compiling with no template config.
func ResolveTemplate(ctx context.Context, db *gorm.DB, tenantID, templateID string) (TemplateInfo, error) {
	templateResolverMu.RLock()
	r := templateResolver
	templateResolverMu.RUnlock()
	if r == nil {
		return TemplateInfo{}, fmt.Errorf("knowledge_compiler: compilation_template_id provided but no TemplateResolver installed (production wiring must call common.SetTemplateResolver)")
	}
	return r(ctx, db, tenantID, templateID)
}