feat(transfer): hybrid rule-based + VDB semantic routing (closes #23) (#90)

* feat(config): add VDBRoutingConfig and Strategy to TransferConfig (issue #23)

Adds VDBRoutingConfig struct with confidence_threshold, min_samples_per_repo,
max_candidates, and explain_decision fields, plus a Strategy field to
TransferConfig. Includes defaults in applyDefaults() and mergeConfigs().

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(transfer): add VDBRouter for semantic transfer routing (issue #23)

Implements VDBRouter.SuggestTransfer() which embeds the issue, searches
the VDB collection, analyses repo distribution of results and returns a
VDBMatchResult when one repo exceeds the confidence threshold with enough
samples. Includes full unit-test coverage.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(gemini): add ExplainTransfer LLM method and prompt (issue #23)

Adds ExplainTransferInput type, LLMClient.ExplainTransfer() method
(temperature 0.3), and buildExplainTransferPrompt() that generates
a 2-3 sentence explanation of why an issue should be transferred.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

* feat(steps): hybrid VDB fallback in transfer_check step (issue #23)

TransferCheck now accepts embedder, vectorStore, and llmClient deps from
the pipeline registry. After rule-based matching fails, when strategy is
"hybrid" or "vdb-only" it calls VDBRouter.SuggestTransfer(). On a
confident match it sets TransferTarget + metadata (transfer_method,
transfer_confidence, transfer_reasoning). Optionally calls
LLMClient.ExplainTransfer when explain_decision=true.

Loop prevention and transfer_blocked flag still apply to VDB path.
Includes integration tests for rule-priority, rules-only strategy,
blocked flag and loop prevention.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Kavirubc

internal/core/config/config.go

@@ -112,15 +112,26 @@ type TransferRule struct {
 	Enabled       *bool    `yaml:"enabled,omitempty"`
 }
 
+// VDBRoutingConfig configures VDB-based semantic transfer routing.
+type VDBRoutingConfig struct {
+	Enabled             *bool   `yaml:"enabled,omitempty"`
+	ConfidenceThreshold float64 `yaml:"confidence_threshold,omitempty"` // Default: 0.75
+	MinSamplesPerRepo   int     `yaml:"min_samples_per_repo,omitempty"` // Default: 20
+	MaxCandidates       int     `yaml:"max_candidates,omitempty"`       // Default: 3
+	ExplainDecision     bool    `yaml:"explain_decision,omitempty"`     // Default: true
+}
+
 // TransferConfig holds transfer routing settings.
 type TransferConfig struct {
-	Enabled                      *bool          `yaml:"enabled,omitempty"`
-	Rules                        []TransferRule `yaml:"rules,omitempty"`
-	LLMRoutingEnabled            *bool          `yaml:"llm_routing_enabled,omitempty"`
-	HighConfidence               float64        `yaml:"high_confidence,omitempty"`                // Default: 0.9
-	MediumConfidence             float64        `yaml:"medium_confidence,omitempty"`              // Default: 0.6
-	DuplicateConfidenceThreshold float64        `yaml:"duplicate_confidence_threshold,omitempty"` // Default: 0.8
-	RepoCollection               string         `yaml:"repo_collection,omitempty"`                // Collection for repository documentation
+	Enabled                      *bool            `yaml:"enabled,omitempty"`
+	Rules                        []TransferRule   `yaml:"rules,omitempty"`
+	LLMRoutingEnabled            *bool            `yaml:"llm_routing_enabled,omitempty"`
+	HighConfidence               float64          `yaml:"high_confidence,omitempty"`                // Default: 0.9
+	MediumConfidence             float64          `yaml:"medium_confidence,omitempty"`              // Default: 0.6
+	DuplicateConfidenceThreshold float64          `yaml:"duplicate_confidence_threshold,omitempty"` // Default: 0.8
+	RepoCollection               string           `yaml:"repo_collection,omitempty"`                // Collection for repository documentation
+	VDBRouting                   VDBRoutingConfig `yaml:"vdb_routing,omitempty"`
+	Strategy                     string           `yaml:"strategy,omitempty"` // "rules-only", "vdb-only", "hybrid" (default: "hybrid" when vdb_routing.enabled)
 }
 
 // Load reads a config file from the given path and expands environment variables.
@@ -296,6 +307,19 @@ func (c *Config) applyDefaults() {
 	if c.Transfer.RepoCollection == "" {
 		c.Transfer.RepoCollection = "simili_repos"
 	}
+	// VDB routing defaults
+	if c.Transfer.VDBRouting.ConfidenceThreshold == 0 {
+		c.Transfer.VDBRouting.ConfidenceThreshold = 0.75
+	}
+	if c.Transfer.VDBRouting.MinSamplesPerRepo == 0 {
+		c.Transfer.VDBRouting.MinSamplesPerRepo = 20
+	}
+	if c.Transfer.VDBRouting.MaxCandidates == 0 {
+		c.Transfer.VDBRouting.MaxCandidates = 3
+	}
+	if c.Transfer.VDBRouting.Enabled != nil && *c.Transfer.VDBRouting.Enabled && c.Transfer.Strategy == "" {
+		c.Transfer.Strategy = "hybrid"
+	}
 	// Auto-close defaults
 	if c.AutoClose.GracePeriodHours == 0 {
 		c.AutoClose.GracePeriodHours = 72
@@ -389,6 +413,24 @@ func mergeConfigs(parent, child *Config) *Config {
 	if child.Transfer.RepoCollection != "" {
 		result.Transfer.RepoCollection = child.Transfer.RepoCollection
 	}
+	if child.Transfer.Strategy != "" {
+		result.Transfer.Strategy = child.Transfer.Strategy
+	}
+	if child.Transfer.VDBRouting.Enabled != nil {
+		result.Transfer.VDBRouting.Enabled = child.Transfer.VDBRouting.Enabled
+	}
+	if child.Transfer.VDBRouting.ConfidenceThreshold != 0 {
+		result.Transfer.VDBRouting.ConfidenceThreshold = child.Transfer.VDBRouting.ConfidenceThreshold
+	}
+	if child.Transfer.VDBRouting.MinSamplesPerRepo != 0 {
+		result.Transfer.VDBRouting.MinSamplesPerRepo = child.Transfer.VDBRouting.MinSamplesPerRepo
+	}
+	if child.Transfer.VDBRouting.MaxCandidates != 0 {
+		result.Transfer.VDBRouting.MaxCandidates = child.Transfer.VDBRouting.MaxCandidates
+	}
+	if child.Transfer.VDBRouting.ExplainDecision {
+		result.Transfer.VDBRouting.ExplainDecision = child.Transfer.VDBRouting.ExplainDecision
+	}
 
 	// AutoClose: override if fields are set.
 	// DryRun is always copied so a child config can explicitly set it to false.

internal/integrations/gemini/llm.go

@@ -278,6 +278,24 @@ func (l *LLMClient) AssessQuality(ctx context.Context, issue *IssueInput) (*Qual
 	return &result, nil
 }
 
+// ExplainTransferInput holds the data needed to generate a transfer explanation.
+type ExplainTransferInput struct {
+	IssueTitle    string
+	IssueBody     string
+	TargetRepo    string
+	SimilarIssues []SimilarIssueInput // From target repo
+}
+
+// ExplainTransfer generates a brief explanation of why an issue should be transferred.
+func (l *LLMClient) ExplainTransfer(ctx context.Context, input *ExplainTransferInput) (string, error) {
+	prompt := buildExplainTransferPrompt(input)
+	text, err := l.generateText(ctx, prompt, 0.3, false)
+	if err != nil {
+		return "", fmt.Errorf("failed to explain transfer: %w", err)
+	}
+	return strings.TrimSpace(text), nil
+}
+
 // DetectDuplicate analyzes semantic similarity for duplicate detection.
 // It retries on transient errors (429/5xx) with exponential backoff.
 func (l *LLMClient) DetectDuplicate(ctx context.Context, input *DuplicateCheckInput) (*DuplicateResult, error) {

internal/integrations/gemini/prompts.go

@@ -255,6 +255,33 @@ Assessment must be one of: "excellent", "good", "needs-improvement", "poor"`,
 	)
 }
 
+// buildExplainTransferPrompt creates a prompt to explain a VDB-driven transfer decision.
+func buildExplainTransferPrompt(input *ExplainTransferInput) string {
+	var similarList strings.Builder
+	for i, s := range input.SimilarIssues {
+		fmt.Fprintf(&similarList, "%d. #%d: %s\n", i+1, s.Number, s.Title)
+	}
+
+	return fmt.Sprintf(`You are an AI assistant helping explain a GitHub issue routing decision.
+
+The following issue is being considered for transfer to the repository "%s":
+- Title: %s
+- Body: %s
+
+Similar issues already in "%s":
+%s
+
+In 2-3 sentences, explain why this issue belongs in "%s" based on the similar issues found there.
+Be concise and specific.`,
+		input.TargetRepo,
+		input.IssueTitle,
+		truncate(input.IssueBody, 500),
+		input.TargetRepo,
+		similarList.String(),
+		input.TargetRepo,
+	)
+}
+
 // buildDuplicateDetectionPrompt creates a prompt for duplicate detection analysis.
 func buildDuplicateDetectionPrompt(input *DuplicateCheckInput) string {
 	var similarList strings.Builder

internal/steps/transfer_check.go

@@ -1,41 +1,54 @@
 // Author: Kaviru Hapuarachchi
 // GitHub: https://github.com/Kavirubc
 // Created: 2026-02-02
-// Last Modified: 2026-02-04
+// Last Modified: 2026-02-27
 
 // Package steps provides the transfer check step.
 package steps
 
 import (
+	"fmt"
 	"log"
 
 	"github.com/similigh/simili-bot/internal/core/pipeline"
+	"github.com/similigh/simili-bot/internal/integrations/gemini"
+	"github.com/similigh/simili-bot/internal/integrations/qdrant"
 	"github.com/similigh/simili-bot/internal/transfer"
 )
 
 // TransferCheck evaluates if an issue should be transferred to another repository.
-type TransferCheck struct{}
+// It first applies rule-based matching; if no rule matches and VDB routing is enabled
+// it falls back to semantic VDB search (hybrid strategy).
+type TransferCheck struct {
+	embedder    *gemini.Embedder
+	vectorStore qdrant.VectorStore
+	llmClient   *gemini.LLMClient
+}
 
 // NewTransferCheck creates a new transfer check step.
 func NewTransferCheck(deps *pipeline.Dependencies) *TransferCheck {
-	return &TransferCheck{}
+	return &TransferCheck{
+		embedder:    deps.Embedder,
+		vectorStore: deps.VectorStore,
+		llmClient:   deps.LLMClient,
+	}
 }
 
 // Name returns the step name.
 func (s *TransferCheck) Name() string {
 	return "transfer_check"
 }
 
-// Run checks if the issue should be transferred using transfer rules.
+// Run checks if the issue should be transferred using transfer rules and optionally VDB routing.
 func (s *TransferCheck) Run(ctx *pipeline.Context) error {
 	if ctx.Issue.EventType == "pull_request" || ctx.Issue.EventType == "pr_comment" {
 		log.Printf("[transfer_check] Pull request event detected, skipping transfer rules")
 		return nil
 	}
 
-	// Skip if transfer is not enabled or no rules configured
-	if ctx.Config.Transfer.Enabled == nil || !*ctx.Config.Transfer.Enabled || len(ctx.Config.Transfer.Rules) == 0 {
-		log.Printf("[transfer_check] Transfer not enabled or no rules, skipping")
+	// Skip if transfer is not enabled
+	if ctx.Config.Transfer.Enabled == nil || !*ctx.Config.Transfer.Enabled {
+		log.Printf("[transfer_check] Transfer not enabled, skipping")
 		return nil
 	}
 
@@ -47,49 +60,148 @@ func (s *TransferCheck) Run(ctx *pipeline.Context) error {
 
 	blockedTargets, _ := ctx.Metadata["blocked_targets"].([]string)
 
-	log.Printf("[transfer_check] Checking transfer rules for issue #%d", ctx.Issue.Number)
-
-	// Create the rule matcher
-	matcher := transfer.NewRuleMatcher(ctx.Config.Transfer.Rules)
+	strategy := ctx.Config.Transfer.Strategy
+	vdbCfg := ctx.Config.Transfer.VDBRouting
+	vdbEnabled := vdbCfg.Enabled != nil && *vdbCfg.Enabled
 
-	// Build issue input for matching
-	input := &transfer.IssueInput{
-		Title:  ctx.Issue.Title,
-		Body:   ctx.Issue.Body,
-		Labels: ctx.Issue.Labels,
-		Author: ctx.Issue.Author,
+	// Determine effective strategy
+	if strategy == "" {
+		if vdbEnabled {
+			strategy = "hybrid"
+		} else {
+			strategy = "rules-only"
+		}
 	}
 
-	// Evaluate rules
-	result := matcher.Match(input)
-	if result.Matched {
-		// Check if target is blocked (loop prevention)
-		isBlocked := false
-		for _, blocked := range blockedTargets {
-			if blocked == result.Target {
-				isBlocked = true
-				break
+	log.Printf("[transfer_check] Strategy=%s vdbEnabled=%v issue=#%d", strategy, vdbEnabled, ctx.Issue.Number)
+
+	// --- Rule-based matching ---
+	ruleMatched := false
+	if strategy != "vdb-only" && len(ctx.Config.Transfer.Rules) > 0 {
+		matcher := transfer.NewRuleMatcher(ctx.Config.Transfer.Rules)
+		input := &transfer.IssueInput{
+			Title:  ctx.Issue.Title,
+			Body:   ctx.Issue.Body,
+			Labels: ctx.Issue.Labels,
+			Author: ctx.Issue.Author,
+		}
+		result := matcher.Match(input)
+		if result.Matched {
+			if isBlockedTarget(result.Target, blockedTargets) {
+				log.Printf("[transfer_check] Skipping transfer to %s: loop prevention (blocked target)", result.Target)
+			} else {
+				log.Printf("[transfer_check] Rule match: rule=%s target=%s", result.Rule.Name, result.Target)
+				setTransferTarget(ctx, result.Target, "rule", 1.0, result.Rule.Name, "")
+				ruleMatched = true
 			}
 		}
+	}
 
-		if isBlocked {
-			log.Printf("[transfer_check] Skipping transfer to %s: detected loop (blocked target)", result.Target)
-			return nil
-		}
+	if ruleMatched {
+		return nil
+	}
 
-		log.Printf("[transfer_check] Issue #%d matched rule '%s', target: %s",
-			ctx.Issue.Number, result.Rule.Name, result.Target)
+	// --- VDB fallback ---
+	if strategy == "rules-only" || !vdbEnabled {
+		log.Printf("[transfer_check] VDB routing disabled or rules-only strategy, skipping VDB")
+		return nil
+	}
+
+	if s.embedder == nil || s.vectorStore == nil {
+		log.Printf("[transfer_check] VDB deps not available, skipping VDB routing")
+		return nil
+	}
+
+	currentRepo := fmt.Sprintf("%s/%s", ctx.Issue.Org, ctx.Issue.Repo)
+	collection := ctx.Config.Qdrant.Collection
+
+	router := transfer.NewVDBRouter(s.embedder, s.vectorStore, collection, 50)
+
+	vdbResult, err := router.SuggestTransfer(
+		ctx.Ctx,
+		&transfer.IssueInput{Title: ctx.Issue.Title, Body: ctx.Issue.Body},
+		currentRepo,
+		vdbCfg.ConfidenceThreshold,
+		vdbCfg.MinSamplesPerRepo,
+		vdbCfg.MaxCandidates,
+	)
+	if err != nil {
+		log.Printf("[transfer_check] VDB routing error: %v", err)
+		return nil // Non-fatal
+	}
+
+	if vdbResult == nil {
+		log.Printf("[transfer_check] VDB found no confident transfer candidate")
+		return nil
+	}
 
-		// Set transfer target
-		ctx.TransferTarget = result.Target
-		ctx.Result.TransferTarget = result.Target
+	if isBlockedTarget(vdbResult.Target, blockedTargets) {
+		log.Printf("[transfer_check] VDB target %s is blocked (loop prevention)", vdbResult.Target)
+		return nil
+	}
 
-		// Store metadata for downstream steps
-		ctx.Metadata["transfer_rule"] = result.Rule.Name
-		ctx.Metadata["skip_duplicate_detection"] = true
-	} else {
-		log.Printf("[transfer_check] Issue #%d did not match any transfer rules", ctx.Issue.Number)
+	// Optionally generate LLM explanation
+	reasoning := ""
+	if vdbCfg.ExplainDecision && s.llmClient != nil {
+		similar := buildSimilarForExplain(vdbResult.SimilarIssues)
+		explanation, err := s.llmClient.ExplainTransfer(ctx.Ctx, &gemini.ExplainTransferInput{
+			IssueTitle:    ctx.Issue.Title,
+			IssueBody:     ctx.Issue.Body,
+			TargetRepo:    vdbResult.Target,
+			SimilarIssues: similar,
+		})
+		if err != nil {
+			log.Printf("[transfer_check] ExplainTransfer error (non-fatal): %v", err)
+		} else {
+			reasoning = explanation
+		}
 	}
 
+	log.Printf("[transfer_check] VDB transfer suggestion: target=%s confidence=%.2f",
+		vdbResult.Target, vdbResult.Confidence)
+
+	setTransferTarget(ctx, vdbResult.Target, "vdb", vdbResult.Confidence, "", reasoning)
 	return nil
 }
+
+// setTransferTarget writes the transfer decision into the pipeline context.
+func setTransferTarget(ctx *pipeline.Context, target, method string, confidence float64, ruleName, reasoning string) {
+	ctx.TransferTarget = target
+	ctx.Result.TransferTarget = target
+	ctx.Result.TransferConfidence = confidence
+	if reasoning != "" {
+		ctx.Result.TransferReason = reasoning
+	}
+
+	ctx.Metadata["transfer_method"] = method
+	ctx.Metadata["transfer_confidence"] = confidence
+	if reasoning != "" {
+		ctx.Metadata["transfer_reasoning"] = reasoning
+	}
+	if ruleName != "" {
+		ctx.Metadata["transfer_rule"] = ruleName
+	}
+	ctx.Metadata["skip_duplicate_detection"] = true
+}
+
+// isBlockedTarget checks if a target repo is in the blocked list.
+func isBlockedTarget(target string, blocked []string) bool {
+	for _, b := range blocked {
+		if b == target {
+			return true
+		}
+	}
+	return false
+}
+
+// buildSimilarForExplain converts VDB result IDs to SimilarIssueInput stubs.
+func buildSimilarForExplain(ids []string) []gemini.SimilarIssueInput {
+	out := make([]gemini.SimilarIssueInput, 0, len(ids))
+	for i, id := range ids {
+		out = append(out, gemini.SimilarIssueInput{
+			Number: i + 1,
+			Title:  id, // Best we have without full payloads
+		})
+	}
+	return out
+}