feat(valkey-store): make connection settings configurable per model

Address review feedback on PR #10801: VALKEY_ADDR, VALKEY_USERNAME,
VALKEY_PASSWORD, and VALKEY_INDEX_ALGO were process-wide env vars only,
so every model sharing this backend had to use the same Valkey server
and credentials.

Add matching model-config options (valkey_addr, valkey_index_algo,
valkey_username_env, valkey_password_env) that take priority over the
env vars when set. The credential options name an env var to read from
rather than taking the value directly, mirroring cloud-proxy's
api_key_env/api_key_file pattern, so multiple valkey-store model
configs can each point at a different server/credential pair without
putting secrets in the YAML.

Existing env-var-only configs keep working unchanged (the options are
purely additive fallthrough). Added unit tests for the new resolution
helpers and a live-server test proving the model option wins over the
env var end-to-end; all 27 specs pass (golangci-lint, go vet, gofmt
clean).

Assisted-by: Claude Code:claude-sonnet-5 golangci-lint go test

Author: ajuijas

backend/go/valkey-store/store.go

@@ -22,8 +22,15 @@ package main
 // Search parity: the index defaults to FLAT with COSINE distance, so
 // Find is an exact scan whose ranking matches local-store; Valkey
 // returns cosine *distance* and similarity is derived as
-// `1 - distance`. Set VALKEY_INDEX_ALGO=HNSW for approximate ANN on
-// large corpora.
+// `1 - distance`. Set VALKEY_INDEX_ALGO=HNSW (or the valkey_index_algo
+// model option) for approximate ANN on large corpora.
+//
+// Connection settings resolve per-model first, then fall back to the
+// process-wide env vars: `valkey_addr` / VALKEY_ADDR, `valkey_index_algo`
+// / VALKEY_INDEX_ALGO, and — mirroring cloud-proxy's api_key_env —
+// `valkey_username_env` / `valkey_password_env` name the env vars that
+// actually hold the credential, so distinct model configs can each
+// point at a different Valkey server with its own credentials.
 //
 // Concurrency: base.SingleThread serialises gRPC calls, matching
 // local-store; Valkey itself is the durable shared state.
@@ -71,12 +78,43 @@ type Store struct {
 	// index, so dimension mismatches fail loudly instead of
 	// producing bogus cosine matches.
 	keyLen int
+
+	// indexAlgo is resolved once at Load (model option, else env var,
+	// else FLAT) and reused by createIndex, which runs later from
+	// StoresSet and has no access to the ModelOptions that carried it.
+	indexAlgo string
 }
 
 func NewStore() *Store {
 	return &Store{keyLen: -1}
 }
 
+// optString reads a model option (key:value form) from ModelOptions,
+// returning def when absent. Mirrors optInt in sibling backends
+// (e.g. moss-transcribe-cpp) for the model YAML's `options:` list.
+func optString(opts *pb.ModelOptions, key, def string) string {
+	for _, o := range opts.GetOptions() {
+		k, v, ok := strings.Cut(o, ":")
+		if ok && strings.TrimSpace(k) == key {
+			return strings.TrimSpace(v)
+		}
+	}
+	return def
+}
+
+// optEnvIndirect resolves a credential the way cloud-proxy's
+// api_key_env does: the model option names an env var to read from,
+// so distinct model configs can each reference a different credential
+// pair without putting secrets in the YAML. Falls back to a single
+// process-wide env var when the model doesn't set the option, keeping
+// the single-Valkey-server default working unchanged.
+func optEnvIndirect(opts *pb.ModelOptions, optKey, fallbackEnvVar string) string {
+	if envVar := optString(opts, optKey, ""); envVar != "" {
+		return os.Getenv(envVar)
+	}
+	return os.Getenv(fallbackEnvVar)
+}
+
 // Load validates the namespace, connects to Valkey and, when the
 // namespace was already populated by a previous process, restores the
 // index dimension from the meta hash. The namespace-prefix gate keeps
