LLM.js — Universal LLM Interface

await LLM("the color of the sky is"); // blue

npm install @themaximalist/llm.js

export OPENAI_API_KEY=...
export ANTHROPIC_API_KEY=...
export GOOGLE_API_KEY=...
export GROQ_API_KEY=...
export DEEPSEEK_API_KEY=...
export XAI_API_KEY=...

import LLM from "@themaximalist/llm.js"
await LLM("hello"); // Response: hi

const llm = new LLM();
await llm.chat("what's the color of the sky in hex value?"); // #87CEEB
await llm.chat("what about at night time?"); // #222d5a

const response = await LLM("what are the primary colors?", { extended: true });
console.log(response.content);   // "The primary colors are red, blue, and yellow"
console.log(response.usage);     // { input_tokens: 6, output_tokens: 12, total_cost: 0.0001 }
console.log(response.service);   // "ollama" 
console.log(response.messages);  // Full conversation history

const stream = await LLM("the color of the sky is", { stream: true });
for await (const message of stream) {
    process.stdout.write(message);
}

const llm = new LLM({ stream: false });
llm.system("You are a friendly AI assistant");
const stream = await llm.chat("hello, how are you?", { stream: true });
for await (const chunk of stream) {
  process.stdout.write(chunk);
}

const response = await LLM("tell me a story", { 
  stream: true, 
  extended: true 
});

// Stream the response in real-time
for await (const chunk of response.stream) {
  if (chunk.type === "content") {
    process.stdout.write(chunk.content);
  }
}

// Get the complete response with metadata
const complete = await response.complete();
console.log(complete.usage.total_cost); // 0.0023

const response = await LLM("solve this math problem: 2x + 5 = 13", { 
  think: true,
});

// thinking automatically enables extended mode

// {
//   thinking: "I need to solve for x. First, I'll subtract 5 from both sides...",
//   content: "x = 4",
//   ...
// }

const response = await LLM("explain quantum physics", { 
  think: true,
  stream: true 
});

let thinking = "", content = "";
for await (const chunk of response.stream) {
  if (chunk.type === "thinking") {
    thinking += chunk.content;
    updateThinkingUI(thinking)
  } else if (chunk.type === "content") {
    content += chunk.content;
    updateContentUI(content)
  }
}

// thinking and content are done, can ask for completed response
const complete = await response.complete();
// {
//   thinking: "I need to solve for x. First, I'll subtract 5 from both sides...",
//   content: "x = 4",
//   ...
// }

const getCurrentWeather = {
  name: "get_current_weather",
  description: "Get the current weather for a city",
  input_schema: {
    type: "object",
    properties: {
      city: { type: "string", description: "The name of the city" }
    },
    required: ["city"]
  }
};

const response = await LLM("What's the weather in Tokyo?", {
  tools: [getCurrentWeather],
});

// tool use automatically enables extended mode

console.log(response.tool_calls); 
// [{ id: "call_123", name: "get_current_weather", input: { city: "Tokyo" } }]

const response = await LLM("What's the weather in Tokyo?", {
  tools: [getCurrentWeather],
  stream: true
});

for await (const chunk of response.stream) {
  if (chunk.type === "tool_calls") {
    console.log("🔧 Tool called:", chunk.content);
  } else if (chunk.type === "content") {
    process.stdout.write(chunk.content); // sometimes LLMs will return content with tool calls
  } else if (chunk.type === "thinking") {
    process.stdout.write(chunk.content); // with `think: true` they'll also return thinking
  }
}

const completed = await response.complete();
console.log("Final result:", completed.tool_calls);

// JSON Parsing
const colors = await LLM("Please return the primary colors in a JSON array", {
  parser: LLM.parsers.json
});
// ["red", "green", "blue"]

// JSON Mode (automatic JSON formatting + parsing)
const data = await LLM("Return the primary colors as a JSON object", {
  json: true
});
// { colors: ["red", "green", "blue"] }

