Skip to content

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

8.9 KB
Raw Blame
package common

import (
	"context"
	"encoding/json"
	"fmt"
	"math/rand"
	"regexp"
	"strings"
	"time"

	"github.com/kaptinlin/jsonrepair"
	"ragflow/internal/agent/runtime"
	appcommon "ragflow/internal/common"

	"go.uber.org/zap"
)

// jsonRetryMax is how many times a non-JSON (or otherwise transiently failed)
// LLM reply is retried before GenJSON gives up. The highest-frequency LLM
// integration must not drop a knowledge unit on a single formatting hiccup, so
// a one-off malformed reply triggers a fresh LLM call instead of an immediate
// failure.
const jsonRetryMax = 5

// jsonRetryDelay is the initial exponential-backoff delay between retries.
const jsonRetryDelay = 2 * time.Second

// fencedJSONRE matches a ```json ... ``` or ``` ... ``` fenced block. Models
// frequently wrap JSON in such fences even when JSONMode is requested, which
// previously slipped through as an unparseable "_raw" payload and was silently
// dropped by the extraction parser (a data-loss path). We strip the fence and
// retry before giving up.
var fencedJSONRE = regexp.MustCompile("(?s)```(?:json)?\\s*(.*?)\\s*```")

// retryDelayCtxKey carries a test-only override for jsonRetryDelay. Production
// code never sets it, so the real backoff budget is preserved at runtime.
type retryDelayCtxKey struct{}

// WithRetryDelay returns a ctx that makes GenJSON use d as the initial
// exponential-backoff delay instead of jsonRetryDelay. It exists so tests that
// exercise the LLM-failure retry path need not wait out the real ~60s budget
// per failed call. Pass 0 or a negative value to keep the default.
func WithRetryDelay(ctx context.Context, d time.Duration) context.Context {
	return context.WithValue(ctx, retryDelayCtxKey{}, d)
}

func RetryDelayFromCtx(ctx context.Context) (time.Duration, bool) {
	d, ok := ctx.Value(retryDelayCtxKey{}).(time.Duration)
	return d, ok && d > 0
}

// GenJSON dispatches a chat call in JSON mode and parses the response into a
// map. It first tries the raw content, then a fenced ```json ... ``` block the
// model may have wrapped around the JSON, and finally the outermost {...} span
// (handles "Here is the JSON: {...}" prose). A genuine parse failure is
// returned as an error (NOT a silent {"_raw": ...}) so the caller fails loudly
// or retries rather than silently dropping the extraction — the
// highest-frequency LLM integration must not lose knowledge units on a
// formatting hiccup.
// GenJSON asks the model for a JSON reply and parses it. retryMax is an
// optional override for jsonRetryMax: pass 0 to disable retries entirely
// (used where the caller already budgets external calls itself, e.g. the
// entity-merge disambiguator — retrying there would blow through the budget).
func GenJSON(ctx context.Context, chat ChatInvoker, req ChatRequest, retryMax ...int) (map[string]any, error) {
	maxRetries := jsonRetryMax
	if len(retryMax) > 0 {
		maxRetries = retryMax[0]
	}
	req.JSONMode = true
	// GenJSON owns retries for both transport failures and malformed JSON. Tell
	// the production ChatInvoker to make exactly one provider request per outer
	// GenJSON attempt, avoiding multiplicative nested retries.
	req.DisableRetry = true
	var lastErr error
	delay := jsonRetryDelay
	if d, ok := RetryDelayFromCtx(ctx); ok {
		delay = d
	}
	failureReporter := RetryFailureReporter{}
	for attempt := 0; attempt <= maxRetries; attempt++ {
		resp, err := chat.Chat(ctx, req)
		if err != nil {
			// Permanent chat errors (auth, unknown model, context-length,
			// cancelled ctx) cannot succeed on a retry; escape immediately.
			if !appcommon.IsTransientError(err) {
				if message, ok := failureReporter.FailureMessage(attempt+1, maxRetries+1, 0, err, true); ok {
					runtime.ReportProgressMessage(ctx, "Compiler", message)
				}
				return nil, err
			}
			// Transient chat failure (timeout / transport / provider); retry
			// with a fresh LLM call.
			lastErr = err
		} else {
			if repaired, repairErr := RepairJSONText(resp.Content); repairErr == nil {
				if m, unmarshalErr := tryUnmarshalJSONErr(repaired); unmarshalErr == nil {
					if message, ok := failureReporter.RecoveryMessage(attempt + 1); ok {
						runtime.ReportProgressMessage(ctx, "Compiler", message)
					}
					return m, nil
				}
			}
			candidates := jsonCandidates(resp.Content)
			for _, candidate := range candidates {
				if m, ok := tryUnmarshalJSON(candidate); ok {
					return m, nil
				}
			}
			// A non-JSON reply must NOT be persisted/reused; discard it and
			// immediately re-issue the call so a formatting hiccup does not
			// abort the whole compile. Log candidate length and the unmarshal
			// error only — the raw body may carry customer-derived content
			// (PII), so it is deliberately excluded from the log.
			for i, candidate := range candidates {
				_, perr := tryUnmarshalJSONErr(candidate)
				appcommon.Info("knowledge_compiler: GenJSON unparseable candidate",
					zap.Int("attempt", attempt), zap.Int("candidate", i),
					zap.Int("len", len(candidate)), zap.Error(perr))
			}
			lastErr = fmt.Errorf("knowledge_compiler: LLM response is not parseable JSON (%d bytes)", len(resp.Content))
		}
		if attempt == maxRetries {
			if message, ok := failureReporter.FailureMessage(attempt+1, maxRetries+1, 0, lastErr, true); ok {
				runtime.ReportProgressMessage(ctx, "Compiler", message)
			}
			break
		}
		if message, ok := failureReporter.FailureMessage(attempt+1, maxRetries+1, delay, lastErr, false); ok {
			runtime.ReportProgressMessage(ctx, "Compiler", message)
		}
		appcommon.Info("knowledge_compiler: GenJSON attempt failed, retrying",
			zap.Int("attempt", attempt), zap.Duration("delay", delay),
			zap.Error(lastErr))
		select {
		case <-ctx.Done():
			return nil, ctx.Err()
		case <-time.After(delay + time.Duration(rand.Int63n(int64(delay/2)+1))):
			// Jittered backoff so concurrent GenJSON jobs (parallel wiki/plan
			// batches) do not back off in lockstep and pile up on the provider.
		}
		delay *= 2
		if delay > time.Minute {
			delay = time.Minute
		}
	}
	return nil, lastErr
}

