feat(engine): Gemini on Vertex AI, and a timing split on every query and answer

cmd/engine/main.go

@@ -20,6 +20,8 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/hallelx2/vectorless-engine/pkg/models"
+
 	"github.com/hallelx2/llmgate"
 	"github.com/hallelx2/llmgate/judge/typesafe"
 	"github.com/hallelx2/llmgate/middleware/limit"
@@ -415,6 +417,11 @@ func modelFor(c config.LLMConfig) string {
 		return c.OpenAI.Model
 	case "gemini":
 		return c.Gemini.Model
+	case "vertex":
+		if c.Vertex.Model != "" {
+			return c.Vertex.Model
+		}
+		return models.DefaultModels[models.ProviderVertex]
 	}
 	return ""
 }
@@ -517,6 +524,10 @@ func buildLLM(c config.LLMConfig) (llmgate.Client, error) {
 			Model:          c.Gemini.Model,
 			ReasoningModel: c.Gemini.ReasoningModel,
 		})
+	case "vertex":
+		return models.BuildClient(models.Generative{Provider: models.ProviderVertex, IngestModel: c.Vertex.Model,
+			Project: c.Vertex.Project, Location: c.Vertex.Location,
+			ThinkingBudget: c.Vertex.ThinkingBudget, ThinkingLevel: c.Vertex.ThinkingLevel})
 	default:
 		// Config.Validate rejects unknown drivers; this is defensive.
 		return nil, fmt.Errorf("unknown llm driver: %s", c.Driver)

cmd/server/main.go

