llms.txt

# groq-rag

> Extended Groq TypeScript SDK with RAG, web browsing, MCP integration, and agent capabilities - 100% groq-sdk API compatible

## Overview

groq-rag extends the official Groq TypeScript SDK (groq-sdk) with:
- RAG (Retrieval-Augmented Generation) with document chunking and retrieval
- Web search (DuckDuckGo, Brave, Serper)
- URL fetching and content extraction
- MCP (Model Context Protocol) server integration
- ReAct-style AI agents with tool use
- Content limiting to control token usage

## Installation

```bash
npm install groq-rag
# or from GitHub Packages
npm install @mithun50/groq-rag --registry=https://npm.pkg.github.com
```

## Quick Start

```typescript
import GroqRAG from 'groq-rag';

const client = new GroqRAG({ apiKey: 'your-api-key' });

// Standard Groq SDK usage (100% compatible)
const response = await client.complete({
  model: 'llama-3.3-70b-versatile',
  messages: [{ role: 'user', content: 'Hello!' }]
});

// RAG with documents
await client.initRAG();
await client.rag.addDocument('Your document content here...');
const ragResponse = await client.chat.withRAG({
  messages: [{ role: 'user', content: 'What is the refund policy?' }],
  topK: 5
});

// Web search augmented
const webResponse = await client.chat.withWebSearch({
  messages: [{ role: 'user', content: 'Latest news about TypeScript?' }],
  maxResults: 5
});

// URL content augmented
const urlResponse = await client.chat.withUrl({
  messages: [{ role: 'user', content: 'Summarize this page' }],
  url: 'https://example.com/article'
});

// AI Agent with built-in tools
const agent = await client.createAgentWithBuiltins({
  model: 'llama-3.3-70b-versatile',
  verbose: true
});
const result = await agent.run('Research and summarize AI trends');
```

## MCP Integration

Connect to Model Context Protocol servers for external tools:

```typescript
// Add MCP server
await client.mcp.addServer({
  name: 'filesystem',
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@modelcontextprotocol/server-filesystem', './data']
});

// Create agent with MCP tools
const agent = await client.createAgentWithBuiltins(
  { model: 'llama-3.3-70b-versatile' },
  { includeMCP: true }
);

const result = await agent.run('List files in the data directory');
await client.mcp.disconnectAll();
```

## Content Limiting (Token Control)

```typescript
// Limit web search content
const response = await client.chat.withWebSearch({
  messages: [{ role: 'user', content: 'Query' }],
  maxResults: 5,
  maxSnippetLength: 200,      // Max chars per snippet
  maxTotalContentLength: 2000 // Max total chars
});

// Limit URL fetch content
const response = await client.chat.withUrl({
  messages: [{ role: 'user', content: 'Summarize' }],
  url: 'https://example.com',
  maxContentLength: 5000, // Max chars
  maxTokens: 1000         // Estimated token limit (~4 chars/token)
});
```

## Supported Models

All Groq models are supported:
- llama-3.3-70b-versatile (recommended)
- llama-3.1-8b-instant (fastest)
- openai/gpt-oss-120b (complex reasoning)
- qwen/qwen3-32b (math & reasoning)
- meta-llama/llama-4-scout-17b-16e-instruct (vision)
- And all other Groq models

## API Reference

### Client Methods
- `complete()` - Standard chat completion
- `stream()` - Streaming chat completion
- `initRAG()` - Initialize RAG system
- `createAgent()` - Create agent with custom tools
- `createAgentWithBuiltins()` - Create agent with built-in + optional MCP tools

### Chat Module (client.chat)
- `withRAG()` - RAG-augmented chat
- `withWebSearch()` - Web search augmented chat
- `withUrl()` - URL content augmented chat

### RAG Module (client.rag)
- `addDocument()` - Add document to knowledge base
- `addUrl()` - Add URL content
- `query()` - Semantic search
- `getContext()` - Get formatted context

### Web Module (client.web)
- `fetch()` - Fetch and parse URL
- `search()` - Web search
- `fetchMany()` - Parallel URL fetching

### MCP Module (client.mcp)
- `addServer()` - Connect to MCP server
- `removeServer()` - Disconnect from server
- `getAllTools()` - Get all MCP tools
- `disconnectAll()` - Cleanup all connections

### Agent Methods
- `run()` - Execute agent with a task
- `runStream()` - Streaming execution
- `addTool()` - Add tool at runtime

### Built-in Tools
- `web_search` - Search the web
- `fetch_url` - Fetch and parse URL content
- `calculator` - Basic math operations
- `get_datetime` - Current date/time
- `rag_query` - Document retrieval (when RAG initialized)

## Links

- GitHub: https://github.com/mithun50/groq-rag
- npm: https://www.npmjs.com/package/groq-rag
- Documentation: https://github.com/mithun50/groq-rag#readme