# groq-browserbase-client

A Groq client implementation for [Stagehand](https://github.com/browserbasehq/stagehand).

[![npm version](https://badge.fury.io/js/groq-browserbase-client.svg)](https://www.npmjs.com/package/groq-browserbase-client)
[![GitHub](https://img.shields.io/github/license/eastlondoner/groq-browserbase-client)](https://github.com/eastlondoner/groq-browserbase-client)

## 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:

```typescript
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

```bash
npm install groq-browserbase-client
```

## Usage


## Configuration Options

The `GroqClient` constructor accepts the following options:

```typescript
{
  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:

```typescript
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

```bash
# Run tests with coverage report
npm run test:coverage

# Run tests in watch mode
npm run test
```

## License

MIT