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 real behavior proof before merge.

Summary
The PR adds local Ollama embedding provider selection and setup, propagates generated vectors into dev seed flows, updates docs/tests/changelog/env examples, and refreshes repo-local Convex agent guidance.

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

Real behavior proof
Needs real behavior proof before merge: Missing: the PR body/comments list test commands but no after-fix output from a real local Ollama/Convex setup; the contributor should add redacted terminal output, logs, screenshots, or a recording, then update the PR body to trigger re-review or ask a maintainer for @clawsweeper re-review.

Next step before merge
This external feature PR needs maintainer product approval, a rebase if mergeability is still false, and real behavior proof that automation cannot provide for the contributor.

Security
Cleared: No concrete security or supply-chain regression was found; the diff adds env-based provider selection and a user-invoked local setup script without new dependencies, workflow permissions, or secret exposure.

Review details

Best possible solution:

Land a rebased version only after maintainers accept the local Ollama default and the contributor adds redacted proof from a real local Ollama/Convex setup, keeping provider logic centralized with matching docs and tests.

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

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

Is this the best way to solve the issue?

Unclear until maintainer acceptance and proof: centralizing provider selection in convex/lib/embeddings.ts is a maintainable direction, but the automatic anonymous Convex default and local setup behavior should be approved and demonstrated before merge.

What I checked:

• Current main lacks Ollama provider support: On current main, generateEmbedding reads only OPENAI_API_KEY and returns a zero vector when it is absent; repository search found no Ollama, OLLAMA, EMBEDDING_PROVIDER, or setup:local-embeddings support on main. (convex/lib/embeddings.ts:67, 5b63d5df6071)
• PR adds provider selection and Ollama request path: PR head adds automatic provider selection, local anonymous Convex detection, Ollama endpoint normalization, /api/embed parsing, and dimension validation before returning embeddings. (convex/lib/embeddings.ts:81, 43d36ef53cfa)
• PR adds setup command: The setup script checks for the ollama CLI, 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:80, 43d36ef53cfa)
• PR wires seed embeddings: 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:557, 43d36ef53cfa)
• PR test coverage targets new behavior: 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, 43d36ef53cfa)
• Real behavior proof is missing: The PR body and follow-up comments list tests and changelog work, but do not include terminal output, logs, screenshots, recordings, or other after-fix proof from a real local Ollama/Convex setup.

Likely related people:

• steipete: Current git history shows Peter Steinberger authored the main commit containing convex/lib/embeddings.ts, dev seed code, and related publish paths this PR extends. (role: original and adjacent embedding/publish owner; confidence: high; commits: 768a50149eee; files: convex/lib/embeddings.ts, convex/devSeed.ts, convex/lib/skillPublish.ts)
• Momo: Recent current-main commits modified skill and soul publish paths that consume generated embeddings and surface embedding errors. (role: recent adjacent maintainer; confidence: medium; commits: 5b63d5df6071, 571a85f53902; files: convex/lib/skillPublish.ts, convex/lib/soulPublish.ts)
• superlowburn: Prior ClawSweeper review context cites superlowburn on the retry/error-handling implementation in the embedding helper that this PR generalizes to multiple providers. (role: embedding helper maintainer; confidence: medium; commits: a57769771f95; files: convex/lib/embeddings.ts, convex/lib/embeddings.test.ts)

Remaining risk / open question:

• No after-fix proof shows the local Ollama setup, Convex env configuration, seeding, or search/publish path working in a real setup.
• Maintainer product acceptance of automatically choosing Ollama for anonymous local Convex deployments is still pending.
• The provided GitHub context reports the PR as mergeable=false, so it may need a rebase before normal CI can gate it.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 5b63d5df6071.

[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

[steipete]

Is that a goal? What are you doing? Setting up a local ClawHub? I don't really wanna support that.