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 8, 2026 4:40am

[cursor]

PR Summary

Medium Risk
Touches knowledge-base embedding generation, multi-provider failover, and usage billing; mis-routing or billing miscounts would affect indexing cost and reliability, though behavior is heavily covered by new tests.

Overview
Adds OpenRouter as an embeddings provider for workflows and an optional self-hosted knowledge-base transport, without changing the fixed 1536-dimension KB contract.

The Embeddings block gains an OpenRouter provider with a dynamic model combobox (live catalog API), a dedicated OpenRouter API key field (required on hosted and self-hosted; no Sim-hosted pool), and routing through embedOpenRouter on the embeddings tool API. Catalog providers keep static model lists; OpenRouter models are listed via GET /api/providers/openrouter/embeddings/models with blacklist filtering.

Knowledge-base indexing/search now calls embedKnowledge, which on non-hosted deployments with OPENROUTER_API_KEY and OpenAI catalog models runs a fallback chain (Azure OpenAI → OpenAI / workspace BYOK → OpenRouter) via KNOWLEDGE_EMBEDDINGS_CAPABILITY, retrying only transient errors and failing fast on auth/config failures. Partial batch success is preserved when only some batches need failover.

Embedding results add billableTokens so usage billing charges platform-funded tokens only (BYOK and explicit user keys stay non-billable). Docs, integrations metadata, and .env.example note OPENROUTER_API_KEY for the KB fallback.

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

[greptile-apps]

Greptile Summary

The PR adds OpenRouter support for explicit Embeddings block calls and as an opt-in self-hosted knowledge-embedding fallback.

• Adds dynamic OpenRouter embedding-model discovery, validation, transport, block, tool, and API-route support.
• Adds deployment capability detection and transient per-batch fallback for knowledge embeddings.
• Separates total provider token usage from platform-billable token usage.
• Updates generated metadata, setup reporting, documentation, and focused tests.

Confidence Score: 5/5

The PR appears safe to merge because both previously reported failures are fixed and no blocking related failure remains.

No blocking failure remains; failover now advances only the failed batch while preserving ordered sibling results, and billing sums only tokens produced with platform-provided credentials.

Important Files Changed

Filename	Overview
apps/sim/lib/embeddings/client.ts	Adds OpenRouter transports and per-batch knowledge fallback while retaining successful batches and computing provider-specific billable token totals.
apps/sim/lib/knowledge/documents/service.ts	Accumulates the new billable-token count across document embedding batches for usage recording.
apps/sim/lib/knowledge/embeddings.ts	Routes knowledge embedding generation through the deployment-aware fallback client and forwards billing metadata.
apps/sim/blocks/blocks/embeddings.ts	Adds the OpenRouter provider, dynamic model selection, explicit user key handling, and tool dispatch.
apps/sim/app/api/tools/embeddings/route.ts	Validates dynamic OpenRouter models and routes explicit OpenRouter requests through the dedicated embedding transport.
apps/sim/lib/core/config/env-capabilities.ts	Introduces the knowledge-embedding fallback capability and conditional fallback behavior.

Sequence Diagram

sequenceDiagram
  participant KB as Knowledge embedding caller
  participant Batch as Batch orchestrator
  participant Primary as OpenAI/Azure
  participant OR as OpenRouter
  participant Billing as Usage billing
  KB->>Batch: Embed inputs
  par Per precomputed batch
    Batch->>Primary: Request batch
    alt Primary succeeds
      Primary-->>Batch: Embeddings and token usage
    else Transient failure
      Batch->>OR: Retry only failed batch
      OR-->>Batch: Embeddings and token usage
    end
  end
  Batch-->>KB: Ordered embeddings, totalTokens, billableTokens
  KB->>Billing: Record platform-billable tokens only

Loading

_{Reviews (8): Last reviewed commit: "fix(embeddings): batch OpenRouter reques..." | 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

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

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