// Markdown Code Block Parsing  
const story = await LLM("Please return a story wrapped in a Markdown story code block", {
  parser: LLM.parsers.codeBlock("story")
});
// A long time ago...

// XML Parsing
const code = await LLM("Please write HTML and put it inside <WEBSITE></WEBSITE> tags", {
  parser: LLM.parsers.xml("WEBSITE")                       
});
// <html>...

const response = await LLM("return a JSON object in the form of {color: '...'} containing the color of the sky in english. no other text", {
  stream: true,
  think: true,
  json: true,
  extended: true, // implied automatically from `think: true`
});

for await (const chunk of response.stream) {
  if (chunk.type === "content") {
    process.stdout.write(chunk.content);
  } else if (chunk.type === "thinking") {
    process.stdout.write(chunk.content);
  }
}

const completed = await response.complete();
// { content: { color: "blue" } }

// Image from base64 data
const data = fs.readFileSync("file.jpg", "base64");
const image = LLM.Attachment.fromJPEG(data);

const response = await LLM("What's in this image?", { attachments: [image] });

// From base64 data
const jpeg = LLM.Attachment.fromJPEG(base64Data);
const pdf = LLM.Attachment.fromPDF(base64Data);

// From image URL
const image = LLM.Attachment.fromImageURL("https://example.com/image.jpg");

// Use with chat
const llm = new LLM();
await llm.chat("Describe this image", { attachments: [jpeg] });
await llm.chat("What color is the main object?"); // References previous image

const response = await LLM("Analyze this document", { 
  attachments: [pdf],
  stream: true 
});

for await (const chunk of response) {
  process.stdout.write(chunk);
}

const response = await LLM("explain quantum physics", { extended: true });
console.log(response.usage.input_tokens);  // 3
console.log(response.usage.output_tokens); // 127
console.log(response.usage.total_tokens);  // 130

const response = await LLM("explain quantum physics", { 
  stream: true,
  extended: true,
});

for await (const chunk of response.stream) {
  // ...
}

const complete = await response.complete();
// {
//   usage: {
//     input_tokens: 3,
//     output_tokens: 127,
//     total_tokens: 130,
//     ...
//   }
// }

const response = await LLM("write a haiku", { 
  service: "openai",
  model: "gpt-4o-mini",
  extended: true 
});
// {
//   usage: {
//     input_cost: 0.000045,
//     output_cost: 0.000234,
//     total_cost: 0.000279,
//     ...
//   }
// }

const response = await LLM("explain quantum physics", { 
  stream: true,
  extended: true,
});

for await (const chunk of response.stream) {
  // ...
}

const complete = await response.complete();
// {
//   usage: {
//     input_cost: 0.000045,
//     output_cost: 0.000234,
//     total_cost: 0.000279,
//     ...
//   }
// }

const llm = new LLM();
llm.system("You are a friendly chat bot.");
await llm.chat("what's the color of the sky in hex value?"); // Response: sky blue
await llm.chat("what about at night time?"); // Response: darker value (uses previous context)

await LLM("hello"); // hi

await LLM([
    { role: "user", content: "remember the secret codeword is blue" },
    { role: "assistant", content: "OK I will remember" },
    { role: "user", content: "what is the secret codeword I just told you?" },
]); // blue

const llm = new LLM(input, {
  service: "openai",        // LLM service provider
  apiKey: "sk-123"          // apiKey
  model: "gpt-4o",          // Specific model
  max_tokens: 1000,         // Maximum response length
  temperature: 0.7,         // "Creativity" (0-2)
  stream: true,             // Enable streaming
  extended: true,           // Extended responses with metadata
  messages: [],             // message history
  think: true,              // Enable thinking mode
  parser: LLM.parsers.json, // Content parser
  tools: [...],             // Available tools
  max_thinking_tokens: 500, // Max tokens for thinking
});

// Defaults to Ollama (local)
await LLM("the color of the sky is");

// OpenAI
await LLM("the color of the sky is", { model: "gpt-4o-mini", service: "openai" });

