groq-browserbase-client

A Groq client implementation for Stagehand.

Using with Stagehand

This client is designed to work seamlessly with Stagehand for AI-powered web automation. The examples use Qwen 2.5 32B, which has a 128k token context window and excellent capabilities for tool calling and structured outputs:

import { Stagehand } from '@browserbasehq/stagehand';
import { GroqClient } from 'groq-browserbase-client';

// Create the Groq client
const llmClient = new GroqClient({
  modelName: 'qwen-2.5-32b',
  clientOptions: {
    apiKey: process.env.GROQ_API_KEY,
  },
});

// Initialize Stagehand with the Groq client
const stagehand = new Stagehand({
  llmClient,
  env: 'LOCAL',
  headless: false,
  verbose: true,
});

// Use Stagehand's natural language commands
await stagehand.act('Go to example.com and click the login button');
const data = await stagehand.extract('Get all product names from the page');
const elements = await stagehand.observe('What interactive elements are visible?');

Installation

npm install groq-browserbase-client

Usage

Configuration Options

The GroqClient constructor accepts the following options:

{
  modelName: string;           // The Groq model to use
  clientOptions: {
    apiKey?: string;          // Your Groq API key
    baseURL?: string;         // Custom API URL (optional)
    maxRetries?: number;      // Number of retries for failed requests (default: 2)
    timeout?: number;         // Request timeout in ms (default: 60000)
    skipTokenLimitCheck?: boolean; // Skip token limit validation (default: false)
  };
  enableCaching?: boolean;    // Enable response caching (default: false)
  cache?: LLMCache;          // Custom cache implementation
}

Token Limit Handling

The client includes built-in token limit validation to help prevent errors when using Groq models:

• Known models have predefined token limits based on their specifications
• Unknown models use a conservative default limit of 8,192 tokens
• Token limit validation can be disabled using skipTokenLimitCheck: true in client options

Example with token limit validation disabled:

const client = new GroqClient({
  modelName: 'new-groq-model',
  clientOptions: {
    apiKey: 'your-groq-api-key',
    skipTokenLimitCheck: true, // Disable token limit validation
  }
});

Features

• Full support for Groq API features
• Compatible with Stagehand's LLM interface
• Proper error handling and retries
• Optional response caching
• Support for structured outputs using response models
• Automatic handling of token limits and parameter validation
• Flexible model support with safe defaults for new models

Testing

The package includes comprehensive test coverage for all major functionality:

Coverage Statistics

----------|---------|----------|---------|---------|---------------------
File      | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s   
----------|---------|----------|---------|---------|---------------------
All files |    95.9 |    77.14 |     100 |   96.38 |                     
 index.ts |    95.9 |    77.14 |     100 |   96.38 | 212,523,687-690,714 
----------|---------|----------|---------|---------|---------------------

Test Suites

• Integration Tests: End-to-end testing of the GroqClient functionality

  • API interaction and response handling
  • Error handling and retries
  • Parameter validation
  • Token limit validation
  • Caching behavior
  • Response model handling
  • Tool call generation and parsing

• System Prompt Tests: Dedicated test suite for system prompt functionality

  • Basic system prompt handling
  • User instruction integration
  • Message content handling
  • Special character handling
  • Mixed content type support

Running Tests

# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode
npm run test

License

MIT