npm package: @generalcompute/sdk
Description: OpenAI-compatible Node.js SDK for GeneralCompute API
Author: GeneralCompute
Latest version: 0.2.1

# @generalcompute/sdk

OpenAI-compatible Node.js SDK for the GeneralCompute API. A drop-in replacement for OpenAI's SDK with the same API surface.

## Installation

```bash
npm install @generalcompute/sdk
```

## Quick Start

```typescript
import GeneralCompute from "@generalcompute/sdk";

const client = new GeneralCompute({
  apiKey: process.env.GENERALCOMPUTE_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "llama3.1-8b",
  messages: [{ role: "user", content: "Hello!" }],
});

console.log(completion.choices[0].message.content);
```

## API Key Setup

You can provide your API key in two ways:

1. **Environment variable** (recommended):

```bash
export GENERALCOMPUTE_API_KEY=gc_your_api_key_here
```

2. **Constructor option**:

```typescript
const client = new GeneralCompute({
  apiKey: "gc_your_api_key_here",
});
```

## Usage Examples

### Basic Chat Completion

```typescript
import GeneralCompute from "@generalcompute/sdk";

const client = new GeneralCompute({
  apiKey: process.env.GENERALCOMPUTE_API_KEY,
});

const response = await client.chat.completions.create({
  model: "llama3.1-8b",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "What is the capital of France?" },
  ],
  temperature: 0.7,
  max_tokens: 100,
});

console.log(response.choices[0].message.content);
```

### Streaming

```typescript
const stream = await client.chat.completions.create({
  model: "llama3.1-8b",
  messages: [{ role: "user", content: "Write a short poem about TypeScript" }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content;
  if (content) {
    process.stdout.write(content);
  }
}
```

### List Available Models

```typescript
const models = await client.models.list();

console.log("Available models:");
models.data.forEach((model) => {
  console.log(`- ${model.id} (owned by ${model.owned_by})`);
});
```

### Error Handling

```typescript
import GeneralCompute, { AuthenticationError, RateLimitError } from "@generalcompute/sdk";

const client = new GeneralCompute({
  apiKey: process.env.GENERALCOMPUTE_API_KEY,
});

try {
  const response = await client.chat.completions.create({
    model: "llama3.1-8b",
    messages: [{ role: "user", content: "Hello!" }],
  });
  console.log(response.choices[0].message.content);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Invalid API key");
  } else if (error instanceof RateLimitError) {
    console.error("Rate limit exceeded. Please try again later.");
  } else {
    console.error("An error occurred:", error);
  }
}
```

## Migration from OpenAI

Switching from OpenAI's SDK to GeneralCompute is simple:

### Before (OpenAI)

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const completion = await client.chat.completions.create({
  model: "gpt-4",
  messages: [{ role: "user", content: "Hello!" }],
});
```

### After (GeneralCompute)

```typescript
import GeneralCompute from "@generalcompute/sdk";

const client = new GeneralCompute({
  apiKey: process.env.GENERALCOMPUTE_API_KEY, // Changed
});

const completion = await client.chat.completions.create({
  model: "llama3.1-70b", // Changed
  messages: [{ role: "user", content: "Hello!" }],
});
```

**What changed:**

1. ✏️ Import: `openai` → `@generalcompute/sdk`
2. ✏️ API key: `OPENAI_API_KEY` → `GENERALCOMPUTE_API_KEY`
3. ✏️ Model name: `gpt-4` → `llama3.1-70b` (or your chosen model)

**What stayed the same:**

- ✅ Method name: `client.chat.completions.create()`
- ✅ Parameters: `messages`, `temperature`, `stream`, etc.
- ✅ Response format: Same structure and types
- ✅ Error handling: Same error classes
- ✅ Streaming: Same async iteration pattern

## Model Compatibility

| OpenAI Model  | GeneralCompute Equivalent | Notes                                |
| ------------- | ------------------------- | ------------------------------------ |
| gpt-4         | llama3.1-70b              | High capability, similar performance |
| gpt-3.5-turbo | llama3.1-8b               | Fast, cost-effective                 |
| gpt-4-turbo   | llama3.3-70b              | Latest generation                    |

Discover all available models:

```typescript
const models = await client.models.list();
console.log(models.data.map((m) => m.id));
```

## API Reference

### Client Options

```typescript
interface GeneralComputeOptions {
  apiKey?: string; // API key (or use GENERALCOMPUTE_API_KEY env var)
  baseURL?: string; // Custom base URL (default: https://api.generalcompute.com/v1)
  timeout?: number; // Request timeout in ms (default: 60000)
  maxRetries?: number; // Max retry attempts (default: 2)
  defaultHeaders?: Record<string, string>; // Additional headers
}
```

### Chat Completions

```typescript
client.chat.completions.create(params);
```

**Parameters:**

- `model` (string, required): Model ID to use
- `messages` (array, required): Array of chat messages
- `temperature` (number, optional): Sampling temperature (0-2)
- `max_tokens` (number, optional): Maximum tokens to generate
- `stream` (boolean, optional): Enable streaming responses
- `top_p` (number, optional): Nucleus sampling (0-1)
- `stop` (string | string[], optional): Stop sequences
- `presence_penalty` (number, optional): Presence penalty (-2 to 2)
- `frequency_penalty` (number, optional): Frequency penalty (-2 to 2)

**Returns:**

- Non-streaming: `Promise<ChatCompletionResponse>`
- Streaming: `Promise<Stream<ChatCompletionChunk>>`

### Models

```typescript
client.models.list();
```

**Returns:** `Promise<ModelsListResponse>`

### Error Classes

All errors extend `APIError`:

- `AuthenticationError` (401): Invalid or missing API key
- `RateLimitError` (429): Rate limit exceeded
- `BadRequestError` (400): Invalid request parameters
- `NotFoundError` (404): Resource not found
- `InternalServerError` (500+): Server errors

## Advanced Usage

### Custom Base URL

```typescript
const client = new GeneralCompute({
  apiKey: "your-api-key",
  baseURL: "https://custom-endpoint.example.com/v1",
});
```

### Custom Timeout

```typescript
const client = new GeneralCompute({
  apiKey: "your-api-key",
  timeout: 120000, // 2 minutes
});
```

### Custom Headers

```typescript
const client = new GeneralCompute({
  apiKey: "your-api-key",
  defaultHeaders: {
    "X-Custom-Header": "value",
  },
});
```

## TypeScript Support

The SDK is written in TypeScript and provides full type definitions out of the box:

```typescript
import GeneralCompute, {
  ChatMessage,
  ChatCompletionResponse,
  ChatCompletionChunk,
} from "@generalcompute/sdk";

const messages: ChatMessage[] = [{ role: "user", content: "Hello!" }];

const response: ChatCompletionResponse = await client.chat.completions.create({
  model: "llama3.1-8b",
  messages,
});
```

## Contributing

Contributions are welcome! Please see our [GitHub repository](https://github.com/generalcompute/sdk) for details.

## License

MIT

## Support

For support, please contact support@generalcompute.ai or visit our [documentation](https://docs.generalcompute.ai).