docs(embeddings): correct comments that drifted from the code

A comment pass over the feature found four that no longer matched what they sat
on, all introduced by earlier rounds of this work.

The contract's `satisfies` note promised that adding a catalog provider could
not leave the wire enum stale. It cannot deliver that: `satisfies` proves every
listed member is valid, not that the list is exhaustive, so an addition stays
silently absent. Reworded to say what it does and does not catch.

The client cited Gemini as a provider that omits usage, which the Gemini adapter
now contradicts — it reads `usageMetadata.promptTokenCount`. Every adapter
defines `parseTokens`, so the fallback is about a response lacking a usage block,
not about a particular provider.

`l2Normalize` documented only Gemini, though Cohere now calls it for a different
and stronger reason, and "normalizes in place" read as mutation when the function
returns a copy.

The route's new size-guard comment claimed it avoids copying the payload; nothing
there copies. The real reason is that summing lengths gates before the per-entry
character scan.

Also: split the derived-sub-block TSDoc so both constants carry hover text, gave
the payload cap its own doc, dropped one comment that restated a signature, and
tightened two long blocks without losing a fact.

Author: waleedlatif1

apps/sim/app/api/tools/embeddings/route.ts

@@ -87,7 +87,10 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       { status: 400 }
     )
   }
-  /** Size is checked before the per-entry scan so an oversized body is rejected without copying it. */
+  /**
+   * Summing lengths is cheap and runs before the per-entry whitespace scan, so
+   * an oversized body is rejected without walking every character.
+   */
   const totalChars = texts.reduce((sum, text) => sum + text.length, 0)
   if (totalChars > MAX_EMBEDDING_TOTAL_CHARS) {
     return NextResponse.json(

apps/sim/blocks/blocks/embeddings.ts

@@ -39,10 +39,9 @@ const TASK_TYPE_LABELS: Record<EmbeddingTaskType, string> = {
 }
 
 /**
- * Model, task-type, and dimension dropdowns are derived from the catalog rather
- * than hand-copied, so adding a catalog model cannot leave this block stale.
- * Each dropdown is scoped by a `condition` naming the provider (and model, where
- * the capability is per-model) because every variant shares one sub-block id.
+ * Dropdowns are derived from the catalog rather than hand-copied, so adding a
+ * catalog model cannot leave this block stale. Every variant shares one
+ * sub-block id, so each is scoped by a `condition` naming the provider.
  */
 const MODEL_SUB_BLOCKS: SubBlockConfig[] = EMBEDDING_CATALOG_PROVIDERS.map((provider) => ({
   id: 'model',
@@ -54,6 +53,11 @@ const MODEL_SUB_BLOCKS: SubBlockConfig[] = EMBEDDING_CATALOG_PROVIDERS.map((prov
   dependsOn: ['provider'],
 }))
 
+/**
+ * Task-type and dimension dropdowns, which are per-model rather than
+ * per-provider: the `condition` names both, and a model contributes a dropdown
+ * only for the capabilities the catalog says it has.
+ */
 const CAPABILITY_SUB_BLOCKS: SubBlockConfig[] = Object.entries(EMBEDDING_MODELS).flatMap(
   ([model, info]) => {
     const scope = { field: 'provider', value: info.provider, and: { field: 'model', value: model } }

apps/sim/lib/api/contracts/tools/embeddings.ts

@@ -3,8 +3,10 @@ import { defineRouteContract } from '@/lib/api/contracts/types'
 import type { EmbeddingCatalogProvider, EmbeddingTaskType } from '@/lib/embeddings/types'
 
 /**
- * `satisfies` ties the wire enums to the catalog's own unions, so adding a
- * provider or task type there cannot silently leave the API contract stale.
+ * `satisfies` ties the wire enums to the catalog's own unions: renaming or
+ * removing a catalog member breaks the build here. It does NOT catch an
+ * addition — a new catalog provider or task type stays absent from the wire
+ * enum until it is added below.
  */
 export const embeddingProviders = [
   'openai',
@@ -23,6 +25,7 @@ export const embeddingTaskTypes = [
 
 /** Guards the route against unbounded fan-out into a paid provider. */
 export const MAX_EMBEDDING_INPUTS = 1000
+/** Caps total payload size independently of the input count. */
 export const MAX_EMBEDDING_TOTAL_CHARS = 1_000_000
 
 const MISSING_EMBEDDING_FIELDS_ERROR = 'Missing required fields: provider, apiKey, and input'

apps/sim/lib/embeddings/catalog.ts

@@ -207,12 +207,11 @@ export function getKbEligibleModels(): string[] {
  * True when a model's tokens cannot be counted exactly.
  *
  * Batching measures with tiktoken, which only has encodings for OpenAI models —
- * every other id falls back to `cl100k_base`, so a Gemini, Cohere, or Mistral
- * ceiling is enforced in approximate units. The ceiling is still applied
- * exactly as declared: discounting it to absorb the error would truncate valid
- * content silently, which is worse than the alternative it guards against. An
- * undercount surfaces as a provider rejection, which is visible and
- * actionable; silently shortening an embedding's input is not.
+ * every other id falls back to `cl100k_base`, so Gemini, Cohere, and Mistral
+ * ceilings are enforced in approximate units. The ceiling is still applied as
+ * declared rather than discounted to absorb the error: an undercount surfaces
+ * as a visible provider rejection, whereas silently shortening an embedding's
+ * input does not.
  */
 export function hasApproximateTokenCount(info: EmbeddingModelInfo): boolean {
   return info.tokenizerProvider !== 'openai'

apps/sim/lib/embeddings/client.ts

@@ -157,9 +157,13 @@ async function callEmbeddingAPI(
 
       const json = await response.json()
       const embeddings = request.parse(json)
+      /**
+       * Fallback for a response that carries no usage block. Estimated with the
+       * provider's own tokenizer, which is approximate for every non-OpenAI
+       * model — see {@link hasApproximateTokenCount}.
+       */
       const totalTokens =
         request.parseTokens?.(json) ??
-        // Providers that omit usage (e.g. Gemini) get an estimate from their tokenizer
         inputs.reduce(
           (sum, text) => sum + estimateTokenCount(text, provider.info.tokenizerProvider).count,
           0
@@ -232,10 +236,8 @@ export async function embed(texts: string[], options: EmbedOptions): Promise<Emb
    *
    * Three bounds compose here:
    *
-   * 1. {@link BATCH_TOKEN_TARGET} is what we actually aim for. It is an
-   *    operational choice, not a provider limit: it keeps a single request well
-   *    inside {@link EMBEDDING_REQUEST_TIMEOUT_MS}, so a timeout costs one small
-   *    batch and its retries rather than a large one.
+   * 1. {@link BATCH_TOKEN_TARGET} is what we actually aim for — an operational
+   *    choice, not a provider limit (see its declaration for the reasoning).
    * 2. A provider's documented summed-token cap, when it publishes one, is a
    *    hard ceiling the target can never exceed.
    * 3. The per-input ceiling is a floor. A budget below it would make

apps/sim/lib/embeddings/normalize.ts

@@ -1,9 +1,13 @@
 /**
- * L2-normalizes a vector in place of the provider doing it.
+ * Returns an L2-normalized copy of a vector, for providers that do not
+ * normalize a Matryoshka-reduced output themselves.
  *
- * Gemini does NOT auto-normalize embeddings when `outputDimensionality` is set
- * below the native 3072 dimension on `gemini-embedding-001`. Normalizing
- * manually keeps cosine and inner-product similarity correct.
+ * Gemini does NOT auto-normalize when `outputDimensionality` is set below the
+ * native 3072 dimension on `gemini-embedding-001`. Cohere never documents
+ * whether it renormalizes a truncated vector, so its reduced output is
+ * normalized here too — the operation is idempotent, so it is a no-op on
+ * already-unit vectors and a correctness fix otherwise. Both keep cosine and
+ * inner-product similarity correct.
  */
 export function l2Normalize(vector: number[]): number[] {
   let sumSquares = 0

apps/sim/lib/knowledge/embeddings.ts

@@ -82,9 +82,6 @@ export async function generateEmbeddings(
   }
 }
 
-/**
- * Generate embedding for a single search query.
- */
 export async function generateSearchEmbedding(
   query: string,
   embeddingModel: string = DEFAULT_EMBEDDING_MODEL,

apps/sim/tools/openai/embeddings.ts

@@ -6,7 +6,8 @@ import type { ToolConfig } from '@/tools/types'
  * Legacy tool id retained for the sunset `openai` Embeddings block and for
  * copilot/VFS callers that reference it by name. It is an alias of
  * `embeddings_openai` so both ids execute the exact same code path; the output
- * shape only gains fields (`provider`, `dimensions`) relative to the original.
+ * shape only gains fields (`provider`, `dimensions`, and the internal
+ * `__embeddingTokens`) relative to the original.
  */
 export const embeddingsTool: ToolConfig<EmbeddingsParams, EmbeddingsResponse> = {
   ...embeddingsOpenAITool,