@@ -25,9 +25,12 @@ import (
 	"net/http"
 	"os"
 	"os/signal"
+	"runtime/debug"
 	"syscall"
 	"time"
 
+	"github.com/hallelx2/vectorless-engine/pkg/reqtiming"
+
 	"github.com/hallelx2/llmgate"
 	"github.com/hallelx2/llmgate/judge/typesafe"
 	"github.com/hallelx2/llmgate/middleware/limit"
@@ -57,6 +60,37 @@ import (
 // version is set at build time via -ldflags "-X main.version=..."
 var version = "dev"
 
+// buildVersion is version, or — for a build without -ldflags, such as
+// go run or go build in a checkout — the commit the binary was built from,
+// so /v1/version always names the build a benchmark measured (HAL-1582).
+func buildVersion() string {
+	if version != "dev" {
+		return version
+	}
+	info, ok := debug.ReadBuildInfo()
+	if !ok {
+		return version
+	}
+	var rev, dirty string
+	for _, s := range info.Settings {
+		switch s.Key {
+		case "vcs.revision":
+			rev = s.Value
+		case "vcs.modified":
+			if s.Value == "true" {
+				dirty = "-dirty"
+			}
+		}
+	}
+	if rev == "" {
+		return version
+	}
+	if len(rev) > 12 {
+		rev = rev[:12]
+	}
+	return "dev-" + rev + dirty
+}
+
 func main() {
 	if err := run(); err != nil {
 		fmt.Fprintf(os.Stderr, "fatal: %v\n", err)
@@ -76,7 +110,7 @@ func run() error {
 
 	logger := newLogger(cfg.Engine.Log)
 	logger.Info("starting vectorless-server",
-		"version", version,
+		"version", buildVersion(),
 		"role", *role,
 		"addr", cfg.Server.Addr,
 		"auth_mode", cfg.Auth.Mode,
@@ -103,7 +137,7 @@ func run() error {
 			Endpoint:    cfg.Tracing.Endpoint,
 			Insecure:    cfg.Tracing.Insecure,
 			ServiceName: cfg.Tracing.ServiceName,
-			Version:     version,
+			Version:     buildVersion(),
 			SampleRate:  cfg.Tracing.SampleRate,
 		})
 		if err != nil {
@@ -135,6 +169,7 @@ func run() error {
 	if err != nil {
 		return fmt.Errorf("init storage: %w", err)
 	}
+	store = reqtiming.WrapStorage(store)
 
 	// ── Queue ─────────────────────────────────────────────────────
 	q, err := buildQueue(cfg.Engine.Queue, cfg.Engine.Database.URL)
@@ -177,11 +212,14 @@ func run() error {
 	logModelStatus(logger, registry.Status())
 
 	// ── LLM + retrieval strategy ──────────────────────────────────
-	llmClient := limit.Client(newLimiter("llm", cfg.Engine.LLM.Concurrency, logger))(registry.Client())
+	// reqtiming wraps outermost, outside the limiter and retries: a call
+	// queued at the limiter is the engine's time, and every attempt of a
+	// retried call is one wait on the provider.
+	llmClient := reqtiming.WrapClient(limit.Client(newLimiter("llm", cfg.Engine.LLM.Concurrency, logger))(registry.Client()))
 	// judge is always the registry's proxy. Code that takes a different
 	// path without a Judge resolves it per job or request through
 	// models.ActiveJudge; judgewalk falls back to treewalk.
-	judge := registry.Judge()
+	judge := reqtiming.WrapJudge(registry.Judge())
 	strategy := buildStrategy(cfg.Engine.Retrieval, llmClient, judge, store, pool)
 
 	// Wrap with caching if enabled in engine config.
@@ -346,7 +384,7 @@ func run() error {
 			Queue:            q,
 			Strategy:         strategy,
 			MultiDoc:         multiDoc,
-			Version:          version,
+			Version:          buildVersion(),
 			Config:           cfg,
 			Strategies:       strategies,
 			LLM:              llmClient,
@@ -487,6 +525,11 @@ func modelFor(c enginecfg.LLMConfig) string {
 		return c.OpenAI.Model
 	case "gemini":
 		return c.Gemini.Model
+	case "vertex":
+		if c.Vertex.Model != "" {
+			return c.Vertex.Model
+		}
+		return models.DefaultModels[models.ProviderVertex]
 	}
 	return ""
 }
@@ -592,6 +635,12 @@ func envModelSettings(cfg config.Config) models.Settings {
 		if l.Gemini.APIKey != "" {
 			g = &models.Generative{Provider: models.ProviderGemini, APIKey: l.Gemini.APIKey, IngestModel: l.Gemini.Model}
 		}
+	case "vertex":
+		// No key to wait for: choosing the driver is the configuration.
+		// Credentials are checked when the client is built.
+		v := l.Vertex
+		g = &models.Generative{Provider: models.ProviderVertex, IngestModel: v.Model, Project: v.Project, Location: v.Location,
+			ThinkingBudget: v.ThinkingBudget, ThinkingLevel: v.ThinkingLevel}
 	}
 	if g != nil {
 		g.AnswerModel = cfg.Models.AnswerModel
@@ -643,6 +692,10 @@ func buildLLM(c enginecfg.LLMConfig) (llmgate.Client, error) {
 			Model:          c.Gemini.Model,
 			ReasoningModel: c.Gemini.ReasoningModel,
 		})
+	case "vertex":
+		return models.BuildClient(models.Generative{Provider: models.ProviderVertex, IngestModel: c.Vertex.Model,
+			Project: c.Vertex.Project, Location: c.Vertex.Location,
+			ThinkingBudget: c.Vertex.ThinkingBudget, ThinkingLevel: c.Vertex.ThinkingLevel})
 	default:
 		return nil, fmt.Errorf("unknown llm driver: %s", c.Driver)
 	}

config.server.example.yaml

@@ -77,7 +77,7 @@ engine:
     #   concurrency: 20
 
   llm:
-    driver: "anthropic"   # "anthropic", "openai", or "gemini"
+    driver: "anthropic"   # "anthropic", "openai", "gemini" or "vertex"
     anthropic:
       api_key: ""   # set via VLS_ANTHROPIC_API_KEY
       model: "claude-sonnet-4-20250514"
@@ -89,6 +89,11 @@ engine:
     # gemini:
     #   api_key: ""
     #   model: "gemini-2.0-flash"
+    # vertex:                     # Gemini on Vertex AI: no key, ADC bills the project
+    #   project: ""               # VLS_LLM_VERTEX_PROJECT (or GOOGLE_CLOUD_PROJECT)
+    #   location: "global"        # VLS_LLM_VERTEX_LOCATION
+    #   model: "gemini-2.5-flash-lite"
+    #   thinking_budget: 0        # VLS_LLM_VERTEX_THINKING_BUDGET; omit for the model default
     #   reasoning_model: ""
     # Adaptive per-provider concurrency (HAL-1372): starts at initial,
     # halves on 429/transport failure, widens on success, capped at max.

go.mod

@@ -14,7 +14,7 @@ require (
 	github.com/aws/smithy-go v1.25.0
 	github.com/go-chi/chi/v5 v5.2.5
 	github.com/google/uuid v1.6.0
-	github.com/hallelx2/llmgate v0.5.1-0.20260928015141-010e07c576e6
+	github.com/hallelx2/llmgate v0.5.1-0.20261016012949-4e674f5d6726
 	github.com/hallelx2/pdftable v0.4.0
 	github.com/hibiken/asynq v0.26.0
 	github.com/jackc/pgx/v5 v5.9.2
@@ -30,6 +30,7 @@ require (
 	go.opentelemetry.io/otel/trace v1.44.0
 	golang.org/x/net v0.57.0
 	golang.org/x/sync v0.22.0
+	google.golang.org/api v0.274.0
 	google.golang.org/grpc v1.83.1
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1
@@ -126,7 +127,6 @@ require (
 	golang.org/x/sys v0.47.0 // indirect
 	golang.org/x/text v0.40.0 // indirect
 	golang.org/x/time v0.15.0 // indirect
-	google.golang.org/api v0.274.0 // indirect
 	google.golang.org/genproto v0.0.0-20260319201613-d00831a3d3e7 // indirect
 	google.golang.org/genproto/googleapis/api v0.0.0-20260526163538-3dc84a4a5aaa // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260729162451-8efbd57d26e0 // indirect

go.sum

@@ -132,14 +132,8 @@ github.com/googleapis/gax-go/v2 v2.21.0 h1:h45NjjzEO3faG9Lg/cFrBh2PgegVVgzqKzuZl
 github.com/googleapis/gax-go/v2 v2.21.0/go.mod h1:But/NJU6TnZsrLai/xBAQLLz+Hc7fHZJt/hsCz3Fih4=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 h1:8Tjv8EJ+pM1xP8mK6egEbD1OgnVTyacbefKhmbLhIhU=
 github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2/go.mod h1:pkJQ2tZHJ0aFOVEEot6oZmaVEZcRme73eIFmhiVuRWs=
-github.com/hallelx2/llmgate v0.4.0 h1:LvaRt1PWEiR0DcNd3j8qX0GEO0oh/rKPHqfL1RABzII=
-github.com/hallelx2/llmgate v0.4.0/go.mod h1:WpKwV/utKOmb+G5DwezSGjmGtz9D5I6MuS4MqAs7rkA=
-github.com/hallelx2/llmgate v0.4.1-0.20260918182842-b2ec96425ecc h1:4b6tUdYQANqf5iCTnDZzY5dWHbRElVznCH4LiAovBkM=
-github.com/hallelx2/llmgate v0.4.1-0.20260918182842-b2ec96425ecc/go.mod h1:WpKwV/utKOmb+G5DwezSGjmGtz9D5I6MuS4MqAs7rkA=
-github.com/hallelx2/llmgate v0.5.0 h1:yNBm7NOtDrCnpeMPz2BqbNcCJeUTw0WN6oiIuEFankg=
-github.com/hallelx2/llmgate v0.5.0/go.mod h1:WpKwV/utKOmb+G5DwezSGjmGtz9D5I6MuS4MqAs7rkA=
-github.com/hallelx2/llmgate v0.5.1-0.20260928015141-010e07c576e6 h1:26w9OIBo0Cfu5vAVyjZgr0Uyh25B+p4jSg2dit6BuBI=
-github.com/hallelx2/llmgate v0.5.1-0.20260928015141-010e07c576e6/go.mod h1:WpKwV/utKOmb+G5DwezSGjmGtz9D5I6MuS4MqAs7rkA=
+github.com/hallelx2/llmgate v0.5.1-0.20261016012949-4e674f5d6726 h1:n0KEoQX4ytgC0ZrqfC5K9lapEcOlfVlcnHBsnCNqekM=
+github.com/hallelx2/llmgate v0.5.1-0.20261016012949-4e674f5d6726/go.mod h1:lvdLI9zL40oeU6rwN0GIUFE5QMJ+QEekdUNLoLjFYCI=
 github.com/hallelx2/pdftable v0.4.0 h1:ldF8qQrUbejWsbB/JSIqliEXF2jF8z8kjEsbKS8r2BU=
 github.com/hallelx2/pdftable v0.4.0/go.mod h1:pxNlc4D43wjzis7M6EfgQZvHOsQ4okggm+xqUu+OokI=
 github.com/hhrutter/lzw v1.0.0 h1:laL89Llp86W3rRs83LvKbwYRx6INE8gDn0XNb1oXtm0=

internal/config/config.go

@@ -344,6 +344,7 @@ func applyEnvOverrides(c *Config) {
 	if v := firstEnv("VLS_GEMINI_API_KEY", "VLE_GEMINI_API_KEY", "VLS_LLM_GEMINI_API_KEY", "VLE_LLM_GEMINI_API_KEY"); v != "" {
 		c.Engine.LLM.Gemini.APIKey = v
 	}
+	enginecfg.ApplyVertexEnv(&c.Engine.LLM.Vertex, "VLS_", "VLE_")
 	if v := firstEnv("VLS_STORAGE_DRIVER", "VLE_STORAGE_DRIVER"); v != "" {
 		c.Engine.Storage.Driver = v
 	}

internal/handler/answer.go

@@ -12,6 +12,8 @@ import (
 	"sync"
 	"time"
 
+	"github.com/hallelx2/vectorless-engine/pkg/reqtiming"
+
 	"github.com/hallelx2/llmgate"
 
 	enginecfg "github.com/hallelx2/vectorless-engine/pkg/config"
@@ -144,7 +146,9 @@ func (h *AnswerHandler) resolveBYOK(w http.ResponseWriter, r *http.Request) (*by
 		writeErr(w, http.StatusBadRequest, "model key: "+err.Error())
 		return nil, false
 	}
-	return &byokClient{client: c, model: model, provider: provider}, true
+	// Timed like the registry's client, so the caller's own model counts
+	// as an answer-model wait rather than engine time.
+	return &byokClient{client: reqtiming.WrapClient(c), model: model, provider: provider}, true
 }
 
 func (b *byokClient) or(c llmgate.Client, model string) (llmgate.Client, string) {
@@ -302,6 +306,7 @@ func (h *AnswerHandler) HandleAnswer(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
+	withTiming(r, resp)
 	raw, err := marshalJSONForReplay(resp)
 	entry := retrieval.ReplayEntry{DocumentID: body.DocumentID, Query: body.Query, Model: model, SelectedIDs: finalIDs}
 	if body.Stream {

internal/handler/answer_treewalk.go

@@ -227,6 +227,7 @@ func (h *AnswerTreeWalkHandler) HandleAnswerTreeWalk(w http.ResponseWriter, r *h
 	}
 
 	finalIDs := append([]tree.SectionID(nil), res.SelectedIDs...)
+	withTiming(r, resp)
 	setTokenHeaders(w.Header(), resp)
 	raw, err := marshalJSONForReplay(resp)
 	if err != nil {
@@ -309,6 +310,7 @@ func (h *AnswerTreeWalkHandler) serveStream(w http.ResponseWriter, r *http.Reque
 		"trace_token": res.TraceToken,
 		"pages_read":  res.PagesRead,
 	}
+	withTiming(r, final)
 	emitSSE("answer", final)
 	setTokenHeaders(w.Header(), final)
 }

internal/handler/helpers.go

@@ -7,6 +7,8 @@ import (
 	"strings"
 	"time"
 
+	"github.com/hallelx2/vectorless-engine/pkg/reqtiming"
+
 	"github.com/hallelx2/vectorless-engine/pkg/retrieval"
 )
 
@@ -41,6 +43,17 @@ func marshalJSONForReplay(v any) ([]byte, error) {
 // MUST see the same bytes; this is the single point where that
 // invariant is enforced. When store is nil or token is empty the
 // replay write is skipped silently.
+// withTiming adds the request's timing split to a response: how much of
+// the wall clock was the engine's own work and how much was waiting on
+// the Judge, the answer model, the database and document storage
+// (pkg/reqtiming). A request served without the timing middleware gets
+// no field rather than a zero one.
+func withTiming(r *http.Request, resp map[string]any) {
+	if rec := reqtiming.From(r.Context()); rec != nil {
+		resp["timing"] = rec.Snapshot()
+	}
+}
+
 func writeJSONWithReplay(w http.ResponseWriter, store retrieval.ReplayStore, status int, raw []byte, token string, entry retrieval.ReplayEntry) {
 	w.Header().Set("Content-Type", "application/json")
 	w.WriteHeader(status)

internal/handler/query.go

@@ -231,6 +231,7 @@ func (h *QueryHandler) HandleQuery(w http.ResponseWriter, r *http.Request) {
 			"llm_calls":     usage.LLMCalls,
 		}
 	}
+	withTiming(r, resp)
 	setTokenHeaders(w.Header(), resp)
 	writeJSON(w, http.StatusOK, resp)
 }

internal/handler/query_multi.go

@@ -141,7 +141,7 @@ func (h *QueryMultiHandler) HandleQueryMulti(w http.ResponseWriter, r *http.Requ
 		errs[string(docID)] = e.Error()
 	}
 
-	writeJSON(w, http.StatusOK, map[string]any{
+	resp := map[string]any{
 		"query":      body.Query,
 		"strategy":   retrieval.PublicName(h.strategy.Name()),
 		"model":      body.Model,
@@ -155,5 +155,7 @@ func (h *QueryMultiHandler) HandleQueryMulti(w http.ResponseWriter, r *http.Requ
 			"cost_usd":      result.TotalUsage.CostUSD,
 			"llm_calls":     result.TotalUsage.LLMCalls,
 		},
-	})
+	}
+	withTiming(r, resp)
+	writeJSON(w, http.StatusOK, resp)
 }

internal/handler/query_stream.go

@@ -9,6 +9,8 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/hallelx2/vectorless-engine/pkg/reqtiming"
+
 	"github.com/hallelx2/vectorless-engine/pkg/db"
 	"github.com/hallelx2/vectorless-engine/pkg/retrieval"
 	"github.com/hallelx2/vectorless-engine/pkg/storage"
@@ -49,6 +51,8 @@ type sseEvent struct {
 	DocumentID  string `json:"document_id,omitempty"`
 	Query       string `json:"query,omitempty"`
 	ElapsedMS   int64  `json:"elapsed_ms,omitempty"`
+	// Timing is the request\'s split, on the completed event only.
+	Timing *reqtiming.Timing `json:"timing,omitempty"`
 }
 
 // HandleQueryStream serves POST /v1/query/stream as Server-Sent Events.
@@ -155,6 +159,10 @@ func (h *QueryStreamHandler) HandleQueryStream(w http.ResponseWriter, r *http.Re
 
 		case retrieval.EventCompleted:
 			sse.ElapsedMS = time.Since(started).Milliseconds()
+			if rec := reqtiming.From(r.Context()); rec != nil {
+				t := rec.Snapshot()
+				sse.Timing = &t
+			}
 
 		case retrieval.EventError:
 			if evt.Error != nil {

internal/handler/query_stream_multi.go

@@ -7,6 +7,8 @@ import (
 	"net/http"
 	"time"
 
+	"github.com/hallelx2/vectorless-engine/pkg/reqtiming"
+
 	"github.com/hallelx2/vectorless-engine/pkg/retrieval"
 	"github.com/hallelx2/vectorless-engine/pkg/storage"
 	"github.com/hallelx2/vectorless-engine/pkg/tree"
@@ -45,6 +47,8 @@ type multiDocSSEEvent struct {
 	Strategy    string `json:"strategy,omitempty"`
 	Query       string `json:"query,omitempty"`
 	ElapsedMS   int64  `json:"elapsed_ms,omitempty"`
+	// Timing is the request\'s split, on the completed event only.
+	Timing *reqtiming.Timing `json:"timing,omitempty"`
 }
 
 // HandleQueryStreamMulti serves POST /v1/query/multi/stream as SSE.
@@ -119,6 +123,10 @@ func (h *QueryStreamMultiHandler) HandleQueryStreamMulti(w http.ResponseWriter,
 
 		case retrieval.EventCompleted:
 			sse.ElapsedMS = time.Since(started).Milliseconds()
+			if rec := reqtiming.From(r.Context()); rec != nil {
+				t := rec.Snapshot()
+				sse.Timing = &t
+			}
 
 		case retrieval.EventError:
 			if evt.Error != nil {