# Groq Client

Interact with Groq's ultra-fast inference API for LLM chat completions with low latency.

## Methods

| Method                                   | Description                                      |
| ---------------------------------------- | ------------------------------------------------ |
| `apiRequest(options, schema, metadata?)` | Make any Groq API request with schema validation |

## Usage

### Step 1: List Available Models

Model availability varies by account and changes over time. Before making requests, validate which models are available:

```typescript
import { api, z, groq } from "@superblocksteam/sdk-api";

// Integration ID from the integrations panel
const PROD_GROQ = "a1b2c3d4-5678-90ab-cdef-groq00000001";

const ModelsResponseSchema = z.object({
  data: z.array(
    z.object({
      id: z.string(),
      object: z.string(),
    }),
  ),
});

const models = await ctx.integrations.groq.apiRequest(
  {
    method: "GET",
    path: "/v1/models",
  },
  { response: ModelsResponseSchema },
);

// Use a model ID from the response in subsequent requests
const availableModelId = models.data[0]?.id;
```

### Chat Completion

```typescript
const ChatCompletionResponseSchema = z.object({
  id: z.string(),
  object: z.literal("chat.completion"),
  created: z.number(),
  model: z.string(),
  choices: z.array(
    z.object({
      index: z.number(),
      message: z.object({
        role: z.string(),
        content: z.string(),
      }),
      finish_reason: z.string(),
    }),
  ),
  usage: z.object({
    prompt_tokens: z.number(),
    completion_tokens: z.number(),
    total_tokens: z.number(),
    queue_time: z.number().optional(),
    prompt_time: z.number().optional(),
    completion_time: z.number().optional(),
    total_time: z.number().optional(),
  }),
});

export default api({
  integrations: {
    groq: groq(PROD_GROQ),
  },
  name: "GroqExample",
  input: z.object({
    prompt: z.string(),
  }),
  output: z.object({
    response: z.string(),
  }),
  async run(ctx, { prompt }) {
    const result = await ctx.integrations.groq.apiRequest(
      {
        method: "POST",
        path: "/v1/chat/completions",
        body: {
          model: "llama-3.3-70b-versatile",
          messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: prompt },
          ],
        },
      },
      { response: ChatCompletionResponseSchema },
    );

    return { response: result.choices[0]?.message.content ?? "" };
  },
});
```

### Using Different Models

```typescript
// Llama 3.3 70B - Best balance of speed and quality
const llama70b = await ctx.integrations.groq.apiRequest(
  {
    method: "POST",
    path: "/v1/chat/completions",
    body: {
      model: "llama-3.3-70b-versatile",
      messages: [{ role: "user", content: "Hello" }],
    },
  },
  { response: ChatCompletionResponseSchema },
);

// Llama 3.1 8B - Fastest, good for simple tasks
const llama8b = await ctx.integrations.groq.apiRequest(
  {
    method: "POST",
    path: "/v1/chat/completions",
    body: {
      model: "llama-3.1-8b-instant",
      messages: [{ role: "user", content: "Hello" }],
    },
  },
  { response: ChatCompletionResponseSchema },
);

// GPT-OSS 120B - Good for code and reasoning
const gptOss = await ctx.integrations.groq.apiRequest(
  {
    method: "POST",
    path: "/v1/chat/completions",
    body: {
      model: "openai/gpt-oss-120b",
      messages: [{ role: "user", content: "Hello" }],
    },
  },
  { response: ChatCompletionResponseSchema },
);
```

### Tool Use (Function Calling)

