Halfred Node.js SDK

Official Halfred SDK for Node.js and TypeScript with modern JavaScript features, full type support, and easy integration.

Installation

Install the Halfred SDK using your preferred package manager:

npm install halfred.ai

yarn add halfred.ai

pnpm add halfred.ai

Quick Start

Basic Setup

import { Halfred } from "halfred.ai";

const client = new Halfred({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

async function main() {
  const completion = await client.chat.completions.create({
    model: "lite",
    messages: [{ role: "user", content: "What is the capital of France?" }],
  });

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

main();

With Environment Variables (Recommended)

# .env file
HALFRED_API_KEY=halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

import { Halfred } from "halfred.ai";

// SDK automatically reads HALFRED_API_KEY from environment
const client = new Halfred();

You can also explicitly provide the API key if needed:

const client = new Halfred({
  apiKey: process.env.HALFRED_API_KEY,
});

Chat Completions

Simple Completion

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

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

With System Message

const completion = await client.chat.completions.create({
  model: "lite",
  messages: [
    {
      role: "system",
      content: "You are a helpful programming assistant.",
    },
    {
      role: "user",
      content: "How do I create an async function in JavaScript?",
    },
  ],
});

Conversation History

const messages = [
  { role: "system", content: "You are a helpful assistant." },
  { role: "user", content: "What's the weather like?" },
  { role: "assistant", content: "I don't have access to real-time weather data." },
  { role: "user", content: "What can you help me with?" },
];

const completion = await client.chat.completions.create({
  model: "standard",
  messages: messages,
});

With Options

const completion = await client.chat.completions.create({
  model: "deepthink",
  messages: [{ role: "user", content: "Explain quantum computing" }],
  temperature: 0.7, // Control randomness (0.0 - 2.0)
  max_tokens: 500, // Limit response length
});

Choosing a Model Profile

Halfred offers different profiles optimized for various use cases:

// LITE - Fast and cost-effective
const lite = await client.chat.completions.create({
  model: "lite",
  messages: [{ role: "user", content: "Quick question..." }],
});

// STANDARD - Balanced performance (recommended)
const standard = await client.chat.completions.create({
  model: "standard",
  messages: [{ role: "user", content: "General query..." }],
});

// DEEPTHINK - Advanced reasoning
const deepthink = await client.chat.completions.create({
  model: "deepthink",
  messages: [{ role: "user", content: "Complex analysis..." }],
});

// DEV - Free for testing
const dev = await client.chat.completions.create({
  model: "dev",
  messages: [{ role: "user", content: "Test message..." }],
});

Learn more about profiles in our Model Profiles guide.

Response Format

JSON Mode

Request JSON-formatted responses:

const completion = await client.chat.completions.create({
  model: "standard",
  messages: [
    {
      role: "user",
      content: "List three programming languages in JSON format",
    },
  ],
  response_format: { type: "json_object" },
});

const data = JSON.parse(completion.choices[0].message.content);
console.log(data);
// Expected output:
// {
//   "languages": ["JavaScript", "Python", "Go"]
// }

JSON Schema Mode

Enforce a specific JSON structure using JSON Schema:

const completion = await client.chat.completions.create({
  model: "standard",
  messages: [
    {
      role: "user",
      content: "Generate information about three programming languages",
    },
  ],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "programming_languages",
      strict: true,
      schema: {
        type: "object",
        properties: {
          languages: {
            type: "array",
            items: {
              type: "object",
              properties: {
                name: { type: "string" },
                year_created: { type: "number" },
                paradigm: { type: "string" },
                popular_frameworks: {
                  type: "array",
                  items: { type: "string" },
                },
              },
              required: ["name", "year_created", "paradigm"],
              additionalProperties: false,
            },
          },
        },
        required: ["languages"],
        additionalProperties: false,
      },
    },
  },
});

const data = JSON.parse(completion.choices[0].message.content);
console.log(data);
// Expected output:
// {
//   "languages": [
//     {
//       "name": "JavaScript",
//       "year_created": 1995,
//       "paradigm": "Multi-paradigm",
//       "popular_frameworks": ["React", "Vue", "Angular"]
//     },
//     {
//       "name": "Python",
//       "year_created": 1991,
//       "paradigm": "Multi-paradigm",
//       "popular_frameworks": ["Django", "Flask", "FastAPI"]
//     },
//     {
//       "name": "Go",
//       "year_created": 2009,
//       "paradigm": "Concurrent",
//       "popular_frameworks": ["Gin", "Echo", "Fiber"]
//     }
//   ]
// }

Error Handling

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

  console.log(completion.choices[0].message.content);
} catch (error) {
  if (error.status === 401) {
    console.error("Invalid API key");
  } else if (error.status === 429) {
    console.error("Rate limit exceeded or insufficient credits");
  } else if (error.status === 400) {
    console.error("Bad request:", error.message);
  } else {
    console.error("API error:", error.message);
  }
}

Streaming Responses (Coming Soon)

Real-time streaming support is coming soon. Contact support for early access.

// Coming soon
const stream = await client.chat.completions.create({
  model: "standard",
  messages: [{ role: "user", content: "Tell me a story" }],
  stream: true,
});

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

List Available Models

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

console.log(models.data);
// [
//   { id: 'standard', object: 'model', ... },
//   { id: 'deepthink', object: 'model', ... },
//   ...
// ]

Best Practices

1. Use Environment Variables

# .env file
HALFRED_API_KEY=halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

// ✅ Good
const client = new Halfred();

// ❌ Bad
const client = new Halfred({
  apiKey: "halfred_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
});

2. Handle Errors Gracefully

async function getCompletion(prompt: string) {
  try {
    const completion = await client.chat.completions.create({
      model: "standard",
      messages: [{ role: "user", content: prompt }]
    });
    return completion.choices[0].message.content;
  } catch (error) {
    console.error("Failed to get completion:", error);
    return "Sorry, I couldn't process that request.";
  }
}

3. Choose the Right Profile

// Simple UI responses - use lite
const uiResponse = await client.chat.completions.create({
  model: "lite",
  messages: [{ role: "user", content: "Format this date" }],
});

// Complex analysis - use deepthink
const analysis = await client.chat.completions.create({
  model: "deepthink",
  messages: [{ role: "user", content: "Analyze this business strategy..." }],
});

4. Monitor Token Usage

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

console.log(`Tokens used: ${completion.usage.total_tokens}`);
console.log(`Prompt tokens: ${completion.usage.prompt_tokens}`);
console.log(`Completion tokens: ${completion.usage.completion_tokens}`);

Troubleshooting

Module Not Found

# Make sure the package is installed
npm install halfred.ai

TypeScript Errors

# Install type definitions (included in package)
npm install --save-dev @types/node

API Key Issues

// Check if API key is loaded
if (!process.env.HALFRED_API_KEY) {
  throw new Error("HALFRED_API_KEY environment variable is required");
}

Support

• Documentation: https://docs.halfred.ai

• Email: [email protected]

• Discord: Join our community

• GitHub: Report issues

Next Steps

• Learn about Model Profiles

• Explore the REST API Reference

• Check out Best Practices