@aethex.os/ai

AI chat client for Node.js — Gemini with tool-calling, chat history, system instructions, and a drop-in Express handler.

Install

npm install @aethex.os/ai @google/genai

Basic usage

import { createAiClient } from "@aethex.os/ai";

const ai = createAiClient({
  apiKey: process.env.GEMINI_API_KEY!,
  model: "gemini-2.5-flash", // default
});

const { response } = await ai.chat("Explain WebSockets in one paragraph");
console.log(response);

With chat history

const { response } = await ai.chat("What was my last question?", {
  history: [
    { role: "user", content: "What is TypeScript?" },
    { role: "model", content: "TypeScript is a typed superset of JavaScript..." },
  ],
});

With system instruction

const ai = createAiClient({
  apiKey: process.env.GEMINI_API_KEY!,
  defaultSystemInstruction: "You are a helpful customer support agent for Acme Corp.",
});

const reply = await ai.complete("How do I reset my password?");

With tool-calling

import { createAiClient, ToolDefinition } from "@aethex.os/ai";

const tools: ToolDefinition[] = [
  {
    name: "get_weather",
    description: "Get current weather for a city",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string", description: "City name" },
      },
      required: ["city"],
    },
  },
];

const { response, toolCallsMade } = await ai.chat("What's the weather in Tokyo?", {
  tools,
  toolHandler: (name, args) => {
    if (name === "get_weather") return { temp: "22°C", condition: "Sunny" };
    return { error: "unknown tool" };
  },
});

Express middleware

import express from "express";
import { createAiClient, createAiChatHandler } from "@aethex.os/ai";

const app = express();
app.use(express.json());

const ai = createAiClient({ apiKey: process.env.GEMINI_API_KEY! });

app.post("/api/chat", createAiChatHandler({ client: ai }));
// POST body: { prompt: string, history?: ChatMessage[] }
// Response: { response: string }

API

createAiClient(config)

| Option | Type | Description | |--------|------|-------------| | apiKey | string | Gemini API key | | model | string | Model ID (default: gemini-2.5-flash) | | defaultSystemInstruction | string | Default system prompt |

ai.chat(prompt, opts?)

Sends a message and returns { response, toolCallsMade? }.

ai.complete(prompt, systemInstruction?)

Single-turn helper. Returns the response string directly.

createAiChatHandler(config)

Returns an Express route handler for POST /api/chat.

Part of the @aethex.os toolkit.