```typescript
const ToolCallResponseSchema = z.object({
  id: z.string(),
  choices: z.array(
    z.object({
      message: z.object({
        role: z.string(),
        content: z.string().nullable(),
        tool_calls: z
          .array(
            z.object({
              id: z.string(),
              type: z.literal("function"),
              function: z.object({
                name: z.string(),
                arguments: z.string(),
              }),
            }),
          )
          .optional(),
      }),
      finish_reason: z.string(),
    }),
  ),
});

const result = await ctx.integrations.groq.apiRequest(
  {
    method: "POST",
    path: "/v1/chat/completions",
    body: {
      model: "llama-3.3-70b-versatile",
      messages: [{ role: "user", content: "What's the weather in Tokyo?" }],
      tools: [
        {
          type: "function",
          function: {
            name: "get_weather",
            description: "Get current weather for a location",
            parameters: {
              type: "object",
              properties: {
                location: { type: "string" },
              },
              required: ["location"],
            },
          },
        },
      ],
      tool_choice: "auto",
    },
  },
  { response: ToolCallResponseSchema },
);

const toolCall = result.choices[0]?.message.tool_calls?.[0];
if (toolCall) {
  const args = JSON.parse(toolCall.function.arguments);
  console.log(`Function: ${toolCall.function.name}`, args);
}
```

### JSON Mode

```typescript
const JSONResponseSchema = z.object({
  id: z.string(),
  choices: z.array(
    z.object({
      message: z.object({
        content: z.string(), // Will be valid JSON
      }),
    }),
  ),
});

const result = await ctx.integrations.groq.apiRequest(
  {
    method: "POST",
    path: "/v1/chat/completions",
    body: {
      model: "llama-3.3-70b-versatile",
      messages: [
        {
          role: "user",
          content:
            "List 3 programming languages with their use cases. Respond in JSON format.",
        },
      ],
      response_format: { type: "json_object" },
    },
  },
  { response: JSONResponseSchema },
);

const data = JSON.parse(result.choices[0]?.message.content ?? "{}");
```

## Trace Metadata

All methods accept an optional `metadata` parameter as the last argument for diagnostics labeling. See the [root SDK README](../../../README.md#trace-metadata) for details.

## Common Pitfalls

### Streaming Is Not Supported

`apiRequest()` does not support streaming or Server-Sent Events. Do not set
`stream: true` — streaming responses fail schema validation. Every call
returns the complete response; if a UI needs real-time token streaming,
handle it at the frontend layer, not through the SDK.

### No Specialized Methods

```typescript
// WRONG - These methods do not exist
await groq.chat({ ... });
await groq.createChatCompletion({ ... });

// CORRECT - Use apiRequest
await ctx.integrations.groq.apiRequest(
  { method: "POST", path: "/v1/chat/completions", body: { ... } },
  { response: ChatCompletionResponseSchema }
);
```

### OpenAI-Compatible Path

The integration's base URL already includes `https://api.groq.com/openai`, so paths should start with `/v1/`:

```typescript
// WRONG - Duplicates the /openai prefix (base URL already includes it)
await ctx.integrations.groq.apiRequest(
  { method: "POST", path: "/openai/v1/chat/completions", body: { ... } },
  { response: schema }
);

// CORRECT - Start with /v1/ (the integration prepends /openai automatically)
await ctx.integrations.groq.apiRequest(
  { method: "POST", path: "/v1/chat/completions", body: { ... } },
  { response: schema }
);
```

### Rate Limits

Groq has rate limits based on tokens per minute. Monitor usage:

```typescript
const result = await ctx.integrations.groq.apiRequest(
  { method: "POST", path: "/v1/chat/completions", body: { ... } },
  { response: ChatCompletionResponseSchema }
);

console.log("Token usage:", result.usage);
console.log("Completion time:", result.usage.completion_time, "seconds");
```

## Error Handling

```typescript
import { RestApiValidationError } from "@superblocksteam/sdk-api";

try {
  const result = await ctx.integrations.groq.apiRequest(
    { method: "POST", path: "/v1/chat/completions", body: { ... } },
    { response: ChatCompletionResponseSchema }
  );
} catch (error) {
  if (error instanceof RestApiValidationError) {
    console.error("Validation failed:", error.details.zodError);
  }
}
```

## API Reference

- [Groq Documentation](https://console.groq.com/docs)
- [Chat Completions](https://console.groq.com/docs/text-chat)
- [Tool Use](https://console.groq.com/docs/tool-use)
- [Models](https://console.groq.com/docs/models)