docs(env): document the embeddings endpoint for Find related + semantic search (LC-687) #653

Merged

longjacksonle merged 1 commit from feat/LC-687-embeddings-config into main 2026-08-09 05:13:00 +02:00

Conversation 0 Commits 1 Files changed 2 +24

longjacksonle commented 2026-08-09 04:58:10 +02:00

Owner

Copy link

Root cause

Find related errored with a toast and no panel because the deployment had no embeddings endpoint configured. Embeddings are a separate service from the chat LLM: EmbeddingsConfig::from_env needs LETS_CHAT_EMBEDDINGS_URL (independent of LETS_CHAT_LLM_URL). The dev deployment set only the LLM, so embedding_client was None and GET /messages/{id}/related returned 400 "related search is not configured". Pre-LC-686 the menu item showed anyway (the CSS gate bug), so it was clickable → error toast. The assistant /ask RAG does not use embeddings, so it working was a red herring.

This PR

The visible symptom is already fixed by LC-686 (hides the Find related item when [data-lc-embeddings] is absent). What was missing was any documentation of how to actually enable embeddings - the example env files documented the LLM but never the embeddings endpoint.

Adds a commented embeddings block to .env.standalone and .env.saas next to the LLM block: point LETS_CHAT_EMBEDDINGS_URL at an OpenAI-compatible /v1/embeddings endpoint, pull an embedding model (ollama pull nomic-embed-text), set LETS_CHAT_EMBEDDINGS_MODEL. Notes the default-off behavior and the LC-679 flag/role gate.

The dev deployment's own compose (internal/compose.dev-web.yml, gitignored) is updated separately to actually enable this for the dev instance.

To make Find related work on the dev box

1. ollama pull nomic-embed-text on the Ollama host.
2. Restart the dev-web stack (the compose now sets LETS_CHAT_EMBEDDINGS_URL + _MODEL).
3. Backfill indexes history at 50 msgs/min; new messages embed on send.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PBAyCesyqJkZ5JgixXf9Lf

## Root cause Find related errored with a toast and no panel because the deployment had **no embeddings endpoint** configured. Embeddings are a **separate service** from the chat LLM: `EmbeddingsConfig::from_env` needs `LETS_CHAT_EMBEDDINGS_URL` (independent of `LETS_CHAT_LLM_URL`). The dev deployment set only the LLM, so `embedding_client` was `None` and `GET /messages/{id}/related` returned 400 "related search is not configured". Pre-LC-686 the menu item showed anyway (the CSS gate bug), so it was clickable → error toast. The assistant `/ask` RAG does **not** use embeddings, so it working was a red herring. ## This PR The visible symptom is already fixed by **LC-686** (hides the Find related item when `[data-lc-embeddings]` is absent). What was missing was any documentation of how to actually enable embeddings - the example env files documented the LLM but never the embeddings endpoint. Adds a commented embeddings block to `.env.standalone` and `.env.saas` next to the LLM block: point `LETS_CHAT_EMBEDDINGS_URL` at an OpenAI-compatible `/v1/embeddings` endpoint, pull an embedding model (`ollama pull nomic-embed-text`), set `LETS_CHAT_EMBEDDINGS_MODEL`. Notes the default-off behavior and the LC-679 flag/role gate. The dev deployment's own compose (`internal/compose.dev-web.yml`, gitignored) is updated separately to actually enable this for the dev instance. ## To make Find related work on the dev box 1. `ollama pull nomic-embed-text` on the Ollama host. 2. Restart the dev-web stack (the compose now sets `LETS_CHAT_EMBEDDINGS_URL` + `_MODEL`). 3. Backfill indexes history at 50 msgs/min; new messages embed on send. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01PBAyCesyqJkZ5JgixXf9Lf

longjacksonle added 1 commit 2026-08-09 04:58:10 +02:00

docs(env): document the separate embeddings endpoint that powers Find related + semantic search (LC-687) ... 095fa88250

Find related errored with "related search is not configured" because the deployment set only the chat LLM (LETS_CHAT_LLM_URL) and no embeddings endpoint - and embeddings are a SEPARATE service (LETS_CHAT_EMBEDDINGS_URL), which the example env files never documented. The visible symptom (a clickable Find related button that 403/400s) is fixed by LC-686 hiding the item when embeddings are unconfigured; this documents how to actually turn the feature ON.

Adds a commented embeddings block to .env.standalone and .env.saas next to the LLM block: point LETS_CHAT_EMBEDDINGS_URL at an OpenAI-compatible /v1/embeddings endpoint, pull an embedding model (e.g. `ollama pull nomic-embed-text`), and set LETS_CHAT_EMBEDDINGS_MODEL to it. Notes that it is unset by default (Find related hidden, semantic search degrades to FTS) and still gated behind the runtime AI flag + role like the rest of the AI surface (LC-679).

The dev deployment compose (gitignored) is updated separately to enable this for the dev instance.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PBAyCesyqJkZ5JgixXf9Lf

longjacksonle merged commit 9f70b8c6bf into main 2026-08-09 05:13:00 +02:00

longjacksonle deleted branch feat/LC-687-embeddings-config 2026-08-09 05:13:00 +02:00

longjacksonle referenced this pull request from a commit 2026-08-09 05:13:01 +02:00

Merge pull request 'docs(env): document the embeddings endpoint for Find related + semantic search (LC-687)' (#653) from feat/LC-687-embeddings-config into main

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

psa-systems/lets-chat!653

No description provided.