mohdel 1.1.0 → 1.3.0

package/README.md

@@ -422,6 +422,7 @@ OPENROUTER_API_SK=sk-or-...
 NOVITA_API_SK=...
 QWEN_API_SK=sk-...
 XIAOMI_API_SK=...
+COHERE_API_SK=...
 MOHDEL_LOCAL_API_SK=...
 ```
 
@@ -462,6 +463,7 @@ What each provider supports through mohdel's unified interface:
 | Xiaomi | Yes | Yes | Yes | No | Auto | MiMo; shared chat-completions path, `reasoning_content` captured |
 | OpenRouter | Yes | Yes | Yes | No | Varies | Meta-provider; `providerOptions.openrouter` for routing prefs |
 | Local | Yes | Yes | Yes | No | No | Any OpenAI-compatible server; endpoint is the catalog entry's `baseURL` |
+| Cohere | n/a | n/a | n/a | n/a | n/a | Embeddings only: no chat models reach mohdel through it |
 | Novita | Yes | Yes | Yes | No | Yes (`reasoning_content`) | Prices in the model list; text via the shared chat-completions path, separate image adapter |
 
 Adapter capability ≠ model capability — whether a given model accepts images, tools, or thinking effort depends on the model spec in `curated.json`. The adapter passes through what the envelope supplies; the provider rejects unsupported combos.

package/config/curated.schema.json

@@ -517,15 +517,53 @@
           "minimum": 0,
           "description": "USD per audio minute (transcription-type entries). Token-billed transcription models (OpenAI gpt-4o-*-transcribe) use inputPrice/outputPrice instead."
         },
+        "embeddingPrice": {
+          "type": "number",
+          "minimum": 0,
+          "description": "USD per 1,000,000 input tokens for an embedding model. Without it, cost is 0 on every embed call."
+        },
+        "dimensions": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Native width of the vectors this model returns."
+        },
+        "dimensionsSelectable": {
+          "type": "boolean",
+          "description": "Whether the model accepts a requested output width. Providers spell the parameter differently (dimensions, output_dimension, outputDimensionality) and support it on some models only; when false, passing `dimensions` fails before dispatch instead of being ignored."
+        },
+        "maxBatch": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Inputs accepted in one embed call. 2048 on OpenAI, 96 on Cohere, 10 on Qwen Cloud, 1 for Gemini's single-content endpoint. A larger batch fails before dispatch; mohdel does not split one, because splitting changes cost attribution and result ordering."
+        },
+        "maxInputTokens": {
+          "type": "number",
+          "minimum": 1,
+          "description": "Token ceiling for a single input, not for the request."
+        },
+        "inputTypes": {
+          "type": "object",
+          "additionalProperties": { "type": "string" },
+          "description": "Maps mohdel's symbolic roles (query, document, classification, clustering) to the provider's own vocabulary, e.g. {\"query\": \"RETRIEVAL_QUERY\"} for Gemini or {\"query\": \"search_query\"} for Cohere. An entry without it rejects `inputType` rather than dropping it: the role is baked into the vector, so a silent drop produces quietly worse retrieval."
+        },
+        "defaultInputType": {
+          "type": "string",
+          "description": "Symbolic role sent when the caller names none. Required for providers that make the parameter mandatory (Cohere v3+)."
+        },
         "rpmLimit": {
           "type": "integer",
           "minimum": 1,
-          "description": "Requests per minute. Overrides provider default."
+          "description": "Requests per minute this key may send. Overrides the provider-level default."
         },
         "tpmLimit": {
           "type": "integer",
           "minimum": 1,
-          "description": "Tokens per minute. Overrides provider default."
+          "description": "Tokens per minute this key may spend. Overrides the provider-level default."
+        },
+        "inpmLimit": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Inputs per minute this key may send to an embedding endpoint, for a provider that meters the endpoint in inputs rather than requests or tokens (Cohere publishes '2,000 inputs / min'). Counted exactly before dispatch from the batch size; a batch larger than the whole allowance is sent rather than delayed, since waiting cannot make it fit."
         },
         "rateLimitScope": {
           "type": "string",
@@ -533,7 +571,7 @@
             "model",
             "provider"
           ],
-          "description": "'model' = private budget. 'provider' = shared with provider-level pool."
+          "description": "Whose budget this key's calls draw on: 'model' = a private bucket for this entry, 'provider' = the pool shared with every other model of the provider."
         },
         "deprecated": {
           "type": "string",

package/js/client/call_embedding.js

@@ -0,0 +1,50 @@
+/**
+ * Send an EmbedEnvelope to thin-gate's `POST /v1/embed`.
+ *
+ * One-shot: a single JSON response body, no streaming, no cooldown or
+ * rate-limit. One call carries N inputs and returns N vectors in request
+ * order; the gate never splits a batch, so a batch larger than the model's
+ * `maxBatch` comes back as an error rather than as several calls.
+ *
+ * @module client/call_embedding
+ */
+
+import { requestUnix } from './transport.js'
+import { readAll, parseErrorBody } from './response.js'
+import { MohdelError } from '#core'
+
+/**
+ * @param {import('#core/embedding.js').EmbedEnvelope} envelope
+ * @param {object} options
+ * @param {string} options.socketPath
+ * @param {AbortSignal} [options.signal]
+ * @param {string} [options.path]  HTTP path; defaults to '/v1/embed'
+ * @returns {Promise<import('#core/embedding.js').EmbedResult>}
+ */
+export async function callEmbedding (envelope, { socketPath, signal, path = '/v1/embed' }) {
+  const res = await requestUnix({
+    socketPath,
+    path,
+    method: 'POST',
+    body: envelope,
+    signal
+  })
+
+  const body = await readAll(res)
+
+  if (res.statusCode !== 200) {
+    throw MohdelError.fromJSON(parseErrorBody(body, res.statusCode ?? 0))
+  }
+
+  let parsed
+  try {
+    parsed = JSON.parse(body)
+  } catch (e) {
+    throw new MohdelError(`gate returned an unparseable embed body: ${body.slice(0, 200)}`, {
+      type: 'PROTOCOL_INVALID_RESPONSE',
+      severity: 'error',
+      retryable: false
+    })
+  }
+  return parsed
+}

package/js/client/index.js

@@ -16,4 +16,5 @@
 export { call } from './call.js'
 export { callImage } from './call_image.js'
 export { callTranscription } from './call_transcription.js'
+export { callEmbedding } from './call_embedding.js'
 export { resolveGateBinary } from './gate-binary.js'

package/js/core/embedding.js

@@ -0,0 +1,76 @@
+/**
+ * Embedding envelope and result.
+ *
+ * Separate call path from `CallEnvelope` / `AnswerResult`: embeddings are a
+ * single synchronous request/response, nothing is generated, and one call
+ * carries N inputs and returns N vectors in request order.
+ * Result shape: `{ status, vectors, dimensions, inputTokens, cost, timestamps }`.
+ *
+ * @module core/embedding
+ */
+
+/**
+ * @typedef {object} EmbedEnvelope
+ *
+ * @property {string} callId
+ * @property {string} authId
+ * @property {import('./envelope.js').Auth} auth
+ * @property {string} [traceparent]
+ * @property {string} [baggage]
+ *
+ * @property {string} model
+ *   Full mohdel id — `"<provider>/<bare>"`. Same shape as
+ *   `CallEnvelope.model` (see `envelope.js`).
+ * @property {string[]} input
+ *   Texts to embed. Always an array, even for one. A batch larger than the
+ *   entry's `maxBatch` fails before dispatch rather than being split:
+ *   splitting would change both cost attribution and result ordering.
+ *
+ * @property {number} [dimensions]
+ *   Requested output width. Providers spell this three ways
+ *   (`dimensions`, `output_dimension`, `outputDimensionality`) and support it
+ *   on some models only; an entry without `dimensionsSelectable` rejects the
+ *   field rather than sending it to be ignored.
+ * @property {string} [inputType]
+ *   Symbolic role of the text: `query`, `document`, `classification`,
+ *   `clustering`. Asymmetric models embed the same string differently
+ *   depending on it, so a query and its matching passage land close together.
+ *   The entry's `inputTypes` maps it to the provider's own vocabulary.
+ */
+
+/**
+ * @typedef {object} EmbedResult
+ *
+ * @property {'completed'} status
+ *   Embeddings are one-shot — no `incomplete` state.
+ * @property {number[][]} vectors
+ *   One per input, in request order.
+ * @property {number} dimensions
+ *   Width of the returned vectors, which is what the provider actually
+ *   produced rather than what was asked for.
+ * @property {string | null} inputType
+ *   The provider-native value that was sent, or null when none was. The role
+ *   is baked into the vector, so a caller storing these must record it and
+ *   query the same namespace the same way.
+ * @property {number} inputTokens
+ * @property {number} cost
+ *   USD. `embeddingPrice` (per million input tokens) × `inputTokens`; 0 when
+ *   the spec carries no price.
+ * @property {{start: string, first: string, end: string}} timestamps
+ *   hrtime-bigint-as-string. `first` = `end` (no streaming).
+ */
+
+export const EMBED_ENVELOPE_FIELDS = Object.freeze([
+  'callId',
+  'authId',
+  'auth',
+  'traceparent',
+  'baggage',
+  'model',
+  'input',
+  'dimensions',
+  'inputType'
+])
+
+/** Symbolic roles a caller may pass; the entry maps them to provider values. */
+export const INPUT_TYPES = Object.freeze(['query', 'document', 'classification', 'clustering'])

package/js/factory/bridge.js

@@ -23,6 +23,7 @@
 import { run } from '../session/run.js'
 import { runImage } from '../session/run_image.js'
 import { runTranscription } from '../session/run_transcription.js'
+import { runEmbedding } from '../session/run_embedding.js'
 import { markTrustedMedia } from '../session/adapters/_media.js'
 import { MohdelError, validateIds } from '#core'
 import { createRealtimeDeltaBuffer } from '../../src/lib/utils.js'
@@ -180,6 +181,49 @@ export async function runAnswerTranscription ({ provider, model, configuration,
   return out.result
 }
 
+/**
+ * Run an `embed()` call through the /session runtime.
+ *
+ * @param {object} args
+ * @param {string} args.provider
+ * @param {string} args.model
+ * @param {string} [args.modelKey]         Mohdel catalog key, for the rate-limit
+ *                                         bucket when the entry is model-scoped.
+ * @param {any} args.configuration
+ * @param {string | string[]} args.input   One text or a batch; normalized to an
+ *                                         array so the result shape never
+ *                                         depends on how the caller asked.
+ * @param {any} [args.options]             `inputType` / `dimensions` map onto
+ *                                         the envelope; `callId` / `authId` are
+ *                                         transport metadata.
+ * @param {any} [args.spec]
+ * @param {BridgeDeps} [deps]
+ * @returns {Promise<any>}
+ */
+export async function runAnswerEmbedding ({ provider, model, modelKey, configuration, input, options = {}, spec }, deps = {}) {
+  const callId = options.callId || newCallId()
+  const authId = options.authId || 'local'
+  assertValidIds(callId, authId, `${provider}/${model}`)
+
+  const envelope = {
+    callId,
+    authId,
+    auth: configToAuth(configuration),
+    model: `${provider}/${model}`,
+    input: Array.isArray(input) ? input : [input]
+  }
+  if (options.inputType) envelope.inputType = options.inputType
+  if (options.dimensions !== undefined) envelope.dimensions = options.dimensions
+
+  const out = await runEmbedding(envelope, {
+    ...deps,
+    ...(modelKey ? { modelKey } : {}),
+    ...(spec ? { spec } : {})
+  })
+  if (!out.ok) throw MohdelError.fromJSON(out.error, { provider, model })
+  return out.result
+}
+
 /**
  * @param {object} args
  * @param {string} args.modelKey      Mohdel catalog key `<provider>/<bare>`. The

package/js/session/_rate_limiter.js

@@ -1,7 +1,9 @@
 /**
  * Minute-bucket rate limiter (per-key: provider or provider/model).
  *
- * Tracks RPM and TPM. Returns ms to wait if over limit — throttles
+ * Tracks RPM, TPM and INPM — inputs per minute, the unit an embedding
+ * endpoint is metered in when the provider counts inputs rather than
+ * requests or tokens. Returns ms to wait if over limit — throttles
  * rather than rejecting, so the caller can absorb small bursts
  * without a 429 round-trip.
  *
@@ -14,7 +16,7 @@
  */
 
 export function createRateLimiter () {
-  /** @type {Map<string, {count: number, tokens: number, minute: number}>} */
+  /** @type {Map<string, {count: number, tokens: number, inputs: number, minute: number}>} */
   const buckets = new Map()
 
   const currentMinute = () => Math.floor(Date.now() / 60000)
@@ -24,7 +26,7 @@ export function createRateLimiter () {
     const minute = currentMinute()
     const b = buckets.get(key)
     if (b && b.minute === minute) return b
-    const fresh = { count: 0, tokens: 0, minute }
+    const fresh = { count: 0, tokens: 0, inputs: 0, minute }
     buckets.set(key, fresh)
     return fresh
   }
@@ -42,15 +44,30 @@ export function createRateLimiter () {
    *     returned regardless of the current bucket.
    *   - positive number → throttle at that value.
    *
+   * `rpmLimit` and `tpmLimit` gate on what the bucket already holds:
+   * the size of the call ahead is not known until it returns.
+   * `inpmLimit` gates on what the call is about to add, which
+   * `pending.inputs` carries — a batch size is exact before dispatch,
+   * so the call is admitted only if the whole batch fits.
+   *
    * @param {string} key
-   * @param {{rpmLimit?: number, tpmLimit?: number}} limits
+   * @param {{rpmLimit?: number, tpmLimit?: number, inpmLimit?: number}} limits
+   * @param {{inputs?: number}} [pending]
    * @returns {number}
    */
-  const check = (key, { rpmLimit, tpmLimit } = {}) => {
-    if (rpmLimit == null && tpmLimit == null) return 0
+  const check = (key, { rpmLimit, tpmLimit, inpmLimit } = {}, pending = {}) => {
+    if (rpmLimit == null && tpmLimit == null && inpmLimit == null) return 0
     const b = getBucket(key)
     if (rpmLimit != null && b.count >= rpmLimit) return msUntilNextMinute(b.minute)
     if (tpmLimit != null && b.tokens >= tpmLimit) return msUntilNextMinute(b.minute)
+    if (inpmLimit != null) {
+      const adding = pending.inputs ?? 0
+      if (inpmLimit === 0) return msUntilNextMinute(b.minute)
+      // A batch larger than the whole allowance never fits, so waiting out the
+      // minute buys nothing: send it and take the provider's answer. Splitting
+      // it is the caller's call, not mohdel's.
+      if (adding <= inpmLimit && b.inputs + adding > inpmLimit) return msUntilNextMinute(b.minute)
+    }
     return 0
   }
 
@@ -67,7 +84,15 @@ export function createRateLimiter () {
     getBucket(key).tokens += tokens
   }
 
-  return { check, recordRequest, recordTokens }
+  /**
+   * @param {string} key
+   * @param {number} inputs
+   */
+  const recordInputs = (key, inputs) => {
+    getBucket(key).inputs += inputs
+  }
+
+  return { check, recordRequest, recordTokens, recordInputs }
 }
 
 // Single session-local instance.
@@ -75,3 +100,4 @@ const defaultLimiter = createRateLimiter()
 export const check = defaultLimiter.check
 export const recordRequest = defaultLimiter.recordRequest
 export const recordTokens = defaultLimiter.recordTokens
+export const recordInputs = defaultLimiter.recordInputs

package/js/session/adapters/_pricing.js

@@ -147,6 +147,21 @@ export function computeTranscriptionCost (spec, usage) {
   return 0
 }
 
+/**
+ * Embedding cost. `embeddingPrice` is USD per million input tokens; nothing is
+ * generated, so there is no output side.
+ *
+ * @param {any} spec
+ * @param {{inputTokens?: number}} usage
+ * @returns {number}
+ */
+export function computeEmbeddingCost (spec, usage) {
+  if (!spec || typeof spec.embeddingPrice !== 'number') return 0
+  const tokens = usage.inputTokens
+  if (typeof tokens !== 'number' || tokens <= 0) return 0
+  return round((tokens / 1_000_000) * spec.embeddingPrice)
+}
+
 /**
  * Test convenience: inject pricing-only specs by model id. Wraps
  * `setCatalog` with the `{input, output, thinking?}` shape used in
@@ -168,6 +183,9 @@ export function setPricing (table) {
 }
 
 /** @param {number} n */
+// 1e-10 USD, not 1e-6. Six decimals reads as plenty until you price a short
+// embedding: 4 tokens at $0.02 per million is 8e-8, which rounds to zero, and
+// a million such calls then sum to zero instead of to their real cost.
 function round (n) {
-  return Math.round(n * 1e6) / 1e6
+  return Math.round(n * 1e10) / 1e10
 }

package/js/session/adapters/embedding/_shared.js

@@ -0,0 +1,92 @@
+/**
+ * Pieces every embedding adapter needs: the pre-dispatch checks that turn a
+ * provider's per-model limits into an error before a request is sent, and the
+ * envelope-to-provider translation of `inputType`.
+ *
+ * These fail rather than drop. A `dimensions` the model ignores, or an
+ * `inputType` silently discarded, both produce vectors that look fine and
+ * retrieve badly, which is the failure mohdel exists to prevent.
+ *
+ * @module session/adapters/embedding/shared
+ */
+
+import { typedError } from '../_errors.js'
+
+/**
+ * @param {import('#core/embedding.js').EmbedEnvelope} envelope
+ * @param {any} spec
+ */
+export function checkBatch (envelope, spec) {
+  const input = envelope.input
+  if (!Array.isArray(input) || input.length === 0) {
+    throw typedError('embed requires a non-empty input array', 'EMBED_INPUT_EMPTY', false)
+  }
+  if (input.some(t => typeof t !== 'string')) {
+    throw typedError('embed input must be strings', 'EMBED_INPUT_INVALID', false)
+  }
+  const max = spec?.maxBatch
+  if (typeof max === 'number' && input.length > max) {
+    throw typedError(
+      `${input.length} inputs exceeds this model's batch limit of ${max}`,
+      'EMBED_BATCH_TOO_LARGE',
+      false
+    )
+  }
+}
+
+/**
+ * @param {import('#core/embedding.js').EmbedEnvelope} envelope
+ * @param {any} spec
+ * @returns {number | undefined}
+ */
+export function checkDimensions (envelope, spec) {
+  const wanted = envelope.dimensions
+  if (wanted === undefined) return undefined
+  if (!spec?.dimensionsSelectable) {
+    throw typedError(
+      'this model returns a fixed vector width; remove `dimensions`',
+      'EMBED_DIMENSIONS_UNSUPPORTED',
+      false
+    )
+  }
+  return wanted
+}
+
+/**
+ * Symbolic role to the provider's own vocabulary. The entry owns the mapping,
+ * the same way `thinkingEffortLevels` owns thinking budgets.
+ *
+ * @param {import('#core/embedding.js').EmbedEnvelope} envelope
+ * @param {any} spec
+ * @returns {string | null}
+ */
+export function resolveInputType (envelope, spec) {
+  const table = spec?.inputTypes
+  const wanted = envelope.inputType ?? spec?.defaultInputType ?? null
+  if (wanted === null) return null
+
+  if (!table || typeof table !== 'object') {
+    throw typedError(
+      'this model declares no inputTypes; remove `inputType`',
+      'EMBED_INPUT_TYPE_UNSUPPORTED',
+      false
+    )
+  }
+  const native = table[wanted]
+  if (typeof native !== 'string') {
+    throw typedError(
+      `inputType '${wanted}' is not declared for this model; known: ${Object.keys(table).join(', ')}`,
+      'EMBED_INPUT_TYPE_UNKNOWN',
+      false
+    )
+  }
+  return native
+}
+
+/**
+ * @param {number[][]} vectors
+ * @returns {number}
+ */
+export function widthOf (vectors) {
+  return vectors.length && Array.isArray(vectors[0]) ? vectors[0].length : 0
+}

