Skip to content

feat: add adaptive RAG prefetching#3167

Open
teerthsharma wants to merge 1 commit into
docker:mainfrom
teerthsharma:Feat/adaptive-rag-prefetcher
Open

feat: add adaptive RAG prefetching#3167
teerthsharma wants to merge 1 commit into
docker:mainfrom
teerthsharma:Feat/adaptive-rag-prefetcher

Conversation

@teerthsharma

@teerthsharma teerthsharma commented Jun 19, 2026

Copy link
Copy Markdown

Closes #3164

How this solves the issue

Issue #3164 proposed an adaptive RAG prefetcher that borrows the useful ideas from Aether-Lang, without importing Aether itself: topology metadata, adaptive drift detection, and conservative pre-warming for likely follow-up retrievals.

This PR implements that proposal in docker-agent's existing RAG architecture:

  • Adds an opt-in results.prefetch configuration block so existing RAG behavior is unchanged by default.
  • Adds pkg/rag/prefetch, a bounded in-memory prefetch layer that tracks normalized query shape, result count, average similarity, and centroid drift.
  • Uses the drift score to decide when a session is stable enough to warm deterministic follow-up candidates, and suppresses background work during topic shifts.
  • Serves exact repeated RAG queries from a cloned result cache, reducing repeated retrieval latency on the active path.
  • Runs candidate prefetch in the background with timeout and in-flight de-duplication, so prefetch never blocks the foreground query.
  • Wires prefetching at pkg/rag/manager.go, preserving the existing strategy, fusion, reranking, limit, full-content, and deduplication order.
  • Clears cached state after explicit reindex checks to avoid holding stale results across index refreshes.
  • Skips background candidate prefetch when reranking is enabled, keeping reranker error/fallback behavior tied to the user-visible foreground query.

Issue acceptance criteria coverage

  • Disabled/conservative by default: results.prefetch.enabled defaults to false.
  • No Aether dependency: the PR translates the topology/drift idea into small Go primitives only.
  • Bounded and non-blocking: cache size, candidate count, timeout, and in-flight de-duplication are all configurable.
  • Drift invalidation: topology drift suppresses candidate generation when the query stream moves away from the current centroid.
  • RAG manager integration: Manager.Query now checks the exact-query cache, stores final successful results, observes topology, and schedules background prefetches after cache misses.
  • Documentation/example: RAG docs and examples/rag/adaptive_prefetch.yaml show the new config.

Validation

  • go test ./pkg/rag/prefetch
  • go test ./pkg/rag -run TestQueryUsesPrefetchCacheForRepeatedQuery
  • go test ./pkg/config -run "TestJsonSchemaWorksForExamples|TestSchemaMatchesGoTypes"
  • go run ./lint .
  • go mod tidy --diff
  • go build -v -o .\bin\docker-agent.exe .\main.go

Local note: task and golangci-lint are not installed in this Windows environment, so task lint, task test, and task build could not run directly. Package-wide go test ./... on Windows still hits existing path/default-agent environment-sensitive tests unrelated to this branch.

Signed-off-by: Teerth Sharma <teerths57@gmail.com>
@teerthsharma teerthsharma marked this pull request as ready for review June 19, 2026 04:28
@teerthsharma teerthsharma requested a review from a team as a code owner June 19, 2026 04:28
@aheritier aheritier added area/core Core agent runtime, session management kind/feature New feature labels Jun 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/core Core agent runtime, session management kind/feature New feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: adaptive RAG prefetcher with topology-aware retrieval planning

2 participants