@elizaos/plugin-groq 2.0.0-beta.1 → 2.0.3-beta.2

package/README.md

@@ -1,75 +1,80 @@
 # @elizaos/plugin-groq
 
-Groq LLM plugin for elizaOS - Fast inference with GPT-OSS models.
+Groq LLM plugin for elizaOS — fast inference for text generation, audio transcription, and text-to-speech synthesis via Groq's API.
 
-This plugin provides Groq API integration for elizaOS agents, enabling ultra-fast text generation, audio transcription, and text-to-speech synthesis.
+## What it does
 
-## Features
+Registers model handlers so any Eliza agent can use Groq as its inference backend. The plugin auto-enables itself whenever `GROQ_API_KEY` is present — no manual registration required.
 
-- 🚀 **Fast Inference** - Leverage Groq's LPU for industry-leading inference speeds
-- 📝 **Text Generation** - Generate text with GPT-OSS models
-- 🎤 **Audio Transcription** - Transcribe audio with Whisper models
-- 🔊 **Text-to-Speech** - Generate speech with PlayAI voices
-- 🔢 **Object Generation** - Generate structured JSON objects
-- 🎯 **Tokenization** - Tokenize and detokenize text
+Supported capabilities:
 
-## Installation
+- **Text generation** across five size tiers (nano, small, medium, large, mega) with native tool-calling and structured JSON output
+- **Audio transcription** via `whisper-large-v3-turbo`
+- **Text-to-speech** synthesis (returns `Uint8Array` audio)
+- **Response handler** and **action planner** model roles with tier-appropriate defaults
 
-### TypeScript/JavaScript (npm)
+## Installation
 
 ```bash
-npm install @elizaos/plugin-groq
-# or
 bun add @elizaos/plugin-groq
+# or
+npm install @elizaos/plugin-groq
 ```
-## Usage
 
-### TypeScript
+## Quick start
 
 ```typescript
 import { groqPlugin } from "@elizaos/plugin-groq";
 
-// Add to your agent's plugins
-const agent = new Agent({
+// Pass to your agent's plugin list — or set GROQ_API_KEY and let auto-enable handle it.
+const agent = new AgentRuntime({
   plugins: [groqPlugin],
+  // ...
 });
 ```
-## Configuration
 
-Set the following environment variables:
-
-| Variable           | Required | Default                          | Description           |
-| ------------------ | -------- | -------------------------------- | --------------------- |
-| `GROQ_API_KEY`     | Yes      | -                                | Your Groq API key     |
-| `GROQ_BASE_URL`    | No       | `https://api.groq.com/openai/v1` | Custom API base URL   |
-| `GROQ_SMALL_MODEL` | No       | `openai/gpt-oss-120b`           | Model for small tasks |
-| `GROQ_LARGE_MODEL` | No       | `openai/gpt-oss-120b`            | Model for large tasks |
-| `GROQ_TTS_MODEL`   | No       | `canopylabs/orpheus-v1-english`  | Text-to-speech model  |
-| `GROQ_TTS_VOICE`   | No       | `troy`                           | TTS voice name        |
-| `GROQ_TTS_RESPONSE_FORMAT` | No | `wav`                          | TTS response format   |
-
-## Model Capabilities
-
-This plugin provides handlers for the following elizaOS model types:
+## Configuration
 
