feat(embeddings): add OpenRouter support

[TheodoreSpeaks]

Summary

• add an opt-in OpenRouter fallback for self-hosted knowledge-base embeddings via the knowledge embeddings environment capability
• let the Embeddings block load the full OpenRouter embeddings catalog dynamically and require a user-entered OpenRouter API key on hosted and self-hosted deployments
• keep explicit block usage independent of OPENROUTER_API_KEY while preserving the fixed 1536-dimension knowledge-base contract
• retain successful batches during transient failover, fail fast on invalid configuration, and bill only platform-provided embedding tokens

Type of Change

• New feature

Testing

• bun run lint
• bun run check:audits
• bun run --cwd apps/sim type-check
• bun run apps/sim/scripts/check-block-registry.ts origin/staging
• 95 focused embeddings block, tool, route, client, adapter, and model-catalog tests
• regenerated tool metadata, integration docs, agent-stream docs, and skill projections

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Aug 10, 2026 7:02pm

[cursor]

PR Summary

Medium Risk
Touches knowledge-base embedding transport, billing (billableTokens), and multi-provider failover on self-hosted deployments; block path is BYOK-only but KB fallback uses env keys and changes which upstream receives document content.

Overview
Adds OpenRouter as an embedding provider in two places: the workflow Embeddings block (explicit BYOK) and self-hosted knowledge-base indexing (optional env fallback).

Embeddings block & tools: Users can pick OpenRouter alongside OpenAI, Gemini, Cohere, and Mistral. Models load dynamically from OpenRouter’s embedding catalog via a new API route and combobox; a dedicated OpenRouter API key is always required (no hosted pool). The embeddings tool route validates model ids against the live catalog and calls embedOpenRouter instead of the static catalog path.

Knowledge bases: Document/query embedding now goes through embedKnowledge, which on self-hosted OpenAI KB models can fall back through Azure OpenAI → OpenAI (including workspace BYOK) → OpenRouter when OPENROUTER_API_KEY is set. Hosted deployments and non-OpenAI KB models keep the previous behavior. Transient failures can failover per batch while successful batches are retained; billing uses billableTokens so only platform-funded tokens are charged.

Supporting work includes an OpenRouter wire adapter, model id normalization, KNOWLEDGE_EMBEDDINGS_CAPABILITY, optional shouldFallback on env capability wiring, docs/env example updates, and broad test coverage.

^{Reviewed by Cursor Bugbot for commit e75c0ba. Bugbot is set up for automated code reviews on this repo. Configure here.}

[greptile-apps]

Greptile Summary

The PR adds OpenRouter embeddings for explicit block usage and as an opt-in self-hosted knowledge-embedding fallback.

• Adds dynamic OpenRouter model discovery, API contracts, provider tooling, and block configuration.
• Executes knowledge fallback independently per precomputed batch, retaining successful sibling batches.
• Tracks billable tokens separately so workspace-BYOK work is excluded from platform billing.
• Extends environment capability and setup reporting for OpenRouter fallback configuration.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported duplicate failover work and mixed-BYOK overbilling paths are both corrected at the current head.

Important Files Changed

Filename	Overview
apps/sim/lib/embeddings/client.ts	Adds OpenRouter transports and per-batch knowledge fallback while preserving output order and separating total from billable token usage.
apps/sim/lib/knowledge/documents/service.ts	Accumulates billable embedding tokens across every outer document batch and uses that total for usage recording.
apps/sim/lib/knowledge/embeddings.ts	Routes knowledge document and search embeddings through the deployment-aware embedding client.
apps/sim/blocks/blocks/embeddings.ts	Adds explicit OpenRouter block selection, dynamic model loading, and a required user-provided OpenRouter key.
apps/sim/app/api/tools/embeddings/route.ts	Validates dynamic OpenRouter models and dispatches them through the dedicated OpenRouter embedding transport.

Sequence Diagram

sequenceDiagram
  participant KB as Knowledge pipeline
  participant Client as Embedding client
  participant OpenAI as OpenAI / workspace BYOK
  participant OR as OpenRouter fallback
  participant Billing as Usage billing
  KB->>Client: Embed precomputed batches
  loop Each batch
    Client->>OpenAI: Retry embedding request
    alt OpenAI succeeds
      OpenAI-->>Client: Embeddings and token usage
    else Transient retries exhausted
      Client->>OR: Retry only failed batch
      OR-->>Client: Embeddings and token usage
    end
  end
  Client-->>KB: Ordered embeddings, totalTokens, billableTokens
  KB->>Billing: Record only billableTokens

Loading

_{Reviews (10): Last reviewed commit: "fix(embeddings): reset stale OpenRouter ..." | Re-trigger Greptile}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e4124c8. Configure here.}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit ca35ea0. Configure here.}

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[TheodoreSpeaks]

@cursor review

[TheodoreSpeaks]

@greptile

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit e75c0ba. Configure here.}