Skip to content

Self-improving AI Employees for everyone

feat(llm): add Sarvam AI as an OpenAI-compat provider + 5 service nodes

trohitgc530b372d6d5
diff --git a/CLAUDE.md b/CLAUDE.md
index 1829f519..b3c67e14 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -16,7 +16,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Theme System](./docs-internal/theme_system.md)** | 12-way visual theme system — 2 base (light, dark) + 5 utopian (renaissance, greek, edo, steampunk, atomic) + 5 dystopian (cyber, wasteland, rot, plague, surveillance) — driven by `<html data-theme>` + per-theme CSS files in `client/src/themes/`. Token taxonomy (surface / fg / border / accent / typography / motion) in **hex + `color-mix()`**; `@theme inline` bridge maps `--color-X: var(--X)` (no `hsl()` wrapper); per-theme files own the colour hex, base.css owns the shared `--tint-*` alpha scale; action role tokens (incl. `-ink` readable text), **per-theme `--code-*` syntax tokens** (tier 6 — the code editor, console/output JSON viewers, and chat code blocks paint in each theme's own palette: keyword→trigger, string→success, number→agent, function→model, on an adaptive dark/light code surface; replaced the global dracula `--prism-*` block + dead `getPrismTokenCSS`; the `OutputPanel` JSON viewer reads the same vars), per-theme `--pulse-keyframe` animation system + `.opencompany-*` helpers in `animations.css`, decorative-layer wrappers (`.app-frame` / `.canvas-host` / `.modal-frame`), per-component decorative ornaments (panel textures + canvas decorations + node pseudo-element overlays + theme-specific keyframes), **canvas-node visual contract via `--node-color` CSS custom property** (no inline `background` / `border` on node components — base.css + per-theme CSS owns visuals; `NodeStyle` helper type at [types/NodeTypes.ts](./client/src/types/NodeTypes.ts) makes the inline custom-prop typecheck-clean), **`--node-pulse-color` separate from `--node-color`** so executing-node glow uses each theme's highest-contrast accent regardless of plugin accent (Cyber neon cyan, Surveillance REC red, Renaissance ultramarine, etc.), **`data-page-hidden` animation pause** (toggled by Dashboard's `visibilitychange` listener; base.css declares `html[data-page-hidden] *, *::before, *::after { animation-play-state: paused !important }` to prevent compositor stall on tab return), **per-theme icon glyph system** (290 SVGs across 29 keys × 10 themes via [themedGlyphs.ts](./client/src/assets/icons/themedGlyphs.ts) + theme-aware [NodeIcon.tsx](./client/src/assets/icons/NodeIcon.tsx)), **per-theme canvas-grid + custom cursors** via `--canvas-grid` / `--cursor-default` slots, **decorative HTML primitives** (`<SvgFilterDefs>` mounting `#ink-blot` / `#noise` / `#crt` filter IDs at app root, `<DropCap>` wrapper for Renaissance ornament rule), **parameter panel migrated to Tailwind tokens** (no `useAppTheme()` reads; section headers carry the display-typography triplet; raw `<Button>` swapped to `<ActionButton intent>`), **per-theme scrollbar webkit rules** in all 12 themes, 9-event WebAudio sound system (10 packs via `--sound-pack` token + `useSound()` hook + global hover delegate + sonner toast monkey-patch + `withSound()` HOC + `Sounds.unlock()` gesture-unlock for AudioContext autoplay-policy compliance), `@media (prefers-reduced-motion: reduce)` accessibility, 30 ms throttle on `type` / `hover`, migration recipe, anti-patterns. Read this before adding a new theme, migrating a component to the new contract, or adding a canvas-node component. |
| **[Design System Bundle](./docs-internal/design-system/IMPLEMENTATION.md)** | Canonical, vendored design-system reference (extracted from this repo; see its `IMPLEMENTATION.md` for the contract). Tokens are **hex + `color-mix()`** (`tokens/{colors,typography,spacing,motion,fonts,base}.css`) — the format the live codebase standardizes on. Includes 34 reference components (`components/`, inline-style reference only — recreate in Tailwind/shadcn idioms), full-app UI kit (`ui_kits/opencompany/index.html`), and 12-theme docs (`guidelines/THEMES.md`, `reference/themes/`). Copy token values verbatim; do not re-derive by eye. Pairs with [Theme System](./docs-internal/theme_system.md). |
| **[Schema Source of Truth RFC](./docs-internal/schema_source_of_truth_rfc.md)** | Backend is SSOT for node schemas, visual metadata, handlers, palette metadata, icons. Plugin pattern: one `BaseNode` subclass in `server/nodes/<group>/<plugin>/__init__.py`. Wire format: `asset:<key>` / `<lib>:<brand>` / URL / emoji. Endpoint: `/api/schemas/nodes/{type}/spec.json`. Live invariant total via `pytest --collect-only`. |
-| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern). 25 `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use). `TaskQueue` constants route to Temporal worker pools. Plugins live across 9 queues (live count via `glob server/nodes/**/__init__.py`); handler bodies fully inlined (`services/handlers/` shrank 12.8K → 1.1K LOC across 16 → 4 files; only cross-cutting orchestration remains: `tools.py` AI-tool dispatch + agent delegation, `triggers.py` generic trigger-node handler, `todo.py` writeTodos shim — `google_auth.py` was retired into `nodes/google/_auth_helper.py`). **Wave 11.H added "self-contained plugin folders"** — up to six generic registries (`ws_handler_registry`, `register_router`, `event_waiter.{register_filter_builder,register_trigger_precheck}`, `status_broadcaster.register_service_refresh`, `node_output_schemas.register_output_schema`) so rich plugins like telegram own their entire surface area without core-services edits. |
+| **[Plugin System (Wave 11)](./docs-internal/plugin_system.md)** | Class-based plugin-first architecture. `BaseNode` / `ActionNode` / `TriggerNode` / `ToolNode` + `@Operation` decorator. Pydantic `Params`/`Output`. Declarative `Routing` DSL + `Connection` facade (Nango pattern; `request()` supports `json` / `data` / `files` — the last for multipart uploads, threaded through the auth-retry rebuild). `Credential` subclasses live in each node folder's `_credentials.py` (or inline for single-use); live count via `len(services.plugin.credential.CREDENTIAL_REGISTRY)` — 27 at time of writing, do not hand-maintain. `TaskQueue` constants route to Temporal worker pools. Plugins live across 9 queues (live count via `glob server/nodes/**/__init__.py`); handler bodies fully inlined (`services/handlers/` shrank 12.8K → 1.1K LOC across 16 → 4 files; only cross-cutting orchestration remains: `tools.py` AI-tool dispatch + agent delegation, `triggers.py` generic trigger-node handler, `todo.py` writeTodos shim — `google_auth.py` was retired into `nodes/google/_auth_helper.py`). **Wave 11.H added "self-contained plugin folders"** — up to six generic registries (`ws_handler_registry`, `register_router`, `event_waiter.{register_filter_builder,register_trigger_precheck}`, `status_broadcaster.register_service_refresh`, `node_output_schemas.register_output_schema`) so rich plugins like telegram own their entire surface area without core-services edits. |
| **[Nodes Cookbook](./server/nodes/README.md)** | 5-minute recipe + folder map + shared helpers (`_base.py` / `_inline.py` per domain) + shared credentials + **canonical folder-per-plugin shape (telegram is the reference implementation)** + contract invariants + common pitfalls. Lives next to the plugin files. |
| **[Node Creation Guide](./docs-internal/node_creation.md)** | Canonical plugin recipe — one self-contained folder per plugin under `server/nodes/<group>/<plugin>/`, rooted at `__init__.py`. Multi-file split (`_service.py` / `_handlers.py` / etc.) when the plugin owns long-lived state. Zero frontend edits, zero core-services edits. Auto-registers via `BaseNode.__init_subclass__` + the six `register_*` hooks. Covers tool nodes, dual-purpose nodes (workflow + AI tool), and specialized agents as variations of the same recipe. |
| **[Agent Architecture](./docs-internal/agent_architecture.md)** | How AI Agent and Chat Agent discover skills/tools, inject them into LLM prompts, and execute through the provider-neutral `run_native_agent_loop` |
@@ -32,6 +32,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[GitHub Service](./docs-internal/github_service.md)** | GitHub CLI integration — `githubAction` (repo_clone / pr_create / pr_list / pr_merge / issue_create / issue_list + `custom` passthrough; AI tool `github`). **Strict Stripe pattern: the gh CLI owns its own auth** — no token stored/injected by OpenCompany, no auth pre-flight (gh's own error surfaces), marker OAuth row for the modal badge, fieldless catalogue entry. Login = spawned `gh auth login --hostname github.com --git-protocol https --web` — source-verified: headless takes the `isInteractive=false` branch (no Press-Enter), prints one-time code + `github.com/login/device` URL on stderr; the modal shows the code via the generic `verificationCode` plumbing (`useCredentialPanel` → `OAuthConnect`). `login_env()` strips `GH_TOKEN`/`GITHUB_TOKEN` (login aborts otherwise). Success gate = `gh auth status` exit 0, then best-effort **`gh auth setup-git`** (official bridge — the future git node needs zero auth code). gh binary: **project-local, pooch-driven** (temporal `_install.py` idiom) — pinned release under `package_dir("gh")`, system gh never consulted (auth state still shared: gh config paths are user-level). Palette group `vcs`. |
| **[Cloudflare Service](./docs-internal/cloudflare_service.md)** | Cloudflare CLI integration — `cloudflareAction` (whoami / zones_list / dns_records CRUD / `graphql_query` / `custom` passthrough; AI tool `cloudflare`) wrapping the official `cf` CLI (npm `[email protected]`, technical preview — "the next version of Wrangler"). **Two cf-specific variants of the CLI-managed-auth pattern**: (1) the CLI opens the browser ITSELF (loopback PKCE callback on fixed port 8877) so the login handler proxies nothing — single-flight guard (concurrent logins collide on the fixed port) + never-kill-the-shim invariant (killing the npm `.cmd` wrapper orphans the node child holding 8877); success gate = `cf auth whoami` JSON (`authenticated: true` — cf exits 0 in BOTH auth states). (2) **Fixed 86-scope OAuth grant with no `--scopes` flag** — only `dns_analytics:read` for analytics; no RUM/zone-analytics OAuth scope exists anywhere, so the optional `cloudflare_api_token` field (injected as `CLOUDFLARE_API_TOKEN`, cf's documented first-priority credential) is the only path to Web Analytics/RUM + the GraphQL Analytics API. `graphql_query` op POSTs the official `client/v4/graphql` endpoint directly (outside the OpenAPI schema cf/SDKs are generated from) — the replacement for the sunsetted Zone Analytics REST API; needs `Account > Account Analytics > Read`. Pinned npm install into the shared packages tree, system cf never consulted (preview argv surface drifts across versions). Palette group `deployment`. |
| **[Google Cloud Service](./docs-internal/gcloud_service.md)** | Google Cloud CLI integration — `gcloudAction` (auth/config/projects + set_project / Compute Engine instances list-start-stop-describe / Cloud Run deploy-list-describe / Cloud Storage ls-cp-rm / `custom` passthrough; AI tool `gcloud`) wrapping the official gcloud CLI (pinned versioned archive via pooch into `package_dir("gcloud")` — NOT npm; the Windows bundled-python zip keeps the legacy `google-cloud-sdk-` filename prefix, the `-cli-` spelling 404s, locked by test). Cloudflare login variant (CLI opens the browser itself, random loopback port — no fixed-port hazard) + the gh marker-token pattern; success gate = `gcloud auth list --filter=status:ACTIVE --format=json` non-empty (exit codes never trusted). **Config isolation divergence from gh**: every invocation pins `CLOUDSDK_CONFIG=<DATA_DIR>/gcloud/`, so terminal logins against the operator's global gcloud are deliberately NOT visible to the node. ADC note: node login mints gcloud USER creds only (CLI commands never read ADC); client-library code gets ADC via the `custom` op `auth application-default login` (lands isolated in the pinned dir). Cold install ~100 MB → login answers `pending: True` within the 22 s WS budget. Provider id `gcloud` is orthogonal to the Workspace `google` OAuth2 provider. Palette group `deployment`. |
+| **[Sarvam AI Service](./docs-internal/sarvam_service.md)** | Sarvam AI (Indic-first) — `sarvamChatModel` registered as an **OpenAI-compat provider** (one `_COMPAT_PROVIDERS` entry + a JSON block; no provider subclass) plus five REST nodes under `nodes/sarvam/` (`sarvamTranslate` / `sarvamTransliterate` / `sarvamDetectLanguage` / `sarvamSpeechToText` / `sarvamTextToSpeech`, palette group `language`). **One stored key spans two auth styles** — the chat route takes `Authorization: Bearer` (what the openai SDK sends) while every other endpoint takes only `api-subscription-key`, so `SarvamCredential` declares the native header and both surfaces share it. Introduces the generic **`supports_model_listing: false`** flag: Sarvam ships no `/v1/models` route, and unhandled that 404 becomes a `NodeUserError` that `AIService.fetch_models` re-raises *before* its curated fallback, breaking key validation and the model dropdown — so `OpenAIProvider.fetch_models` serves the curated list and probes with a one-token completion instead (defaults `true`; the other 12 providers are untouched, locked by test). Reasoning needs zero Python (`thinking_type: "effort"` + `reasoning_content` are already handled); `thinking_default_on` and `reasoning_models` are deliberately omitted. Also added generic **`Connection.request(files=)`** multipart support for the STT node (threaded through the auth-retry rebuild). TTS writes audio to `<workspace>/audio/` by default — inline base64 is opt-in and size-capped because a full request is ~12 MB. |
| **[CI/CD Pipeline](./docs-internal/ci_cd.md)** | GitHub Actions workflows, predeploy validation, release publishing, and composite setup action |
| **[Performance](./docs-internal/performance.md)** | Cold-start measurements (Application startup complete 2.90 s warm, 21.5 s cold post-`company clean` — was 71 s before the 2026-07-14 boot-delay fixes; first WS connect 8.29 s) + warm and cold per-phase timelines + optimisation history (lazy LangChain imports, lazy LLM-SDK exception refs, esbuild sidecar bundle, bytecode-at-build, PartySocket reconnect, TanStack Query auth bootstrap, `manualChunks`, Vite dep-cache preservation, off-loop Temporal build-id hash) + bottleneck inventory + reproduction commands + anti-patterns to never reintroduce (incl. eager SDK import at LLM provider registration, unconditional `.vite` wipe, synchronous `Worker()` on the event loop). Pairs with the build-time pipeline doc below. |
| **[Release Build Pipeline](./docs-internal/release_build_pipeline.md)** | npm-distribution build pipeline: `tsgo` for type-check (5× faster than tsc), Vite `manualChunks` + `target: 'es2022'`, esbuild Node.js sidecar bundle (drops `tsx` interpreter cost), bytecode pre-compile in two halves — `[tool.uv] compile-bytecode = true` (uv sync compiles `.venv/` site-packages) + `python -m compileall` for project source (plain `.pyc`, **no `-O`** — per PEP 488 the non-`-O` runtimes never load `.opt-1.pyc`; excludes `.venv/`, `tests/`). Single source of truth for the bytecode-compile path list: `cli.commands.build.COMPILEALL_SOURCE_DIRS`. |
@@ -47,7 +48,7 @@ This is a React Flow-based workflow automation platform implementing n8n-inspire
| **[Onboarding Service](./docs-internal/onboarding.md)** | First-launch welcome wizard with 5 steps, database persistence, and replay from Settings |
| **[CLI Services Integration](./docs-internal/cli_services_integration.md)** | Guide for integrating CLI-based services (Temporal, etc.) with proper lifecycle management |
| **[Temporal Architecture](./docs-internal/TEMPORAL_ARCHITECTURE.md)** | Distributed workflow execution: activities, FIRST_COMPLETED scheduling, horizontal scaling |
-| **[Native LLM SDK](./docs-internal/native_llm_sdk.md)** | Native SDK layer in `services/llm/`: protocol-based providers, config-driven base URLs, and 12 providers (10 cloud plus Ollama / LM Studio; xAI is agent-selectable without a standalone chat-model node). LangChain is isolated to replay compatibility for legacy Temporal histories. |
+| **[Native LLM SDK](./docs-internal/native_llm_sdk.md)** | Native SDK layer in `services/llm/`: protocol-based providers, config-driven base URLs, and 13 providers (11 cloud plus Ollama / LM Studio; xAI is agent-selectable without a standalone chat-model node). A JSON-driven `supports_model_listing: false` flag covers endpoints that speak the OpenAI chat wire format but ship no `/v1/models` route (Sarvam) — `OpenAIProvider.fetch_models` then serves the curated list and probes the key with a one-token completion. LangChain is isolated to replay compatibility for legacy Temporal histories. |
| **[Event Waiter System](./docs-internal/event_waiter_system.md)** | In-memory asyncio.Future waiter for push-based trigger nodes on the canvas-Run path (WhatsApp, Telegram, Webhook, Chat, Task completion). Deployed triggers ride the Temporal canary path; the Redis-Streams backend was retired in Wave 15.3 |
| **[Credentials Encryption](./docs-internal/credentials_encryption.md)** | Fernet + PBKDF2 encryption pipeline, separate credentials.db, two credential systems (OAuth vs API keys), multi-backend abstraction |
| **[Status Broadcaster](./docs-internal/status_broadcaster.md)** | WebSocket-first communication: StatusBroadcaster singleton, live count via `len(MESSAGE_HANDLERS) + len(get_ws_handlers())`, broadcast message types, Android two-state model |
@@ -494,7 +495,7 @@ class CacheEntry(SQLModel, table=True):
## Codebase Summary
- **Hybrid architecture**: Python (FastAPI + Pydantic plugins) + React/TypeScript frontend + Node.js subprocess for JS/TS code execution.
-- **Backend NodeSpec is the single source of truth.** Plugins live in [`server/nodes/<group>/<name>.py`](./server/nodes/) and auto-register via `BaseNode.__init_subclass__`. Authoritative node count is whatever globs out of `server/nodes/**/*.py` (excluding `_*.py` helpers and `__init__.py`); folders cover agent / model / android / google / whatsapp / twitter / telegram / social / email / search / scraper / document / code / filesystem / proxy / location / chat / text / scheduler / trigger / tool / utility / workflow / skill / browser / stripe / vercel / github / cloudflare / gcloud.
+- **Backend NodeSpec is the single source of truth.** Plugins live in [`server/nodes/<group>/<name>.py`](./server/nodes/) and auto-register via `BaseNode.__init_subclass__`. Authoritative node count is whatever globs out of `server/nodes/**/*.py` (excluding `_*.py` helpers and `__init__.py`); folders cover agent / model / android / google / whatsapp / twitter / telegram / social / email / search / scraper / document / code / filesystem / proxy / location / chat / text / scheduler / trigger / tool / utility / workflow / skill / browser / stripe / vercel / github / cloudflare / gcloud / sarvam.
- **WebSocket-first frontend-backend communication.** Authoritative handler count is the size of the `MESSAGE_HANDLERS` dict in [`server/routers/websocket.py`](./server/routers/websocket.py) plus plugin-registered handlers via `services.ws_handler_registry`. Don't hand-maintain the count in this doc — it drifts on every plugin add.
- **Plugin-first architecture (Wave 11).** One file = one node. `services/handlers/` shrank from 12.8K → 1.1K LOC across 16 → 4 files. Live invariant total via `pytest --collect-only`.
@@ -614,9 +615,9 @@ The project uses WebSocket as the primary communication method between frontend
### Node Catalogue (collapsed)
-> The authoritative, per-node reference is the backend plugin registry plus the per-node "logic-flow" cards under [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) (one card per node, grouped by category, with handles / params / outputs / side-effects / edge-cases). Live node list = the plugin registry (one folder per node under `server/nodes/<group>/`, ~118 node types today; a bare `__init__.py` glob also counts the 26 group packages); live total via `pytest --collect-only`. Do NOT maintain a per-node catalogue here — it drifts on every plugin add.
+> The authoritative, per-node reference is the backend plugin registry plus the per-node "logic-flow" cards under [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) (one card per node, grouped by category, with handles / params / outputs / side-effects / edge-cases). Live node list = the plugin registry (one folder per node under `server/nodes/<group>/`, 131 node types today via `len(services.node_registry.NODE_METADATA)`; a bare `__init__.py` glob overcounts by also matching the group packages). Do NOT maintain a per-node catalogue here — it drifts on every plugin add.
-Node groups (palette categories): agent, model, skill, tool, trigger, workflow, search, google, android, whatsapp, telegram, twitter, social, email, proxy, chat, scheduler, text, code, document, location, utility, browser, scraper, filesystem, stripe, vercel, github (palette group `vcs`), cloudflare and gcloud (palette group `deployment`). See [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) for the card index.
+Node groups (palette categories): agent, model, skill, tool, trigger, workflow, search, google, android, whatsapp, telegram, twitter, social, email, proxy, chat, scheduler, text, code, document, location, utility, browser, scraper, filesystem, stripe, vercel, github (palette group `vcs`), cloudflare and gcloud (palette group `deployment`), sarvam (palette group `language` — translate / transliterate / detect-language / speech-to-text / text-to-speech, sharing one API key with `sarvamChatModel`). See [docs-internal/node-logic-flows/](./docs-internal/node-logic-flows/) for the card index.
## Backend Services
@@ -650,7 +651,7 @@ Node groups (palette categories): agent, model, skill, tool, trigger, workflow,
- `GET /webhook/` - Webhook endpoint info and usage documentation
#### Workflow Services (`server/services/workflow.py`)
-- Node execution dispatches every registered plugin via the `BaseNode` registry (one self-contained folder per node under `server/nodes/<group>/`; ~118 node types today — a bare `__init__.py` glob overcounts by also matching the 26 group packages; live total via `pytest --collect-only`)
+- Node execution dispatches every registered plugin via the `BaseNode` registry (one self-contained folder per node under `server/nodes/<group>/`; 131 node types today via `len(services.node_registry.NODE_METADATA)` — a bare `__init__.py` glob overcounts by also matching the group packages)
- Parameter resolution and template variable substitution
- Result formatting and error handling
diff --git a/client/src/components/icons/AIProviderIcons.tsx b/client/src/components/icons/AIProviderIcons.tsx
index 4f130015..6ed9b815 100644
--- a/client/src/components/icons/AIProviderIcons.tsx
+++ b/client/src/components/icons/AIProviderIcons.tsx
@@ -16,6 +16,7 @@ import Mistral from '@lobehub/icons/es/Mistral';
import Ollama from '@lobehub/icons/es/Ollama';
import LmStudio from '@lobehub/icons/es/LmStudio';
import { dracula, solarized } from '../../styles/theme';
+import { API_CONFIG } from '../../config/api';
// Icon size constant for consistency
const ICON_SIZE = 28;
@@ -71,6 +72,17 @@ export const LmStudioIcon: React.FC<{ size?: number }> = ({ size = ICON_SIZE })
<LmStudio.Avatar size={size} />
);
+// Sarvam AI has no @lobehub/icons brand entry, so its mark is served by the
+// backend credential-icon endpoint (server/credentials/icons/sarvam.svg).
+// That `/api/...` form is the same wire format `resolveIcon` already handles
+// for asset-backed credentials like apify / stripe / telegram, so no new
+// mechanism is needed — only an <img> wrapper for the direct-FC consumers.
+const SARVAM_ICON_URL = `${API_CONFIG.PYTHON_BASE_URL}/api/schemas/credentials/sarvam/icon`;
+
+export const SarvamIcon: React.FC<{ size?: number }> = ({ size = ICON_SIZE }) => (
+ <img src={SARVAM_ICON_URL} alt="Sarvam AI" width={size} height={size} />
+);
+
// Map provider IDs to their icon components
export const AI_PROVIDER_ICONS: Record<string, React.FC<{ size?: number }>> = {
openai: OpenAIIcon,
@@ -82,6 +94,7 @@ export const AI_PROVIDER_ICONS: Record<string, React.FC<{ size?: number }>> = {
deepseek: DeepSeekIcon,
kimi: KimiIcon,
mistral: MistralIcon,
+ sarvam: SarvamIcon,
ollama: OllamaIcon,
lmstudio: LmStudioIcon,
};
@@ -101,6 +114,8 @@ export const AI_PROVIDER_META: Record<string, { iconRef: string; Icon: React.FC<
deepseek: { iconRef: 'lobehub:DeepSeek', Icon: DeepSeekIcon, color: dracula.cyan, label: 'DeepSeek' },
kimi: { iconRef: 'lobehub:Kimi', Icon: KimiIcon, color: dracula.purple, label: 'Kimi' },
mistral: { iconRef: 'lobehub:Mistral', Icon: MistralIcon, color: dracula.pink, label: 'Mistral' },
+ // No lobehub brand — iconRef points at the backend-served SVG instead.
+ sarvam: { iconRef: '/api/schemas/credentials/sarvam/icon', Icon: SarvamIcon, color: '#F97316', label: 'Sarvam AI' },
ollama: { iconRef: 'lobehub:Ollama', Icon: OllamaIcon, color: dracula.foreground, label: 'Ollama' },
lmstudio: { iconRef: 'lobehub:LmStudio', Icon: LmStudioIcon, color: solarized.cyan, label: 'LM Studio' },
};
diff --git a/client/src/lib/aiModelProviders.ts b/client/src/lib/aiModelProviders.ts
index 6ec60dc9..017896a5 100644
--- a/client/src/lib/aiModelProviders.ts
+++ b/client/src/lib/aiModelProviders.ts
@@ -18,6 +18,7 @@ const AI_MODEL_PROVIDERS = [
'deepseek',
'kimi',
'mistral',
+ 'sarvam',
// Local-server providers — the chat-model plugins exist
// (`ollamaChatModel`, `lmstudioChatModel`), so they MUST live in this
// map for `ParameterRenderer` to derive the provider id from the node
diff --git a/docs-internal/native_llm_sdk.md b/docs-internal/native_llm_sdk.md
index 8d18c820..5bcf1b0e 100644
--- a/docs-internal/native_llm_sdk.md
+++ b/docs-internal/native_llm_sdk.md
@@ -40,8 +40,8 @@ server/services/llm/
|-- openai.py OpenAIProvider (openai SDK)
|-- gemini.py GeminiProvider (google-genai SDK)
|-- openrouter.py OpenRouterProvider (extends OpenAIProvider with headers)
- `-- _compat.py Registers the 8 OpenAI-compatible providers (xai, deepseek, kimi,
- mistral, groq, cerebras, ollama, lmstudio) via base_url specs
+ `-- _compat.py Registers the 9 OpenAI-compatible providers (xai, deepseek, kimi,
+ mistral, groq, cerebras, ollama, lmstudio, sarvam) via base_url specs
```
Each provider module calls `register_provider(ProviderSpec(...))` at module
@@ -51,7 +51,7 @@ providers share `_compat.py` and its explicit `_COMPAT_PROVIDERS` tuple.
## Supported Providers
-The native layer currently supports **12 providers**, grouped by implementation:
+The native layer currently supports **13 providers**, grouped by implementation:
| Provider | Implementation | SDK | Notes |
|---|---|---|---|
@@ -67,14 +67,19 @@ The native layer currently supports **12 providers**, grouped by implementation:
| `lmstudio` | `providers/openai.py` + `{provider}_proxy` URL | `openai` (chat) + `lmstudio` (probe) | Local server. Validator probes via `lmstudio.AsyncClient.llm.list_loaded()` for typed `LlmInstanceInfo.context_length`. Same OpenAI-compat runtime path as Ollama. |
| `groq` | `providers/_compat.py` + base_url | `openai` | OpenAI-compatible (chat-path LangChain fallback retired in Phase D) |
| `cerebras` | `providers/_compat.py` + base_url | `openai` | OpenAI-compatible (chat-path LangChain fallback retired in Phase D) |
+| `sarvam` | `providers/_compat.py` + base_url | `openai` | Indic-first (`sarvam-105b` 128K, `sarvam-30b` 64K) at `api.sarvam.ai/v1`. Ships **no model-list route**, so it sets `supports_model_listing: false` — see below. Reasoning is on by default and returns in `reasoning_content`, which `OpenAIProvider._normalize` already reads. |
Source of truth for this list: `server/config/llm_defaults.json` (the `providers` dict) and the `register_provider(ProviderSpec(...))` calls in `server/services/llm/providers/` (each provider module registers itself at import; the legacy `factory.py` was removed).
### Native chat path vs agent dropdown — two different counts
-- **Native chat path (`execute_chat` / `fetch_models`) supports 12 providers, all native** — Anthropic and Gemini via their own SDKs; OpenAI and OpenRouter via the openai SDK; and 8 more through the shared OpenAI-compatible client with a per-provider `base_url` (xai, deepseek, kimi, mistral, groq, cerebras, ollama, lmstudio — registered in `providers/_compat.py`). `execute_chat` delegates every provider to `ChatUnifier.chat`; there is no per-provider branch and no chat-path LangChain fallback. `xai` lives here.
-- **The agent dropdown exposes the same 12 providers** for `aiAgent`,
+- **Native chat path (`execute_chat` / `fetch_models`) supports 13 providers, all native** — Anthropic and Gemini via their own SDKs; OpenAI and OpenRouter via the openai SDK; and 9 more through the shared OpenAI-compatible client with a per-provider `base_url` (xai, deepseek, kimi, mistral, groq, cerebras, ollama, lmstudio, sarvam — registered in `providers/_compat.py`). `execute_chat` delegates every provider to `ChatUnifier.chat`; there is no per-provider branch and no chat-path LangChain fallback. `xai` lives here.
+- **The agent dropdown exposes the same 13 providers** for `aiAgent`,
`chatAgent` (Zeenie), and all specialized agents, including `xai`.
+ `test_plugin_shape.py` asserts exact set equality between the registry and
+ the `provider` Literal in all three agent Params classes, so registering a
+ provider without updating `nodes/agent/ai_agent`, `nodes/agent/chat_agent`
+ and `nodes/agent/_specialized` fails CI immediately.
- Groq, Cerebras, xAI, and the other compatible endpoints use the same native
OpenAI SDK adapter for both standalone chat and agent tool calls.
@@ -436,11 +441,12 @@ the plugin folder or add a `visuals.json` entry (`"openrouterChatModel":
**Backend steps:**
-1. **OpenAI-compatible provider** (DeepSeek, Kimi, Mistral pattern):
+1. **OpenAI-compatible provider** (DeepSeek, Kimi, Mistral, Sarvam pattern):
- Add an entry to `llm_defaults.json` with `base_url`, `default_model`, `detection_patterns`, `max_output_tokens._default`, `context_length._default`, `temperature_range`.
- Add the provider name to the compat list in `services/llm/providers/_compat.py` — its import loop calls `register_provider(ProviderSpec(...))` for every listed name.
- Chat and agent calls both use the native OpenAI SDK with that configured
`base_url`; do not add a branch in `AIService`.
+ - **If the endpoint has no `/v1/models` route**, set `"supports_model_listing": false` on the JSON block. `OpenAIProvider.fetch_models` then serves the curated list (`popular_models`, else the `max_output_tokens` keys) and validates the key with a one-token completion instead. Without the flag the 404 surfaces as an `openai.OpenAIError`, which `ChatUnifier` converts to `NodeUserError` and `AIService.fetch_models` re-raises **before** its curated fallback — breaking credential validation and the model dropdown for a valid key. Sarvam is the reference case; the flag defaults to `true` so no other provider is affected. Locked by `tests/llm/test_model_listing_fallback.py`.
2. **Custom-SDK provider** (Anthropic, Gemini pattern):
- Create `services/llm/providers/<name>.py` implementing the `LLMProvider` protocol.
diff --git a/docs-internal/node-logic-flows/README.md b/docs-internal/node-logic-flows/README.md
index a4f4dd82..9331d123 100644
--- a/docs-internal/node-logic-flows/README.md
+++ b/docs-internal/node-logic-flows/README.md
@@ -47,6 +47,7 @@ match its doc here, and each doc must still describe what the code does.
- [Ollama Chat Model (`ollamaChatModel`)](./ai_chat_models/ollamaChatModel.md)
- [OpenAI Chat Model (`openaiChatModel`)](./ai_chat_models/openaiChatModel.md)
- [OpenRouter Chat Model (`openrouterChatModel`)](./ai_chat_models/openrouterChatModel.md)
+- [Sarvam AI Chat Model (`sarvamChatModel`)](./ai_chat_models/sarvamChatModel.md)
### ai_tools
@@ -130,6 +131,17 @@ match its doc here, and each doc must still describe what the code does.
- [Proxy Request (`proxyRequest`)](./http_proxy/proxyRequest.md)
- [Proxy Status (`proxyStatus`)](./http_proxy/proxyStatus.md)
+### language
+
+Sarvam AI's non-chat REST APIs. The chat models live under `ai_chat_models`
+and share the same credential.
+
+- [Sarvam Detect Language (`sarvamDetectLanguage`)](./language/sarvamDetectLanguage.md)
+- [Sarvam Speech to Text (`sarvamSpeechToText`)](./language/sarvamSpeechToText.md)
+- [Sarvam Text to Speech (`sarvamTextToSpeech`)](./language/sarvamTextToSpeech.md)
+- [Sarvam Translate (`sarvamTranslate`)](./language/sarvamTranslate.md)
+- [Sarvam Transliterate (`sarvamTransliterate`)](./language/sarvamTransliterate.md)
+
### search
- [Brave Search (`braveSearch`)](./search/braveSearch.md)
diff --git a/docs-internal/node-logic-flows/ai_chat_models/sarvamChatModel.md b/docs-internal/node-logic-flows/ai_chat_models/sarvamChatModel.md
new file mode 100644
index 00000000..3dad668a
--- /dev/null
+++ b/docs-internal/node-logic-flows/ai_chat_models/sarvamChatModel.md
@@ -0,0 +1,120 @@
+# Sarvam AI Chat Model (`sarvamChatModel`)
+
+| Field | Value |
+|------|-------|
+| **Category** | ai_chat_models |
+| **Backend handler** | [`server/nodes/model/sarvam_chat_model/__init__.py`](../../../server/nodes/model/sarvam_chat_model/__init__.py) (dispatch via `BaseNode.execute()` -> `@Operation("chat")` in [`server/nodes/model/_base.py`](../../../server/nodes/model/_base.py)) |
+| **AI service** | [`server/services/ai.py::AIService.execute_chat`](../../../server/services/ai.py) |
+| **Tests** | [`server/tests/nodes/test_ai_chat_models.py`](../../../server/tests/nodes/test_ai_chat_models.py), [`server/tests/llm/test_model_listing_fallback.py`](../../../server/tests/llm/test_model_listing_fallback.py) |
+| **Skill (if any)** | n/a |
+| **Dual-purpose tool** | no (group `('model',)`) |
+
+## Purpose
+
+Sarvam AI's Indic-first LLMs — `sarvam-105b` (flagship, 128K context) and
+`sarvam-30b` (64K) — covering the 10 most-spoken Indian languages plus English
+in native script, romanised and code-mixed input. Registered as an
+OpenAI-compatible provider (one `_COMPAT_PROVIDERS` entry, no provider
+subclass); reasoning is on by default server-side.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data; not consumed directly |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `prompt` | string | `""` | yes | - | User message |
+| `system_prompt` | string | `""` | no | - | System prompt |
+| `model` | string | `""` (injected) | no | - | `sarvam-105b` / `sarvam-30b` |
+| `temperature` | number\|null | `null` | no | - | 0-2. Sarvam's own default is 0.5 with reasoning on, 0.2 without |
+| `max_tokens` | number\|null | `null` | no | - | Defaults to the `llm_defaults.json` value (65536 / 32768) |
+| `top_p` | number\|null | `1.0` | no | - | |
+| `frequency_penalty` | number\|null | `0.0` | no | - | -2.0 to 2.0 |
+| `presence_penalty` | number\|null | `0.0` | no | - | -2.0 to 2.0 |
+| `response_format` | enum\|null | `"text"` | no | - | `text` / `json_object` |
+| `thinking_enabled` | boolean | `false` | no | - | Only decides whether we override Sarvam's default effort |
+| `reasoning_effort` | enum\|null | `"medium"` | no | `thinking_enabled: [true]` | `low` / `medium` / `high` |
+| `api_key` | string\|null | `null` (injected) | no | - | `auth_service.get_api_key('sarvam', 'default')` |
+
+(Field names are snake_case on `SarvamChatModelParams`; unknown keys ignored.)
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-model` | object | Model output; standard envelope payload |
+
+### Output payload
+
+```ts
+{
+ response: string;
+ thinking: string | null; // from message.reasoning_content
+ thinking_enabled: boolean;
+ model: string;
+ provider: 'sarvam';
+ finish_reason: string;
+ timestamp: string;
+ input: { prompt: string; system_prompt: string };
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[NodeExecutor dispatch -> BaseNode.execute] --> B[ChatModelBase.chat Operation]
+ B --> C[AIService.execute_chat]
+ C --> D{valid key + prompt?}
+ D -- no --> X[error envelope]
+ D -- yes --> E[detect_ai_provider -> 'sarvam']
+ E --> F[_model_policy reads thinking_type='effort' from JSON]
+ F --> G[ChatUnifier.chat -> registry.get_provider sarvam<br/>OpenAI SDK w/ api.sarvam.ai/v1 base_url]
+ G --> H[provider.chat -> reasoning_effort in body]
+ H --> I[_normalize lifts reasoning_content -> thinking]
+ I --> J[success envelope]
+ G -- Exception --> X
+```
+
+## Decision Logic
+
+- **Validation**: missing api_key / empty prompt -> error envelope.
+- **Provider routing**: `detect_ai_provider` matches `'sarvam' in node_type.lower()`; the token collides with no other branch.
+- **Thinking**: `thinking_type: "effort"` in `llm_defaults.json` drives `params["reasoning_effort"]` — no Python branch. `thinking_enabled=false` sends *no* effort field, so Sarvam applies its own default (reasoning on, medium).
+- **Temperature stays allowed while reasoning**: `reasoning_models` is deliberately empty for sarvam, so `_model_policy` does not set `temperature_allowed=False` or pin 1.0.
+- **No `thinking_default_on`**: that key would emit Moonshot's proprietary `extra_body.thinking = {"type": "disabled"}`, which Sarvam never defined.
+- **Model listing**: the provider declares `supports_model_listing: false`; `fetch_models` returns the curated list and probes the key with a one-token completion (see edge cases).
+
+## Side Effects
+
+- **Database writes**: none on the bare chat path.
+- **Broadcasts**: none.
+- **External API calls**: `POST https://api.sarvam.ai/v1/chat/completions` (via the OpenAI SDK with an overridden base URL).
+- **File I/O**: none.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `auth_service.get_api_key('sarvam', 'default')` plus optional `sarvam_proxy`. The same key authenticates the five `nodes/sarvam/` REST nodes.
+- **Services**: `services/llm/providers/openai.py` (reused with Sarvam's base_url), registered in `providers/_compat.py`.
+- **Python packages**: `openai`.
+- **Environment variables**: none.
+
+## Edge cases & known limits
+
+- **No `/v1/models` endpoint.** Verified against <https://docs.sarvam.ai/openapi.json> (25 paths, none for model listing). Unhandled, the 404 surfaces as an `openai.OpenAIError` -> `NodeUserError`, which `AIService.fetch_models` re-raises *before* its curated fallback — breaking credential validation and the model dropdown for a valid key. The `supports_model_listing: false` flag routes around this generically.
+- **`max_output_tokens` is half the context window** (65536 / 32768), not Sarvam's documented Business-tier ceilings (128000 / 64000). Those are ~98% of the context window and `resolve_max_tokens` uses the value as both the unset default and the clamp ceiling, so a request at the documented ceiling could not fit a prompt.
+- **`popular_models` is `[]`** per the >=1M-context policy (Sarvam maxes at 131072); the dropdown falls through to the `max_output_tokens` keys, so both models still appear.
+- **`sarvam-m` is deprecated** and removed from the API — deliberately absent from the config.
+- **`wiki_grounding` is not exposed.** Sarvam accepts it, but an extra `Params` field cannot reach the API today: `execute_chat` reads a closed key set off `flattened`. See [Sarvam AI Service](../../sarvam_service.md#known-limits).
+- **Error boundary**: typed OpenAI SDK failures become user-safe `NodeUserError` values in `ChatUnifier` and are re-raised to `BaseNode.execute()`.
+
+## Related
+
+- **Peer nodes**: see the other chat-model docs in this folder.
+- **Sibling plugins**: the five Sarvam REST nodes in [`language/`](../language/) share this node's credential.
+- **Architecture docs**: [Native LLM SDK](../../native_llm_sdk.md), [Sarvam AI Service](../../sarvam_service.md).
diff --git a/docs-internal/node-logic-flows/language/sarvamDetectLanguage.md b/docs-internal/node-logic-flows/language/sarvamDetectLanguage.md
new file mode 100644
index 00000000..4f1a532a
--- /dev/null
+++ b/docs-internal/node-logic-flows/language/sarvamDetectLanguage.md
@@ -0,0 +1,97 @@
+# Sarvam Detect Language (`sarvamDetectLanguage`)
+
+| Field | Value |
+|------|-------|
+| **Category** | language |
+| **Backend handler** | [`server/nodes/sarvam/sarvam_detect_language.py`](../../../server/nodes/sarvam/sarvam_detect_language.py) |
+| **Shared helpers** | [`server/nodes/sarvam/_base.py`](../../../server/nodes/sarvam/_base.py) (`post_json`, `track_sarvam_usage`) |
+| **Tests** | [`server/tests/nodes/test_sarvam.py`](../../../server/tests/nodes/test_sarvam.py) |
+| **Skill (if any)** | [`server/skills/language_agent/sarvam-translate-skill/SKILL.md`](../../../server/skills/language_agent/sarvam-translate-skill/SKILL.md) |
+| **Dual-purpose tool** | yes — tool name `sarvam_detect_language` |
+
+## Purpose
+
+Identify which Indian language a piece of text is written in and in which
+script, via Sarvam's `/text-lid` endpoint. Typically used to route a message
+to the right handler, or to supply an explicit `source_language_code` to a
+downstream translate call.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data injected into params |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `input` | string | - | yes | - | Text to classify (max 1000 characters) |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | Standard envelope payload |
+
+### Output payload
+
+```ts
+{
+ language_code: string | null; // en-IN hi-IN bn-IN gu-IN kn-IN ml-IN mr-IN od-IN pa-IN ta-IN te-IN
+ script_code: string | null; // Latn Deva Beng Gujr Knda Mlym Orya Guru Taml Telu
+ request_id: string | null;
+}
+```
+
+Both classification fields are `Optional` on the output model **by design** —
+Sarvam returns nulls for text it cannot classify, and coercing those to `""`
+would hide the failure from downstream nodes.
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Receive params] --> B{len input > 1000?}
+ B -- yes --> X[NodeUserError w/ actual length]
+ B -- no --> C[ctx.connection sarvam -> POST /text-lid]
+ C -- status >= 400 --> Y[NodeUserError w/ Sarvam message]
+ C -- ok --> D[track_sarvam_usage detect_language, len input]
+ D --> E[Return SarvamDetectLanguageOutput incl. possible nulls]
+```
+
+## Decision Logic
+
+- **Validation**: input over 1000 characters short-circuits before the HTTP
+ call with the actual length in the message.
+- **Null passthrough**: an unclassifiable result is a *successful* envelope
+ with null fields, not an error. Callers must check before chaining.
+- **Error paths**: non-2xx becomes `NodeUserError` with Sarvam's own message.
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per call (characters).
+- **Broadcasts**: standard node status only.
+- **External API calls**: `POST https://api.sarvam.ai/text-lid`, `api-subscription-key` header.
+- **File I/O**: none.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `SarvamCredential` via `ctx.connection("sarvam")`.
+- **Python packages**: `httpx` (through `Connection`).
+
+## Edge cases & known limits
+
+- **Nulls are normal.** Short or ambiguous input returns `language_code: null`
+ and `script_code: null`. Feeding that straight into `sarvamTranslate` as a
+ source language will fail — check first, or pass `auto`.
+- 1000-character hard cap; sample or truncate longer text rather than looping.
+- Covers 11 languages, fewer than translate's 22.
+- Cheapest of the Sarvam text APIs (3.5 INR / 10K characters).
+
+## Related
+
+- **Skills using this as a tool**: `sarvam-translate-skill`.
+- **Downstream nodes**: [`sarvamTranslate`](./sarvamTranslate.md) (pass the detected code as `source_language_code`).
+- **Architecture docs**: [Sarvam AI Service](../../sarvam_service.md).
diff --git a/docs-internal/node-logic-flows/language/sarvamSpeechToText.md b/docs-internal/node-logic-flows/language/sarvamSpeechToText.md
new file mode 100644
index 00000000..bf1add32
--- /dev/null
+++ b/docs-internal/node-logic-flows/language/sarvamSpeechToText.md
@@ -0,0 +1,119 @@
+# Sarvam Speech to Text (`sarvamSpeechToText`)
+
+| Field | Value |
+|------|-------|
+| **Category** | language |
+| **Backend handler** | [`server/nodes/sarvam/sarvam_speech_to_text.py`](../../../server/nodes/sarvam/sarvam_speech_to_text.py) |
+| **Shared helpers** | [`server/nodes/sarvam/_base.py`](../../../server/nodes/sarvam/_base.py) (`post_multipart`, `track_sarvam_usage`) |
+| **Tests** | [`server/tests/nodes/test_sarvam.py`](../../../server/tests/nodes/test_sarvam.py), [`server/tests/services/test_connection_multipart.py`](../../../server/tests/services/test_connection_multipart.py) |
+| **Skill (if any)** | [`server/skills/language_agent/sarvam-speech-skill/SKILL.md`](../../../server/skills/language_agent/sarvam-speech-skill/SKILL.md) |
+| **Dual-purpose tool** | yes — tool name `sarvam_speech_to_text` |
+
+## Purpose
+
+Transcribe short audio clips across 23 Indian languages using Sarvam's Saaras
+models, with optional direct translation to English. This is the repo's first
+`multipart/form-data` node.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data injected into params (commonly a file path) |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `audio_file` | string \| object | `""` | yes | - | Path, **or** the file-widget upload envelope. `widget: file`, `accept: audio/*` |
+| `model` | enum | `saaras:v3` | no | - | `saaras:v3` (23 langs) / `saarika:v2.5` (legacy) |
+| `language_code` | string | `unknown` | no | - | BCP-47, or `unknown` to auto-detect |
+| `mode` | enum | `transcribe` | no | - | `transcribe` / `translate` / `verbatim` / `translit` / `codemix` |
+| `input_audio_codec` | enum\|null | `null` | no | - | `pcm_s16le` / `pcm_l16` / `pcm_raw` — headerless PCM only |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | Standard envelope payload |
+
+### Output payload
+
+```ts
+{
+ transcript: string;
+ language_code: string | null;
+ language_probability: number | null; // null when language_code was supplied
+ timestamps: object | null; // conditional
+ diarized_transcript: object | null; // Batch API only — always null here
+ request_id: string | null;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Receive params] --> B{mode advanced && model != saaras:v3?}
+ B -- yes --> X[NodeUserError]
+ B -- no --> C[_read_audio: dict upload or path]
+ C -- dict, bad base64 --> X
+ C -- path missing --> X
+ C -- empty or oversize --> X
+ C -- ok --> D[guess mime from filename]
+ D --> E[ctx.connection sarvam -> POST /speech-to-text<br/>files= + data=, no Content-Type]
+ E -- status >= 400 --> Y[NodeUserError w/ Sarvam message]
+ E -- ok --> F[track_sarvam_usage speech_to_text, 30s]
+ F --> G[Return SarvamSpeechToTextOutput]
+```
+
+## Decision Logic
+
+- **Mode/model compatibility**: `verbatim` / `translit` / `codemix` require
+ `saaras:v3`; asking for them on `saarika:v2.5` fails before the call.
+- **Dual-shaped `audio_file`** (`_read_audio`): the frontend file widget sends
+ `{"type": "upload", "data": "<base64>", "filename", "mimeType"}` when the
+ user picks a file, and a bare string when they type a path or drag an
+ upstream value in. The param is typed `Union[str, Dict]` for exactly this
+ reason — `whatsapp_send` declares the same field as `str` and only survives
+ because its handler reads the raw dict.
+- **Path resolution**: relative paths resolve against `ctx.workspace_dir`, so
+ they line up with `fileDownloader` and `sarvamTextToSpeech` output.
+- **Size guard**: empty files and payloads over 24 MB fail with a message that
+ names the 30-second limit and points at the Batch API.
+- **Billing**: `resource_count` is the documented 30-second ceiling; the node
+ does not decode the clip to measure real duration.
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per call (seconds).
+- **Broadcasts**: standard node status only.
+- **External API calls**: `POST https://api.sarvam.ai/speech-to-text` as `multipart/form-data`, `api-subscription-key` header.
+- **File I/O**: reads the audio file when given a path. Writes nothing.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `SarvamCredential` via `ctx.connection("sarvam")`.
+- **Framework**: `Connection.request(files=)` — added generically for this
+ node and threaded through the auth-retry rebuild, so a 401 replays the file
+ parts rather than an empty body. Pass **bytes**, never an open handle.
+- **Python packages**: `httpx` (through `Connection`), stdlib `base64` / `mimetypes`.
+
+## Edge cases & known limits
+
+- **30-second hard limit.** This is the synchronous endpoint; longer audio
+ needs Sarvam's Batch API, which is a separate job-based surface and is not
+ wired. Tell the user rather than retrying.
+- **Diarization is Batch-only.** `diarized_transcript` is declared on the
+ output model for shape stability but will always be `null` here.
+- Accuracy is best at 16 kHz; PCM inputs are limited to 16 kHz.
+- `language_probability` is `null` whenever `language_code` was supplied
+ explicitly (nothing was inferred).
+- No streaming — the WebSocket transcription surface is not wired.
+
+## Related
+
+- **Skills using this as a tool**: `sarvam-speech-skill`.
+- **Peer nodes**: [`sarvamTextToSpeech`](./sarvamTextToSpeech.md) (the other half of a voice loop).
+- **Architecture docs**: [Sarvam AI Service](../../sarvam_service.md).
diff --git a/docs-internal/node-logic-flows/language/sarvamTextToSpeech.md b/docs-internal/node-logic-flows/language/sarvamTextToSpeech.md
new file mode 100644
index 00000000..88291663
--- /dev/null
+++ b/docs-internal/node-logic-flows/language/sarvamTextToSpeech.md
@@ -0,0 +1,141 @@
+# Sarvam Text to Speech (`sarvamTextToSpeech`)
+
+| Field | Value |
+|------|-------|
+| **Category** | language |
+| **Backend handler** | [`server/nodes/sarvam/sarvam_text_to_speech.py`](../../../server/nodes/sarvam/sarvam_text_to_speech.py) |
+| **Shared helpers** | [`server/nodes/sarvam/_base.py`](../../../server/nodes/sarvam/_base.py) (`post_json`, `track_sarvam_usage`) |
+| **Tests** | [`server/tests/nodes/test_sarvam.py`](../../../server/tests/nodes/test_sarvam.py) |
+| **Skill (if any)** | [`server/skills/language_agent/sarvam-speech-skill/SKILL.md`](../../../server/skills/language_agent/sarvam-speech-skill/SKILL.md) |
+| **Dual-purpose tool** | yes — tool name `sarvam_text_to_speech` |
+
+## Purpose
+
+Synthesize natural speech in 11 Indian languages using Sarvam's Bulbul voices
+(37 on v3, 7 on v2). Writes audio into the workflow workspace and returns a
+path; inline base64 is opt-in and size-capped.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data injected into params |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `text` | string | - | yes | - | Text to speak (2500 chars v3, 1500 v2) |
+| `target_language_code` | enum | `hi-IN` | no | - | 11 core codes |
+| `model` | enum | `bulbul:v3` | no | - | `bulbul:v3` / `bulbul:v2` |
+| `speaker` | string | `shubh` | no | - | Voice name, lowercase. Per-model sets |
+| `pace` | number | `1.0` | no | - | v3 0.5-2.0, v2 0.3-3.0 |
+| `speech_sample_rate` | enum | `24000` | no | - | 8000 / 16000 / 22050 / 24000 / 32000 / 44100 / 48000 |
+| `output_audio_codec` | enum | `wav` | no | - | wav / mp3 / linear16 / mulaw / alaw / opus / flac / aac |
+| `temperature` | number\|null | `null` | no | `model: [bulbul:v3]` | 0.01-2.0, v3 only |
+| `pitch` | number\|null | `null` | no | `model: [bulbul:v2]` | -0.75 to 0.75, v2 only |
+| `loudness` | number\|null | `null` | no | `model: [bulbul:v2]` | 0.3-3.0, v2 only |
+| `enable_preprocessing` | boolean\|null | `null` | no | `model: [bulbul:v2]` | v2 only (v3 always preprocesses) |
+| `return_audio` | enum | `file` | no | - | `file` / `base64` |
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | Standard envelope payload |
+
+### Output payload
+
+```ts
+{
+ file_path: string | null; // chunk 1; null in base64 mode
+ files: string[]; // one entry per chunk
+ chunk_count: number;
+ audio_format: string; // echoes output_audio_codec
+ audio_base64: string | null; // opt-in, size-capped
+ note: string | null; // multi-chunk or suppression explanation
+ request_id: string | null;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Receive params] --> B{len text > model cap?}
+ B -- yes --> X[NodeUserError]
+ B -- no --> C{speaker in model's voice set?}
+ C -- no --> X
+ C -- yes --> D{v3 && pace outside 0.5-2.0?}
+ D -- yes --> X
+ D -- no --> E[Build body: v3 -> temperature; v2 -> pitch/loudness/preprocessing]
+ E --> F[ctx.connection sarvam -> POST /text-to-speech]
+ F -- status >= 400 --> Y[NodeUserError w/ Sarvam message]
+ F -- ok --> G{audios empty?}
+ G -- yes --> X
+ G -- no --> H{return_audio}
+ H -- file --> I[_write_chunks -> workspace/audio, one file per chunk]
+ H -- base64 --> J{chunk 1 over _MAX_INLINE_B64?}
+ J -- yes --> K[audio_base64 null + note]
+ J -- no --> L[audio_base64 = chunk 1]
+ I --> M[track usage v3 or v2 rate]
+ K --> M
+ L --> M
+ M --> N[Return SarvamTextToSpeechOutput]
+```
+
+## Decision Logic
+
+- **Per-model validation**: character cap, voice-set membership and (for v3)
+ pace range all fail before the HTTP call. A v2 voice on v3 is an error, not
+ a silent fallback.
+- **Version-gated body**: v3 sends `temperature`; v2 sends `pitch` /
+ `loudness` / `enable_preprocessing`. They are mutually exclusive because v3
+ rejects the v2 fields outright — `displayOptions` hides them in the UI and
+ the body builder filters them regardless of what the caller sent.
+- **Default is file, not base64.** A 2500-character v3 request is roughly
+ 12 MB of base64, which would land in the `node_outputs` JSON column, ride a
+ status-WebSocket broadcast, and — because this node is tool-exposed — be
+ serialized into an LLM message.
+- **Inline cap**: `_MAX_INLINE_B64 = 1_000_000`. Over it, `audio_base64` stays
+ `None` and `note` says why and names `return_audio='file'`. Never a silent
+ truncation.
+- **Multi-chunk**: Sarvam may split long text across `audios[]`. Each chunk is
+ a standalone container with its own header, so byte-wise concatenation
+ produces an unplayable file. One file per chunk; `file_path` is chunk 1;
+ `note` explains.
+- **Billing**: `bulbul:v2` is half the v3 character rate, so the tracked
+ action differs (`text_to_speech` vs `text_to_speech_v2`).
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per call (characters).
+- **Broadcasts**: standard node status only.
+- **External API calls**: `POST https://api.sarvam.ai/text-to-speech`, `api-subscription-key` header.
+- **File I/O**: writes `<workspace_dir>/audio/<slug>-<node8>-<rand6>[-N].<ext>` in `file` mode; creates the directory if absent. Falls back to a relative `audio/` dir when no workspace is set.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `SarvamCredential` via `ctx.connection("sarvam")`.
+- **Python packages**: `httpx` (through `Connection`), stdlib `base64` / `uuid` / `re`.
+
+## Edge cases & known limits
+
+- **Audio is a file, not bytes.** Downstream nodes should consume `file_path`.
+ Only reach for `return_audio: "base64"` for very short clips that must be
+ inlined (e.g. chaining into `whatsappSend` with `media_source: "base64"`).
+- Voice sets do not overlap between v2 and v3.
+- `pitch` / `loudness` are silently unavailable on v3 — that is Sarvam's
+ limitation, surfaced through `displayOptions` rather than an error.
+- Sample rates above 24000 are v3-REST-only.
+- No streaming — the HTTP-stream and WebSocket TTS surfaces are not wired.
+- Filenames embed a random suffix, so repeated runs never collide or
+ silently overwrite prior audio.
+
+## Related
+
+- **Skills using this as a tool**: `sarvam-speech-skill`.
+- **Upstream nodes**: [`sarvamTransliterate`](./sarvamTransliterate.md) with `spoken_form: true` produces speech-ready text.
+- **Peer nodes**: [`sarvamSpeechToText`](./sarvamSpeechToText.md).
+- **Architecture docs**: [Sarvam AI Service](../../sarvam_service.md).
diff --git a/docs-internal/node-logic-flows/language/sarvamTranslate.md b/docs-internal/node-logic-flows/language/sarvamTranslate.md
new file mode 100644
index 00000000..1a28238e
--- /dev/null
+++ b/docs-internal/node-logic-flows/language/sarvamTranslate.md
@@ -0,0 +1,107 @@
+# Sarvam Translate (`sarvamTranslate`)
+
+| Field | Value |
+|------|-------|
+| **Category** | language |
+| **Backend handler** | [`server/nodes/sarvam/sarvam_translate.py`](../../../server/nodes/sarvam/sarvam_translate.py) |
+| **Shared helpers** | [`server/nodes/sarvam/_base.py`](../../../server/nodes/sarvam/_base.py) (`post_json`, `track_sarvam_usage`) |
+| **Tests** | [`server/tests/nodes/test_sarvam.py`](../../../server/tests/nodes/test_sarvam.py) |
+| **Skill (if any)** | [`server/skills/language_agent/sarvam-translate-skill/SKILL.md`](../../../server/skills/language_agent/sarvam-translate-skill/SKILL.md) |
+| **Dual-purpose tool** | yes — tool name `sarvam_translate` |
+
+## Purpose
+
+Translate text between English and 22 Indian languages via Sarvam's
+`/translate` endpoint. Supports formal, colloquial and code-mixed registers,
+optional gendered inflection, and output-script control (native, Roman, or
+spoken form). Distinct from `sarvamTransliterate`, which changes script
+without changing language.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data injected into params |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `input` | string | - | yes | - | Text to translate |
+| `source_language_code` | enum | `auto` | no | - | `auto` + the 22 language codes |
+| `target_language_code` | enum | `hi-IN` | no | - | The 22 language codes (no `auto`) |
+| `model` | enum | `sarvam-translate:v1` | no | - | `sarvam-translate:v1` (22 langs, 2000 chars) / `mayura:v1` (1000 chars) |
+| `mode` | enum | `formal` | no | - | `formal` / `modern-colloquial` / `classic-colloquial` / `code-mixed` |
+| `speaker_gender` | enum\|null | `null` | no | - | `Male` / `Female` |
+| `output_script` | enum\|null | `null` | no | - | `roman` / `fully-native` / `spoken-form-in-native` |
+| `numerals_format` | enum | `international` | no | - | `international` / `native` |
+
+Language codes: `as-IN bn-IN brx-IN doi-IN en-IN gu-IN hi-IN kn-IN kok-IN
+ks-IN mai-IN ml-IN mni-IN mr-IN ne-IN od-IN pa-IN sa-IN sat-IN sd-IN ta-IN
+te-IN ur-IN`.
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | Standard envelope payload |
+
+### Output payload
+
+```ts
+{
+ translated_text: string;
+ source_language_code: string; // detected when input was 'auto'
+ request_id: string | null;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Receive params] --> B{len input > model cap?}
+ B -- yes --> X[NodeUserError with actual length + cap]
+ B -- no --> C{source == target?}
+ C -- yes --> X
+ C -- no --> D[Build body, strip None values]
+ D --> E[ctx.connection sarvam -> POST /translate]
+ E -- status >= 400 --> Y[NodeUserError w/ Sarvam message]
+ E -- ok --> F[track_sarvam_usage translate, len input]
+ F --> G[Return SarvamTranslateOutput]
+```
+
+## Decision Logic
+
+- **Validation**: input over the per-model character cap, and an identical
+ source/target pair, both short-circuit before the HTTP call — no paid call
+ is burned on a guaranteed no-op.
+- **`None` stripping**: `post_json` drops unset optionals rather than sending
+ explicit nulls; Sarvam 422s on several of those.
+- **Error paths**: non-2xx becomes `NodeUserError` carrying Sarvam's own
+ `error.message` (or `message` / `detail`), prefixed with the status code.
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per call (characters as `resource_count`).
+- **Broadcasts**: standard node status only.
+- **External API calls**: `POST https://api.sarvam.ai/translate`, `api-subscription-key` header.
+- **File I/O**: none.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `SarvamCredential` (`nodes/model/_credentials.py`) via `ctx.connection("sarvam")`.
+- **Python packages**: `httpx` (through `Connection`).
+
+## Edge cases & known limits
+
+- Caps are per model: 1000 chars for `mayura:v1`, 2000 for `sarvam-translate:v1`. Split on sentence boundaries for longer text — splitting mid-sentence degrades quality.
+- `mayura:v1` covers only 10 languages despite the shared enum; an unsupported pair returns a Sarvam 422 surfaced verbatim.
+- Usage is billed per character; transliteration has no separately published rate and is priced identically in `pricing.json`.
+
+## Related
+
+- **Skills using this as a tool**: `sarvam-translate-skill`.
+- **Peer nodes**: [`sarvamTransliterate`](./sarvamTransliterate.md), [`sarvamDetectLanguage`](./sarvamDetectLanguage.md).
+- **Architecture docs**: [Sarvam AI Service](../../sarvam_service.md).
diff --git a/docs-internal/node-logic-flows/language/sarvamTransliterate.md b/docs-internal/node-logic-flows/language/sarvamTransliterate.md
new file mode 100644
index 00000000..69000258
--- /dev/null
+++ b/docs-internal/node-logic-flows/language/sarvamTransliterate.md
@@ -0,0 +1,102 @@
+# Sarvam Transliterate (`sarvamTransliterate`)
+
+| Field | Value |
+|------|-------|
+| **Category** | language |
+| **Backend handler** | [`server/nodes/sarvam/sarvam_transliterate.py`](../../../server/nodes/sarvam/sarvam_transliterate.py) |
+| **Shared helpers** | [`server/nodes/sarvam/_base.py`](../../../server/nodes/sarvam/_base.py) (`post_json`, `track_sarvam_usage`) |
+| **Tests** | [`server/tests/nodes/test_sarvam.py`](../../../server/tests/nodes/test_sarvam.py) |
+| **Skill (if any)** | [`server/skills/language_agent/sarvam-translate-skill/SKILL.md`](../../../server/skills/language_agent/sarvam-translate-skill/SKILL.md) |
+| **Dual-purpose tool** | yes — tool name `sarvam_transliterate` |
+
+## Purpose
+
+Convert text between scripts while preserving pronunciation — romanised Hindi
+("namaste") to Devanagari ("नमस्ते") and back. **This is not translation**:
+the words and meaning are unchanged, only the writing system. Optionally
+expands numerals and abbreviations into spoken form, which is useful when the
+output feeds `sarvamTextToSpeech`.
+
+## Inputs (handles)
+
+| Handle | Connection type | Required | Purpose |
+|--------|-----------------|----------|---------|
+| `input-main` | main | no | Upstream data injected into params |
+
+## Parameters
+
+| Name | Type | Default | Required | displayOptions.show | Description |
+|------|------|---------|----------|---------------------|-------------|
+| `input` | string | - | yes | - | Text to transliterate |
+| `source_language_code` | enum | `auto` | no | - | `auto` + the 11 core codes |
+| `target_language_code` | enum | `hi-IN` | no | - | The 11 core codes |
+| `numerals_format` | enum | `international` | no | - | `international` / `native` |
+| `spoken_form` | boolean | `false` | no | - | Expand numbers / dates / abbreviations as spoken |
+| `spoken_form_numerals_language` | enum | `native` | no | `spoken_form: [true]` | `english` / `native` |
+
+Language codes: `bn-IN en-IN gu-IN hi-IN kn-IN ml-IN mr-IN od-IN pa-IN ta-IN
+te-IN` (a narrower set than `sarvamTranslate`).
+
+## Outputs (handles)
+
+| Handle | Shape | Description |
+|--------|-------|-------------|
+| `output-main` | object | Standard envelope payload |
+
+### Output payload
+
+```ts
+{
+ transliterated_text: string;
+ source_language_code: string;
+ request_id: string | null;
+}
+```
+
+## Logic Flow
+
+```mermaid
+flowchart TD
+ A[Receive params] --> B{source == target?}
+ B -- yes --> X[NodeUserError]
+ B -- no --> C[Build body; spoken_form_numerals_language only when spoken_form]
+ C --> D[ctx.connection sarvam -> POST /transliterate]
+ D -- status >= 400 --> Y[NodeUserError w/ Sarvam message]
+ D -- ok --> E[track_sarvam_usage transliterate, len input]
+ E --> F[Return SarvamTransliterateOutput]
+```
+
+## Decision Logic
+
+- **Validation**: identical source/target short-circuits before the HTTP call.
+- **Conditional field**: `spoken_form_numerals_language` is set to `None` (and
+ therefore stripped by `post_json`) unless `spoken_form` is true, so the API
+ never receives a meaningless pairing.
+- **Error paths**: non-2xx becomes `NodeUserError` with Sarvam's own message.
+
+## Side Effects
+
+- **Database writes**: one `api_usage_metrics` row per call (characters).
+- **Broadcasts**: standard node status only.
+- **External API calls**: `POST https://api.sarvam.ai/transliterate`, `api-subscription-key` header.
+- **File I/O**: none.
+- **Subprocess**: none.
+
+## External Dependencies
+
+- **Credentials**: `SarvamCredential` via `ctx.connection("sarvam")`.
+- **Python packages**: `httpx` (through `Connection`).
+
+## Edge cases & known limits
+
+- Narrower language set than translate — 11 codes, not 22.
+- No published per-character rate; `pricing.json` prices it as translation.
+- Easy to reach for by mistake: if the goal is changing *language*, use
+ [`sarvamTranslate`](./sarvamTranslate.md). The skill spells out the
+ distinction for the LLM.
+
+## Related
+
+- **Skills using this as a tool**: `sarvam-translate-skill`.
+- **Peer nodes**: [`sarvamTranslate`](./sarvamTranslate.md), [`sarvamTextToSpeech`](./sarvamTextToSpeech.md) (a common downstream consumer of spoken-form output).
+- **Architecture docs**: [Sarvam AI Service](../../sarvam_service.md).
diff --git a/docs-internal/sarvam_service.md b/docs-internal/sarvam_service.md
new file mode 100644
index 00000000..8b26d345
--- /dev/null
+++ b/docs-internal/sarvam_service.md
@@ -0,0 +1,259 @@
+# Sarvam AI Service
+
+Indic-first AI: two chat models plus five REST APIs for translation,
+transliteration, language identification, speech-to-text and text-to-speech.
+
+Sarvam is unusual in this codebase because **one API key spans two very
+different auth styles**. Its chat endpoint is OpenAI-compatible and accepts
+`Authorization: Bearer`; every other endpoint accepts only
+`api-subscription-key`. Both are served by a single stored credential.
+
+| | |
+|---|---|
+| **Provider id** | `sarvam` |
+| **Base URL** | `https://api.sarvam.ai` (chat at `/v1`) |
+| **Auth** | `api-subscription-key: <key>`; the chat route also accepts `Authorization: Bearer <key>` |
+| **Credential class** | [`SarvamCredential`](../server/nodes/model/_credentials.py) (`_LLMApiKey` → `ApiKeyCredential`) |
+| **Chat plugin** | [`server/nodes/model/sarvam_chat_model/`](../server/nodes/model/sarvam_chat_model/) |
+| **Service plugins** | [`server/nodes/sarvam/`](../server/nodes/sarvam/) |
+| **Palette groups** | `model` (chat), `language` (services) |
+| **Official docs** | <https://docs.sarvam.ai> |
+
+---
+
+## Chat models — an OpenAI-compat provider
+
+`sarvamChatModel` is a plain `ChatModelBase` subclass. The provider itself is
+registered declaratively in
+[`_compat.py`](../server/services/llm/providers/_compat.py) — one entry in
+`_COMPAT_PROVIDERS`, `factory=OpenAIProvider`, `base_url` pinned from
+`llm_defaults.json`. No `SarvamProvider` class exists and none is needed.
+
+| Model | Context | `max_output_tokens` in JSON | Notes |
+|---|---|---|---|
+| `sarvam-105b` | 131072 | 65536 | Flagship, `default_model` |
+| `sarvam-30b` | 65536 | 32768 | Cheaper tier |
+
+`sarvam-m` is deprecated and removed from the API; it is deliberately absent.
+
+**`max_output_tokens` is half the context window, not Sarvam's documented
+ceiling.** Sarvam publishes per-tier output caps (Business: 128000 for the
+105b, 64000 for the 30b), but those are ~98% of the context window, and
+`resolve_max_tokens` uses this value as *both* the default budget when a node
+leaves `max_tokens` unset *and* the clamp ceiling — a request at the documented
+ceiling could not fit any prompt. Half the window keeps paid tiers unclamped
+and usable. The tier table is recorded in `_max_output_note`.
+
+### Reasoning is entirely JSON-driven
+
+Sarvam runs reasoning **on by default** at `reasoning_effort: "medium"` and
+returns the trace in `message.reasoning_content`. Both halves are already
+handled generically:
+
+- `thinking_type: "effort"` → [`openai.py:99-100`](../server/services/llm/providers/openai.py) sets `params["reasoning_effort"]`
+- `reasoning_content` → [`openai.py:315-322`](../server/services/llm/providers/openai.py) lifts it into a `reasoning` `ContentBlock`, surfacing as `thinking`
+
+Two keys are **deliberately omitted** from the JSON block, and re-adding either
+is a bug:
+
+| Key | Why it must stay out |
+|---|---|
+| `thinking_default_on` | Emits Moonshot's proprietary `extra_body.thinking = {"type": "disabled"}`. Sarvam documents no way to disable reasoning and never defined that field. |
+| `reasoning_models` | Would set `temperature_allowed = False` and pin `temperature` to 1.0. Sarvam accepts temperature alongside reasoning (its own default is 0.5 with reasoning on, 0.2 without). |
+
+With both omitted the behaviour is right on **both** toggle states: thinking
+off sends no `reasoning_effort` and Sarvam applies its own default; thinking on
+sends ours.
+
+### No model-list endpoint — the `supports_model_listing` flag
+
+**Sarvam ships no `/v1/models` route.** Verified against
+<https://docs.sarvam.ai/openapi.json>: 25 paths, none for model listing.
+
+This matters more than it sounds. `OpenAIProvider.fetch_models` calls
+`client.models.list()`; the resulting 404 arrives as an `openai.OpenAIError`,
+which `ChatUnifier.fetch_models` converts to `NodeUserError`, which
+`AIService.fetch_models` **re-raises before reaching its curated fallback**
+([`ai.py:1232`](../server/services/ai.py)). Unhandled, a perfectly valid Sarvam
+key would fail validation in the Credentials modal *and* leave the model
+dropdown empty.
+
+The fix is a generic JSON flag rather than a Sarvam-shaped subclass:
+
+```json
+"supports_model_listing": false
+```
+
+[`OpenAIProvider.fetch_models`](../server/services/llm/providers/openai.py)
+reads it via `services.llm.config.supports_model_listing(provider)` and, when
+false, serves `curated_models(provider)` and validates the key with a
+one-token chat completion instead. An invalid key still raises the typed SDK
+error the unifier knows how to translate, so it remains a real credential
+check.
+
+The flag **defaults to `true`**, so the other twelve providers are untouched —
+`tests/llm/test_model_listing_fallback.py` asserts exactly that, and that
+Sarvam is the only opt-out.
+
+`popular_models` is `[]` per the repo's ≥1M-context policy (Sarvam tops out at
+131072), so `curated_models` falls through to the `max_output_tokens` keys.
+Both the per-node dropdown and the global model selector still list both
+models.
+
+---
+
+## Service nodes — `server/nodes/sarvam/`
+
+Five stateless REST nodes, palette group `language`, all
+`usable_as_tool = True` and `TaskQueue.REST_API`. There is no `_service.py`:
+nothing here owns long-lived state, so the folder is helpers plus node files.
+
+| Node type | Tool name | Endpoint | Billing unit |
+|---|---|---|---|
+| `sarvamTranslate` | `sarvam_translate` | `POST /translate` | characters |
+| `sarvamTransliterate` | `sarvam_transliterate` | `POST /transliterate` | characters |
+| `sarvamDetectLanguage` | `sarvam_detect_language` | `POST /text-lid` | characters |
+| `sarvamSpeechToText` | `sarvam_speech_to_text` | `POST /speech-to-text` (multipart) | seconds |
+| `sarvamTextToSpeech` | `sarvam_text_to_speech` | `POST /text-to-speech` | characters |
+
+All authenticate through `ctx.connection("sarvam")`, which injects
+`api-subscription-key` via `ApiKeyCredential.inject` — no per-node auth code.
+
+### Translate vs transliterate
+
+Routinely confused, and the skill spells it out for the LLM: translate changes
+the **language** ("Hello" → "नमस्ते"); transliterate changes the **script**
+while preserving the words ("namaste" → "नमस्ते"). The nodes reject an
+identical source/target pair rather than burning a paid call on a no-op.
+
+Per-model input caps are enforced client-side (`mayura:v1` 1000 chars,
+`sarvam-translate:v1` 2000, `/text-lid` 1000) so the LLM gets an actionable
+message instead of an opaque 422.
+
+### Speech-to-text: multipart and the 30-second wall
+
+This is the repo's first multipart upload. Rather than bypass the authed
+facade, `Connection.request` gained a generic `files=` parameter
+([`connection.py`](../server/services/plugin/connection.py)) — threaded into
+**both** the initial request and the auth-retry rebuild, so a 401 replays the
+file parts instead of an empty body. Pass file *bytes*, never an open handle,
+for exactly that reason.
+
+`audio_file` accepts **either** shape the frontend can produce: a path string
+(absolute, or relative to the workflow workspace) or the file widget's
+`{"type": "upload", "data": "<base64>", "filename", "mimeType"}` envelope.
+Typing it as `Union[str, Dict]` is deliberate — `whatsapp_send` declares the
+same field as `str` and only survives because its handler reads the raw dict.
+
+**The synchronous endpoint caps at 30 seconds of audio.** Longer recordings
+need Sarvam's Batch API, a separate job-based surface that is out of scope.
+Diarization is Batch-only too, so `diarized_transcript` is declared on the
+output model but will be `None` here.
+
+### Text-to-speech: files, not base64
+
+Sarvam returns audio as base64 inside the JSON body. A 2500-character v3
+request is roughly **12 MB of base64** — which would land in the
+`node_outputs` JSON column, ride a status-WebSocket broadcast, and (because the
+node is tool-exposed) be serialized into an LLM message.
+
+So the default is `return_audio: "file"`: audio is written under
+`<workspace>/audio/` and the node returns `file_path`. `return_audio: "base64"`
+is opt-in and capped at `_MAX_INLINE_B64 = 1_000_000`; over the cap
+`audio_base64` stays `None` and `note` explains why and points at the file
+mode. It never silently truncates.
+
+Sarvam may split long text into several chunks in `audios[]`. Each chunk is a
+standalone container with its own header, so **concatenating them byte-wise
+produces an unplayable file**. The node writes one file per chunk, points
+`file_path` at the first, lists all of them in `files`, and sets `note`.
+
+Voices are per model and do not overlap — 37 for `bulbul:v3`, 7 for
+`bulbul:v2`. Asking for a v2 voice on v3 is a `NodeUserError`, not a silent
+fallback. v2-only params (`pitch`, `loudness`, `enable_preprocessing`) and
+v3-only params (`temperature`, `dict_id`) are gated by `displayOptions` in the
+UI *and* filtered from the request body, since v3 rejects the v2 fields.
+
+---
+
+## Cost tracking
+
+`@Operation(cost=...)` is declarative metadata that nothing reads at runtime,
+so attribution is an explicit `track_sarvam_usage()` call per operation —
+the same shape as [`nodes/twitter/_base.py`](../server/nodes/twitter/_base.py).
+It never raises: a metrics failure must not fail a successful API call.
+
+Sarvam publishes INR list prices. [`pricing.json`](../server/config/pricing.json)
+stores USD converted at **1 INR = 0.0113 USD (~88.5 INR/USD, 2026-07)**, with
+the rate and the source figures recorded in a `_note` key. Both an
+`api.sarvam` block and an `operation_map.sarvam` block are required —
+`calculate_api_cost` returns 0 without the latter.
+
+Token pricing for the chat models lives separately under `llm.sarvam`.
+
+---
+
+## Icons
+
+`@lobehub/icons` has no Sarvam brand (278 entries, none matching), so the
+usual `lobehub:<brand>` route in `visuals.json` is unavailable. Instead the
+mark ships as SVG and is served by the backend:
+
+- `server/nodes/model/sarvam_chat_model/icon.svg` and `server/nodes/sarvam/icon.svg` → `GET /api/schemas/nodes/<type>/icon`
+- `server/credentials/icons/sarvam.svg` → `GET /api/schemas/credentials/sarvam/icon`
+
+The frontend's `/api/` branch in
+[`assets/icons/index.ts`](../client/src/assets/icons/index.ts) already resolves
+that wire format, so no icon-registry edit was needed — only an `<img>` wrapper
+in `AIProviderIcons.tsx` for the direct-FC consumers. Skills inherit the same
+icons automatically: `_parse_skill_metadata` tries `get_plugin_icon_path`
+before `visuals.json`.
+
+The shipped SVGs are a **geometric placeholder** in `#F97316`, not Sarvam's
+official mark. Replacing those three files is the whole change.
+
+---
+
+## Registration checklist
+
+Everything Sarvam touches, for reference when adding the next provider:
+
+| File | What |
+|---|---|
+| [`llm_defaults.json`](../server/config/llm_defaults.json) | `providers.sarvam` block (`base_url` required, `supports_model_listing: false`) |
+| [`_compat.py`](../server/services/llm/providers/_compat.py) | `"sarvam"` in `_COMPAT_PROVIDERS` |
+| [`llm/config.py`](../server/services/llm/config.py) | `curated_models()` / `supports_model_listing()` helpers |
+| [`llm/providers/openai.py`](../server/services/llm/providers/openai.py) | generic no-listing branch in `fetch_models` |
+| [`constants.py`](../server/constants.py) | `AI_CHAT_MODEL_TYPES` + a `detect_ai_provider` branch — **without the latter the node silently calls api.openai.com** |
+| [`llm/protocol.py`](../server/services/llm/protocol.py) | `provider_names["sarvam"]` for user-facing errors |
+| [`model_registry.py`](../server/services/model_registry.py) | `DEFAULT_TEMP_RANGES["sarvam"]` |
+| [`node_output_schemas.py`](../server/services/node_output_schemas.py) | `_CHAT_MODEL_TYPES` |
+| [`nodes/model/_credentials.py`](../server/nodes/model/_credentials.py) | `SarvamCredential` |
+| [`credential_providers.json`](../server/config/credential_providers.json) | catalogue entry (`extends: "_ai_base"`) |
+| [`node_allowlist.json`](../server/config/node_allowlist.json) | `sarvamChatModel` in `enabled_nodes` (normal-mode visible) |
+| [`groups.py`](../server/nodes/groups.py) | `language` palette group |
+| [`pricing.json`](../server/config/pricing.json) | `llm.sarvam` + `api.sarvam` + `operation_map.sarvam` |
+| 3× agent `Literal` | [ai_agent](../server/nodes/agent/ai_agent/__init__.py), [chat_agent](../server/nodes/agent/chat_agent/__init__.py), [_specialized](../server/nodes/agent/_specialized.py) — `test_plugin_shape.py` asserts **exact set equality** with the registry; miss one and CI fails |
+| Frontend | [`aiModelProviders.ts`](../client/src/lib/aiModelProviders.ts), [`AIProviderIcons.tsx`](../client/src/components/icons/AIProviderIcons.tsx) |
+
+## Tests
+
+| File | Locks |
+|---|---|
+| [`tests/llm/test_model_listing_fallback.py`](../server/tests/llm/test_model_listing_fallback.py) | The `supports_model_listing` contract both ways, incl. that Sarvam is the only opt-out and every other provider still calls `models.list()` |
+| [`tests/nodes/test_sarvam.py`](../server/tests/nodes/test_sarvam.py) | All five nodes: happy paths, `None`-stripping, per-model caps, v2/v3 param gating, TTS file-vs-base64 and multi-chunk, STT dual-shaped input |
+| [`tests/services/test_connection_multipart.py`](../server/tests/services/test_connection_multipart.py) | `Connection.request(files=)` incl. the auth-retry replay |
+| `tests/llm/test_provider_self_registration.py` | Sarvam in the compat matrix + its pinned `base_url` |
+| `tests/llm/test_live_providers.py` | Opt-in live smoke, gated on `SARVAM_API_KEY` |
+
+## Known limits
+
+- Speech-to-text: 30-second clips only (Batch API not wired); no diarization.
+- No streaming for chat, TTS or STT — the WebSocket/HTTP-stream surfaces are not wired.
+- Document digitization, pronunciation dictionaries and voice cloning are out of scope.
+- `wiki_grounding` (a Sarvam-specific chat param) is **not exposed**: an extra
+ `Params` field cannot reach the API today, because `execute_chat` reads a
+ closed key set off `flattened` and drops the rest. Adding it needs a generic
+ `provider_options` passthrough seam through `ChatUnifier` → `OpenAIProvider`
+ `extra_body`; shipping the field without that seam would render a checkbox
+ that does nothing.
diff --git a/server/config/credential_providers.json b/server/config/credential_providers.json
index 5dbfdb96..df2bf620 100644
--- a/server/config/credential_providers.json
+++ b/server/config/credential_providers.json
@@ -117,6 +117,20 @@
{ "key": "apiKey", "placeholder": "sk-..." }
]
},
+ "sarvam": {
+ "_description": "@lobehub/icons ships no Sarvam brand, so icon_ref points at the backend credential-icon endpoint (server/credentials/icons/sarvam.svg) — the same wire format apify / stripe / telegram already use.",
+ "extends": "_ai_base",
+ "icon_ref": "/api/schemas/credentials/sarvam/icon",
+ "name": "Sarvam AI",
+ "color": "#F97316",
+ "fields": [
+ {
+ "key": "apiKey",
+ "placeholder": "sk_...",
+ "help": "One subscription key from dashboard.sarvam.ai covers every Sarvam API — chat, translate, transliterate, language ID, speech-to-text and text-to-speech."
+ }
+ ]
+ },
"ollama": {
"_description": "Local Ollama server. The single field stores a base URL; the backend's _LocalLLM credential class returns a placeholder api_key, and execute_chat reads `{provider}_proxy` to override base_url via the existing OpenAI-style auth-delegation path. No `extends` — the field shape diverges from the cloud `_ai_base` template.",
diff --git a/server/config/llm_defaults.json b/server/config/llm_defaults.json
index bc0524a6..6583b904 100644
--- a/server/config/llm_defaults.json
+++ b/server/config/llm_defaults.json
@@ -312,6 +312,35 @@
},
"temperature_range": [0.0, 1.5]
},
+ "sarvam": {
+ "default_model": "sarvam-105b",
+ "popular_models": [],
+ "_popular_note": "Empty per the 1M-context policy — sarvam-105b tops out at 131072. Both models stay reachable via the per-node dropdown (fetch_models returns the curated list) and via the global selector, which falls back to the max_output_tokens keys when popular_models is empty.",
+ "_models_note": "sarvam-105b (128K ctx) and sarvam-30b (64K ctx), OpenAI-compatible at api.sarvam.ai/v1. sarvam-m is deprecated/removed and deliberately absent. Reasoning is ON by default (reasoning_effort defaults to 'medium' server-side) and the trace comes back as message.reasoning_content, which OpenAIProvider._normalize already reads.",
+ "detection_patterns": ["sarvam"],
+ "base_url": "https://api.sarvam.ai/v1",
+ "models_endpoint": "",
+ "supports_model_listing": false,
+ "_models_listing_note": "Sarvam ships NO model-list endpoint — verified against https://docs.sarvam.ai/openapi.json (25 paths, none for model listing). OpenAIProvider.fetch_models reads this flag and swaps models.list() for a 1-token chat probe plus the curated list. Without it the 404 becomes an openai.OpenAIError, ChatUnifier turns that into NodeUserError, and AIService.fetch_models re-raises before its curated fallback — breaking both credential validation and the model dropdown.",
+ "api_key_param": "api_key",
+ "max_tokens_param": "max_tokens",
+ "supported_params": ["temperature", "max_tokens", "top_p", "frequency_penalty", "presence_penalty", "stop", "seed", "n", "tools", "tool_choice", "response_format", "reasoning_effort"],
+ "max_output_tokens": {
+ "sarvam-105b": 65536,
+ "sarvam-30b": 32768,
+ "_default": 8192
+ },
+ "_max_output_note": "Sarvam documents per-tier output ceilings of Starter 4096 / Pro 16384 / Business 128000 (105b) and 4096 / 8192 / 64000 (30b). The Business figures are ~98% of each context window, and resolve_max_tokens uses these values BOTH as the default budget when the node leaves max_tokens unset AND as the clamp ceiling — a request at that budget could not fit any prompt. Half the window keeps paid tiers unclamped while staying usable; same shape as groq's gpt-oss-120b (131072 ctx / 65536 out).",
+ "context_length": {
+ "sarvam-105b": 131072,
+ "sarvam-30b": 65536,
+ "_default": 65536
+ },
+ "thinking_models": ["sarvam-"],
+ "thinking_type": "effort",
+ "_thinking_note": "reasoning_models is deliberately empty: listing sarvam there would set temperature_allowed=False and pin temperature to 1.0, but Sarvam accepts temperature alongside reasoning. thinking_default_on is deliberately absent too — it emits Moonshot's proprietary extra_body.thinking={'type':'disabled'}, which Sarvam never documented. With both omitted, thinking off = Sarvam's own default (reasoning on, effort medium) and thinking on = our reasoning_effort.",
+ "temperature_range": [0.0, 2.0]
+ },
"ollama": {
"_description": "Local Ollama server (OpenAI-compatible /v1). No `default_model` because the dropdown should reflect the user's actually-pulled models — fetch_models hits the user's saved {provider}_proxy URL and returns whatever Ollama reports; when the server is offline we want an empty list (a 'start your server' cue), not a placeholder name the user almost certainly doesn't have.",
diff --git a/server/config/node_allowlist.json b/server/config/node_allowlist.json
index d8f4f2cc..b69b75b1 100644
--- a/server/config/node_allowlist.json
+++ b/server/config/node_allowlist.json
@@ -19,6 +19,7 @@
"openaiChatModel",
"anthropicChatModel",
"geminiChatModel",
+ "sarvamChatModel",
"calculatorTool",
"currentTimeTool",
diff --git a/server/config/pricing.json b/server/config/pricing.json
index 3c016fd5..6fb9b517 100644
--- a/server/config/pricing.json
+++ b/server/config/pricing.json
@@ -88,6 +88,12 @@
"open-mistral-nemo": {"input": 0.15, "output": 0.15},
"_default": {"input": 0.20, "output": 0.60}
},
+ "sarvam": {
+ "_note": "Sarvam publishes INR list prices; converted at 1 INR = 0.0113 USD (~88.5 INR/USD, 2026-07). Source rates per MTok: sarvam-105b 4 in / 16 out / 2.5 cached; sarvam-30b 2.5 / 10 / 1.5. _default mirrors sarvam-105b (the provider default_model) so an unresolved id never under-reports. PricingService._build_llm_registry skips non-dict values, so this key is inert.",
+ "sarvam-105b": {"input": 0.045, "output": 0.181, "cache_read": 0.028},
+ "sarvam-30b": {"input": 0.028, "output": 0.113, "cache_read": 0.017},
+ "_default": {"input": 0.045, "output": 0.181, "cache_read": 0.028}
+ },
"ollama": {
"_description": "Local inference is free at the API layer — user-borne hardware costs are not tracked here.",
"_default": {"input": 0.00, "output": 0.00}
@@ -246,6 +252,18 @@
"sonar_search": 0.005,
"sonar_pro_search": 0.005,
"_default": 0.005
+ },
+ "sarvam": {
+ "_description": "Sarvam non-chat APIs. Text endpoints bill per CHARACTER and speech-to-text bills per SECOND, so these are per-unit prices and the nodes pass the unit count as resource_count. Converted from Sarvam's INR list prices at 1 INR = 0.0113 USD (~88.5 INR/USD, 2026-07): translate 20 INR/10K chars, language ID 3.5 INR/10K chars, TTS bulbul:v3 30 INR/10K chars and bulbul:v2 15 INR/10K chars, speech-to-text 30 INR/hour. Transliteration has no separately published rate and is priced as translation. Chat-model token pricing lives under `llm.sarvam`.",
+ "_source": "https://docs.sarvam.ai/api/getting-started/pricing",
+ "_updated": "2026-07",
+ "translate": 0.0000226,
+ "transliterate": 0.0000226,
+ "detect_language": 0.00000396,
+ "text_to_speech": 0.0000339,
+ "text_to_speech_v2": 0.00001695,
+ "speech_to_text": 0.00009417,
+ "_default": 0.0000226
}
},
@@ -342,6 +360,14 @@
},
"perplexity": {
"sonar_search": "sonar_search"
+ },
+ "sarvam": {
+ "translate": "translate",
+ "transliterate": "transliterate",
+ "detect_language": "detect_language",
+ "text_to_speech": "text_to_speech",
+ "text_to_speech_v2": "text_to_speech_v2",
+ "speech_to_text": "speech_to_text"
}
},
diff --git a/server/constants.py b/server/constants.py
index d25f8faf..93e20d16 100644
--- a/server/constants.py
+++ b/server/constants.py
@@ -21,6 +21,7 @@ AI_CHAT_MODEL_TYPES: FrozenSet[str] = frozenset(
"deepseekChatModel",
"kimiChatModel",
"mistralChatModel",
+ "sarvamChatModel",
# Local-server providers (Phase 1 of the LiteLLM adoption — see
# plans/i-plan-to-implement-nested-orbit.md).
"ollamaChatModel",
@@ -433,6 +434,8 @@ def detect_ai_provider(node_type: str, parameters: dict = None) -> str:
return "kimi"
if "mistral" in nt:
return "mistral"
+ if "sarvam" in nt:
+ return "sarvam"
if "cerebras" in nt:
return "cerebras"
if "groq" in nt:
diff --git a/server/credentials/icons/sarvam.svg b/server/credentials/icons/sarvam.svg
new file mode 100644
index 00000000..39df9ea2
--- /dev/null
+++ b/server/credentials/icons/sarvam.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="Sarvam AI">
+ <rect width="24" height="24" rx="5" fill="#F97316"/>
+ <circle cx="12" cy="12" r="2.2" fill="#FFFFFF"/>
+ <path d="M15.82 8.18a5.4 5.4 0 0 1 0 7.64" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round"/>
+ <path d="M8.18 15.82a5.4 5.4 0 0 1 0-7.64" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round"/>
+ <path d="M18.36 5.64a9 9 0 0 1 0 12.72" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round" opacity="0.55"/>
+ <path d="M5.64 18.36a9 9 0 0 1 0-12.72" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round" opacity="0.55"/>
+</svg>
diff --git a/server/nodes/README.md b/server/nodes/README.md
index b7f48728..21b3b8d5 100644
--- a/server/nodes/README.md
+++ b/server/nodes/README.md
@@ -132,6 +132,9 @@ vercel/ — Vercel (CLI deploy / inspect / list / custom passthrough)
github/ — GitHub (gh CLI: clone / PRs / issues / custom; palette group "vcs")
cloudflare/ — Cloudflare (cf CLI: zones / DNS / GraphQL analytics / custom; palette group "deployment")
gcloud/ — Google Cloud (gcloud CLI: projects / Compute Engine / Cloud Run / Cloud Storage / custom; palette group "deployment")
+sarvam/ — Sarvam AI text + speech REST APIs (translate / transliterate / detect_language /
+ speech_to_text / text_to_speech; palette group "language"). Its chat models are a
+ separate plugin at model/sarvam_chat_model/ and share one SarvamCredential.
```
---
@@ -146,7 +149,8 @@ these first before writing new code:
|---|---|---|
| `agent/` | `_inline.prepare_agent_call` | One-shot pre-dispatch for every agent (memory + skill + tool + teammate collection) |
| `agent/` | `_specialized.SpecializedAgentBase` | Base for 13 specialized agents |
-| `model/` | `_base.ChatModelBase` | 11 chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` |
+| `model/` | `_base.ChatModelBase` | 12 chat models inherit → same `@Operation("chat")` body that calls `ai_service.execute_chat` |
+| `sarvam/` | `_base.post_json` / `_base.post_multipart` / `_base.track_sarvam_usage` | 5 stateless REST nodes share one `api-subscription-key` connection, `None`-stripping request builder, and manual usage tracking (no `_service.py` — nothing long-lived to own) |
| `android/` | `_base.AndroidServiceBase` | 16 Android services inherit; payload translation + `SERVICE_ID_MAP` lives on this base |
| `android/` | `_base.execute_android_service_tool` | AI-tool dispatcher — called from `services/handlers/tools.py` for direct service tools (the `androidTool` aggregator + `execute_android_toolkit` were retired) |
| `code/` | `_base.CodeExecutorBase` + `_nodejs.NodeJSClient` | Python/JS/TS executors; `monty_executor/` is sandboxed Python via `pydantic-monty` (enforced limits + opt-in capabilities) |
@@ -187,7 +191,7 @@ from ._credentials import TwitterCredential # shared with 3 sibling
| `nodes/twitter/` | `TwitterCredential` (OAuth2 + PKCE) | twitter_send / _search / _user / _receive |
| `nodes/telegram/` | `TelegramCredential` (bot token + owner chat id) | telegram_send / _receive |
| `nodes/scraper/` | `ApifyCredential` (Bearer) | apify_actor |
-| `nodes/model/` | 12 LLM credential classes: 10 cloud (`OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / xAI`) plus Ollama / LM Studio | 11 chat models (xAI has no standalone chat-model node) |
+| `nodes/model/` | 13 LLM credential classes: 11 cloud (`OpenAI / Anthropic / Gemini / OpenRouter / Groq / Cerebras / DeepSeek / Kimi / Mistral / xAI / Sarvam`) plus Ollama / LM Studio | 12 chat models (xAI has no standalone chat-model node) **plus the 5 `nodes/sarvam/` service nodes**, which import `SarvamCredential` from here — one stored key serves Sarvam's OpenAI-compatible chat endpoint *and* its `api-subscription-key` REST APIs |
| `nodes/search/` | `BraveSearch / Serper / Perplexity` inlined in each plugin file | single-use per plugin |
Declare inline only when genuinely single-use (see
diff --git a/server/nodes/agent/_specialized.py b/server/nodes/agent/_specialized.py
index b31f89e3..b8a1fde9 100644
--- a/server/nodes/agent/_specialized.py
+++ b/server/nodes/agent/_specialized.py
@@ -46,6 +46,7 @@ class SpecializedAgentParams(BaseModel):
"deepseek",
"kimi",
"mistral",
+ "sarvam",
# Local-server providers — see ai_agent.Params for the proxy_url
# rationale. Same fix; same reason.
"ollama",
diff --git a/server/nodes/agent/ai_agent/__init__.py b/server/nodes/agent/ai_agent/__init__.py
index faa64ec3..9bfb2b23 100644
--- a/server/nodes/agent/ai_agent/__init__.py
+++ b/server/nodes/agent/ai_agent/__init__.py
@@ -49,6 +49,7 @@ class AIAgentParams(BaseModel):
"deepseek",
"kimi",
"mistral",
+ "sarvam",
# Local-server providers — agent execution reads
# ``{provider}_proxy`` to point the native OpenAI client at the
# user's localhost server. Without these entries the dropdown
diff --git a/server/nodes/agent/chat_agent/__init__.py b/server/nodes/agent/chat_agent/__init__.py
index 9b802442..c5105114 100644
--- a/server/nodes/agent/chat_agent/__init__.py
+++ b/server/nodes/agent/chat_agent/__init__.py
@@ -36,6 +36,7 @@ class ChatAgentParams(BaseModel):
"deepseek",
"kimi",
"mistral",
+ "sarvam",
# Local-server providers — see ai_agent.Params for the proxy_url
# rationale. Same fix; same reason.
"ollama",
diff --git a/server/nodes/groups.py b/server/nodes/groups.py
index 409c184c..6a10300c 100644
--- a/server/nodes/groups.py
+++ b/server/nodes/groups.py
@@ -57,4 +57,5 @@ register_group(key="scraper", metadata={"label": "Scrapers", "icon": "🕸", "co
register_group(key="filesystem", metadata={"label": "Filesystem", "icon": "📁", "color": "#8be9fd", "visibility": "dev"})
register_group(key="service", metadata={"label": "Services", "icon": "⚙️", "color": "#50fa7b", "visibility": "dev"})
register_group(key="text", metadata={"label": "Text", "icon": "📝", "color": "#bd93f9", "visibility": "dev"})
+register_group(key="language", metadata={"label": "Language & Speech", "icon": "🗣️", "color": "#F97316", "visibility": "dev"})
register_group(key="memory", metadata={"label": "Memory", "icon": "💾", "color": "#f1fa8c", "visibility": "dev"})
diff --git a/server/nodes/model/_credentials.py b/server/nodes/model/_credentials.py
index 13b0ecd9..c592583b 100644
--- a/server/nodes/model/_credentials.py
+++ b/server/nodes/model/_credentials.py
@@ -135,6 +135,28 @@ class XaiCredential(_LLMApiKey):
docs_url = "https://console.x.ai"
+class SarvamCredential(_LLMApiKey):
+ """One subscription key for every Sarvam API.
+
+ Sarvam's chat endpoint is OpenAI-compatible and accepts the key as a
+ Bearer token, which is what the openai SDK sends — so the chat path
+ never reads ``key_name``. Its other APIs (translate / transliterate /
+ text-lid / speech-to-text / text-to-speech, all under
+ ``server/nodes/sarvam/``) accept ONLY ``api-subscription-key``, and
+ those nodes authenticate through ``ctx.connection("sarvam")`` ->
+ :meth:`ApiKeyCredential.inject`. Declaring the native header here
+ means a single stored key serves both surfaces.
+
+ Same override shape as :class:`AnthropicCredential`'s ``x-api-key``.
+ """
+
+ id = "sarvam"
+ display_name = "Sarvam AI"
+ docs_url = "https://dashboard.sarvam.ai"
+ key_name = "api-subscription-key"
+ key_location = "header"
+
+
class _LocalLLM(_LLMApiKey):
"""Base for local-server credentials (Ollama, LM Studio).
diff --git a/server/nodes/model/sarvam_chat_model/__init__.py b/server/nodes/model/sarvam_chat_model/__init__.py
new file mode 100644
index 00000000..7310cac3
--- /dev/null
+++ b/server/nodes/model/sarvam_chat_model/__init__.py
@@ -0,0 +1,47 @@
+from typing import Literal, Optional
+
+from pydantic import Field
+
+from .._base import ChatModelBase, ChatModelParams
+
+from .._credentials import SarvamCredential
+
+
+class SarvamChatModelParams(ChatModelParams):
+ frequency_penalty: Optional[float] = Field(
+ default=0.0,
+ ge=-2.0,
+ le=2.0,
+ json_schema_extra={"numberStepSize": 0.1},
+ )
+ presence_penalty: Optional[float] = Field(
+ default=0.0,
+ ge=-2.0,
+ le=2.0,
+ json_schema_extra={"numberStepSize": 0.1},
+ )
+ response_format: Optional[Literal["text", "json_object"]] = Field(default="text")
+ # Sarvam runs reasoning ON by default at effort "medium"; this toggle only
+ # decides whether we override that effort. There is no documented way to
+ # turn reasoning off, which is why the provider block omits
+ # ``thinking_default_on`` — that key emits Moonshot's proprietary
+ # ``extra_body.thinking = {"type": "disabled"}``.
+ thinking_enabled: bool = Field(default=False)
+ reasoning_effort: Optional[Literal["low", "medium", "high"]] = Field(
+ default="medium",
+ json_schema_extra={"displayOptions": {"show": {"thinking_enabled": [True]}}},
+ )
+
+
+class SarvamChatModelNode(ChatModelBase):
+ type = "sarvamChatModel"
+ display_name = "Sarvam AI"
+ subtitle = "Chat Model"
+ group = ("model",)
+ description = (
+ "Sarvam AI Indic-first models (sarvam-105b 128K, sarvam-30b 64K) with "
+ "always-on reasoning across 10 Indian languages plus English"
+ )
+
+ credentials = (SarvamCredential,)
+ Params = SarvamChatModelParams
diff --git a/server/nodes/model/sarvam_chat_model/icon.svg b/server/nodes/model/sarvam_chat_model/icon.svg
new file mode 100644
index 00000000..39df9ea2
--- /dev/null
+++ b/server/nodes/model/sarvam_chat_model/icon.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="Sarvam AI">
+ <rect width="24" height="24" rx="5" fill="#F97316"/>
+ <circle cx="12" cy="12" r="2.2" fill="#FFFFFF"/>
+ <path d="M15.82 8.18a5.4 5.4 0 0 1 0 7.64" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round"/>
+ <path d="M8.18 15.82a5.4 5.4 0 0 1 0-7.64" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round"/>
+ <path d="M18.36 5.64a9 9 0 0 1 0 12.72" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round" opacity="0.55"/>
+ <path d="M5.64 18.36a9 9 0 0 1 0-12.72" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round" opacity="0.55"/>
+</svg>
diff --git a/server/nodes/model/sarvam_chat_model/meta.json b/server/nodes/model/sarvam_chat_model/meta.json
new file mode 100644
index 00000000..203caa61
--- /dev/null
+++ b/server/nodes/model/sarvam_chat_model/meta.json
@@ -0,0 +1,3 @@
+{
+ "color": "#F97316"
+}
diff --git a/server/nodes/sarvam/__init__.py b/server/nodes/sarvam/__init__.py
new file mode 100644
index 00000000..bc7c7543
--- /dev/null
+++ b/server/nodes/sarvam/__init__.py
@@ -0,0 +1,47 @@
+"""Sarvam AI service plugins.
+
+Five stateless REST nodes over ``api.sarvam.ai`` — translate,
+transliterate, language ID, speech-to-text and text-to-speech — sharing
+one ``api-subscription-key`` credential. Node classes register themselves
+on import via ``BaseNode.__init_subclass__``; the only explicit wiring
+here is the output-schema registry, which the parameter panel reads to
+render "Input Data & Variables" for downstream nodes.
+
+Sarvam's OpenAI-compatible chat endpoint is a separate plugin
+(``nodes/model/sarvam_chat_model``) registered through the standard
+LLM-provider path, and both surfaces share ``SarvamCredential``.
+"""
+
+from services.node_output_schemas import register_output_schema
+
+from .sarvam_detect_language import (
+ SarvamDetectLanguageNode,
+ SarvamDetectLanguageOutput,
+)
+from .sarvam_speech_to_text import (
+ SarvamSpeechToTextNode,
+ SarvamSpeechToTextOutput,
+)
+from .sarvam_text_to_speech import (
+ SarvamTextToSpeechNode,
+ SarvamTextToSpeechOutput,
+)
+from .sarvam_translate import SarvamTranslateNode, SarvamTranslateOutput
+from .sarvam_transliterate import (
+ SarvamTransliterateNode,
+ SarvamTransliterateOutput,
+)
+
+register_output_schema(SarvamTranslateNode.type, SarvamTranslateOutput)
+register_output_schema(SarvamTransliterateNode.type, SarvamTransliterateOutput)
+register_output_schema(SarvamDetectLanguageNode.type, SarvamDetectLanguageOutput)
+register_output_schema(SarvamSpeechToTextNode.type, SarvamSpeechToTextOutput)
+register_output_schema(SarvamTextToSpeechNode.type, SarvamTextToSpeechOutput)
+
+__all__ = [
+ "SarvamDetectLanguageNode",
+ "SarvamSpeechToTextNode",
+ "SarvamTextToSpeechNode",
+ "SarvamTranslateNode",
+ "SarvamTransliterateNode",
+]
diff --git a/server/nodes/sarvam/_base.py b/server/nodes/sarvam/_base.py
new file mode 100644
index 00000000..5806fcf1
--- /dev/null
+++ b/server/nodes/sarvam/_base.py
@@ -0,0 +1,141 @@
+"""Sarvam AI shared helpers.
+
+Five plugins (translate / transliterate / detect_language / speech_to_text /
+text_to_speech) hit ``https://api.sarvam.ai`` with the same
+``api-subscription-key`` header, which :class:`SarvamCredential` injects
+automatically through ``ctx.connection("sarvam")``. There is no service
+singleton here — these are stateless REST calls, so per the plugin
+cookbook the folder stays helpers + node files.
+
+The credential itself lives with the other LLM credentials in
+``nodes/model/_credentials.py`` because the *same* key also authenticates
+Sarvam's OpenAI-compatible chat endpoint (``sarvamChatModel``). One stored
+key, one catalogue entry, both surfaces.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import httpx
+
+from core.logging import get_logger
+from services.plugin import NodeContext, NodeUserError
+from services.pricing import get_pricing_service
+
+logger = get_logger(__name__)
+
+SARVAM_BASE_URL = "https://api.sarvam.ai"
+
+# Sarvam's own language-code vocabulary (BCP-47-ish, always ``-IN``).
+# Translate accepts the full 22-language set; transliterate and TTS accept
+# the 10-language core plus English. Kept as tuples so the node modules can
+# splat them into ``Literal[...]`` without drifting apart.
+TRANSLATE_LANGUAGES = (
+ "as-IN", "bn-IN", "brx-IN", "doi-IN", "en-IN", "gu-IN", "hi-IN",
+ "kn-IN", "kok-IN", "ks-IN", "mai-IN", "ml-IN", "mni-IN", "mr-IN",
+ "ne-IN", "od-IN", "pa-IN", "sa-IN", "sat-IN", "sd-IN", "ta-IN",
+ "te-IN", "ur-IN",
+)
+
+CORE_LANGUAGES = (
+ "bn-IN", "en-IN", "gu-IN", "hi-IN", "kn-IN", "ml-IN", "mr-IN",
+ "od-IN", "pa-IN", "ta-IN", "te-IN",
+)
+
+
+async def post_json(
+ ctx: NodeContext, path: str, body: Dict[str, Any]
+) -> Dict[str, Any]:
+ """POST a JSON body to ``api.sarvam.ai{path}`` and return the payload.
+
+ Drops ``None`` values so an unset optional never reaches the API as an
+ explicit null (Sarvam rejects several of those with a 422). Non-2xx
+ responses become :class:`NodeUserError` carrying Sarvam's own message
+ — these are almost always user-correctable (bad language pair, text
+ over the per-model character cap, missing key).
+ """
+ payload = {k: v for k, v in body.items() if v is not None}
+ async with ctx.connection("sarvam") as conn:
+ response = await conn.post(
+ f"{SARVAM_BASE_URL}{path}",
+ json=payload,
+ headers={"Content-Type": "application/json"},
+ )
+ _raise_for_status(response, path)
+ return response.json()
+
+
+async def post_multipart(
+ ctx: NodeContext, path: str, *, files: Any, data: Dict[str, Any]
+) -> Dict[str, Any]:
+ """POST ``multipart/form-data`` to ``api.sarvam.ai{path}``.
+
+ No ``Content-Type`` header — httpx generates the multipart boundary.
+ ``files`` must carry raw bytes rather than a file handle so the
+ Connection's auth-retry can replay the request intact.
+ """
+ form = {k: str(v) for k, v in data.items() if v is not None}
+ async with ctx.connection("sarvam") as conn:
+ response = await conn.post(
+ f"{SARVAM_BASE_URL}{path}", files=files, data=form
+ )
+ _raise_for_status(response, path)
+ return response.json()
+
+
+def _raise_for_status(response: httpx.Response, path: str) -> None:
+ if response.status_code < 400:
+ return
+ detail = ""
+ try:
+ body = response.json()
+ if isinstance(body, dict):
+ error = body.get("error")
+ if isinstance(error, dict):
+ detail = str(error.get("message") or error.get("code") or "")
+ detail = detail or str(body.get("message") or body.get("detail") or "")
+ except Exception:
+ detail = response.text[:400]
+ raise NodeUserError(
+ f"Sarvam {path} failed ({response.status_code})"
+ + (f": {detail}" if detail else "")
+ )
+
+
+async def track_sarvam_usage(
+ ctx: NodeContext, action: str, resource_count: int
+) -> Dict[str, float]:
+ """Record a Sarvam API call in ``api_usage_metrics``.
+
+ ``@Operation(cost=...)`` is declarative metadata that nothing reads at
+ runtime, so cost attribution is an explicit call — same shape as
+ ``nodes/twitter/_base.track_twitter_usage``. ``resource_count`` is the
+ billable unit for the operation: characters for the text and speech
+ endpoints, seconds of audio for transcription.
+
+ Never raises: a metrics failure must not fail a successful API call.
+ """
+ try:
+ from services.plugin.deps import get_database
+
+ pricing = get_pricing_service()
+ cost_data = pricing.calculate_api_cost("sarvam", action, resource_count)
+ await get_database().save_api_usage_metric(
+ {
+ "session_id": ctx.session_id,
+ "node_id": ctx.node_id,
+ "workflow_id": ctx.workflow_id,
+ "service": "sarvam",
+ "operation": cost_data.get("operation", action),
+ "endpoint": action,
+ "resource_count": resource_count,
+ "cost": cost_data.get("total_cost", 0.0),
+ }
+ )
+ return cost_data
+ except Exception as e:
+ logger.warning(
+ "sarvam usage tracking failed", action=action, error=str(e)
+ )
+ return {}
diff --git a/server/nodes/sarvam/icon.svg b/server/nodes/sarvam/icon.svg
new file mode 100644
index 00000000..39df9ea2
--- /dev/null
+++ b/server/nodes/sarvam/icon.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="24" height="24" role="img" aria-label="Sarvam AI">
+ <rect width="24" height="24" rx="5" fill="#F97316"/>
+ <circle cx="12" cy="12" r="2.2" fill="#FFFFFF"/>
+ <path d="M15.82 8.18a5.4 5.4 0 0 1 0 7.64" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round"/>
+ <path d="M8.18 15.82a5.4 5.4 0 0 1 0-7.64" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round"/>
+ <path d="M18.36 5.64a9 9 0 0 1 0 12.72" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round" opacity="0.55"/>
+ <path d="M5.64 18.36a9 9 0 0 1 0-12.72" fill="none" stroke="#FFFFFF" stroke-width="1.8" stroke-linecap="round" opacity="0.55"/>
+</svg>
diff --git a/server/nodes/sarvam/meta.json b/server/nodes/sarvam/meta.json
new file mode 100644
index 00000000..203caa61
--- /dev/null
+++ b/server/nodes/sarvam/meta.json
@@ -0,0 +1,3 @@
+{
+ "color": "#F97316"
+}
diff --git a/server/nodes/sarvam/sarvam_detect_language.py b/server/nodes/sarvam/sarvam_detect_language.py
new file mode 100644
index 00000000..1866a831
--- /dev/null
+++ b/server/nodes/sarvam/sarvam_detect_language.py
@@ -0,0 +1,93 @@
+"""Sarvam Detect Language — POST /text-lid (language + script ID)."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+
+from ._base import post_json, track_sarvam_usage
+from ..model._credentials import SarvamCredential
+
+_MAX_INPUT = 1000
+
+
+class SarvamDetectLanguageParams(BaseModel):
+ tool_name: str = Field(
+ default="sarvam_detect_language",
+ description="Override name shown to the LLM when used as a tool.",
+ )
+ tool_description: str = Field(
+ default=(
+ "Identify which Indian language a piece of text is written in, and in which "
+ "script. Returns BCP-47 language and ISO 15924 script codes."
+ ),
+ description="Override description shown to the LLM when used as a tool.",
+ json_schema_extra={"rows": 3},
+ )
+ input: str = Field(
+ ...,
+ min_length=1,
+ description="Text whose language should be identified (max 1000 characters).",
+ json_schema_extra={"rows": 4},
+ )
+
+ model_config = {"extra": "ignore"}
+
+
+class SarvamDetectLanguageOutput(BaseModel):
+ # Sarvam returns nulls when it cannot classify the input, so both stay
+ # Optional rather than defaulting to a misleading empty string.
+ language_code: Optional[str] = None
+ script_code: Optional[str] = None
+ request_id: Optional[str] = None
+
+ model_config = {"extra": "allow"}
+
+
+class SarvamDetectLanguageNode(ActionNode):
+ type = "sarvamDetectLanguage"
+ display_name = "Sarvam Detect Language"
+ subtitle = "Language ID"
+ group = ("language", "tool")
+ description = "Identify the language and script of Indic or English text"
+ component_kind = "square"
+ tool_name = "sarvam_detect_language"
+ tool_description = (
+ "Identify which Indian language a piece of text is written in, and in which script. "
+ "Returns a BCP-47 language_code (e.g. hi-IN) and an ISO 15924 script_code (e.g. Deva). "
+ "Both may be null when the text is too short or ambiguous to classify. Useful before "
+ "calling sarvam_translate with an explicit source language."
+ )
+ handles = (
+ {"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
+ {"name": "output-main", "kind": "output", "position": "right", "label": "Output", "role": "main"},
+ )
+ credentials = (SarvamCredential,)
+ annotations = {"destructive": False, "readonly": True, "open_world": True}
+ task_queue = TaskQueue.REST_API
+ usable_as_tool = True
+
+ Params = SarvamDetectLanguageParams
+ Output = SarvamDetectLanguageOutput
+
+ @Operation("detect", cost={"service": "sarvam", "action": "detect_language", "count": 1})
+ async def detect(
+ self, ctx: NodeContext, params: SarvamDetectLanguageParams
+ ) -> SarvamDetectLanguageOutput:
+ if len(params.input) > _MAX_INPUT:
+ raise NodeUserError(
+ f"input is {len(params.input)} characters; /text-lid accepts at most "
+ f"{_MAX_INPUT}. Truncate or sample the text before detecting."
+ )
+
+ data = await post_json(ctx, "/text-lid", {"input": params.input})
+
+ await track_sarvam_usage(ctx, "detect_language", len(params.input))
+ return SarvamDetectLanguageOutput(
+ language_code=data.get("language_code"),
+ script_code=data.get("script_code"),
+ request_id=data.get("request_id"),
+ )
diff --git a/server/nodes/sarvam/sarvam_speech_to_text.py b/server/nodes/sarvam/sarvam_speech_to_text.py
new file mode 100644
index 00000000..a80370d5
--- /dev/null
+++ b/server/nodes/sarvam/sarvam_speech_to_text.py
@@ -0,0 +1,201 @@
+"""Sarvam Speech to Text — POST /speech-to-text (multipart transcription)."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import mimetypes
+from pathlib import Path
+from typing import Any, Dict, List, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+
+from ._base import post_multipart, track_sarvam_usage
+from ..model._credentials import SarvamCredential
+
+# The synchronous REST endpoint is documented for clips under 30 seconds;
+# anything longer needs Sarvam's Batch API, which is a different job-based
+# surface and out of scope for this node.
+_MAX_SECONDS = 30
+# Guard against a caller pasting a multi-hundred-MB blob into the param.
+_MAX_BYTES = 24 * 1024 * 1024
+
+
+class SarvamSpeechToTextParams(BaseModel):
+ tool_name: str = Field(
+ default="sarvam_speech_to_text",
+ description="Override name shown to the LLM when used as a tool.",
+ )
+ tool_description: str = Field(
+ default=(
+ "Transcribe a short audio clip (under 30 seconds) in any of 23 Indian "
+ "languages. Can also translate speech directly into English."
+ ),
+ description="Override description shown to the LLM when used as a tool.",
+ json_schema_extra={"rows": 3},
+ )
+ # Accepts either a workspace/absolute path OR the upload envelope the
+ # file widget emits ({type, data, filename, mimeType}) — the frontend
+ # sends whichever the user chose, so the field must tolerate both.
+ audio_file: Union[str, Dict[str, Any]] = Field(
+ default="",
+ description="Path to an audio file, or an uploaded file.",
+ json_schema_extra={
+ "widget": "file",
+ "accept": "audio/*,.wav,.mp3,.m4a,.ogg,.opus,.flac,.aac,.webm,.amr",
+ },
+ )
+ model: Literal["saaras:v3", "saarika:v2.5"] = Field(
+ default="saaras:v3",
+ description="saaras:v3 covers 23 languages; saarika:v2.5 is the legacy 11-language model.",
+ )
+ language_code: str = Field(
+ default="unknown",
+ description="BCP-47 code of the spoken language, or 'unknown' to auto-detect.",
+ )
+ mode: Literal["transcribe", "translate", "verbatim", "translit", "codemix"] = Field(
+ default="transcribe",
+ description=(
+ "transcribe = native script; translate = English output; verbatim keeps "
+ "disfluencies; translit = Roman script; codemix preserves mixed-language input. "
+ "Everything except transcribe/translate requires saaras:v3."
+ ),
+ )
+ input_audio_codec: Optional[Literal["pcm_s16le", "pcm_l16", "pcm_raw"]] = Field(
+ default=None,
+ description="Only needed for headerless PCM; every other format is auto-detected.",
+ )
+
+ model_config = {"extra": "ignore"}
+
+
+class SarvamSpeechToTextOutput(BaseModel):
+ transcript: str = ""
+ language_code: Optional[str] = None
+ language_probability: Optional[float] = None
+ # Present only when Sarvam returns them; the sync endpoint omits
+ # diarization entirely (Batch API only).
+ timestamps: Optional[Dict[str, Any]] = None
+ diarized_transcript: Optional[Dict[str, Any]] = None
+ request_id: Optional[str] = None
+
+ model_config = {"extra": "allow"}
+
+
+class SarvamSpeechToTextNode(ActionNode):
+ type = "sarvamSpeechToText"
+ display_name = "Sarvam Speech to Text"
+ subtitle = "Transcribe Audio"
+ group = ("language", "tool")
+ description = "Transcribe or translate short audio clips across 23 Indian languages"
+ component_kind = "square"
+ tool_name = "sarvam_speech_to_text"
+ tool_description = (
+ "Transcribe a short audio clip (under 30 seconds) in any of 23 Indian languages. "
+ "Pass a file path in `audio_file`. Set mode='translate' to get English text from "
+ "non-English speech. Leave language_code='unknown' to auto-detect. Returns the "
+ "transcript and the detected language."
+ )
+ handles = (
+ {"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
+ {"name": "output-main", "kind": "output", "position": "right", "label": "Output", "role": "main"},
+ )
+ credentials = (SarvamCredential,)
+ annotations = {"destructive": False, "readonly": True, "open_world": True}
+ task_queue = TaskQueue.REST_API
+ usable_as_tool = True
+
+ Params = SarvamSpeechToTextParams
+ Output = SarvamSpeechToTextOutput
+
+ @Operation("transcribe", cost={"service": "sarvam", "action": "speech_to_text", "count": 1})
+ async def transcribe(
+ self, ctx: NodeContext, params: SarvamSpeechToTextParams
+ ) -> SarvamSpeechToTextOutput:
+ if params.mode not in ("transcribe", "translate") and params.model != "saaras:v3":
+ raise NodeUserError(
+ f"mode='{params.mode}' requires model='saaras:v3'; "
+ f"'{params.model}' supports only transcribe and translate."
+ )
+
+ filename, blob = _read_audio(params.audio_file, ctx.workspace_dir)
+ mime = mimetypes.guess_type(filename)[0] or "application/octet-stream"
+
+ data = await post_multipart(
+ ctx,
+ "/speech-to-text",
+ files={"file": (filename, blob, mime)},
+ data={
+ "model": params.model,
+ "language_code": params.language_code,
+ "mode": params.mode,
+ "input_audio_codec": params.input_audio_codec,
+ },
+ )
+
+ # Billed per second of audio; we do not decode the clip to measure
+ # it, so charge the documented sync-endpoint ceiling.
+ await track_sarvam_usage(ctx, "speech_to_text", _MAX_SECONDS)
+ return SarvamSpeechToTextOutput(
+ transcript=data.get("transcript", ""),
+ language_code=data.get("language_code"),
+ language_probability=data.get("language_probability"),
+ timestamps=data.get("timestamps"),
+ diarized_transcript=data.get("diarized_transcript"),
+ request_id=data.get("request_id"),
+ )
+
+
+def _read_audio(
+ audio_file: Union[str, Dict[str, Any]], workspace_dir: Optional[str]
+) -> tuple[str, bytes]:
+ """Resolve the dual-shaped ``audio_file`` param to ``(filename, bytes)``.
+
+ The file widget emits ``{"type": "upload", "data": "<base64>", ...}``
+ when the user picks a local file, and a bare path string when they type
+ one or drag an upstream value in. Relative paths resolve against the
+ per-workflow workspace so they line up with ``fileDownloader`` output.
+ """
+ if isinstance(audio_file, dict):
+ if audio_file.get("type") != "upload" or not audio_file.get("data"):
+ raise NodeUserError(
+ "audio_file is an object but not a file upload. Provide a file "
+ "path or re-select the file."
+ )
+ try:
+ blob = base64.b64decode(audio_file["data"], validate=True)
+ except (binascii.Error, ValueError) as e:
+ raise NodeUserError(f"Uploaded audio is not valid base64: {e}") from e
+ name = str(audio_file.get("filename") or "audio.wav")
+ else:
+ raw = (audio_file or "").strip()
+ if not raw:
+ raise NodeUserError(
+ "audio_file is required — provide a path to an audio file or upload one."
+ )
+ path = Path(raw)
+ if not path.is_absolute() and workspace_dir:
+ path = Path(workspace_dir) / path
+ if not path.is_file():
+ raise NodeUserError(f"Audio file not found: {path}")
+ blob = path.read_bytes()
+ name = path.name
+
+ if not blob:
+ raise NodeUserError("Audio file is empty.")
+ if len(blob) > _MAX_BYTES:
+ raise NodeUserError(
+ f"Audio is {len(blob) // (1024 * 1024)} MB. The synchronous endpoint takes "
+ f"clips under {_MAX_SECONDS} seconds — trim it, or use Sarvam's Batch API "
+ "for long recordings."
+ )
+ return name, blob
+
+
+__all__: List[str] = [
+ "SarvamSpeechToTextNode",
+ "SarvamSpeechToTextOutput",
+ "SarvamSpeechToTextParams",
+]
diff --git a/server/nodes/sarvam/sarvam_text_to_speech.py b/server/nodes/sarvam/sarvam_text_to_speech.py
new file mode 100644
index 00000000..a26cf82d
--- /dev/null
+++ b/server/nodes/sarvam/sarvam_text_to_speech.py
@@ -0,0 +1,284 @@
+"""Sarvam Text to Speech — POST /text-to-speech (Bulbul v2/v3)."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import re
+import uuid
+from pathlib import Path
+from typing import List, Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+
+from ._base import post_json, track_sarvam_usage
+from ..model._credentials import SarvamCredential
+
+_MAX_TEXT = {"bulbul:v3": 2500, "bulbul:v2": 1500}
+
+# Sarvam returns audio as base64 inside the JSON body. A 2500-character v3
+# request is roughly 12 MB of base64, and node outputs are persisted to the
+# DB, broadcast over the status WebSocket, and — for a tool-exposed node —
+# serialized into an LLM message. Writing to the workspace is therefore the
+# default; inline base64 is opt-in and capped.
+_MAX_INLINE_B64 = 1_000_000
+
+_V3_SPEAKERS = (
+ "shubh", "aditya", "ritu", "priya", "neha", "rahul", "pooja", "rohan",
+ "simran", "kavya", "amit", "dev", "ishita", "shreya", "ratan", "varun",
+ "manan", "sumit", "roopa", "kabir", "aayan", "ashutosh", "advait",
+ "anand", "tanya", "tarun", "sunny", "mani", "gokul", "vijay", "shruti",
+ "suhani", "mohit", "kavitha", "rehan", "soham", "rupali",
+)
+_V2_SPEAKERS = (
+ "anushka", "manisha", "vidya", "arya", "abhilash", "karun", "hitesh",
+)
+
+_CODEC_EXT = {
+ "wav": "wav", "mp3": "mp3", "flac": "flac", "aac": "aac",
+ "opus": "opus", "linear16": "pcm", "mulaw": "ulaw", "alaw": "alaw",
+}
+
+
+class SarvamTextToSpeechParams(BaseModel):
+ tool_name: str = Field(
+ default="sarvam_text_to_speech",
+ description="Override name shown to the LLM when used as a tool.",
+ )
+ tool_description: str = Field(
+ default=(
+ "Synthesize natural speech from text in 11 Indian languages using Sarvam's "
+ "Bulbul voices. Writes an audio file and returns its path."
+ ),
+ description="Override description shown to the LLM when used as a tool.",
+ json_schema_extra={"rows": 3},
+ )
+ text: str = Field(
+ ...,
+ min_length=1,
+ description="Text to speak.",
+ json_schema_extra={"rows": 4},
+ )
+ target_language_code: Literal[
+ "bn-IN", "en-IN", "gu-IN", "hi-IN", "kn-IN", "ml-IN",
+ "mr-IN", "od-IN", "pa-IN", "ta-IN", "te-IN",
+ ] = Field(default="hi-IN", description="Language of the spoken output.")
+ model: Literal["bulbul:v3", "bulbul:v2"] = Field(
+ default="bulbul:v3",
+ description="bulbul:v3 is the current model (37 voices, 2500 chars).",
+ )
+ speaker: str = Field(
+ default="shubh",
+ description="Voice name (lowercase). v3 and v2 have separate voice sets.",
+ )
+ pace: float = Field(
+ default=1.0, ge=0.3, le=3.0, description="Speaking rate. v3 allows 0.5-2.0; v2 allows 0.3-3.0."
+ )
+ speech_sample_rate: Literal[8000, 16000, 22050, 24000, 32000, 44100, 48000] = Field(
+ default=24000, description="Output sample rate in Hz."
+ )
+ output_audio_codec: Literal[
+ "wav", "mp3", "linear16", "mulaw", "alaw", "opus", "flac", "aac"
+ ] = Field(default="wav", description="Audio container/codec.")
+ temperature: Optional[float] = Field(
+ default=None,
+ ge=0.01,
+ le=2.0,
+ description="Expressiveness. bulbul:v3 only.",
+ json_schema_extra={"displayOptions": {"show": {"model": ["bulbul:v3"]}}},
+ )
+ pitch: Optional[float] = Field(
+ default=None,
+ ge=-0.75,
+ le=0.75,
+ description="Pitch shift. bulbul:v2 only.",
+ json_schema_extra={"displayOptions": {"show": {"model": ["bulbul:v2"]}}},
+ )
+ loudness: Optional[float] = Field(
+ default=None,
+ ge=0.3,
+ le=3.0,
+ description="Output gain. bulbul:v2 only.",
+ json_schema_extra={"displayOptions": {"show": {"model": ["bulbul:v2"]}}},
+ )
+ enable_preprocessing: Optional[bool] = Field(
+ default=None,
+ description="Normalise numbers and abbreviations. bulbul:v2 only (v3 always preprocesses).",
+ json_schema_extra={"displayOptions": {"show": {"model": ["bulbul:v2"]}}},
+ )
+ return_audio: Literal["file", "base64"] = Field(
+ default="file",
+ description=(
+ "'file' writes the audio into the workflow workspace and returns its path "
+ "(recommended). 'base64' returns the bytes inline — only for short clips."
+ ),
+ )
+
+ model_config = {"extra": "ignore"}
+
+
+class SarvamTextToSpeechOutput(BaseModel):
+ file_path: Optional[str] = None
+ files: List[str] = Field(default_factory=list)
+ chunk_count: int = 0
+ audio_format: str = "wav"
+ audio_base64: Optional[str] = None
+ note: Optional[str] = None
+ request_id: Optional[str] = None
+
+ model_config = {"extra": "allow"}
+
+
+class SarvamTextToSpeechNode(ActionNode):
+ type = "sarvamTextToSpeech"
+ display_name = "Sarvam Text to Speech"
+ subtitle = "Synthesize Speech"
+ group = ("language", "tool")
+ description = "Generate natural speech in 11 Indian languages with Sarvam Bulbul voices"
+ component_kind = "square"
+ tool_name = "sarvam_text_to_speech"
+ tool_description = (
+ "Synthesize natural speech from text in 11 Indian languages using Sarvam's Bulbul "
+ "voices. Writes an audio file into the workflow workspace and returns its path in "
+ "`file_path` — pass that path to other nodes rather than expecting audio bytes. "
+ "Keep `text` under 2500 characters."
+ )
+ handles = (
+ {"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
+ {"name": "output-main", "kind": "output", "position": "right", "label": "Output", "role": "main"},
+ )
+ credentials = (SarvamCredential,)
+ annotations = {"destructive": False, "readonly": False, "open_world": True}
+ task_queue = TaskQueue.REST_API
+ usable_as_tool = True
+
+ Params = SarvamTextToSpeechParams
+ Output = SarvamTextToSpeechOutput
+
+ @Operation("synthesize", cost={"service": "sarvam", "action": "text_to_speech", "count": 1})
+ async def synthesize(
+ self, ctx: NodeContext, params: SarvamTextToSpeechParams
+ ) -> SarvamTextToSpeechOutput:
+ is_v3 = params.model == "bulbul:v3"
+ cap = _MAX_TEXT[params.model]
+ if len(params.text) > cap:
+ raise NodeUserError(
+ f"text is {len(params.text)} characters; {params.model} accepts at most "
+ f"{cap}. Split the text across multiple calls."
+ )
+
+ speakers = _V3_SPEAKERS if is_v3 else _V2_SPEAKERS
+ speaker = params.speaker.strip().lower()
+ if speaker not in speakers:
+ raise NodeUserError(
+ f"'{params.speaker}' is not a {params.model} voice. Available: "
+ + ", ".join(speakers)
+ )
+ if is_v3 and not (0.5 <= params.pace <= 2.0):
+ raise NodeUserError(
+ f"pace {params.pace} is out of range for bulbul:v3 (0.5-2.0)."
+ )
+
+ body = {
+ "text": params.text,
+ "target_language_code": params.target_language_code,
+ "model": params.model,
+ "speaker": speaker,
+ "pace": params.pace,
+ "speech_sample_rate": params.speech_sample_rate,
+ "output_audio_codec": params.output_audio_codec,
+ }
+ if is_v3:
+ body["temperature"] = params.temperature
+ else:
+ # v3 rejects these outright, so they are only sent for v2.
+ body["pitch"] = params.pitch
+ body["loudness"] = params.loudness
+ body["enable_preprocessing"] = params.enable_preprocessing
+
+ data = await post_json(ctx, "/text-to-speech", body)
+
+ chunks = [c for c in (data.get("audios") or []) if c]
+ if not chunks:
+ raise NodeUserError("Sarvam returned no audio for this request.")
+
+ out = SarvamTextToSpeechOutput(
+ chunk_count=len(chunks),
+ audio_format=params.output_audio_codec,
+ request_id=data.get("request_id"),
+ )
+
+ if params.return_audio == "file":
+ out.files = _write_chunks(
+ chunks,
+ workspace_dir=ctx.workspace_dir,
+ node_id=ctx.node_id,
+ codec=params.output_audio_codec,
+ text=params.text,
+ )
+ out.file_path = out.files[0]
+ if len(chunks) > 1:
+ out.note = (
+ f"Sarvam split this request into {len(chunks)} audio chunks. "
+ "file_path is the first; see `files` for all of them. Each chunk "
+ "is a standalone file — concatenating them byte-wise is invalid."
+ )
+ else:
+ first = chunks[0]
+ if len(first) > _MAX_INLINE_B64:
+ out.note = (
+ f"Inline audio suppressed: {len(first)} base64 characters exceeds the "
+ f"{_MAX_INLINE_B64} limit. Re-run with return_audio='file'."
+ )
+ else:
+ out.audio_base64 = first
+ if len(chunks) > 1:
+ out.note = (
+ f"audio_base64 is chunk 1 of {len(chunks)}. Use "
+ "return_audio='file' to capture every chunk."
+ )
+
+ # bulbul:v2 is billed at half the v3 character rate.
+ await track_sarvam_usage(
+ ctx,
+ "text_to_speech" if is_v3 else "text_to_speech_v2",
+ len(params.text),
+ )
+ return out
+
+
+def _write_chunks(
+ chunks: List[str],
+ *,
+ workspace_dir: Optional[str],
+ node_id: str,
+ codec: str,
+ text: str,
+) -> List[str]:
+ """Decode each base64 chunk to its own file under ``<workspace>/audio``.
+
+ One file per chunk: every chunk carries its own container header, so
+ concatenating them produces an unplayable file.
+ """
+ base = Path(workspace_dir) / "audio" if workspace_dir else Path("audio")
+ base.mkdir(parents=True, exist_ok=True)
+
+ slug = re.sub(r"[^a-z0-9]+", "-", text[:32].lower()).strip("-") or "speech"
+ stem = f"{slug}-{node_id[:8]}-{uuid.uuid4().hex[:6]}"
+ ext = _CODEC_EXT.get(codec, "wav")
+
+ paths: List[str] = []
+ for index, chunk in enumerate(chunks, start=1):
+ try:
+ blob = base64.b64decode(chunk, validate=True)
+ except (binascii.Error, ValueError) as e:
+ raise NodeUserError(
+ f"Sarvam returned audio chunk {index} that is not valid base64: {e}"
+ ) from e
+ suffix = "" if len(chunks) == 1 else f"-{index}"
+ target = base / f"{stem}{suffix}.{ext}"
+ target.write_bytes(blob)
+ paths.append(str(target))
+ return paths
diff --git a/server/nodes/sarvam/sarvam_translate.py b/server/nodes/sarvam/sarvam_translate.py
new file mode 100644
index 00000000..def6108b
--- /dev/null
+++ b/server/nodes/sarvam/sarvam_translate.py
@@ -0,0 +1,141 @@
+"""Sarvam Translate — POST /translate (Mayura / Sarvam-Translate)."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+
+from ._base import post_json, track_sarvam_usage
+from ..model._credentials import SarvamCredential
+
+# Per-model input caps from the Sarvam docs. Enforced client-side so the
+# LLM gets an actionable message instead of an opaque 422.
+_MAX_INPUT = {"mayura:v1": 1000, "sarvam-translate:v1": 2000}
+
+
+class SarvamTranslateParams(BaseModel):
+ tool_name: str = Field(
+ default="sarvam_translate",
+ description="Override name shown to the LLM when used as a tool.",
+ )
+ tool_description: str = Field(
+ default=(
+ "Translate text between English and 22 Indian languages using Sarvam AI. "
+ "Supports formal, colloquial and code-mixed registers."
+ ),
+ description="Override description shown to the LLM when used as a tool.",
+ json_schema_extra={"rows": 3},
+ )
+ input: str = Field(
+ ...,
+ min_length=1,
+ description="Text to translate.",
+ json_schema_extra={"rows": 4},
+ )
+ source_language_code: Literal[
+ "auto", "as-IN", "bn-IN", "brx-IN", "doi-IN", "en-IN", "gu-IN", "hi-IN",
+ "kn-IN", "kok-IN", "ks-IN", "mai-IN", "ml-IN", "mni-IN", "mr-IN",
+ "ne-IN", "od-IN", "pa-IN", "sa-IN", "sat-IN", "sd-IN", "ta-IN",
+ "te-IN", "ur-IN",
+ ] = Field(default="auto", description="Source language, or 'auto' to detect.")
+ target_language_code: Literal[
+ "as-IN", "bn-IN", "brx-IN", "doi-IN", "en-IN", "gu-IN", "hi-IN",
+ "kn-IN", "kok-IN", "ks-IN", "mai-IN", "ml-IN", "mni-IN", "mr-IN",
+ "ne-IN", "od-IN", "pa-IN", "sa-IN", "sat-IN", "sd-IN", "ta-IN",
+ "te-IN", "ur-IN",
+ ] = Field(default="hi-IN", description="Language to translate into.")
+ model: Literal["mayura:v1", "sarvam-translate:v1"] = Field(
+ default="sarvam-translate:v1",
+ description="sarvam-translate:v1 covers 22 languages and 2000 chars; mayura:v1 covers 10 and 1000.",
+ )
+ mode: Literal["formal", "modern-colloquial", "classic-colloquial", "code-mixed"] = Field(
+ default="formal", description="Register of the translation."
+ )
+ speaker_gender: Optional[Literal["Male", "Female"]] = Field(
+ default=None,
+ description="Speaker gender, for languages that inflect on it.",
+ )
+ output_script: Optional[Literal["roman", "fully-native", "spoken-form-in-native"]] = Field(
+ default=None,
+ description="Transliteration applied to the output. Leave unset for the language's native script.",
+ )
+ numerals_format: Literal["international", "native"] = Field(
+ default="international", description="Render digits as 0-9 or in the native script."
+ )
+
+ model_config = {"extra": "ignore"}
+
+
+class SarvamTranslateOutput(BaseModel):
+ translated_text: str = ""
+ source_language_code: str = ""
+ request_id: Optional[str] = None
+
+ model_config = {"extra": "allow"}
+
+
+class SarvamTranslateNode(ActionNode):
+ type = "sarvamTranslate"
+ display_name = "Sarvam Translate"
+ subtitle = "Indic Translation"
+ group = ("language", "tool")
+ description = "Translate text between English and 22 Indian languages via Sarvam AI"
+ component_kind = "square"
+ tool_name = "sarvam_translate"
+ tool_description = (
+ "Translate text between English and 22 Indian languages using Sarvam AI. "
+ "Set source_language_code to 'auto' when the input language is unknown. "
+ "Returns the translated text and the detected source language."
+ )
+ handles = (
+ {"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
+ {"name": "output-main", "kind": "output", "position": "right", "label": "Output", "role": "main"},
+ )
+ credentials = (SarvamCredential,)
+ annotations = {"destructive": False, "readonly": True, "open_world": True}
+ task_queue = TaskQueue.REST_API
+ usable_as_tool = True
+
+ Params = SarvamTranslateParams
+ Output = SarvamTranslateOutput
+
+ @Operation("translate", cost={"service": "sarvam", "action": "translate", "count": 1})
+ async def translate(
+ self, ctx: NodeContext, params: SarvamTranslateParams
+ ) -> SarvamTranslateOutput:
+ cap = _MAX_INPUT[params.model]
+ if len(params.input) > cap:
+ raise NodeUserError(
+ f"input is {len(params.input)} characters; {params.model} accepts at most "
+ f"{cap}. Split the text or switch to sarvam-translate:v1 (2000)."
+ )
+ if params.source_language_code == params.target_language_code:
+ raise NodeUserError(
+ "source_language_code and target_language_code are identical "
+ f"({params.target_language_code}) — nothing to translate."
+ )
+
+ data = await post_json(
+ ctx,
+ "/translate",
+ {
+ "input": params.input,
+ "source_language_code": params.source_language_code,
+ "target_language_code": params.target_language_code,
+ "model": params.model,
+ "mode": params.mode,
+ "speaker_gender": params.speaker_gender,
+ "output_script": params.output_script,
+ "numerals_format": params.numerals_format,
+ },
+ )
+
+ await track_sarvam_usage(ctx, "translate", len(params.input))
+ return SarvamTranslateOutput(
+ translated_text=data.get("translated_text", ""),
+ source_language_code=data.get("source_language_code", ""),
+ request_id=data.get("request_id"),
+ )
diff --git a/server/nodes/sarvam/sarvam_transliterate.py b/server/nodes/sarvam/sarvam_transliterate.py
new file mode 100644
index 00000000..7db96473
--- /dev/null
+++ b/server/nodes/sarvam/sarvam_transliterate.py
@@ -0,0 +1,121 @@
+"""Sarvam Transliterate — POST /transliterate (script conversion)."""
+
+from __future__ import annotations
+
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from services.plugin import ActionNode, NodeContext, NodeUserError, Operation, TaskQueue
+
+from ._base import post_json, track_sarvam_usage
+from ..model._credentials import SarvamCredential
+
+
+class SarvamTransliterateParams(BaseModel):
+ tool_name: str = Field(
+ default="sarvam_transliterate",
+ description="Override name shown to the LLM when used as a tool.",
+ )
+ tool_description: str = Field(
+ default=(
+ "Convert text between scripts while preserving pronunciation — e.g. romanised "
+ "Hindi to Devanagari. This is NOT translation; meaning is unchanged."
+ ),
+ description="Override description shown to the LLM when used as a tool.",
+ json_schema_extra={"rows": 3},
+ )
+ input: str = Field(
+ ...,
+ min_length=1,
+ description="Text to transliterate.",
+ json_schema_extra={"rows": 4},
+ )
+ source_language_code: Literal[
+ "auto", "bn-IN", "en-IN", "gu-IN", "hi-IN", "kn-IN", "ml-IN",
+ "mr-IN", "od-IN", "pa-IN", "ta-IN", "te-IN",
+ ] = Field(default="auto", description="Source language, or 'auto' to detect.")
+ target_language_code: Literal[
+ "bn-IN", "en-IN", "gu-IN", "hi-IN", "kn-IN", "ml-IN",
+ "mr-IN", "od-IN", "pa-IN", "ta-IN", "te-IN",
+ ] = Field(default="hi-IN", description="Script to transliterate into.")
+ numerals_format: Literal["international", "native"] = Field(
+ default="international", description="Render digits as 0-9 or in the native script."
+ )
+ spoken_form: bool = Field(
+ default=False,
+ description="Expand numbers, dates and abbreviations into how they are spoken.",
+ )
+ spoken_form_numerals_language: Literal["english", "native"] = Field(
+ default="native",
+ description="Language used when spelling out numerals in spoken form.",
+ json_schema_extra={"displayOptions": {"show": {"spoken_form": [True]}}},
+ )
+
+ model_config = {"extra": "ignore"}
+
+
+class SarvamTransliterateOutput(BaseModel):
+ transliterated_text: str = ""
+ source_language_code: str = ""
+ request_id: Optional[str] = None
+
+ model_config = {"extra": "allow"}
+
+
+class SarvamTransliterateNode(ActionNode):
+ type = "sarvamTransliterate"
+ display_name = "Sarvam Transliterate"
+ subtitle = "Script Conversion"
+ group = ("language", "tool")
+ description = "Convert text between Indic scripts and Roman while preserving pronunciation"
+ component_kind = "square"
+ tool_name = "sarvam_transliterate"
+ tool_description = (
+ "Convert text between scripts while preserving pronunciation — e.g. romanised Hindi "
+ "('namaste') to Devanagari, or the reverse. This is NOT translation: the words and "
+ "meaning stay the same, only the script changes. Use sarvam_translate to change language."
+ )
+ handles = (
+ {"name": "input-main", "kind": "input", "position": "left", "label": "Input", "role": "main"},
+ {"name": "output-main", "kind": "output", "position": "right", "label": "Output", "role": "main"},
+ )
+ credentials = (SarvamCredential,)
+ annotations = {"destructive": False, "readonly": True, "open_world": True}
+ task_queue = TaskQueue.REST_API
+ usable_as_tool = True
+
+ Params = SarvamTransliterateParams
+ Output = SarvamTransliterateOutput
+
+ @Operation("transliterate", cost={"service": "sarvam", "action": "transliterate", "count": 1})
+ async def transliterate(
+ self, ctx: NodeContext, params: SarvamTransliterateParams
+ ) -> SarvamTransliterateOutput:
+ if params.source_language_code == params.target_language_code:
+ raise NodeUserError(
+ "source_language_code and target_language_code are identical "
+ f"({params.target_language_code}) — nothing to transliterate."
+ )
+
+ data = await post_json(
+ ctx,
+ "/transliterate",
+ {
+ "input": params.input,
+ "source_language_code": params.source_language_code,
+ "target_language_code": params.target_language_code,
+ "numerals_format": params.numerals_format,
+ "spoken_form": params.spoken_form,
+ "spoken_form_numerals_language": (
+ params.spoken_form_numerals_language if params.spoken_form else None
+ ),
+ },
+ )
+
+ await track_sarvam_usage(ctx, "transliterate", len(params.input))
+ return SarvamTransliterateOutput(
+ transliterated_text=data.get("transliterated_text", ""),
+ source_language_code=data.get("source_language_code", ""),
+ request_id=data.get("request_id"),
+ )
diff --git a/server/services/ai.py b/server/services/ai.py
index 04401feb..614c3b7b 100644
--- a/server/services/ai.py
+++ b/server/services/ai.py
@@ -1196,16 +1196,13 @@ class AIService:
def _get_curated_models(self, provider: str) -> List[str]:
"""Get curated model list from llm_defaults.json for a provider.
- Prefer the explicit ``popular_models`` list, preserving its order.
- Older provider blocks fall back to max_output_tokens keys (excluding
- _default). Returns empty when neither source has a curated list.
+ Delegates to ``services.llm.config.curated_models`` — the same
+ list backs ``OpenAIProvider.fetch_models`` for providers that
+ declare no model-list route, and the two must not drift.
"""
- provider_cfg = _LLM_DEFAULTS.get("providers", {}).get(provider, {})
- explicit = provider_cfg.get("popular_models") or []
- if explicit:
- return list(explicit)
- max_tokens_map = provider_cfg.get("max_output_tokens", {})
- return [m for m in max_tokens_map if m != "_default"]
+ from services.llm.config import curated_models
+
+ return curated_models(provider)
async def fetch_models(self, provider: str, api_key: str) -> List[str]:
"""Fetch available models from a provider via ``ChatUnifier``.
diff --git a/server/services/llm/config.py b/server/services/llm/config.py
index dc032a15..d28c08d8 100644
--- a/server/services/llm/config.py
+++ b/server/services/llm/config.py
@@ -150,6 +150,45 @@ async def get_default_model_async(provider: str, database) -> str:
return get_default_model(provider)
+def curated_models(provider: str) -> list:
+ """JSON-curated model ids for ``provider``.
+
+ Prefers the explicit ``popular_models`` list, preserving its order.
+ Older provider blocks (and every block that carries an empty
+ ``popular_models`` under the >=1M-context policy) fall back to the
+ ``max_output_tokens`` keys, minus the ``_default`` sentinel. Returns
+ an empty list when neither source has anything.
+
+ Shared by ``AIService._get_curated_models`` (the API-failure
+ fallback) and ``OpenAIProvider.fetch_models`` (the curated list
+ served when a provider declares no model-list route).
+
+ ``GeminiProvider._curated_models`` deliberately does NOT use this:
+ it reads the ``max_output_tokens`` keys *specifically* because those
+ are real model names while gemini's ``popular_models`` carries
+ ``-latest`` aliases the Vertex backend rejects.
+ """
+ provider_cfg = LLM_DEFAULTS.get("providers", {}).get(provider, {})
+ explicit = provider_cfg.get("popular_models") or []
+ if explicit:
+ return list(explicit)
+ max_tokens_map = provider_cfg.get("max_output_tokens", {})
+ return [m for m in max_tokens_map if m != "_default"]
+
+
+def supports_model_listing(provider: str) -> bool:
+ """Whether ``provider`` exposes an OpenAI-style model-list endpoint.
+
+ Defaults to ``True`` — only a provider that explicitly declares
+ ``"supports_model_listing": false`` in llm_defaults.json opts out.
+ Sarvam is the first: it serves OpenAI-compatible chat completions but
+ ships no model-list route at all (verified against its published
+ OpenAPI spec), so calling ``client.models.list()`` there 404s.
+ """
+ provider_cfg = LLM_DEFAULTS.get("providers", {}).get(provider, {})
+ return bool(provider_cfg.get("supports_model_listing", True))
+
+
# ---------------------------------------------------------------------------
# Max-tokens / temperature resolution
# ---------------------------------------------------------------------------
diff --git a/server/services/llm/protocol.py b/server/services/llm/protocol.py
index f0fcfa5a..dfac60ec 100644
--- a/server/services/llm/protocol.py
+++ b/server/services/llm/protocol.py
@@ -357,6 +357,7 @@ class LLMError(Exception):
"deepseek": "DeepSeek",
"kimi": "Kimi",
"mistral": "Mistral",
+ "sarvam": "Sarvam AI",
"ollama": "Ollama",
"lmstudio": "LM Studio",
}
diff --git a/server/services/llm/providers/_compat.py b/server/services/llm/providers/_compat.py
index 231158e5..7100a771 100644
--- a/server/services/llm/providers/_compat.py
+++ b/server/services/llm/providers/_compat.py
@@ -1,15 +1,18 @@
"""OpenAI-compatible provider registrations.
-Eight providers (``xai`` / ``deepseek`` / ``kimi`` / ``mistral`` / ``ollama`` /
-``lmstudio`` / ``groq`` / ``cerebras``) all ride the OpenAI Python SDK with a custom ``base_url``,
-so they share one factory (``OpenAIProvider``) and one typed-exception
-tuple (``openai.OpenAIError``). The per-provider differences live in
-``llm_defaults.json`` (``base_url``, plus the provider quirks block
-added in Phase C) — there is no per-provider Python here.
+Nine providers (``xai`` / ``deepseek`` / ``kimi`` / ``mistral`` / ``ollama`` /
+``lmstudio`` / ``groq`` / ``cerebras`` / ``sarvam``) all ride the OpenAI Python SDK
+with a custom ``base_url``, so they share one factory (``OpenAIProvider``)
+and one typed-exception tuple (``openai.OpenAIError``). The per-provider
+differences live in ``llm_defaults.json`` (``base_url``, plus the provider
+quirks block added in Phase C) — there is no per-provider Python here.
Adding a new OpenAI-compat provider is a JSON edit + one entry in
``_COMPAT_PROVIDERS`` below. Groq + Cerebras registered here in
-Phase D (see the ``_COMPAT_PROVIDERS`` comment below).
+Phase D (see the ``_COMPAT_PROVIDERS`` comment below); Sarvam followed and
+brought the ``supports_model_listing`` flag with it — a provider can be
+wire-compatible yet ship no model-list route, which ``OpenAIProvider``
+handles generically off that JSON key.
"""
from __future__ import annotations
@@ -42,6 +45,12 @@ _COMPAT_PROVIDERS: Tuple[str, ...] = (
"lmstudio",
"groq",
"cerebras",
+ # Sarvam serves OpenAI-compatible chat completions and accepts
+ # ``Authorization: Bearer`` alongside its native ``api-subscription-key``,
+ # so it needs no provider subclass. It is the first provider with no
+ # model-list route, which it declares via ``supports_model_listing: false``
+ # in llm_defaults.json — handled generically in ``OpenAIProvider``.
+ "sarvam",
)
diff --git a/server/services/llm/providers/openai.py b/server/services/llm/providers/openai.py
index 46065a22..378474d4 100644
--- a/server/services/llm/providers/openai.py
+++ b/server/services/llm/providers/openai.py
@@ -156,9 +156,43 @@ class OpenAIProvider:
# ------------------------------------------------------------------
async def fetch_models(self, api_key: str) -> List[str]:
- """Fetch models using the client's configured base_url."""
- models = await self._client.models.list()
- return sorted([m.id for m in models.data])
+ """Fetch models using the client's configured base_url.
+
+ Providers that declare ``supports_model_listing: false`` in
+ llm_defaults.json expose no model-list route at all (Sarvam).
+ Calling ``models.list()`` there 404s, and that 404 arrives as an
+ ``openai.OpenAIError`` which ``ChatUnifier.fetch_models``
+ translates into ``NodeUserError`` and ``AIService.fetch_models``
+ re-raises *before* reaching its curated fallback — breaking both
+ credential validation and the model dropdown for a perfectly
+ valid key. For those providers, serve the JSON-curated list and
+ validate the key with the cheapest real call the OpenAI wire
+ format offers: a one-token completion. An invalid key still
+ raises the typed SDK error the unifier already knows how to
+ translate, so the probe stays a real credential check.
+
+ The flag is read per provider from config rather than branched on
+ a provider name, so any future no-listing endpoint is a JSON edit.
+ """
+ from services.llm.config import curated_models, supports_model_listing
+
+ if supports_model_listing(self.provider_name):
+ models = await self._client.models.list()
+ return sorted([m.id for m in models.data])
+
+ curated = curated_models(self.provider_name)
+ if not curated:
+ raise ValueError(
+ f"llm_defaults.json providers.{self.provider_name} sets "
+ "supports_model_listing=false but declares no models "
+ "(popular_models and max_output_tokens are both empty)"
+ )
+ await self._client.chat.completions.create(
+ model=curated[0],
+ messages=[{"role": "user", "content": "hi"}],
+ max_tokens=1,
+ )
+ return curated
# ------------------------------------------------------------------
# internals
diff --git a/server/services/model_registry.py b/server/services/model_registry.py
index 6acde729..589e14a3 100644
--- a/server/services/model_registry.py
+++ b/server/services/model_registry.py
@@ -59,6 +59,7 @@ DEFAULT_TEMP_RANGES = {
"deepseek": (0.0, 2.0),
"kimi": (0.0, 1.0),
"mistral": (0.0, 1.0),
+ "sarvam": (0.0, 2.0),
}
diff --git a/server/services/node_output_schemas.py b/server/services/node_output_schemas.py
index 49889475..3fdcd939 100644
--- a/server/services/node_output_schemas.py
+++ b/server/services/node_output_schemas.py
@@ -684,6 +684,7 @@ _CHAT_MODEL_TYPES = [
"deepseekChatModel",
"kimiChatModel",
"mistralChatModel",
+ "sarvamChatModel",
]
_SEARCH_TYPES = ["braveSearch", "serperSearch", "perplexitySearch"]
diff --git a/server/services/plugin/connection.py b/server/services/plugin/connection.py
index 054efc59..d684825a 100644
--- a/server/services/plugin/connection.py
+++ b/server/services/plugin/connection.py
@@ -87,8 +87,18 @@ class Connection:
params: Optional[Dict[str, Any]] = None,
json: Optional[Any] = None,
data: Optional[Any] = None,
+ files: Optional[Any] = None,
_retry_on_auth: bool = True,
) -> httpx.Response:
+ """Issue an authed request.
+
+ ``files`` is handed straight to httpx for ``multipart/form-data``
+ uploads; pair it with ``data=`` for the non-file form fields and
+ do NOT set a ``Content-Type`` header — httpx generates the
+ boundary. Pass file **bytes**, not an open file handle: the
+ auth-retry path below re-sends the same kwargs, and a consumed
+ handle would replay as an empty part.
+ """
secrets = await self.credentials()
req: Dict[str, Any] = {
"headers": dict(headers or {}),
@@ -98,6 +108,8 @@ class Connection:
req["json"] = json
if data is not None:
req["data"] = data
+ if files is not None:
+ req["files"] = files
req = self._cred_cls.inject(secrets, req)
client = self._get_client()
@@ -119,6 +131,7 @@ class Connection:
"params": dict(params or {}),
**({"json": json} if json is not None else {}),
**({"data": data} if data is not None else {}),
+ **({"files": files} if files is not None else {}),
},
)
response = await client.request(method, url, **req_retry)
diff --git a/server/skills/language_agent/sarvam-speech-skill/SKILL.md b/server/skills/language_agent/sarvam-speech-skill/SKILL.md
new file mode 100644
index 00000000..8b22ce0d
--- /dev/null
+++ b/server/skills/language_agent/sarvam-speech-skill/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: sarvam-speech-skill
+description: Transcribe speech to text and synthesize natural speech in Indian languages using Sarvam AI's Saaras and Bulbul models.
+allowed-tools: sarvam_speech_to_text sarvam_text_to_speech
+metadata:
+ author: opencompany
+ version: "1.0"
+ category: language
+
+---
+
+# Sarvam Speech Skill
+
+Speech-to-text across 23 Indian languages (Saaras) and text-to-speech with
+37 voices (Bulbul).
+
+## How It Works
+
+This skill provides instructions and context. To execute, connect the
+**Sarvam Speech to Text** and/or **Sarvam Text to Speech** nodes to the
+agent's `input-tools` handle.
+
+## sarvam_speech_to_text
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| audio_file | string | Yes | Path to an audio file |
+| model | enum | No | `saaras:v3` (default, 23 languages) or `saarika:v2.5` (legacy) |
+| language_code | string | No | BCP-47 code, or `unknown` (default) to auto-detect |
+| mode | enum | No | `transcribe` (default), `translate`, `verbatim`, `translit`, `codemix` |
+
+Modes:
+- `transcribe` — native script, cleaned up
+- `translate` — English output regardless of the spoken language
+- `verbatim` — keeps disfluencies ("um", repetitions); use for compliance
+ or verbatim-record work
+- `translit` — Roman script
+- `codemix` — preserves mixed-language speech as spoken
+
+Everything except `transcribe` and `translate` requires `saaras:v3`.
+
+```json
+{
+ "transcript": "नमस्ते, आप कैसे हैं?",
+ "language_code": "hi-IN",
+ "language_probability": 0.97
+}
+```
+
+**Hard limit: clips under 30 seconds.** This node calls the synchronous
+endpoint. Longer recordings need Sarvam's Batch API, which is not wired
+here — split the audio first, or tell the user it is out of scope rather
+than retrying.
+
+Formats: WAV, MP3, AAC, AIFF, OGG, OPUS, FLAC, MP4/M4A, AMR, WMA, WebM,
+PCM. Accuracy is best at a 16 kHz sample rate.
+
+## sarvam_text_to_speech
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| text | string | Yes | Text to speak (max 2500 chars on v3, 1500 on v2) |
+| target_language_code | enum | No | Defaults to `hi-IN` |
+| model | enum | No | `bulbul:v3` (default) or `bulbul:v2` |
+| speaker | string | No | Voice name, lowercase. Defaults to `shubh` |
+| pace | number | No | v3: 0.5–2.0, v2: 0.3–3.0. Default 1.0 |
+| speech_sample_rate | enum | No | 8000–48000 Hz, default 24000 |
+| output_audio_codec | enum | No | `wav` (default), `mp3`, `flac`, `aac`, `opus`, `linear16`, `mulaw`, `alaw` |
+| return_audio | enum | No | `file` (default) or `base64` |
+
+Voices are **per model** and do not overlap:
+- `bulbul:v3` — shubh, aditya, ritu, priya, neha, rahul, pooja, rohan,
+ simran, kavya, amit, dev, ishita, shreya, ratan, varun, manan, sumit,
+ roopa, kabir, aayan, ashutosh, advait, anand, tanya, tarun, sunny, mani,
+ gokul, vijay, shruti, suhani, mohit, kavitha, rehan, soham, rupali
+- `bulbul:v2` — anushka, manisha, vidya, arya, abhilash, karun, hitesh
+
+Asking for a v2 voice on v3 is an error, not a fallback.
+
+```json
+{
+ "file_path": "/…/workspaces/My_Flow_1/audio/namaste-a1b2c3d4-9f8e7d.wav",
+ "files": ["/…/namaste-a1b2c3d4-9f8e7d.wav"],
+ "chunk_count": 1,
+ "audio_format": "wav"
+}
+```
+
+**The audio is written to a file, not returned inline.** Pass `file_path`
+along to whatever consumes it. Only set `return_audio: "base64"` for very
+short clips you must inline — a full-length request is roughly 12 MB of
+base64, which bloats the workflow output and your own context.
+
+For long text, Sarvam may return several chunks. Each is a standalone audio
+file with its own header, so `files` lists them all and `file_path` points
+at the first. Concatenating them byte-wise produces an unplayable file.
+
+## When to Use
+
+- Transcribing voice notes, IVR recordings or short call clips
+- Generating voice prompts and announcements in Indian languages
+- Building a voice loop: transcribe → reason → synthesize a reply
+
+## When NOT to Use
+
+- Recordings longer than 30 seconds (Batch API territory)
+- Speaker diarization — only the Batch API returns it
+- Real-time streaming — this is the request/response endpoint
+- Languages outside the Indian set plus English
+
+## API Details
+
+- **Speech to Text**: POST `https://api.sarvam.ai/speech-to-text` (multipart) — 30 INR/hour
+- **Text to Speech**: POST `https://api.sarvam.ai/text-to-speech` — 30 INR / 10K chars (v3)
+- **Auth**: `api-subscription-key` header
+
+## Setup Requirements
+
+A single Sarvam API key from [dashboard.sarvam.ai](https://dashboard.sarvam.ai),
+entered once in the Credentials modal under **Sarvam AI**. The same key
+covers speech, translation and the Sarvam chat models.
diff --git a/server/skills/language_agent/sarvam-translate-skill/SKILL.md b/server/skills/language_agent/sarvam-translate-skill/SKILL.md
new file mode 100644
index 00000000..0ee8462f
--- /dev/null
+++ b/server/skills/language_agent/sarvam-translate-skill/SKILL.md
@@ -0,0 +1,123 @@
+---
+name: sarvam-translate-skill
+description: Translate and transliterate text across 22 Indian languages, and detect which language a piece of text is written in, using Sarvam AI.
+allowed-tools: sarvam_translate sarvam_transliterate sarvam_detect_language
+metadata:
+ author: opencompany
+ version: "1.0"
+ category: language
+
+---
+
+# Sarvam Text Skill
+
+Sarvam AI's text APIs cover the Indian language space: translation across 22
+languages, script conversion that preserves pronunciation, and language
+identification.
+
+## How It Works
+
+This skill provides instructions and context. To execute, connect the
+**Sarvam Translate**, **Sarvam Transliterate**, and/or **Sarvam Detect
+Language** nodes to the agent's `input-tools` handle. All three share one
+Sarvam API key.
+
+## Choosing the right tool
+
+These three are routinely confused. The distinction matters:
+
+| You want to... | Use |
+|---|---|
+| Change the **language** — "Hello" to "नमस्ते" | `sarvam_translate` |
+| Change the **script**, keeping the words — "namaste" to "नमस्ते" | `sarvam_transliterate` |
+| Find out **what language** some text is in | `sarvam_detect_language` |
+
+Transliteration is not translation. `sarvam_transliterate` on "namaste"
+returns the same word in Devanagari; it does not turn it into "hello".
+
+## sarvam_translate
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| input | string | Yes | Text to translate |
+| source_language_code | enum | No | Defaults to `auto` |
+| target_language_code | enum | No | Defaults to `hi-IN` |
+| model | enum | No | `sarvam-translate:v1` (22 langs, 2000 chars) or `mayura:v1` (10 langs, 1000 chars) |
+| mode | enum | No | `formal` (default), `modern-colloquial`, `classic-colloquial`, `code-mixed` |
+| speaker_gender | enum | No | `Male` / `Female`, for languages that inflect on it |
+| output_script | enum | No | `roman`, `fully-native`, `spoken-form-in-native` |
+| numerals_format | enum | No | `international` (default) or `native` |
+
+Languages: `as-IN bn-IN brx-IN doi-IN en-IN gu-IN hi-IN kn-IN kok-IN ks-IN
+mai-IN ml-IN mni-IN mr-IN ne-IN od-IN pa-IN sa-IN sat-IN sd-IN ta-IN te-IN
+ur-IN`.
+
+```json
+{
+ "translated_text": "नमस्ते दुनिया",
+ "source_language_code": "en-IN"
+}
+```
+
+Pick `mode` deliberately: `formal` for documents and notices,
+`modern-colloquial` for chat and app copy, `code-mixed` when the audience
+naturally mixes English with the target language.
+
+## sarvam_transliterate
+
+Languages: `bn-IN en-IN gu-IN hi-IN kn-IN ml-IN mr-IN od-IN pa-IN ta-IN
+te-IN` (plus `auto` as a source).
+
+Set `spoken_form: true` to expand numbers, dates and abbreviations into how
+they are said aloud — useful when the output feeds text-to-speech.
+
+```json
+{
+ "transliterated_text": "नमस्ते",
+ "source_language_code": "en-IN"
+}
+```
+
+## sarvam_detect_language
+
+Takes `input` (max 1000 characters) and returns a BCP-47 language code plus
+an ISO 15924 script code.
+
+```json
+{
+ "language_code": "hi-IN",
+ "script_code": "Deva"
+}
+```
+
+**Both fields can be `null`** when the text is too short or ambiguous.
+Always check before feeding the result into another call — do not assume a
+language was detected.
+
+## When to Use
+
+- Localising content into Indian languages
+- Normalising user input typed in Roman script into native script
+- Routing a message to the right handler based on its language
+- Preparing text for `sarvam_text_to_speech`, which needs a target language
+
+## When NOT to Use
+
+- Non-Indian languages — Sarvam covers Indian languages plus English only
+- Long documents in one call: cap is 2000 characters (`sarvam-translate:v1`)
+ or 1000 (`mayura:v1`). Split on sentence boundaries and translate in
+ batches; splitting mid-sentence degrades quality badly.
+- Changing script only — reach for `sarvam_transliterate`, not translate
+
+## API Details
+
+- **Translate**: POST `https://api.sarvam.ai/translate` — 20 INR / 10K characters
+- **Transliterate**: POST `https://api.sarvam.ai/transliterate`
+- **Language ID**: POST `https://api.sarvam.ai/text-lid` — 3.5 INR / 10K characters
+- **Auth**: `api-subscription-key` header
+
+## Setup Requirements
+
+A single Sarvam API key from [dashboard.sarvam.ai](https://dashboard.sarvam.ai),
+entered once in the Credentials modal under **Sarvam AI**. The same key
+covers translation, speech and the Sarvam chat models.
diff --git a/server/tests/llm/test_live_providers.py b/server/tests/llm/test_live_providers.py
index b2ec3a62..4feb962e 100644
--- a/server/tests/llm/test_live_providers.py
+++ b/server/tests/llm/test_live_providers.py
@@ -119,6 +119,7 @@ _PROVIDER_KEYS = {
"deepseek": ("DEEPSEEK_API_KEY",),
"kimi": ("KIMI_API_KEY", "MOONSHOT_API_KEY"),
"mistral": ("MISTRAL_API_KEY",),
+ "sarvam": ("SARVAM_API_KEY",),
"groq": ("GROQ_API_KEY",),
"cerebras": ("CEREBRAS_API_KEY",),
}
@@ -135,6 +136,7 @@ _LIVE_MODELS = {
"deepseek": "deepseek-chat",
"kimi": "kimi-k2.6",
"mistral": "mistral-small-latest",
+ "sarvam": "sarvam-30b",
"groq": "openai/gpt-oss-120b",
"cerebras": "gpt-oss-120b",
"ollama": None, # discovered from server
diff --git a/server/tests/llm/test_model_listing_fallback.py b/server/tests/llm/test_model_listing_fallback.py
new file mode 100644
index 00000000..bdc57c8c
--- /dev/null
+++ b/server/tests/llm/test_model_listing_fallback.py
@@ -0,0 +1,149 @@
+"""Contract for the JSON-driven ``supports_model_listing`` flag.
+
+A provider can speak the OpenAI wire format for chat completions and still
+ship no model-list route. Sarvam is the first: calling ``models.list()``
+against it 404s, and because that 404 surfaces as an ``openai.OpenAIError``
+the unifier turns it into ``NodeUserError`` and ``AIService.fetch_models``
+re-raises before reaching its curated fallback — so credential validation
+and the model dropdown would both fail for a perfectly valid key.
+
+``OpenAIProvider.fetch_models`` therefore reads
+``providers.<name>.supports_model_listing`` from llm_defaults.json. These
+tests pin both halves of that contract: the opt-out behaves, and — the part
+that actually protects the other twelve providers — nobody else takes the
+branch.
+"""
+
+from __future__ import annotations
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+import services.llm # noqa: F401 — side-effect import populates the registry
+from services.llm.config import (
+ LLM_DEFAULTS,
+ curated_models,
+ supports_model_listing,
+)
+from services.llm.providers.openai import OpenAIProvider
+from services.llm.registry import all_providers
+
+
+def _provider_with_mock_client(provider_name: str) -> OpenAIProvider:
+ with patch("openai.AsyncOpenAI"):
+ provider = OpenAIProvider("key", provider_name=provider_name)
+ provider._client = MagicMock(name="AsyncOpenAI")
+ provider._client.models.list = AsyncMock()
+ provider._client.chat.completions.create = AsyncMock()
+ return provider
+
+
+class TestFlagDefaults:
+ def test_absent_key_means_listing_is_supported(self):
+ assert supports_model_listing("provider-that-does-not-exist") is True
+
+ def test_sarvam_is_the_only_opt_out(self):
+ """Guards the other twelve providers against a behaviour change.
+
+ If this ever fails, some provider gained the flag — confirm that
+ was deliberate before updating the expectation.
+ """
+ opted_out = {p for p in all_providers() if not supports_model_listing(p)}
+ assert opted_out == {"sarvam"}
+
+
+class TestListingSupported:
+ """The default path is untouched: hit the real models endpoint."""
+
+ @pytest.mark.parametrize(
+ "provider_name",
+ sorted(p for p in all_providers() if supports_model_listing(p)),
+ )
+ async def test_calls_models_list_and_sorts(self, provider_name):
+ provider = _provider_with_mock_client(provider_name)
+ provider._client.models.list.return_value = SimpleNamespace(
+ data=[SimpleNamespace(id="z-model"), SimpleNamespace(id="a-model")]
+ )
+
+ models = await provider.fetch_models("key")
+
+ assert models == ["a-model", "z-model"]
+ provider._client.models.list.assert_awaited_once()
+ provider._client.chat.completions.create.assert_not_awaited()
+
+
+class TestListingUnsupported:
+ """The opt-out path: curated list + a one-token key probe."""
+
+ async def test_returns_curated_list_without_listing_models(self):
+ provider = _provider_with_mock_client("sarvam")
+
+ models = await provider.fetch_models("key")
+
+ assert models == curated_models("sarvam")
+ assert models == ["sarvam-105b", "sarvam-30b"]
+ provider._client.models.list.assert_not_awaited()
+
+ async def test_probes_the_key_with_a_one_token_completion(self):
+ provider = _provider_with_mock_client("sarvam")
+
+ await provider.fetch_models("key")
+
+ provider._client.chat.completions.create.assert_awaited_once()
+ kwargs = provider._client.chat.completions.create.await_args.kwargs
+ assert kwargs["max_tokens"] == 1
+ assert kwargs["model"] == "sarvam-105b"
+
+ async def test_probe_failure_propagates_as_the_typed_sdk_error(self):
+ """An invalid key must still fail validation, not silently pass."""
+ import openai
+
+ provider = _provider_with_mock_client("sarvam")
+ provider._client.chat.completions.create.side_effect = (
+ openai.AuthenticationError(
+ "bad key",
+ response=MagicMock(status_code=401, headers={}),
+ body=None,
+ )
+ )
+
+ with pytest.raises(openai.OpenAIError):
+ await provider.fetch_models("key")
+
+ async def test_empty_curated_list_fails_loudly(self, monkeypatch):
+ """A misedited JSON block must not hand the modal an empty dropdown."""
+ blocks = dict(LLM_DEFAULTS["providers"])
+ blocks["sarvam"] = {
+ **blocks["sarvam"],
+ "popular_models": [],
+ "max_output_tokens": {},
+ }
+ monkeypatch.setitem(LLM_DEFAULTS, "providers", blocks)
+
+ provider = _provider_with_mock_client("sarvam")
+ with pytest.raises(ValueError, match="declares no models"):
+ await provider.fetch_models("key")
+
+
+class TestCuratedModels:
+ def test_prefers_popular_models_when_present(self):
+ assert curated_models("openai") == LLM_DEFAULTS["providers"]["openai"]["popular_models"]
+
+ def test_falls_back_to_max_output_token_keys(self):
+ """Sarvam carries an empty popular_models under the >=1M policy."""
+ assert LLM_DEFAULTS["providers"]["sarvam"]["popular_models"] == []
+ assert curated_models("sarvam") == ["sarvam-105b", "sarvam-30b"]
+ assert "_default" not in curated_models("sarvam")
+
+ def test_unknown_provider_is_empty(self):
+ assert curated_models("nope") == []
+
+ def test_ai_service_delegates_to_the_shared_helper(self):
+ """Both callers must serve the same list or the dropdown drifts."""
+ from services.ai import AIService
+
+ service = AIService.__new__(AIService)
+ for provider in ("openai", "sarvam", "mistral"):
+ assert service._get_curated_models(provider) == curated_models(provider)
diff --git a/server/tests/llm/test_provider_self_registration.py b/server/tests/llm/test_provider_self_registration.py
index 112c432b..6c4a1006 100644
--- a/server/tests/llm/test_provider_self_registration.py
+++ b/server/tests/llm/test_provider_self_registration.py
@@ -33,6 +33,9 @@ EXPECTED_REGISTERED_PROVIDERS = {
# OpenAI-compatible /v1 endpoints so they share OpenAIProvider.
"groq",
"cerebras",
+ # Indic-first; OpenAI-compatible chat endpoint but no model-list route,
+ # which it declares via `supports_model_listing: false`.
+ "sarvam",
}
COMPAT_PROVIDERS = (
"xai",
@@ -43,6 +46,7 @@ COMPAT_PROVIDERS = (
"lmstudio",
"groq",
"cerebras",
+ "sarvam",
)
@@ -51,7 +55,7 @@ def test_all_expected_providers_registered():
assert set(all_providers()) >= EXPECTED_REGISTERED_PROVIDERS
-def test_all_twelve_providers_route_to_the_expected_native_class():
+def test_all_thirteen_providers_route_to_the_expected_native_class():
from services.llm.providers.anthropic import AnthropicProvider
from services.llm.providers.gemini import GeminiProvider
from services.llm.providers.openai import OpenAIProvider
@@ -90,6 +94,7 @@ def test_compat_providers_carry_base_url_in_client_kwargs():
"lmstudio": "http://localhost:1234/v1",
"groq": "https://api.groq.com/openai/v1",
"cerebras": "https://api.cerebras.ai/v1",
+ "sarvam": "https://api.sarvam.ai/v1",
}
for name, url in expected_base_urls.items():
spec = get_provider(name)
@@ -102,7 +107,7 @@ def test_compat_providers_carry_base_url_in_client_kwargs():
def test_every_compat_provider_inherits_shared_response_and_tool_contract(
provider_name,
):
- """One matrix gate covers normalization/schema behavior for all 8."""
+ """One matrix gate covers normalization/schema behavior for all 9."""
from services.llm.providers.openai import OpenAIProvider
diff --git a/server/tests/nodes/test_ai_chat_models.py b/server/tests/nodes/test_ai_chat_models.py
index 5e1013a3..51b21acb 100644
--- a/server/tests/nodes/test_ai_chat_models.py
+++ b/server/tests/nodes/test_ai_chat_models.py
@@ -1,10 +1,10 @@
-"""Contract tests for the 9 ai_chat_models nodes.
+"""Contract tests for the 10 ai_chat_models nodes.
Covered nodes: openaiChatModel, anthropicChatModel, geminiChatModel,
openrouterChatModel, groqChatModel, cerebrasChatModel, deepseekChatModel,
-kimiChatModel, mistralChatModel.
+kimiChatModel, mistralChatModel, sarvamChatModel.
-All 9 nodes share the SAME registry binding:
+All 10 nodes share the SAME registry binding:
partial(handle_ai_chat_model, ai_service=self.ai_service)
`handle_ai_chat_model` is a thin pass-through that awaits
@@ -44,6 +44,7 @@ ALL_PROVIDERS = [
("deepseekChatModel", "deepseek"),
("kimiChatModel", "kimi"),
("mistralChatModel", "mistral"),
+ ("sarvamChatModel", "sarvam"),
]
diff --git a/server/tests/nodes/test_sarvam.py b/server/tests/nodes/test_sarvam.py
new file mode 100644
index 00000000..bc666591
--- /dev/null
+++ b/server/tests/nodes/test_sarvam.py
@@ -0,0 +1,599 @@
+"""Contract tests for the five Sarvam service nodes.
+
+sarvamTranslate / sarvamTransliterate / sarvamDetectLanguage /
+sarvamSpeechToText / sarvamTextToSpeech.
+
+All five authenticate through ``ctx.connection("sarvam")``, which injects
+the ``api-subscription-key`` header from the shared credential — the same
+key the OpenAI-compatible ``sarvamChatModel`` uses. httpx is mocked with
+respx so no network is touched.
+"""
+
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+
+import httpx
+import pytest
+import respx
+
+from tests.nodes._mocks import patched_container, patched_pricing
+
+
+pytestmark = pytest.mark.node_contract
+
+_KEYS = {"sarvam": "sk_sarvam_test"}
+_BASE = "https://api.sarvam.ai"
+
+
+# ============================================================================
+# sarvamTranslate
+# ============================================================================
+
+
+class TestSarvamTranslate:
+ URL = f"{_BASE}/translate"
+
+ @respx.mock
+ async def test_happy_path(self, harness):
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 200,
+ json={
+ "request_id": "req-1",
+ "translated_text": "नमस्ते दुनिया",
+ "source_language_code": "en-IN",
+ },
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTranslate",
+ {
+ "input": "Hello world",
+ "source_language_code": "auto",
+ "target_language_code": "hi-IN",
+ },
+ )
+
+ harness.assert_envelope(result, success=True)
+ payload = result["result"]
+ assert payload["translated_text"] == "नमस्ते दुनिया"
+ assert payload["source_language_code"] == "en-IN"
+
+ sent = respx.calls.last.request
+ assert sent.headers["api-subscription-key"] == "sk_sarvam_test"
+
+ @respx.mock
+ async def test_unset_optionals_are_omitted_not_nulled(self, harness):
+ """Sarvam 422s on explicit nulls for several optional fields."""
+ import json
+
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 200, json={"translated_text": "x", "source_language_code": "en-IN"}
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ await harness.execute(
+ "sarvamTranslate",
+ {"input": "hi", "target_language_code": "ta-IN"},
+ )
+
+ body = json.loads(respx.calls.last.request.content)
+ assert "speaker_gender" not in body
+ assert "output_script" not in body
+ assert body["model"] == "sarvam-translate:v1"
+
+ async def test_input_over_model_cap_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTranslate",
+ {
+ "input": "x" * 1001,
+ "model": "mayura:v1",
+ "target_language_code": "hi-IN",
+ },
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "1001 characters" in result["error"]
+ assert "mayura:v1" in result["error"]
+
+ async def test_identical_language_pair_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTranslate",
+ {
+ "input": "hi",
+ "source_language_code": "hi-IN",
+ "target_language_code": "hi-IN",
+ },
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "identical" in result["error"]
+
+ @respx.mock
+ async def test_api_error_surfaces_sarvam_message(self, harness):
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 422, json={"error": {"message": "unsupported language pair"}}
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTranslate",
+ {"input": "hi", "target_language_code": "hi-IN"},
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "unsupported language pair" in result["error"]
+ assert "422" in result["error"]
+
+
+# ============================================================================
+# sarvamTransliterate
+# ============================================================================
+
+
+class TestSarvamTransliterate:
+ URL = f"{_BASE}/transliterate"
+
+ @respx.mock
+ async def test_happy_path(self, harness):
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 200,
+ json={
+ "transliterated_text": "नमस्ते",
+ "source_language_code": "en-IN",
+ },
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTransliterate",
+ {"input": "namaste", "target_language_code": "hi-IN"},
+ )
+
+ harness.assert_envelope(result, success=True)
+ assert result["result"]["transliterated_text"] == "नमस्ते"
+
+ @respx.mock
+ async def test_spoken_form_numerals_only_sent_when_spoken_form_on(self, harness):
+ import json
+
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 200, json={"transliterated_text": "x", "source_language_code": "en-IN"}
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ await harness.execute(
+ "sarvamTransliterate",
+ {"input": "42", "target_language_code": "hi-IN", "spoken_form": False},
+ )
+
+ body = json.loads(respx.calls.last.request.content)
+ assert body["spoken_form"] is False
+ assert "spoken_form_numerals_language" not in body
+
+
+# ============================================================================
+# sarvamDetectLanguage
+# ============================================================================
+
+
+class TestSarvamDetectLanguage:
+ URL = f"{_BASE}/text-lid"
+
+ @respx.mock
+ async def test_happy_path(self, harness):
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 200,
+ json={"request_id": "r", "language_code": "hi-IN", "script_code": "Deva"},
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamDetectLanguage", {"input": "नमस्ते"}
+ )
+
+ harness.assert_envelope(result, success=True)
+ assert result["result"]["language_code"] == "hi-IN"
+ assert result["result"]["script_code"] == "Deva"
+
+ @respx.mock
+ async def test_nulls_survive_as_none(self, harness):
+ """Sarvam returns nulls for unclassifiable input; don't coerce them."""
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 200, json={"language_code": None, "script_code": None}
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute("sarvamDetectLanguage", {"input": "?!"})
+
+ harness.assert_envelope(result, success=True)
+ assert result["result"]["language_code"] is None
+
+ async def test_over_cap_input_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamDetectLanguage", {"input": "x" * 1001}
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "1000" in result["error"]
+
+
+# ============================================================================
+# sarvamSpeechToText
+# ============================================================================
+
+
+class TestSarvamSpeechToText:
+ URL = f"{_BASE}/speech-to-text"
+
+ @respx.mock
+ async def test_accepts_a_file_path(self, harness, tmp_path):
+ clip = tmp_path / "clip.wav"
+ clip.write_bytes(b"RIFF....WAVE")
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(
+ 200,
+ json={
+ "transcript": "hello",
+ "language_code": "en-IN",
+ "language_probability": 0.98,
+ },
+ )
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamSpeechToText", {"audio_file": str(clip)}
+ )
+
+ harness.assert_envelope(result, success=True)
+ assert result["result"]["transcript"] == "hello"
+
+ sent = respx.calls.last.request
+ assert sent.headers["content-type"].startswith("multipart/form-data")
+ assert b"RIFF" in sent.content
+
+ @respx.mock
+ async def test_accepts_the_file_widget_upload_envelope(self, harness):
+ """The file widget sends {type, data, filename, mimeType}, not a path."""
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(200, json={"transcript": "ok"})
+ )
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamSpeechToText",
+ {
+ "audio_file": {
+ "type": "upload",
+ "data": base64.b64encode(b"AUDIOBYTES").decode(),
+ "filename": "voice.mp3",
+ "mimeType": "audio/mpeg",
+ }
+ },
+ )
+
+ harness.assert_envelope(result, success=True)
+ assert b"AUDIOBYTES" in respx.calls.last.request.content
+
+ @respx.mock
+ async def test_relative_path_resolves_against_the_workspace(self, harness, tmp_path):
+ (tmp_path / "audio").mkdir()
+ (tmp_path / "audio" / "a.wav").write_bytes(b"WAV")
+ respx.post(self.URL).mock(
+ return_value=httpx.Response(200, json={"transcript": "ok"})
+ )
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamSpeechToText", {"audio_file": "audio/a.wav"}, context=ctx
+ )
+
+ harness.assert_envelope(result, success=True)
+
+ async def test_missing_file_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamSpeechToText", {"audio_file": "/nope/missing.wav"}
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "not found" in result["error"].lower()
+
+ async def test_empty_audio_file_param_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute("sarvamSpeechToText", {})
+
+ harness.assert_envelope(result, success=False)
+ assert "audio_file is required" in result["error"]
+
+ async def test_advanced_mode_requires_saaras_v3(self, harness, tmp_path):
+ clip = tmp_path / "c.wav"
+ clip.write_bytes(b"WAV")
+
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamSpeechToText",
+ {
+ "audio_file": str(clip),
+ "model": "saarika:v2.5",
+ "mode": "codemix",
+ },
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "saaras:v3" in result["error"]
+
+
+# ============================================================================
+# sarvamTextToSpeech
+# ============================================================================
+
+
+class TestSarvamTextToSpeech:
+ URL = f"{_BASE}/text-to-speech"
+
+ @staticmethod
+ def _audio_response(chunks: int = 1) -> httpx.Response:
+ blob = base64.b64encode(b"RIFFfakeWAVEdata").decode()
+ return httpx.Response(
+ 200, json={"request_id": "r", "audios": [blob] * chunks}
+ )
+
+ @respx.mock
+ async def test_writes_to_the_workspace_by_default(self, harness, tmp_path):
+ respx.post(self.URL).mock(return_value=self._audio_response())
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech",
+ {"text": "Namaste", "target_language_code": "hi-IN"},
+ context=ctx,
+ )
+
+ harness.assert_envelope(result, success=True)
+ payload = result["result"]
+ written = Path(payload["file_path"])
+ assert written.is_file()
+ assert written.parent == tmp_path / "audio"
+ assert written.read_bytes() == b"RIFFfakeWAVEdata"
+ assert payload["chunk_count"] == 1
+ assert payload["files"] == [str(written)]
+ # The DB/WS bloat guard: no inline base64 unless asked for.
+ assert payload.get("audio_base64") is None
+
+ @respx.mock
+ async def test_base64_mode_returns_inline_and_writes_nothing(self, harness, tmp_path):
+ respx.post(self.URL).mock(return_value=self._audio_response())
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech",
+ {"text": "Namaste", "return_audio": "base64"},
+ context=ctx,
+ )
+
+ payload = result["result"]
+ assert payload["audio_base64"] == base64.b64encode(b"RIFFfakeWAVEdata").decode()
+ assert payload.get("file_path") is None
+ assert not (tmp_path / "audio").exists()
+
+ @respx.mock
+ async def test_multi_chunk_writes_one_file_per_chunk(self, harness, tmp_path):
+ respx.post(self.URL).mock(return_value=self._audio_response(chunks=3))
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech", {"text": "long text"}, context=ctx
+ )
+
+ payload = result["result"]
+ assert payload["chunk_count"] == 3
+ assert len(payload["files"]) == 3
+ assert all(Path(p).is_file() for p in payload["files"])
+ assert payload["file_path"] == payload["files"][0]
+ assert "3 audio chunks" in payload["note"]
+
+ @respx.mock
+ async def test_oversize_inline_audio_is_suppressed_with_a_note(
+ self, harness, tmp_path, monkeypatch
+ ):
+ """Never silently truncate — say why and point at the file mode."""
+ monkeypatch.setattr(
+ "nodes.sarvam.sarvam_text_to_speech._MAX_INLINE_B64", 4
+ )
+ respx.post(self.URL).mock(return_value=self._audio_response())
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech",
+ {"text": "hi", "return_audio": "base64"},
+ context=ctx,
+ )
+
+ payload = result["result"]
+ assert payload["audio_base64"] is None
+ assert "return_audio='file'" in payload["note"]
+
+ @respx.mock
+ async def test_v2_only_params_are_not_sent_for_v3(self, harness, tmp_path):
+ import json
+
+ respx.post(self.URL).mock(return_value=self._audio_response())
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ await harness.execute(
+ "sarvamTextToSpeech",
+ {"text": "hi", "model": "bulbul:v3", "speaker": "shubh"},
+ context=ctx,
+ )
+
+ body = json.loads(respx.calls.last.request.content)
+ assert "pitch" not in body
+ assert "loudness" not in body
+ assert "enable_preprocessing" not in body
+
+ @respx.mock
+ async def test_v2_params_are_sent_for_v2(self, harness, tmp_path):
+ import json
+
+ respx.post(self.URL).mock(return_value=self._audio_response())
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ await harness.execute(
+ "sarvamTextToSpeech",
+ {
+ "text": "hi",
+ "model": "bulbul:v2",
+ "speaker": "anushka",
+ "pitch": 0.2,
+ },
+ context=ctx,
+ )
+
+ body = json.loads(respx.calls.last.request.content)
+ assert body["pitch"] == 0.2
+ assert "temperature" not in body
+
+ async def test_speaker_from_the_wrong_model_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech",
+ {"text": "hi", "model": "bulbul:v3", "speaker": "anushka"},
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "not a bulbul:v3 voice" in result["error"]
+
+ async def test_text_over_model_cap_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech",
+ {"text": "x" * 1501, "model": "bulbul:v2", "speaker": "anushka"},
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "1500" in result["error"]
+
+ async def test_v3_pace_out_of_range_is_a_user_error(self, harness):
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech", {"text": "hi", "pace": 2.5}
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "0.5-2.0" in result["error"]
+
+ @respx.mock
+ async def test_empty_audio_array_is_a_user_error(self, harness, tmp_path):
+ respx.post(self.URL).mock(return_value=httpx.Response(200, json={"audios": []}))
+
+ ctx = harness.build_context(workspace_dir=str(tmp_path))
+ with patched_container(auth_api_keys=_KEYS), patched_pricing():
+ result = await harness.execute(
+ "sarvamTextToSpeech", {"text": "hi"}, context=ctx
+ )
+
+ harness.assert_envelope(result, success=False)
+ assert "no audio" in result["error"].lower()
+
+
+# ============================================================================
+# Cross-node contracts
+# ============================================================================
+
+
+class TestSarvamPluginContract:
+ NODE_TYPES = (
+ "sarvamTranslate",
+ "sarvamTransliterate",
+ "sarvamDetectLanguage",
+ "sarvamSpeechToText",
+ "sarvamTextToSpeech",
+ )
+
+ @pytest.mark.parametrize("node_type", NODE_TYPES)
+ def test_registered_in_the_language_group_and_usable_as_tool(self, node_type):
+ from services.node_registry import get_node_class
+
+ cls = get_node_class(node_type)
+ assert cls is not None
+ assert cls.group == ("language", "tool")
+ assert cls.usable_as_tool is True
+ assert cls.task_queue == "rest-api"
+
+ @pytest.mark.parametrize("node_type", NODE_TYPES)
+ def test_tool_name_is_the_snake_case_node_type(self, node_type):
+ """Skill `allowed-tools` resolution keys on this exact mapping."""
+ import re
+
+ from services.node_registry import get_node_class
+
+ expected = re.sub(r"(?<!^)(?=[A-Z])", "_", node_type).lower()
+ assert get_node_class(node_type).tool_name == expected
+
+ @pytest.mark.parametrize("node_type", NODE_TYPES)
+ def test_tool_schema_has_no_refs(self, node_type):
+ """LLM tool schemas must be flat — no $defs/$ref survive inlining.
+
+ Mirrors what ``AIService._get_tool_schema`` does for a plugin
+ exposed as a tool: inline the Params JSON schema.
+ """
+ from services.node_registry import get_node_class
+ from services.plugin.tool import inline_schema_refs
+
+ schema = inline_schema_refs(
+ get_node_class(node_type).Params.model_json_schema()
+ )
+ rendered = repr(schema)
+ assert "$defs" not in rendered
+ assert "$ref" not in rendered
+
+ @pytest.mark.parametrize("node_type", NODE_TYPES)
+ def test_shares_the_single_sarvam_credential(self, node_type):
+ from nodes.model._credentials import SarvamCredential
+ from services.node_registry import get_node_class
+
+ assert get_node_class(node_type).credentials == (SarvamCredential,)
+
+ def test_credential_injects_sarvams_native_header(self):
+ """Chat rides Bearer via the openai SDK; these APIs need this header."""
+ from nodes.model._credentials import SarvamCredential
+
+ req = SarvamCredential.inject({"api_key": "k"}, {"headers": {}})
+ assert req["headers"] == {"api-subscription-key": "k"}
+
+ @pytest.mark.parametrize("node_type", NODE_TYPES)
+ def test_output_schema_is_registered(self, node_type):
+ """Drives the parameter panel's "Input Data & Variables" listing."""
+ from services.node_output_schemas import get_node_output_schema
+
+ schema = get_node_output_schema(node_type)
+ assert schema is not None
+ assert schema.get("properties")
diff --git a/server/tests/services/test_connection_multipart.py b/server/tests/services/test_connection_multipart.py
new file mode 100644
index 00000000..eb85e50b
--- /dev/null
+++ b/server/tests/services/test_connection_multipart.py
@@ -0,0 +1,106 @@
+"""Contract for ``Connection.request(files=...)`` multipart support.
+
+``Connection`` is the authed HTTP facade every REST plugin uses. It
+originally accepted only ``headers`` / ``params`` / ``json`` / ``data``,
+which meant any plugin needing a file upload had to bypass it and hand-roll
+credential resolution — losing the auth-retry and the structured
+missing-credential envelope. ``files`` closes that gap generically; the
+Sarvam speech-to-text node is the first consumer.
+
+The replay assertion is the load-bearing one: the auth-retry path rebuilds
+the request kwargs from scratch, so ``files`` must be threaded into BOTH
+branches or a 401 would silently retry with an empty body.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+import respx
+
+from services.plugin.credential import ApiKeyCredential
+from services.plugin.connection import Connection
+
+
+class _StubCredential(ApiKeyCredential):
+ id = "multipart_stub"
+ display_name = "Multipart Stub"
+ category = "Test"
+ key_name = "X-Stub-Key"
+ key_location = "header"
+
+ _resolve_calls = 0
+
+ @classmethod
+ async def resolve(cls, *, user_id: str = "owner"):
+ cls._resolve_calls += 1
+ return {"api_key": f"key-{cls._resolve_calls}"}
+
+
+URL = "https://upload.example.com/v1/transcribe"
+
+
[email protected](autouse=True)
+def _reset_stub():
+ _StubCredential._resolve_calls = 0
+ yield
+
+
+async def test_files_reach_httpx_as_multipart():
+ respx.post(URL).mock(return_value=httpx.Response(200, json={"ok": True}))
+
+ async with Connection(_StubCredential) as conn:
+ response = await conn.post(
+ URL,
+ files={"file": ("clip.wav", b"RIFFDATA", "audio/wav")},
+ data={"model": "saaras:v3"},
+ )
+
+ assert response.status_code == 200
+ sent = respx.calls.last.request
+ assert sent.headers["content-type"].startswith("multipart/form-data")
+ assert b"RIFFDATA" in sent.content
+ assert b'name="model"' in sent.content
+ # Auth still injected by the credential class, not the caller.
+ assert sent.headers["X-Stub-Key"] == "key-1"
+
+
+async def test_auth_retry_replays_the_file_payload():
+ """A 401 must re-send the same parts, not an empty body."""
+ respx.post(URL).mock(
+ side_effect=[
+ httpx.Response(401, json={"error": "expired"}),
+ httpx.Response(200, json={"ok": True}),
+ ]
+ )
+
+ async with Connection(_StubCredential) as conn:
+ response = await conn.post(
+ URL,
+ files={"file": ("clip.wav", b"RIFFDATA", "audio/wav")},
+ data={"model": "saaras:v3"},
+ )
+
+ assert response.status_code == 200
+ assert len(respx.calls) == 2
+
+ retry = respx.calls[1].request
+ assert b"RIFFDATA" in retry.content
+ assert b'name="model"' in retry.content
+ # Credentials were re-resolved, so the retry carries the fresh key.
+ assert retry.headers["X-Stub-Key"] == "key-2"
+
+
+async def test_absent_files_is_unchanged_json_behaviour():
+ """The new kwarg must not perturb the existing JSON path."""
+ respx.post(URL).mock(return_value=httpx.Response(200, json={"ok": True}))
+
+ async with Connection(_StubCredential) as conn:
+ await conn.post(URL, json={"hello": "world"})
+
+ sent = respx.calls.last.request
+ assert sent.headers["content-type"] == "application/json"
+ assert b'"hello"' in sent.content
diff --git a/server/tests/test_node_spec.py b/server/tests/test_node_spec.py
index ab05e255..8b53b807 100644
--- a/server/tests/test_node_spec.py
+++ b/server/tests/test_node_spec.py
@@ -263,7 +263,7 @@ class TestPhase3cCoverage:
"ai_employee",
"rlm_agent",
"claude_code_agent",
- # Chat models (9)
+ # Chat models (10)
"openaiChatModel",
"anthropicChatModel",
"geminiChatModel",
@@ -273,6 +273,7 @@ class TestPhase3cCoverage:
"deepseekChatModel",
"kimiChatModel",
"mistralChatModel",
+ "sarvamChatModel",
]
def test_all_have_metadata(self):