@pinecall/skills 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinecall/skills",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Agent Skills for the Pinecall SDK — installable into Claude Code, Antigravity, Cursor, Copilot and any agent that supports the open Skills format.",
   "type": "module",
   "license": "MIT",

package/skills/pinecall-reference/SKILL.md

@@ -20,6 +20,7 @@ table below indexes every page; open the `references/…` file for the full text
 | **STT Providers** | Speech-to-text providers, models, and tuning parameters. | [`references/reference/stt-providers.md`](references/reference/stt-providers.md) · [docs](https://docs.pinecall.io/reference/stt-providers) |
 | **TTS Providers** | Text-to-speech providers, voices, and tuning parameters. | [`references/reference/tts-providers.md`](references/reference/tts-providers.md) · [docs](https://docs.pinecall.io/reference/tts-providers) |
 | **LLM Providers** | Server-side LLM providers and configuration. | [`references/reference/llm-providers.md`](references/reference/llm-providers.md) · [docs](https://docs.pinecall.io/reference/llm-providers) |
+| **Managed vs Bring-Your-Own-Key** | Which STT/TTS/LLM models Pinecall serves with its own keys, and which require yours. | [`references/reference/managed-vs-byok.md`](references/reference/managed-vs-byok.md) · [docs](https://docs.pinecall.io/reference/managed-vs-byok) |
 | **Session Limits** | Safety limits to prevent runaway sessions. | [`references/reference/session-limits.md`](references/reference/session-limits.md) · [docs](https://docs.pinecall.io/reference/session-limits) |
 | **REST API** | Static helpers for the Pinecall management API. No WebSocket needed. | [`references/reference/rest-api.md`](references/reference/rest-api.md) · [docs](https://docs.pinecall.io/reference/rest-api) |
 

package/skills/pinecall-reference/references/reference/llm-providers.md

@@ -37,6 +37,28 @@ llm: "gpt-5-chat-latest"
 
 > The legacy `provider:model` format (e.g. `"openai:gpt-5-chat-latest"`) still works but is not recommended.
 
+## Managed vs bring-your-own-key (BYOK)
+
+Data-driven from the rate table — see [Managed vs BYOK](/reference/managed-vs-byok)
+for the full list and the live `GET /api/rates/models` query.
+
+| LLM provider | Managed (no key needed) | Notes |
+|---|---|---|
+| `openai` | ✅ Yes | Default, recommended |
+| `anthropic` (`claude`) | ✅ Yes | |
+| `google` (`gemini`) | ✅ Yes | |
+| `mistral` | ✅ Yes | |
+| `xai` (`grok`) | ❌ BYOK only | Add an xAI key |
+| `groq` | ❌ BYOK only | Add a Groq key |
+| `cerebras` | ❌ BYOK only | Add a Cerebras key |
+| `deepseek` | ❌ BYOK only | Add a DeepSeek key |
+| `openrouter` | ❌ BYOK only | One key → many models; model = full slug, e.g. `x-ai/grok-4` |
+
+> **BYOK enforcement:** configuring a BYOK-only LLM provider without a saved key for
+> it rejects agent registration with `PROVIDER_KEY_REQUIRED` — Pinecall never falls
+> back to its own key. With your own key, those tokens are billed by the provider
+> directly and are **not** deducted from your Pinecall credits.
+
 ## Tuning with a full config object
 
 For `temperature`, `max_tokens`, and other tuning parameters, use the full config object:
@@ -104,7 +126,7 @@ llm: {
 ## Google (Gemini)
 
 ```typescript
-llm: "google/gemini-2.0-flash"
+llm: "google/gemini-2.5-flash"
 ```
 
 Or with tuning:
@@ -112,7 +134,7 @@ Or with tuning:
 ```typescript
 llm: {
   provider: "google",
-  model: "gemini-2.0-flash",
+  model: "gemini-2.5-flash",
   enabled: true,
   temperature: 0.7,
   max_tokens: 512,
@@ -125,8 +147,7 @@ llm: {
 
 | Model | Best for |
 |---|---|
-| `gemini-2.0-flash` | Most voice agents — fast and low cost (recommended default) |
-| `gemini-2.5-flash` | Stronger reasoning at a modest cost bump |
+| `gemini-2.5-flash` | Most voice agents — fast, low cost, strong reasoning (recommended default) |
 
 ## Anthropic
 
@@ -157,6 +178,66 @@ llm: {
 
 > Opus is intentionally **not** offered for voice agents — it's the premium tier (too slow/costly for real-time). Sonnet 4.6 and Haiku 4.5 are the supported Anthropic models. Set your `ANTHROPIC_API_KEY` on the server (managed) or add an Anthropic credential to your org (BYOK).
 
+## xAI Grok (BYOK)
+
+```typescript
+llm: "xai/grok-4"        // "grok" is accepted as an alias for "xai"
+```
+
+Or with tuning (same config shape as OpenAI — see [Temperature & max_tokens](#temperature--max_tokens)):
+
+```typescript
+llm: {
+  provider: "xai",
+  model: "grok-4",
+  enabled: true,
+  temperature: 0.7,
+  max_tokens: 512,
+}
+```
+
+OpenAI-compatible. Requires your own xAI key. Models: `grok-4`, `grok-4-fast`, `grok-3`.
+
+> **All BYOK LLM providers below (Groq, Cerebras, DeepSeek, OpenRouter) are
+> OpenAI-compatible** — they take the **identical config object** (`provider`,
+> `model`, `temperature`, `max_tokens`, `enabled`) and support the same tools /
+> tuning as OpenAI. Only the `provider` and `model` change.
+
+## Groq (BYOK)
+
+```typescript
+llm: "groq/llama-3.3-70b-versatile"
+```
+
+Fastest open-model inference. Requires your own Groq key.
+
+## Cerebras (BYOK)
+
+```typescript
+llm: "cerebras/llama-3.3-70b"
+```
+
+Highest tokens/sec. Requires your own Cerebras key.
+
+## DeepSeek (BYOK)
+
+```typescript
+llm: "deepseek/deepseek-chat"     // or "deepseek/deepseek-reasoner" (no tools)
+```
+
+Requires your own DeepSeek key.
+
+## OpenRouter (BYOK)
+
+One key unlocks hundreds of models (OpenAI, Anthropic, Google, xAI/Grok, Llama, …).
+The `model` is the **full OpenRouter slug** — it keeps its own slash:
+
+```typescript
+llm: { provider: "openrouter", model: "x-ai/grok-4" }
+```
+
+Requires your own OpenRouter key.
+
 ## The `enabled` field
 
 `enabled: false` disables server-side LLM for this agent. The server still does STT and TTS, but it won't generate responses — you handle every `turn.end` yourself with a client-side LLM.

package/skills/pinecall-reference/references/reference/managed-vs-byok.md

@@ -0,0 +1,92 @@
+---
+title: "Managed vs Bring-Your-Own-Key"
+description: "Which STT/TTS/LLM models Pinecall serves with its own keys, and which require yours."
+---
+
+# Managed vs Bring-Your-Own-Key (BYOK)
+
+Every STT, TTS and LLM model on Pinecall is one of two kinds:
+
+- **Managed** — Pinecall serves it with **its own provider key**. You don't add
+  anything; usage is deducted from your Pinecall **credits**.
+- **BYOK (bring your own key)** — Pinecall does **not** host a key for it. You must
+  save your **own** API key under **Provider Keys**. That usage is billed by the
+  provider **directly** and is **not** deducted from your Pinecall credits.
+
+> This split is **data-driven** — it comes from the Pinecall **rate table** in the
+> database (each rate has a `managed` flag), not from a hardcoded list. The tables
+> below are the current state; query the API (below) for the authoritative, live list.
+
+## What Pinecall provides managed (no key needed)
+
+| Service | Managed providers |
+|---|---|
+| **STT** | `deepgram` (flux, nova-3), `gladia`, `transcribe` (AWS) |
+| **TTS** | `elevenlabs`, `cartesia` (sonic), `polly` (AWS) |
+| **LLM** | `openai`, `anthropic`, `google` (gemini), `mistral` |
+
+## What requires your own key (BYOK)
+
+| Service | BYOK-only providers |
+|---|---|
+| **STT** | `cartesia` (ink-whisper), `elevenlabs` (scribe), `assemblyai` |
+| **TTS** | `rime` |
+| **LLM** | `xai` (grok), `groq`, `cerebras`, `deepseek`, `openrouter` |
+
+> Note a provider can be **managed for one service and BYOK for another** — e.g.
+> Cartesia **TTS** (sonic) is managed, but Cartesia **STT** (ink-whisper) is BYOK.
+> ElevenLabs **TTS** is managed, ElevenLabs **STT** (scribe) is BYOK.
+
+## Check it from the API (authoritative, live)
+
+The rate table is the source of truth. Query it any time:
+
+```bash
+curl https://playground.pinecall.io/api/rates/models
+```
+
+```jsonc
+{
+  "models": [
+    { "service": "stt", "provider": "deepgram",   "model": "nova-3",      "managed": true  },
+    { "service": "stt", "provider": "assemblyai",  "model": "universal",   "managed": false },
+    { "service": "llm", "provider": "xai",         "model": "grok-4",      "managed": false },
+    { "service": "tts", "provider": "rime",        "model": "mistv2",      "managed": false }
+    // ...
+  ],
+  "managedProviders": {
+    "stt": ["deepgram", "gladia", "transcribe"],
+    "tts": ["cartesia", "elevenlabs", "polly"],
+    "llm": ["anthropic", "google", "mistral", "openai"]
+  }
+}
+```
+
+`managed: true` → usable with no key. `managed: false` → add your own key.
+
+## BYOK enforcement
+
+If you configure a BYOK-only provider and your org has **not** saved a key for it,
+**agent registration is rejected** with code `PROVIDER_KEY_REQUIRED`:
+
+```
+LLM provider 'xai' requires your own API key. Pinecall does not provide a managed
+key for 'xai' — add your key under Provider Keys in the dashboard, then reconnect.
+```
+
+Pinecall never silently falls back to its own key for a BYOK provider.
+
+## Add your own key
+
+- **Dashboard** → **Provider Keys** → pick the provider, paste the key.
+- **API**: `PUT /api/credentials` with `{ "provider": "xai", "apiKey": "..." }`.
+
+One key can cover multiple services where a provider shares it — e.g. an
+**ElevenLabs** key enables both ElevenLabs TTS and ElevenLabs Scribe STT; a
+**Cartesia** key enables Sonic TTS and Ink-Whisper STT.
+
+## What's next
+
+- [STT Providers](/reference/stt-providers)
+- [TTS Providers](/reference/tts-providers)
+- [LLM Providers](/reference/llm-providers)

package/skills/pinecall-reference/references/reference/stt-providers.md

@@ -24,8 +24,35 @@ Pinecall supports multiple STT providers. Use the `provider/model` format or a f
 
 // AWS Transcribe
 { stt: "transcribe" }
+
+// ── Bring-your-own-key only (add your key under Provider Keys first) ──
+{ stt: "cartesia/ink-whisper" }      // Cartesia Ink-Whisper
+{ stt: "elevenlabs/scribe" }         // ElevenLabs Scribe v2 (realtime)
+{ stt: "assemblyai/universal" }      // AssemblyAI Universal-3
 ```
 
+## Managed vs bring-your-own-key (BYOK)
+
+Some providers work out of the box on Pinecall's managed keys; the newer ones
+require **your own API key** (saved under **Provider Keys** in the dashboard). This
+split is data-driven from the rate table — see [Managed vs BYOK](/reference/managed-vs-byok)
+for the full list and the live `GET /api/rates/models` query.
+
+| STT provider | Managed (no key needed) | Notes |
+|---|---|---|
+| `deepgram` (flux/nova) | ✅ Yes | Default, recommended |
+| `gladia` | ✅ Yes | |
+| `transcribe` (AWS) | ✅ Yes | |
+| `cartesia` (ink-whisper) | ❌ BYOK only | Add a Cartesia key |
+| `elevenlabs` (scribe) | ❌ BYOK only | Add an ElevenLabs key |
+| `assemblyai` (universal) | ❌ BYOK only | Add an AssemblyAI key |
+
+> **BYOK enforcement:** if you configure a BYOK-only STT provider and your org has
+> not saved a key for it, **agent registration is rejected** with
+> `PROVIDER_KEY_REQUIRED` — Pinecall never falls back to its own key for these.
+> When you bring your own key, that usage is billed by the provider directly and is
+> **not** deducted from your Pinecall credits.
+
 ## Naming convention
 
 Configuration objects that pass through to providers keep **snake_case** to mirror what the receiving side expects (`endpointing_ms`, `interim_results`, etc.). This avoids an unnecessary translation layer and lets you copy-paste from provider docs directly.
@@ -108,6 +135,48 @@ stt: {
 }
 ```
 
+## Cartesia Ink-Whisper (BYOK)
+
+Pairs naturally with Cartesia (Sonic) TTS for a single-vendor voice stack. Requires
+your own Cartesia key.
+
+```typescript
+stt: "cartesia/ink-whisper"
+// or
+stt: { provider: "cartesia", model: "ink-whisper", language: "en" }
+```
+
+## ElevenLabs Scribe (BYOK)
+
+Realtime `scribe_v2_realtime`. Uses the same ElevenLabs key as ElevenLabs TTS.
+
+```typescript
+stt: "elevenlabs/scribe"
+// or with tuning
+stt: {
+  provider: "elevenlabs",
+  model: "scribe_v2_realtime",
+  language: "en",
+  commit_strategy: "vad",   // "vad" (server segments turns) | "manual"
+}
+```
+
+## AssemblyAI (BYOK)
+
+Universal-3 streaming (`u3-rt-pro`) — strong accuracy + diarization. Requires your
+own AssemblyAI key.
+
+```typescript
+stt: "assemblyai/universal"
+// or with tuning
+stt: {
+  provider: "assemblyai",
+  model: "u3-rt-pro",
+  language: "en",
+  format_turns: true,   // punctuated/cased final transcripts
+}
+```
+
 ## Which to choose
 
 | Provider | Best for | Trade-off |
@@ -116,6 +185,9 @@ stt: {
 | `deepgram/nova-3` | Arabic, Hindi, Thai, CJK, and 60+ languages | Slightly higher latency; smart_turn + silero VAD |
 | `gladia/solaria` | Code-switching, multilingual | Higher latency than Deepgram |
 | `transcribe` | AWS-native deployments | AWS pricing model |
+| `cartesia/ink-whisper` | Single-vendor with Cartesia TTS | BYOK only |
+| `elevenlabs/scribe` | Single-vendor with ElevenLabs TTS | BYOK only |
+| `assemblyai/universal` | Accuracy + diarization | BYOK only |
 
 For most agents, start with `deepgram/flux`. Use `deepgram/nova-3` for languages Flux doesn't cover (Arabic, Hindi, Thai, Chinese, Japanese, Korean, etc.).
 

package/skills/pinecall-reference/references/reference/tts-providers.md

@@ -21,6 +21,22 @@ Pinecall supports multiple TTS providers. Use the `provider/friendly-id` format
 
 > The legacy `provider:rawId` format (e.g. `"elevenlabs:EXAVITQu4vr4xnSDxMaL"`) still works but is not recommended.
 
+## Managed vs bring-your-own-key (BYOK)
+
+Data-driven from the rate table — see [Managed vs BYOK](/reference/managed-vs-byok)
+for the full list and the live `GET /api/rates/models` query.
+
+| TTS provider | Managed (no key needed) | Notes |
+|---|---|---|
+| `elevenlabs` | ✅ Yes | Default, recommended |
+| `cartesia` (sonic) | ✅ Yes | |
+| `polly` (AWS) | ✅ Yes | |
+| `rime` | ❌ BYOK only | Add a Rime key under Provider Keys |
+
+> **BYOK enforcement:** configuring `rime` without a saved Rime key rejects agent
+> registration with `PROVIDER_KEY_REQUIRED`. With your own key, that usage is billed
+> by the provider directly — **not** deducted from your Pinecall credits.
+
 ## Discovering voices
 
 Use the CLI to browse voices. Without flags, you get a catalog overview:
@@ -173,6 +189,21 @@ Shortcut: `"polly/joanna"`
 - `engine: "neural"` is required for natural-sounding output. The older `standard` engine is robotic.
 - Polly is the cheapest option but the least natural — fine for IVR-style flows, not for engaging conversation.
 
+## Rime (BYOK)
+
+Ultra-natural, expressive English. Requires your own Rime key.
+
+```typescript
+voice: {
+  provider: "rime",
+  voice_id: "cove",      // Rime speaker id
+  model: "mistv2",        // or "arcana" (most expressive)
+  speed: 1.0,
+}
+```
+
+Shortcut: `"rime/cove"`
+
 ## Which to choose
 
 | Provider | Best for | Trade-off |
@@ -180,6 +211,7 @@ Shortcut: `"polly/joanna"`
 | **ElevenLabs** | Most natural-sounding output | Higher cost per character |
 | **Cartesia** | Real-time streaming, low latency | Smaller voice library |
 | **Polly** | Cheap IVR, simple flows | Less natural |
+| **Rime** | Ultra-natural expressive English | BYOK only; English-focused |
 
 For most agents, start with ElevenLabs (`eleven_flash_v2_5`) or Cartesia (`sonic-3`). Use Polly only for high-volume, low-engagement flows.