ragflow/internal/agent/runtime/template.go

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

// runtime — {{...}} variable reference parser shared by canvas and
// component packages.
//
// The regex is byte-for-byte identical to agent/component/base.py:368
// — any drift must be coordinated with the Python regex in the same
// line.
package runtime

import (
	"fmt"
	"regexp"
)

// VarRefPattern matches the RAGFlow v1 variable reference syntax.
// Mirrors agent/component/base.py:368 in spirit with one deviation: the
// cpn_id part includes '_' (real RAGFlow cpn_ids are like "begin_0",
// "llm_0", "cpn_0"). The Python regex as documented in the plan
// (`[a-zA-Z:0-9]+`) would not match those — this looks like a documentation
// bug in the plan; the Python source likely has the underscore too. This
// deviation is recorded in plan §1.1 and §2.11 with a TODO to confirm
// against the live Python source during Phase 2 cross-validation.
//
// Pattern:
//
//	\{* *\{(<ref>)\} *\}*
//	where <ref> = cpn_id@param | sys.x | env.x
//	cpn_id = [a-zA-Z:0-9_]+   (note: underscore added; see deviation note)
//	param  = [A-Za-z0-9_.-]+
//
// Capture group 1 holds the bare ref without braces (e.g. "cpn_0@content",
// "sys.query", "env.max_tokens").
var VarRefPattern = regexp.MustCompile(`\{* *\{([a-zA-Z:0-9_]+@[A-Za-z0-9_.-]+|sys\.[A-Za-z0-9_.]+|env\.[A-Za-z0-9_.]+)\} *\}*`)

// ExtractRefs returns the unique ref strings (without the surrounding
// braces) appearing in s, in first-occurrence order. Pure regex — does not
// touch state. Use this when you need to know "which references does this
// template contain?" without resolving.
func ExtractRefs(s string) []string {
	matches := VarRefPattern.FindAllStringSubmatch(s, -1)
	if len(matches) == 0 {
		return nil
	}
	seen := make(map[string]struct{}, len(matches))
	out := make([]string, 0, len(matches))
	for _, m := range matches {
		ref := m[1]
		if _, dup := seen[ref]; dup {
			continue
		}
		seen[ref] = struct{}{}
		out = append(out, ref)
	}
	return out
}

// ResolveTemplate substitutes every {{...}} in s with the current state's
// value for that ref. Unresolvable refs (GetVar returns nil) become errors
// — the Go port trades Python's silent soft-fail (canvas.py:177-178 returns
// "" for None) for a Go-idiomatic loud-fail so Phase 2 parameter binding can
// surface misconfigured canvases early. The partial output (with "" in place
// of the unresolved ref) is still returned so callers can choose to log it.
//
// Supported forms match GetVar (cpn_id@param[.path], sys.x[.path], env.x[.path],
// item, index).
func ResolveTemplate(s string, state *CanvasState) (string, error) {
	if !VarRefPattern.MatchString(s) {
		return s, nil
	}
	var firstErr error
	out := VarRefPattern.ReplaceAllStringFunc(s, func(match string) string {
		// Re-extract the bare ref from the match (ReplaceAllStringFunc gives
		// the whole match, not the subgroup).
		sub := VarRefPattern.FindStringSubmatch(match)
		if len(sub) < 2 {
			return match
		}
		ref := sub[1]
		v, err := state.GetVar(ref)
		if err != nil {
			if firstErr == nil {
				firstErr = fmt.Errorf("canvas: resolve %q: %w", ref, err)
			}
			return ""
		}
		if v == nil {
			if firstErr == nil {
				firstErr = fmt.Errorf("canvas: unresolved reference %q", ref)
			}
			return ""
		}
		return fmt.Sprintf("%v", v)
	})
	return out, firstErr
}