-| Model Type              | Description                                     |
-| ----------------------- | ----------------------------------------------- |
-| `TEXT_SMALL`            | Fast text + structured output via native tool calling (tools, toolChoice, responseSchema) |
-| `TEXT_LARGE`            | Capable text + structured output via native tool calling (tools, toolChoice, responseSchema) |
-| `TRANSCRIPTION`         | Audio transcription with Whisper                |
-| `TEXT_TO_SPEECH`        | Speech synthesis with PlayAI                    |
-| `TEXT_TOKENIZER_ENCODE` | Tokenize text to tokens                         |
-| `TEXT_TOKENIZER_DECODE` | Detokenize tokens to text                       |
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `GROQ_API_KEY` | **Yes** | — | Groq API key; also triggers auto-enable |
+| `GROQ_BASE_URL` | No | `https://api.groq.com/openai/v1` | Override for proxies |
+| `GROQ_SMALL_MODEL` | No | `openai/gpt-oss-120b` | Model for small/nano/medium tiers |
+| `GROQ_LARGE_MODEL` | No | `openai/gpt-oss-120b` | Model for large/mega tiers |
+| `GROQ_NANO_MODEL` | No | falls back to small | Explicit nano-tier model |
+| `GROQ_MEDIUM_MODEL` | No | falls back to small | Explicit medium-tier model |
+| `GROQ_MEGA_MODEL` | No | falls back to large | Explicit mega-tier model |
+| `GROQ_RESPONSE_HANDLER_MODEL` | No | nano tier | Model for response-handler role |
+| `GROQ_ACTION_PLANNER_MODEL` | No | large tier | Model for action-planner role |
+| `GROQ_TTS_MODEL` | No | `canopylabs/orpheus-v1-english` | Text-to-speech model |
+| `GROQ_TTS_VOICE` | No | `troy` | TTS voice |
+| `GROQ_TTS_RESPONSE_FORMAT` | No | `wav` | TTS audio format |
+
+All settings can also be passed via `agentConfig.pluginParameters` in your agent's character file.
+
+## Model types registered
+
+| elizaOS model type | Notes |
+|---|---|
+| `TEXT_NANO` | Fastest/cheapest text generation |
+| `TEXT_SMALL` | Small-tier text; supports tools + structured output |
+| `TEXT_MEDIUM` | Medium-tier text |
+| `TEXT_LARGE` | Large-tier text; supports tools + structured output |
+| `TEXT_MEGA` | Mega-tier text |
+| `RESPONSE_HANDLER` | Defaults to nano for low-latency response routing |
+| `ACTION_PLANNER` | Defaults to large for reasoning-heavy planning |
+| `TRANSCRIPTION` | Whisper transcription (Node only) |
+| `TEXT_TO_SPEECH` | Speech synthesis (Node only) |
+
+## Browser support
+
+Text generation works in browser contexts when `GROQ_BASE_URL` points to a server-side proxy. `TRANSCRIPTION` and `TEXT_TO_SPEECH` are Node-only and will throw in browser environments. Set `GROQ_ALLOW_BROWSER_API_KEY=true` only if you intentionally want to expose the API key from browser code.
 
 ## Development
 
-### Building from Source
-
 ```bash
-# TypeScript
-bun install
-bun run build
-# TypeScript
-bun run test
-# TypeScript
-bun run format:check
+bun run --cwd plugins/plugin-groq build    # compile
+bun run --cwd plugins/plugin-groq test     # unit tests
+bun run --cwd plugins/plugin-groq typecheck
+bun run --cwd plugins/plugin-groq lint
+```

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@elizaos/plugin-groq",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.3-beta.2",
   "type": "module",
   "main": "dist/node/index.node.js",
   "module": "dist/node/index.node.js",
-  "types": "dist/node/index.d.ts",
+  "types": "dist/index.d.ts",
   "browser": "dist/browser/index.browser.js",
   "repository": {
     "type": "git",
@@ -13,7 +13,7 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "types": "./dist/node/index.d.ts",
+      "types": "./dist/index.d.ts",
       "browser": {
         "types": "./dist/browser/index.d.ts",
         "import": "./dist/browser/index.browser.js",
@@ -24,14 +24,13 @@
         "import": "./dist/node/index.node.js",
         "default": "./dist/node/index.node.js"
       },
-      "import": {
-        "types": "./dist/node/index.d.ts",
-        "default": "./dist/node/index.node.js"
-      },
-      "default": {
-        "types": "./dist/node/index.d.ts",
-        "default": "./dist/node/index.node.js"
-      }
+      "default": "./dist/node/index.node.js"
+    },
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
     }
   },
   "sideEffects": false,
@@ -52,7 +51,7 @@
   },
   "dependencies": {
     "@ai-sdk/groq": "^3.0.4",
-    "@elizaos/core": "2.0.0-beta.1",
+    "@elizaos/core": "2.0.3-beta.2",
     "ai": "^6.0.0"
   },
   "devDependencies": {
@@ -64,7 +63,7 @@
   },
   "scripts": {
     "dev": "bun run build.ts --watch",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "tsgo --noEmit -p tsconfig.json",
     "clean": "rm -rf dist",
     "format": "bunx @biomejs/biome format --write .",
     "test": "vitest run --config vitest.config.ts",
@@ -134,5 +133,6 @@
       "browser": "Browser-compatible build available via exports.browser",
       "node": "Node.js build available via exports.node"
     }
-  }
+  },
+  "gitHead": "82fe0f44215954c2417328203f5bd6510985c1fc"
 }