// RepairJSONText extracts and repairs a JSON object or array from an LLM response.
// It accepts plain JSON, fenced JSON, JSON surrounded by prose, and common
// malformed forms such as trailing commas or unquoted keys. The returned text
// is guaranteed to be a valid JSON object or array.
func RepairJSONText(s string) (string, error) {
	s = appcommon.StripThinkTrailing(s)
	var lastErr error
	for _, candidate := range jsonCandidates(s) {
		candidate = strings.TrimSpace(candidate)
		if candidate == "" {
			lastErr = fmt.Errorf("empty JSON candidate")
			continue
		}
		if isJSONObjectOrArray(candidate) {
			return candidate, nil
		}
		repaired, err := jsonrepair.Repair(candidate)
		if err != nil {
			lastErr = err
			continue
		}
		if isJSONObjectOrArray(repaired) {
			return repaired, nil
		}
		lastErr = fmt.Errorf("repaired candidate is not a JSON object or array")
	}
	if lastErr == nil {
		lastErr = fmt.Errorf("no JSON candidate")
	}
	return "", lastErr
}

func isJSONObjectOrArray(s string) bool {
	s = strings.TrimSpace(s)
	if len(s) < 2 || (s[0] != '{' && s[0] != '[') {
		return false
	}
	return json.Valid([]byte(s))
}

// CompactError produces a bounded, single-line error suitable for progress
// messages. Provider errors may contain credentials, so redact common secret
// fields and API-key-shaped values before exposing the result to users.
func CompactError(err error) string {
	if err == nil {
		return "unknown error"
	}
	const maxLength = 1000
	message := strings.Join(strings.Fields(err.Error()), " ")
	message = errorCredentialRE.ReplaceAllString(message, "$1=[REDACTED]")
	message = errorAPIKeyRE.ReplaceAllString(message, "[REDACTED]")
	if len(message) > maxLength {
		return message[:maxLength] + "..."
	}
	return message
}

var errorCredentialRE = regexp.MustCompile(`(?i)(api[-_ ]?key|access[-_ ]?token|authorization|password|secret)\s*["']?\s*[:=]\s*["']?[^,\s}"']+`)
var errorAPIKeyRE = regexp.MustCompile(`\bsk-[A-Za-z0-9_-]+`)

// jsonCandidates yields progressively "cleaned" versions of an LLM reply that
// may contain JSON: the raw text, a fenced ```json ... ``` block, and the
// outermost {...} span.
func jsonCandidates(s string) []string {
	cands := []string{s}
	if loc := fencedJSONRE.FindStringSubmatch(s); len(loc) == 2 {
		cands = append(cands, loc[1])
	}
	if i := strings.Index(s, "{"); i >= 0 {
		if j := strings.LastIndex(s, "}"); j > i {
			cands = append(cands, s[i:j+1])
		}
	}
	if i := strings.Index(s, "["); i >= 0 {
		if j := strings.LastIndex(s, "]"); j > i {
			cands = append(cands, s[i:j+1])
		}
	}
	return cands
}

func tryUnmarshalJSON(s string) (map[string]any, bool) {
	m, err := tryUnmarshalJSONErr(s)
	return m, err == nil
}

func tryUnmarshalJSONErr(s string) (map[string]any, error) {
	s = strings.TrimSpace(s)
	if s == "" {
		return nil, fmt.Errorf("empty candidate")
	}
	var m map[string]any
	if err := json.Unmarshal([]byte(s), &m); err != nil {
		return nil, err
	}
	return m, nil
}

func truncate(s string, n int) string {
	r := []rune(s)
	if len(r) <= n {
		return s
	}
	return string(r[:n]) + "..."
}