feat(stores): add valkey-store vector store backend

[ajuijas]

Description

This PR fixes #10708

Adds valkey-store, a Go gRPC store backend that realizes option (2) of the vector-search design discussion (#1792) through the existing pluggable store-backend seam: it is selected by passing backend: "valkey-store" (alias "valkey") on the existing /stores/* requests — no proto and no HTTP API changes. Core plumbing already forwards the backend field (core/http/endpoints/localai/stores.go → backend.StoreBackend), so the only core change is the alias/constant in pkg/model/initializers.go.

What it does:

• Implements the four Stores RPCs (Set/Get/Delete/Find) against the Valkey Search module (FT.* on the valkey/valkey-bundle image), mirroring backend/go/local-store in structure and contract (same namespace-prefix Load gate against greedy autoload — checklist item from If you add opus as a backend via api, then add a model via the api that should use llama.cpp or vllm, it then tries to use opus #9287 — same upsert/omission/error semantics).
• Durability: vectors persist across restarts via Valkey RDB/AOF — the capability local-store fundamentally can't offer. A restarted backend process restores the index dimension from a meta hash and keeps serving the same namespace (covered by a test).
• Exact-search parity by default: FLAT index with COSINE distance; similarity is derived as 1 - distance. Opt-in HNSW via VALKEY_INDEX_ALGO=HNSW for approximate ANN on large corpora.
• Vector-as-key: hash key = localai:store:<namespace>: + hex of the little-endian float32 bytes; raw vector bytes in an indexed vec field, opaque payload in val. Upsert falls out of the encoding.
• Config via env: VALKEY_ADDR (default 127.0.0.1:6379), VALKEY_USERNAME, VALKEY_PASSWORD, VALKEY_INDEX_ALGO — documented in docs/content/features/stores.md.

Integration surface (mirrors local-store everywhere): backend dir, root Makefile (.NOTPARALLEL, backend definition, docker-build eval, TEST_PATHS), .github/backend-matrix.yml (linux amd64+arm64 CPU with shared tag-suffix, plus includeDarwin — pure Go, CGO_ENABLED=0, builds on macOS), backend/index.yaml (meta + cpu/metal × latest/development), docs (stores.md, backends.md, compatibility table, backend/README.md). No importer entry, matching local-store: store backends are not /import-model models. scripts/changed-backends.js needs no change (reuses the generic Dockerfile.golang suffix).

Notes for Reviewers

• Tests mirror the local-store suite at the same wire-shaped boundary, plus durability-across-restart and namespace-isolation specs. The suite needs a live Valkey with the Search module: it uses a valkey/valkey-bundle testcontainer (skipped on darwin, following the repo pattern in core/services/testutil/testdb.go), with a VALKEY_TEST_ADDR override to run against any live server.
• Verified locally on macOS against a real valkey/valkey-bundle:latest container: VALKEY_TEST_ADDR=127.0.0.1:16379 go test ./backend/go/valkey-store/ → 21/21 specs pass, in both default FLAT and VALKEY_INDEX_ALGO=HNSW modes. Without a server, 1 spec runs (the Load namespace gate) and 20 skip cleanly.
• One Valkey-Search-specific finding baked into the implementation: unlike RediSearch, Valkey Search rejects SORTBY on the KNN score alias (Index field does not exist), so results are re-ordered client-side by the returned distance.
• make lint (golangci-lint, new-from-merge-base) and the repo pre-commit coverage gate pass locally; go vet and gofmt clean. I did not run a full make build; the backend builds standalone with make -C backend/go/valkey-store build and the touched core packages (pkg/model, core/backend) compile.
• New dependency: github.com/valkey-io/valkey-go (pure Go, keeps CGO_ENABLED=0).

Signed commits

• Yes, I signed my commits.

Per .agents/ai-coding-assistants.md, this contribution was AI-assisted and the commit carries an Assisted-by: trailer instead of an AI sign-off; the policy reserves Signed-off-by for humans, so I've left it off rather than have the agent certify the DCO. Happy to add a human sign-off if required.

[richiejp]

I do wonder if also we could bundle valkey itself and start the server if the user doesn't have one already? I don't know what your usecase, but if you are just using your instance with LocalAI then it might be easier than maintaining a separate instance. However the main thing is the env vars and signing off on the commits.

I thought I had already reviewed this BTW, not sure what happened.

[localai-bot]

Thanks @ajuijas for this contribution, and apologies that you ended up in a PR collision. This is solid work: the store.NamespacePrefix gate on Load (the #9287 checklist item) with a test, and the valkey_username_env/valkey_password_env credential indirection following the cloud-proxy pattern are both genuinely good calls.

That said, #10770 by @daric93 (who also authored issue #10708 and its design) was opened a few days earlier, has gone through three review rounds with @richiejp, carries his approval, and has a full green CI run. It also threads the per-store model config through core/backend/stores.go, which is needed for model-config options to actually reach the backend: in this PR the valkey_addr/valkey_index_algo options are read from ModelOptions.Options, but the core StoreBackend path never populates that field, so they only take effect in the unit tests, and env vars remain the real config surface here.

Two smaller notes for completeness: the test suite starts a valkey/valkey-bundle:latest testcontainer inside the default TEST_PATHS unit-test path (this would run in the main tests job and the pre-commit gate; pinning the tag and gating it like the integration suites do would be safer), and richiejp's requested changes are still marked outstanding.

@mudler my recommendation is to merge #10770 (after its DCO fix and rebase) and close this one. @ajuijas, your namespace gate and the env-indirect credential options are improvements #10770 doesn't have yet. It would be great to see them as follow-up PRs on top of it, and I hope this doesn't discourage you from contributing again. For future reference, checking the linked issue for an existing PR (and commenting there) helps avoid duplicated effort.

[localai-bot]

Thanks again @ajuijas for the work here, and apologies once more for the PR collision on #10708. Having re-read both implementations side by side, this remains a competent, self-contained backend, and several of its ideas were genuinely first: the store.NamespacePrefix gate on Load with a test, the valkey_username_env/valkey_password_env credential indirection following the cloud-proxy pattern, and the small completeness touches (.gitignore, backend/README.md, the compatibility-table row) that #10770 still lacks.

That said, the recommendation to proceed with #10770 stands: it was opened first by the issue author, has been through three review rounds with @richiejp, and has since adopted the namespace gate and the env-indirect credentials. For transparency, here is what this PR would still need if it were to continue, beyond resolving the merge conflicts:

1. The model-config options do not reach the backend in production. valkey_addr, valkey_index_algo and the credential options are read from ModelOptions.Options in the backend, but core's StoreBackend() path never populates that field, so they only take effect in the unit tests; env vars remain the real config surface. Richie's changes-requested review asks for model-config-driven settings, and making that real requires threading the per-store model config through core/backend/stores.go (this is exactly what feat(stores): add Valkey Search vector store backend #10770 does).
2. The testcontainer suite runs inside the default unit-test path. TEST_PATHS includes ./backend/go/valkey-store/..., so the main tests job and the pre-commit gate pull and boot valkey/valkey-bundle:latest (unpinned). Pinning the tag and gating the suite like the repo's integration suites would make CI reproducible.
3. Smaller robustness items: StoresFind dereferences opts.Key.Floats without a nil guard (a malformed gRPC request panics the backend); the namespace from opts.Model is embedded raw in the key prefix and index name with no sanitization or collision handling; and commands after Load run on context.Background() with no deadline, so a stalled server hangs the RPC.

Rather than reworking all of that here, I would suggest closing this once #10770 lands and bringing the deltas as follow-up PRs on top of it, for example the compatibility-table/README/gitignore additions, or a bundled-Valkey mode as Richie floated in his review. Your contribution has already made the merged result better, and I hope the collision does not put you off contributing again.

[ajuijas]

Thanks for the review, @richiejp.

On the DCO note: sign-off is already present on all three commits here, so no action is needed on that front. That part of the comment may have been written before it synced with the latest push.

On bundling: I considered adding an opt-in mode that spawns a valkey-server subprocess when no external address is configured, but decided against implementing it here for two reasons. First, LocalAI's backend process model does not currently manage the lifecycle of an embedded, non-gRPC child server: startup ordering, health checks, log capture, and shutdown would all need new plumbing that no other backend needs today, since both local-store and cloud-proxy talk to something the operator already runs or an external API. Second, embedding a full Valkey server binary (with the Search module) inside the backend image is a much heavier and more failure-prone surface than the current design of a small Go client pointed at VALKEY_ADDR. Requiring an external instance keeps the backend itself thin and lets operators run Valkey however they already run their other infrastructure.

I also re-read localai-bot's two most recent comments about the collision with the other implementation for #10708, #10770. Given that PR was opened first by the issue author, has been through three review rounds with you, and has since adopted the namespace gate and env-indirect credential pattern that started here, I agree consolidating on #10770 is the right call rather than asking you to spend more time reconciling two competing backends for the same feature.

I've rebased this branch on current master, so it is conflict-free again. I'll leave the call on whether to keep this open or close it in favor of #10770 to you and the maintainers.

[ajuijas]

Agreed, consolidating on #10770 is the right call here since it was opened first, has been through three review rounds, and has already adopted the namespace-gate and env-indirect credential ideas from this PR. Closing in its favor. Thanks for the thorough review.