Llama API Client

Common errors

• Error: LLAMA_API_KEY is not set

  cause The Llama API client was initialized without an API key, and the `LLAMA_API_KEY` environment variable was not found in the current process environment.
  fix Set the `LLAMA_API_KEY` environment variable in your system or shell, or explicitly pass the `apiKey` option to the `LlamaAPIClient` constructor: `new LlamaAPIClient({ apiKey: 'your_key' })`.

• LlamaAPIClient.APIError: Request failed with status code 401

  cause The provided API key is either invalid, expired, revoked, or does not have the necessary permissions for the requested operation.
  fix Verify that your `LLAMA_API_KEY` is correct, active, and has appropriate access rights by checking your Llama API account and key management page.

• LlamaAPIClient.APIError: Request failed with status code 400 (Bad Request)

  cause The request payload or parameters sent to the API were malformed, contained invalid values, or were incomplete according to the Llama API's specification.
  fix Review the request parameters you are sending to the API call against the official Llama API documentation and the TypeScript type definitions provided by the library for correctness.

• TypeError: fetch failed

  cause A low-level network connectivity issue (e.g., DNS resolution failure, firewall block, or no internet connection) prevented the client from establishing a connection to the Llama API endpoint.
  fix Check your internet connection, ensure the Llama API service is operational (consult their status page), and verify that your network environment allows outgoing HTTPS connections to the API endpoint.

Warnings

• breaking The library is currently below version 1.0.0. This means the API surface may introduce breaking changes in minor versions (e.g., `0.2.x` to `0.3.x`) without strict adherence to semantic versioning until a stable 1.0.0 release. Always review changelogs for updates.
  Fix: Pin to exact patch versions (`~0.x.y` rather than `^0.x.y` in `package.json`) and carefully review changelogs for new releases to identify breaking changes before upgrading.
• gotcha Failure to properly configure the `LLAMA_API_KEY` (either via environment variable `process.env['LLAMA_API_KEY']` or explicitly in the `LlamaAPIClient` constructor) will result in authentication errors (e.g., 401 Unauthorized responses).
  Fix: Ensure `process.env['LLAMA_API_KEY']` is set securely in your environment or provide the `apiKey` directly in the client constructor: `new LlamaAPIClient({ apiKey: 'YOUR_API_KEY_HERE' })`.
• gotcha While breaking from a `for await...of` loop for streaming responses stops processing new chunks, it might not immediately abort the underlying HTTP request. This could leave resources open or cause unnecessary network usage.
  Fix: For explicit and immediate cancellation of an active stream, access the `controller` property of the stream object and call `stream.controller.abort()`.
• gotcha The client throws `LlamaAPIClient.APIError` for non-success HTTP responses (4xx, 5xx). Not catching this specific error type means your application might not gracefully handle API-specific problems, potentially leading to uncaught exceptions or generic error messages.
  Fix: Wrap API calls in `try-catch` blocks and use `if (error instanceof LlamaAPIClient.APIError)` to handle API-specific errors, allowing access to `error.status`, `error.code`, and `error.message` for detailed diagnostics.

Install

• npm install llama-api-client npm
• yarn add llama-api-client yarn
• pnpm add llama-api-client pnpm

Imports

• LlamaAPIClient
  wrong:

  const LlamaAPIClient = require('llama-api-client');

  correct:

  import LlamaAPIClient from 'llama-api-client';

  This is the default export for the main client class. While CommonJS `require` might work in some transpiled environments, native ESM `import` is the idiomatic and recommended way, especially in modern TypeScript projects.
• toFile
  wrong:

  import LlamaAPIClient from 'llama-api-client';
  const file = LlamaAPIClient.toFile(buffer, 'name.txt');

  correct:

  import { toFile } from 'llama-api-client';

  The `toFile` utility function, used for standardizing file upload inputs, is a named export, not a property of the default `LlamaAPIClient` instance or class.
• Chat.CompletionCreateParams

  import LlamaAPIClient from 'llama-api-client';
  
  const params: LlamaAPIClient.Chat.CompletionCreateParams = {
    messages: [{ content: 'string', role: 'user' }],
    model: 'model',
  };

  Type definitions for request parameters are nested as static members under the main `LlamaAPIClient` object for clear categorization and IntelliSense.
• APIError

  import LlamaAPIClient from 'llama-api-client';
  
  try { /* ... */ } catch (error) {
    if (error instanceof LlamaAPIClient.APIError) { /* ... */ }
  }

  The base class for all API-specific errors thrown by the client is nested under the main `LlamaAPIClient` object, allowing for structured error handling.

Quickstart

This quickstart demonstrates how to initialize the Llama API client, perform a basic chat completion, handle streaming responses, and shows how to approach error handling using `LlamaAPIClient.APIError`.

import LlamaAPIClient from 'llama-api-client';
import { toFile } from 'llama-api-client'; // Included for file upload example context, though commented out for brevity

// Ensure your LLAMA_API_KEY is set as an environment variable (e.g., in a .env file or production config).
// For local development, 'dotenv' package might be used: `require('dotenv').config();`
const client = new LlamaAPIClient({
  apiKey: process.env['LLAMA_API_KEY'] ?? '', // Provide an empty string fallback or handle validation for missing key
});

async function runLlamaClientExamples() {
  try {
    console.log('--- Creating a Chat Completion ---');
    const chatResponse = await client.chat.completions.create({
      messages: [{ content: 'Hello, what is the capital of France?', role: 'user' }],
      model: 'llama-3-8b-instruct', // Using an example model identifier
      max_tokens: 50,
      temperature: 0.7,
    });
    console.log('Chat completion response:', chatResponse.completion_message?.content);

    console.log('\n--- Streaming Response Example ---');
    const stream = await client.chat.completions.create({
      messages: [{ content: 'Tell me a short story about a brave knight.', role: 'user' }],
      model: 'llama-3-8b-instruct',
      stream: true,
      max_tokens: 100,
    });
    process.stdout.write('Streamed story: ');
    for await (const chunk of stream) {
      if (chunk.completion_message) {
        process.stdout.write(chunk.completion_message.content || '');
      }
    }
    process.stdout.write('\n'); // Newline after stream finishes

    // Conceptual example for file upload (requires an 'uploads' endpoint and actual file data)
    // For a real scenario, you would typically use fs.createReadStream, a web File object, or Buffer.
    // const dummyFileContent = Buffer.from('This is a test file for upload.');
    // const dummyFile = await toFile(dummyFileContent, 'my-document.txt');
    // const uploadResponse = await client.uploads.create({ file: dummyFile, purpose: 'fine-tune' });
    // console.log('\nUpload initiated:', uploadResponse);

  } catch (error) {
    if (error instanceof LlamaAPIClient.APIError) {
      console.error('Llama API Error caught:', error.status, error.code, error.message, 'Details:', error.error);
    } else {
      console.error('An unexpected error occurred:', error);
    }
  }
}

runLlamaClientExamples();