Streamline local Ollama embeddings

[fuller-stack-dev]

Summary

• add automatic Ollama embedding selection for local anonymous Convex deployments when OPENAI_API_KEY is absent
• add bun run setup:local-embeddings to pull/configure the default local embedding model
• generate real embeddings for local seed fixtures when an embedding provider is available
• document local embedding behavior, hosted Convex caveats, and reseeding requirements

Tests

• bunx vitest run convex/lib/embeddings.test.ts
• bunx tsc --noEmit
• bun run lint
• bun run test
• node scripts/setup-local-embeddings.mjs --help
• bun run format:check -- convex/lib/embeddings.ts convex/lib/embeddings.test.ts convex/devSeed.ts convex/devSeedExtra.ts convex/lib/skillPublish.ts convex/lib/soulPublish.ts scripts/setup-local-embeddings.mjs package.json README.md CONTRIBUTING.md docs/README.md docs/quickstart.md docs/troubleshooting.md docs/local-embeddings.md

Note: full bun run format:check was also attempted locally, but failed only on pre-existing unstaged .agents/... worktree files that are not included in this PR.

[vercel]

@fuller-stack-dev is attempting to deploy a commit to the Amantus Machina Team on Vercel.

A member of the Team first needs to authorize it.

[clawsweeper]

Codex review: needs maintainer review before merge.

Summary
The PR adds automatic local Ollama embedding selection, seed-time embedding generation, a setup script, local env defaults, tests, docs, and a changelog entry.

Reproducibility: not applicable. this is a feature PR, not a bug report. Source inspection confirms current main lacks the requested Ollama provider/setup/docs and PR head adds targeted tests for the new behavior.

Next step before merge
This is an open feature PR with no narrow automated repair finding; maintainers should decide whether the auto-Ollama local default should land and let checks gate merge.

Security
Cleared: No concrete security or supply-chain regression was found in the diff.

Review details

Best possible solution:

Land the PR after maintainer acceptance of the local Ollama default and normal CI, keeping provider selection centralized in the embedding helper with docs and seed behavior aligned.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR, not a bug report. Source inspection confirms current main lacks the requested Ollama provider/setup/docs and PR head adds targeted tests for the new behavior.

Is this the best way to solve the issue?

Yes, pending product acceptance: centralizing provider selection in convex/lib/embeddings.ts and passing generated vectors through seed actions is the narrow maintainable path. I did not find a safer implementation direction from this review.

Acceptance criteria:

• bunx vitest run convex/lib/embeddings.test.ts
• bunx tsc --noEmit
• bun run lint
• bun run test
• node scripts/setup-local-embeddings.mjs --help

What I checked:

• Current main lacks Ollama provider support: On current main, generateEmbedding reads OPENAI_API_KEY and returns zero vectors when it is absent; repository search found no Ollama, OLLAMA, EMBEDDING_PROVIDER, or setup:local-embeddings support on main. (convex/lib/embeddings.ts:67, 395862fadf63)
• PR adds provider selection and Ollama request path: PR head adds automatic provider selection, anonymous local Convex detection, Ollama endpoint normalization, /api/embed parsing, and dimension validation before returning embeddings. (convex/lib/embeddings.ts:81, 2da46c2fff5d)
• PR adds local setup command: The setup script checks for Ollama, pulls the configured model, and sets Convex env vars for EMBEDDING_PROVIDER, OLLAMA_EMBEDDING_MODEL, and OLLAMA_EMBEDDING_BASE_URL. (scripts/setup-local-embeddings.mjs:71, 2da46c2fff5d)
• PR wires seed embeddings through internal mutations: Seed actions generate embedding text, call generateEmbedding with zero-vector fallback, and pass the resulting vector into seed mutations instead of always inserting zero vectors. (convex/devSeed.ts:525, 2da46c2fff5d)
• PR covers the new behavior in tests: Added tests cover configured Ollama, auto-Ollama for anonymous local Convex deployments, hosted Convex non-selection, host normalization, and dimension mismatch rejection. (convex/lib/embeddings.test.ts:124, 2da46c2fff5d)
• Changelog feedback was addressed: The PR now includes an Unreleased Added entry for local Ollama embeddings and setup:local-embeddings, matching the author's follow-up comments about the amended changelog commit. (CHANGELOG.md:5, 2da46c2fff5d)

Likely related people:

• superlowburn: GitHub commit history for convex/lib/embeddings.ts shows Steve authored the retry/error-handling implementation that this PR extends into multi-provider requests. (role: embedding helper maintainer; confidence: high; commits: a57769771f95; files: convex/lib/embeddings.ts, convex/lib/embeddings.test.ts)
• steipete: Peter authored the bootstrap commit for the embedding helper area and co-authored adjacent OpenAI embedding retry work; skill and soul publish history also routes through this embedding path. (role: original and adjacent embedding/publish owner; confidence: medium; commits: 8df19780ea0a, a57769771f95; files: convex/lib/embeddings.ts, convex/lib/skillPublish.ts, convex/lib/soulPublish.ts)
• Patrick-Erichsen: Patrick introduced recent local rescan seed fixtures in convex/devSeed.ts, and this PR changes those fixture paths to store generated embeddings. (role: seed fixture owner; confidence: medium; commits: d3ed4434b958; files: convex/devSeed.ts)

Remaining risk / open question:

• Maintainer product acceptance of automatically choosing Ollama for anonymous local Convex deployments is still pending.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 395862fadf63.

[fuller-stack-dev]

Addressed the review feedback by adding the required CHANGELOG.md entry under Unreleased → Added.

New commit: caec0a9 (docs: add local embeddings changelog entry)

Verified:

bun run format:check -- CHANGELOG.md

[fuller-stack-dev]

Updated the changelog entry to match the existing attribution style:

(#2012) (thanks @fuller-stack-dev)

Amended commit: 2da46c2 (docs: add local embeddings changelog entry)

Verified:

bun run format:check -- CHANGELOG.md