// Anthropic
await LLM("the color of the sky is", { model: "claude-3-5-sonnet-latest", service: "anthropic" });

// Google
await LLM("the color of the sky is", { model: "gemini-1.5-pro", service: "google" });

// xAI
await LLM("the color of the sky is", { service: "xai", model: "grok-beta" });

// DeepSeek with thinking
await LLM("solve this puzzle", { service: "deepseek", model: "deepseek-reasoner", think: true });

// Ollama (local)
await LLM("the color of the sky is", { model: "llama3.2:3b", service: "ollama" });

const llm = new LLM({ service: "openai" });
const models = await llm.fetchModels();

console.log(models.length); // 50+ models
console.log(models[0]);     // { name: "gpt-4o", created: Date, service: "openai", ... }

import { ModelUsage } from "@themaximalist/llm.js";

// Get all cached models
const allModels = ModelUsage.getAll();
console.log(allModels.length); // 100+

// Refresh from latest sources  
const refreshedModels = await ModelUsage.refresh();
console.log(refreshedModels.length); // Even more models

// Get specific model info
const gpt4 = ModelUsage.get("openai", "gpt-4o");
console.log(gpt4.input_cost_per_token);  // 0.0000025
console.log(gpt4.max_input_tokens);      // 128000

const llm = new LLM({ service: "anthropic" });
const qualityModels = await llm.getQualityModels();

for (const model of qualityModels) {
  console.log(model.model);                 // "claude-3-5-sonnet-latest"
  console.log(model.input_cost_per_token);  // 0.000003
  console.log(model.output_cost_per_token); // 0.000015
  console.log(model.max_tokens);            // 8192
  console.log(model.created);               // 2024-10-22T00:00:00.000Z
}

import { ModelUsage } from "@themaximalist/llm.js";

ModelUsage.addCustom({
  model: "my-custom-gpt",
  service: "openai", 
  input_cost_per_token: 0.00001,
  output_cost_per_token: 0.00003,
  max_tokens: 4096
});

// Now use it like any other model
const response = await LLM("hello", { 
  service: "openai", 
  model: "my-custom-gpt",
  extended: true 
});
console.log(response.usage.total_cost); // Uses your custom pricing

const llm = new LLM({
    service: "together",
    baseUrl: "https://api.together.xyz/v1",
    model: "meta-llama/Llama-3-70b-chat-hf",
    apiKey,
});

class Together extends LLM.APIv1 {
    static readonly service: ServiceName = "together";
    static DEFAULT_BASE_URL: string = "https://api.together.xyz/v1";
    static DEFAULT_MODEL: string = "meta-llama/Llama-3-70b-chat-hf";
}

const llm = new Together();

LLM.register(Together);
const llm = new LLM({ service: "together" });

class Custom extends LLM {
    static readonly service: ServiceName = "secretAGI";
    static DEFAULT_BASE_URL: string = "http://localhost:9876";
    static DEFAULT_MODEL: string = "gpt-999";
    static isLocal: boolean = false; // don't track pricing
    static isBearerAuth: boolean = false;

    get chatUrl() { return `${this.baseUrl}/chat` }
    get modelsUrl() { return `${this.baseUrl}/models` }

    parseContent(data: any): string { ... }
    parseTools(data: any): ToolCall[] { ... }
    parseThinking(data: any): string { ... }
    parseModel(model: any): Model { ... }
    parseOptions(options: Options): Options { ... }
    parseTokenUsage(usage: any): InputOutputTokens | null { ... }
    parseUsage(tokenUsage: InputOutputTokens): Usage { ... }

    // streaming methods
    parseToolsChunk(chunk: any): ToolCall[] { return this.parseTools(chunk) }
    parseContentChunk(chunk: any): string { return this.parseContent(chunk) }
    parseThinkingChunk(chunk: any): string { return this.parseThinking(chunk) }
}

const llm = new LLM({ service: "openai" });
const isConnected = await llm.verifyConnection();
console.log(isConnected); // true if API key and service work

> DEBUG=llm.js* node your-script.js
# debug logs
blue