Merge pull request #13 from hallelx2/feat/agentic-retrieval

pkg/retrieval: add agentic-navigation strategy (Phase 1.4)

Author: hallelx2

cmd/engine/main.go

@@ -10,6 +10,7 @@ import (
 	"errors"
 	"flag"
 	"fmt"
+	"io"
 	"log/slog"
 	"net/http"
 	"os"
@@ -87,7 +88,7 @@ func run() error {
 	if err != nil {
 		return fmt.Errorf("init llm: %w", err)
 	}
-	strategy := buildStrategy(cfg.Retrieval, llmClient)
+	strategy := buildStrategy(cfg.Retrieval, llmClient, store)
 
 	// Wrap with caching if enabled.
 	if cfg.Retrieval.Cache.Enabled {
@@ -252,17 +253,39 @@ func buildLLM(c config.LLMConfig) (llmgate.Client, error) {
 	}
 }
 
-func buildStrategy(c config.RetrievalConfig, client llmgate.Client) retrieval.Strategy {
+func buildStrategy(c config.RetrievalConfig, client llmgate.Client, store storage.Storage) retrieval.Strategy {
 	switch c.Strategy {
 	case "single-pass":
 		return retrieval.NewSinglePass(client)
 	case "chunked-tree":
 		return retrieval.NewChunkedTree(client)
+	case "agentic":
+		a := retrieval.NewAgentic(client, storageFetcher{s: store})
+		if c.Agentic.MaxHops > 0 {
+			a.MaxHops = c.Agentic.MaxHops
+		}
+		a.ModelOverride = c.Agentic.Model
+		return a
 	default:
 		return retrieval.NewChunkedTree(client)
 	}
 }
 
+// storageFetcher adapts a storage.Storage to retrieval.ContentFetcher.
+// The agentic strategy reads section bodies one at a time, so we
+// materialize the full reader contents into a []byte here rather than
+// streaming — section bodies are typically a few KB.
+type storageFetcher struct{ s storage.Storage }
+
+func (sf storageFetcher) Get(ctx context.Context, ref string) ([]byte, error) {
+	rc, _, err := sf.s.Get(ctx, ref)
+	if err != nil {
+		return nil, err
+	}
+	defer rc.Close()
+	return io.ReadAll(rc)
+}
+
 // buildTLSConfig returns a *tls.Config when direct TLS is enabled, or nil
 // when the engine should serve plaintext (behind a proxy). Returning nil
 // leaves http.Server's TLSConfig unset, which is exactly what ListenAndServe

cmd/server/main.go

@@ -18,6 +18,7 @@ import (
 	"errors"
 	"flag"
 	"fmt"
+	"io"
 	"log/slog"
 	"net/http"
 	"os"
@@ -131,7 +132,7 @@ func run() error {
 	if err != nil {
 		return fmt.Errorf("init llm: %w", err)
 	}
-	strategy := buildStrategy(cfg.Engine.Retrieval, llmClient)
+	strategy := buildStrategy(cfg.Engine.Retrieval, llmClient, store)
 
 	// Wrap with caching if enabled in engine config.
 	if cfg.Engine.Retrieval.Cache.Enabled {
@@ -328,17 +329,39 @@ func buildLLM(c enginecfg.LLMConfig) (llmgate.Client, error) {
 	}
 }
 
-func buildStrategy(c enginecfg.RetrievalConfig, client llmgate.Client) retrieval.Strategy {
+func buildStrategy(c enginecfg.RetrievalConfig, client llmgate.Client, store storage.Storage) retrieval.Strategy {
 	switch c.Strategy {
 	case "single-pass":
 		return retrieval.NewSinglePass(client)
 	case "chunked-tree":
 		return retrieval.NewChunkedTree(client)
+	case "agentic":
+		a := retrieval.NewAgentic(client, storageFetcher{s: store})
+		if c.Agentic.MaxHops > 0 {
+			a.MaxHops = c.Agentic.MaxHops
+		}
+		a.ModelOverride = c.Agentic.Model
+		return a
 	default:
 		return retrieval.NewChunkedTree(client)
 	}
 }
 
+// storageFetcher adapts a storage.Storage to retrieval.ContentFetcher.
+// The agentic strategy reads section bodies one at a time, so we
+// materialize the full reader contents into a []byte here rather than
+// streaming — section bodies are typically a few KB.
+type storageFetcher struct{ s storage.Storage }
+
+func (sf storageFetcher) Get(ctx context.Context, ref string) ([]byte, error) {
+	rc, _, err := sf.s.Get(ctx, ref)
+	if err != nil {
+		return nil, err
+	}
+	defer rc.Close()
+	return io.ReadAll(rc)
+}
+
 func buildTLSConfig(c config.TLSConfig) *tls.Config {
 	if !c.Enabled() {
 		return nil

pkg/config/config.go

@@ -188,6 +188,7 @@ type GeminiBlock struct {
 type RetrievalConfig struct {
 	Strategy    string           `yaml:"strategy"`
 	ChunkedTree ChunkedTreeBlock `yaml:"chunked_tree"`
+	Agentic     AgenticBlock     `yaml:"agentic"`
 	Cache       CacheBlock       `yaml:"cache"`
 }
 
@@ -212,6 +213,23 @@ type ChunkedTreeBlock struct {
 	IncludeSiblingBreadcrumb bool `yaml:"include_sibling_breadcrumbs"`
 }
 
+// AgenticBlock configures the agentic-navigation strategy.
+//
+// The agentic loop trades sequential latency for the ability to handle
+// arbitrarily large trees: the model issues outline/expand/read actions
+// until it picks a final set of section IDs or hits MaxHops.
+type AgenticBlock struct {
+	// MaxHops caps the number of LLM turns one query consumes, counting
+	// the terminal "done" turn. Default: 6.
+	MaxHops int `yaml:"max_hops"`
+
+	// Model optionally overrides the budget's model for navigation
+	// turns. Empty means use the budget's model. Useful when the
+	// retrieval engine wants the navigation loop on a fast/cheap
+	// model while answering is on a stronger one.
+	Model string `yaml:"model"`
+}
+
 // LogConfig configures logging.
 type LogConfig struct {
 	Level  string `yaml:"level"`
@@ -244,6 +262,9 @@ func Default() Config {
 				MaxParallelCalls:         8,
 				IncludeSiblingBreadcrumb: true,
 			},
+			Agentic: AgenticBlock{
+				MaxHops: 6,
+			},
 			Cache: CacheBlock{
 				Enabled:    true,
 				MaxEntries: 1024,
@@ -352,6 +373,14 @@ func applyEnvOverrides(c *Config) {
 	if v := os.Getenv("VLE_TLS_KEY_FILE"); v != "" {
 		c.Server.TLS.KeyFile = v
 	}
+	if v := os.Getenv("VLE_RETRIEVAL_AGENTIC_MAX_HOPS"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n >= 0 {
+			c.Retrieval.Agentic.MaxHops = n
+		}
+	}
+	if v := os.Getenv("VLE_RETRIEVAL_AGENTIC_MODEL"); v != "" {
+		c.Retrieval.Agentic.Model = v
+	}
 	// Ingest / HyDE knobs. Booleans accept the usual truthy strings —
 	// kept narrow so a typo doesn't silently flip the flag.
 	if v := os.Getenv("VLE_INGEST_HYDE_ENABLED"); v != "" {
@@ -428,11 +457,15 @@ func (c Config) Validate() error {
 	}
 
 	switch c.Retrieval.Strategy {
-	case "single-pass", "chunked-tree":
+	case "single-pass", "chunked-tree", "agentic":
 	default:
 		return fmt.Errorf("unknown retrieval.strategy: %q", c.Retrieval.Strategy)
 	}
 
+	if c.Retrieval.Agentic.MaxHops < 0 {
+		return fmt.Errorf("retrieval.agentic.max_hops must be >= 0, got %d", c.Retrieval.Agentic.MaxHops)
+	}
+
 	if c.Server.TLS.CertFile != "" && c.Server.TLS.KeyFile == "" {
 		return errors.New("server.tls.key_file is required when cert_file is set")
 	}