package/js/session/adapters/embedding/cohere.js

@@ -0,0 +1,91 @@
+/**
+ * Cohere embedding adapter.
+ *
+ * The most divergent shape mohdel talks to: `POST /v2/embed` rather than
+ * `/embeddings`, inputs under `texts`, `input_type` **required**, and
+ * `embeddings` returned as an object keyed by dtype
+ * (`{ float: [[...]] }`) instead of a `data[]` array. Tokens live at
+ * `meta.billed_units.input_tokens`.
+ *
+ * @module session/adapters/embedding/cohere
+ */
+
+import { getSpec } from '../_catalog.js'
+import { classifyProviderError, fromHttpStatus, typedError } from '../_errors.js'
+import { computeEmbeddingCost } from '../_pricing.js'
+import { catalogKey, bareOf } from '#core/model-id.js'
+import { checkBatch, checkDimensions, resolveInputType, widthOf } from './_shared.js'
+
+const BASE_URL = 'https://api.cohere.com/v2'
+
+export async function cohereEmbedding (envelope, deps = {}) {
+  const fetchFn = deps.fetch ?? globalThis.fetch
+  const spec = deps.spec ?? getSpec(catalogKey(envelope.model)) ?? {}
+  const start = String(process.hrtime.bigint())
+
+  checkBatch(envelope, spec)
+  const dimensions = checkDimensions(envelope, spec)
+  const inputType = resolveInputType(envelope, spec)
+
+  // Cohere rejects a call without it, so an entry that declares no mapping is
+  // unusable rather than merely less accurate.
+  if (!inputType) {
+    throw typedError(
+      'cohere requires an input_type; set inputType or the entry\'s defaultInputType',
+      'EMBED_INPUT_TYPE_REQUIRED',
+      false
+    )
+  }
+
+  const body = {
+    model: spec.model ?? bareOf(envelope.model),
+    texts: envelope.input,
+    input_type: inputType,
+    embedding_types: ['float'],
+    ...(dimensions !== undefined ? { output_dimension: dimensions } : {})
+  }
+
+  let res
+  try {
+    res = await fetchFn(`${BASE_URL}/embed`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${envelope.auth.key}`
+      },
+      body: JSON.stringify(body)
+    })
+  } catch (e) {
+    throw typedError(classifyProviderError(e, envelope.auth?.key).message, 'NET_ERROR', true)
+  }
+
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    throw fromHttpStatus(res.status, detail, envelope.auth?.key)
+  }
+
+  const payload = await res.json()
+  const vectors = payload?.embeddings?.float ?? []
+
+  if (vectors.length !== envelope.input.length || vectors.some(v => !Array.isArray(v))) {
+    throw typedError(
+      `expected ${envelope.input.length} vectors, got ${vectors.length}`,
+      'EMBED_RESULT_MISMATCH',
+      false
+    )
+  }
+
+  const inputTokens = payload?.meta?.billed_units?.input_tokens ??
+    payload?.meta?.tokens?.input_tokens ?? 0
+  const end = String(process.hrtime.bigint())
+
+  return {
+    status: 'completed',
+    vectors,
+    dimensions: widthOf(vectors),
+    inputType,
+    inputTokens,
+    cost: computeEmbeddingCost(spec, { inputTokens }),
+    timestamps: { start, first: end, end }
+  }
+}

package/js/session/adapters/embedding/gemini.js

@@ -0,0 +1,92 @@
+/**
+ * Gemini embedding adapter.
+ *
+ * Shares nothing with the OpenAI shape: a different endpoint per batch size
+ * (`:embedContent` for one input, `:batchEmbedContents` for several), vectors
+ * under `embedding.values`, and tokens under
+ * `usageMetadata.promptTokenCount`. The dimension parameter is
+ * `outputDimensionality` and lives inside a config object rather than at the
+ * top level.
+ *
+ * @module session/adapters/embedding/gemini
+ */
+
+import { getSpec } from '../_catalog.js'
+import { classifyProviderError, fromHttpStatus, typedError } from '../_errors.js'
+import { computeEmbeddingCost } from '../_pricing.js'
+import { catalogKey, bareOf } from '#core/model-id.js'
+import { checkBatch, checkDimensions, resolveInputType, widthOf } from './_shared.js'
+
+const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'
+
+export async function geminiEmbedding (envelope, deps = {}) {
+  const fetchFn = deps.fetch ?? globalThis.fetch
+  const spec = deps.spec ?? getSpec(catalogKey(envelope.model)) ?? {}
+  const start = String(process.hrtime.bigint())
+
+  checkBatch(envelope, spec)
+  const dimensions = checkDimensions(envelope, spec)
+  const taskType = resolveInputType(envelope, spec)
+
+  const model = spec.model ?? bareOf(envelope.model)
+  const name = model.startsWith('models/') ? model : `models/${model}`
+  const batched = envelope.input.length > 1
+
+  const one = (text) => ({
+    model: name,
+    content: { parts: [{ text }] },
+    ...(taskType ? { taskType } : {}),
+    ...(dimensions !== undefined ? { outputDimensionality: dimensions } : {})
+  })
+  const body = batched
+    ? { requests: envelope.input.map(one) }
+    : one(envelope.input[0])
+
+  const method = batched ? 'batchEmbedContents' : 'embedContent'
+  let res
+  try {
+    res = await fetchFn(`${BASE_URL}/${name}:${method}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-goog-api-key': envelope.auth.key
+      },
+      body: JSON.stringify(body)
+    })
+  } catch (e) {
+    throw typedError(classifyProviderError(e, envelope.auth?.key).message, 'NET_ERROR', true)
+  }
+
+  if (!res.ok) {
+    const detail = await res.text().catch(() => '')
+    throw fromHttpStatus(res.status, detail, envelope.auth?.key)
+  }
+
+  const payload = await res.json()
+  const vectors = batched
+    ? (payload?.embeddings ?? []).map(e => e?.values)
+    : [payload?.embedding?.values]
+
+  if (vectors.length !== envelope.input.length || vectors.some(v => !Array.isArray(v))) {
+    throw typedError(
+      `expected ${envelope.input.length} vectors, got ${vectors.length}`,
+      'EMBED_RESULT_MISMATCH',
+      false
+    )
+  }
+
+  // Only the single-content endpoint reports usage; the batch one does not,
+  // so a batched call prices at 0 rather than on a guessed token count.
+  const inputTokens = payload?.usageMetadata?.promptTokenCount ?? 0
+  const end = String(process.hrtime.bigint())
+
+  return {
+    status: 'completed',
+    vectors,
+    dimensions: widthOf(vectors),
+    inputType: taskType,
+    inputTokens,
+    cost: computeEmbeddingCost(spec, { inputTokens }),
+    timestamps: { start, first: end, end }
+  }
+}