@@ -93,14 +131,15 @@ func (s *Store) Load(opts *pb.ModelOptions) error {
 	s.prefix = keyspacePrefix + ns + ":"
 	s.index = s.prefix + "idx"
 
-	addr := os.Getenv("VALKEY_ADDR")
+	addr := optString(opts, "valkey_addr", os.Getenv("VALKEY_ADDR"))
 	if addr == "" {
 		addr = "127.0.0.1:6379"
 	}
+	s.indexAlgo = optString(opts, "valkey_index_algo", os.Getenv("VALKEY_INDEX_ALGO"))
 	client, err := valkey.NewClient(valkey.ClientOption{
 		InitAddress: []string{addr},
-		Username:    os.Getenv("VALKEY_USERNAME"),
-		Password:    os.Getenv("VALKEY_PASSWORD"),
+		Username:    optEnvIndirect(opts, "valkey_username_env", "VALKEY_USERNAME"),
+		Password:    optEnvIndirect(opts, "valkey_password_env", "VALKEY_PASSWORD"),
 		// The store contract is request/response; the client-side
 		// cache would only add invalidation traffic.
 		DisableCache: true,
@@ -170,12 +209,12 @@ func (s *Store) createIndex(dim int) error {
 	if dim == 0 {
 		return fmt.Errorf("valkey-store: Set: cannot index zero-length vectors")
 	}
-	algo := strings.ToUpper(os.Getenv("VALKEY_INDEX_ALGO"))
+	algo := strings.ToUpper(s.indexAlgo)
 	if algo == "" {
 		algo = "FLAT"
 	}
 	if algo != "FLAT" && algo != "HNSW" {
-		return fmt.Errorf("valkey-store: VALKEY_INDEX_ALGO %q not supported (FLAT or HNSW)", algo)
+		return fmt.Errorf("valkey-store: valkey_index_algo/VALKEY_INDEX_ALGO %q not supported (FLAT or HNSW)", algo)
 	}
 
 	ctx := context.Background()

backend/go/valkey-store/store_test.go

@@ -37,6 +37,41 @@ var _ = Describe("StoresLoad namespace gate", func() {
 	})
 })
 
+var _ = Describe("model-config option resolution", func() {
+	It("optString prefers the model option over the default", func() {
+		opts := &pb.ModelOptions{Options: []string{"valkey_addr:10.0.0.1:6379"}}
+		Expect(optString(opts, "valkey_addr", "127.0.0.1:6379")).To(Equal("10.0.0.1:6379"))
+	})
+
+	It("optString falls back to the default when the option is absent", func() {
+		Expect(optString(&pb.ModelOptions{}, "valkey_addr", "127.0.0.1:6379")).To(Equal("127.0.0.1:6379"))
+	})
+
+	It("optEnvIndirect reads the env var named by the model option", func() {
+		Expect(os.Setenv("VALKEY_STORE_TEST_CRED_A", "creds-a")).To(Succeed())
+		defer func() { _ = os.Unsetenv("VALKEY_STORE_TEST_CRED_A") }()
+		opts := &pb.ModelOptions{Options: []string{"valkey_password_env:VALKEY_STORE_TEST_CRED_A"}}
+		Expect(optEnvIndirect(opts, "valkey_password_env", "VALKEY_PASSWORD")).To(Equal("creds-a"))
+	})
+
+	It("optEnvIndirect falls back to the process-wide env var when unset", func() {
+		Expect(os.Setenv("VALKEY_PASSWORD", "fallback-cred")).To(Succeed())
+		defer func() { _ = os.Unsetenv("VALKEY_PASSWORD") }()
+		Expect(optEnvIndirect(&pb.ModelOptions{}, "valkey_password_env", "VALKEY_PASSWORD")).To(Equal("fallback-cred"))
+	})
+
+	It("lets two models pick different credential env vars against the same server", func() {
+		Expect(os.Setenv("VALKEY_STORE_TEST_CRED_A", "creds-a")).To(Succeed())
+		Expect(os.Setenv("VALKEY_STORE_TEST_CRED_B", "creds-b")).To(Succeed())
+		defer func() { _ = os.Unsetenv("VALKEY_STORE_TEST_CRED_A") }()
+		defer func() { _ = os.Unsetenv("VALKEY_STORE_TEST_CRED_B") }()
+		a := &pb.ModelOptions{Options: []string{"valkey_username_env:VALKEY_STORE_TEST_CRED_A"}}
+		b := &pb.ModelOptions{Options: []string{"valkey_username_env:VALKEY_STORE_TEST_CRED_B"}}
+		Expect(optEnvIndirect(a, "valkey_username_env", "VALKEY_USERNAME")).To(Equal("creds-a"))
+		Expect(optEnvIndirect(b, "valkey_username_env", "VALKEY_USERNAME")).To(Equal("creds-b"))
+	})
+})
+
 var _ = Describe("valkey-store against a live server", Ordered, func() {
 	var nsCounter int
 
@@ -99,6 +134,26 @@ var _ = Describe("valkey-store against a live server", Ordered, func() {
 			Expect(s.Load(&pb.ModelOptions{Model: store.NamespacePrefix})).To(Succeed())
 			DeferCleanup(func() { dropNamespace(s) })
 		})
+
+		It("takes the index algorithm from the model option over VALKEY_INDEX_ALGO", func() {
+			Expect(os.Setenv("VALKEY_INDEX_ALGO", "HNSW")).To(Succeed())
+			defer func() { _ = os.Unsetenv("VALKEY_INDEX_ALGO") }()
+
+			nsCounter++
+			ns := fmt.Sprintf("test-%d-%d", GinkgoRandomSeed(), nsCounter)
+			s := NewStore()
+			Expect(s.Load(&pb.ModelOptions{
+				Model:   store.NamespacePrefix + ns,
+				Options: []string{"valkey_index_algo:FLAT"},
+			})).To(Succeed())
+			DeferCleanup(func() { dropNamespace(s) })
+			Expect(s.indexAlgo).To(Equal("FLAT"), "model option should win over the env var")
+
+			mustSet(s, [][]float32{{1, 0, 0}}, [][]byte{[]byte("x")})
+			info, err := s.client.Do(context.Background(), s.client.B().Arbitrary("FT.INFO").Args(s.index).Build()).ToAny()
+			Expect(err).NotTo(HaveOccurred())
+			Expect(fmt.Sprintf("%v", info)).To(ContainSubstring("FLAT"), "index should have been created with the option's algorithm, not the env var's")
+		})
 	})
 
 	Describe("StoresSet", func() {

docs/content/features/stores.md

@@ -51,14 +51,30 @@ All endpoints also accept an optional `backend` field selecting which store back
 request. The default is `local-store`, an in-memory exact-search store. Alternatively,
 `valkey-store` (alias `valkey`) stores the vectors in a Valkey server running the
 [Valkey Search](https://valkey.io/topics/search/) module (the `valkey/valkey-bundle` image), which
-makes them durable across restarts. `valkey-store` is configured through environment variables:
-
-| Variable | Default | Description |
-|---|---|---|
-| `VALKEY_ADDR` | `127.0.0.1:6379` | Valkey server address |
-| `VALKEY_USERNAME` | | Username, if the server requires AUTH |
-| `VALKEY_PASSWORD` | | Password, if the server requires AUTH |
-| `VALKEY_INDEX_ALGO` | `FLAT` | Vector index algorithm: `FLAT` (exact, matches `local-store` results) or `HNSW` (approximate, for large corpora) |
+makes them durable across restarts. `valkey-store` is configured through environment variables,
+or per-model via the model config's `options:` list, which takes priority over the env var:
+
+| Variable | Model option | Default | Description |
+|---|---|---|---|
+| `VALKEY_ADDR` | `valkey_addr` | `127.0.0.1:6379` | Valkey server address |
+| `VALKEY_USERNAME` | `valkey_username_env` | | Username, if the server requires AUTH |
+| `VALKEY_PASSWORD` | `valkey_password_env` | | Password, if the server requires AUTH |
+| `VALKEY_INDEX_ALGO` | `valkey_index_algo` | `FLAT` | Vector index algorithm: `FLAT` (exact, matches `local-store` results) or `HNSW` (approximate, for large corpora) |
+
+The username/password options name an environment variable to read the credential from, rather
+than taking the credential directly, so each model config can point at its own Valkey server with
+its own credentials without putting secrets in the YAML (the same pattern `cloud-proxy`'s
+`api_key_env` uses):
+
+```yaml
+name: my-valkey-store
+backend: valkey-store
+options:
+  - "valkey_addr:valkey.internal:6379"
+  - "valkey_username_env:MY_VALKEY_USERNAME"
+  - "valkey_password_env:MY_VALKEY_PASSWORD"
+  - "valkey_index_algo:HNSW"
+```
 
 ## Set