Maniac TypeScript SDK

The official TypeScript / Node.js client for the Maniac Inference Gateway API — an OpenAI-compatible inference gateway with telemetry, containers, evaluation, and optimization.

Installation

npm install maniac-js

Quick Start

import Maniac from "maniac-js";

const client = new Maniac(); // uses MANIAC_API_KEY env var

const completion = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});
console.log(completion.choices[0].message.content);

Chat Completions

Create a completion

const completion = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "What is the capital of France?" }],
});

maniac chat completions create \
  --model openai/gpt-4o \
  --messages '[{"role": "user", "content": "What is the capital of France?"}]'

Stream a completion

const stream = await client.chat.completions.create({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Write a haiku." }],
  stream: true,
});

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

maniac chat completions create \
  --model openai/gpt-4o \
  --messages '[{"role": "user", "content": "Write a haiku."}]' \
  --stream

List completions

const completions = await client.chat.completions.list({
  limit: 10,
  container: "my-container",
});

maniac chat completions list --limit 10 --container my-container

Retrieve a completion

const completion = await client.chat.completions.retrieve("completion-id");

maniac chat completions retrieve completion-id

Register examples

await client.chat.completions.register({
  container: "my-container",
  items: [
    {
      input: {
        model: "openai/gpt-4o",
        messages: [{ role: "user", content: "Hi" }],
      },
      output: {
        choices: [{ message: { role: "assistant", content: "Hello!" } }],
      },
    },
  ],
});

maniac chat completions register \
  --container my-container \
  --items '[{"input": {"model": "openai/gpt-4o", "messages": [{"role": "user", "content": "Hi"}]}, "output": {"choices": [{"message": {"role": "assistant", "content": "Hello!"}}]}}]'

Containers

Create a container

const container = await client.containers.create({
  label: "my-container",
  initial_model: "openai/gpt-4o",
});

maniac containers create --label my-container --initial-model openai/gpt-4o

List containers

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

maniac containers list

Retrieve a container

const container = await client.containers.retrieve("my-container");

maniac containers retrieve my-container

Delete a container

await client.containers.delete("my-container");

maniac containers delete my-container

Models

List models

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

maniac models list

Add a model to a container

await client.models.add({
  container: "my-container",
  model: "anthropic/claude-sonnet-4-20250514",
  slug: "claude",
});

maniac models add \
  --container my-container \
  --model anthropic/claude-sonnet-4-20250514 \
  --slug claude

Files

Upload a file

import { readFileSync } from "node:fs";

const file = await client.files.create(readFileSync("data.jsonl"), "fine-tune");

maniac files create data.jsonl --purpose fine-tune

List files

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

maniac files list

Retrieve file metadata

const file = await client.files.retrieve("file-id");

maniac files retrieve file-id

Download file content

const content = await client.files.content("file-id");

maniac files content file-id

Delete a file

await client.files.delete("file-id");

maniac files delete file-id

Evaluators

Create an evaluator

const evaluator = await client.evaluators.create({
  type: "judge",
  model: "openai/gpt-4o",
  name: "quality-judge",
  prompt: "Rate the quality of the response from 1-10.",
  container: "my-container",
});

maniac evaluators create \
  --type judge \
  --model openai/gpt-4o \
  --name quality-judge \
  --prompt "Rate the quality of the response from 1-10." \
  --container my-container

List evaluators

const evaluators = await client.evaluators.list({
  container: "my-container",
});

maniac evaluators list --container my-container

Retrieve an evaluator

const evaluator = await client.evaluators.retrieve("evaluator-id");

maniac evaluators retrieve evaluator-id

Update an evaluator

await client.evaluators.update("evaluator-id", {
  prompt: "New prompt text.",
});

maniac evaluators update evaluator-id --prompt "New prompt text."

Delete an evaluator

await client.evaluators.delete("evaluator-id");

maniac evaluators delete evaluator-id

Evaluation Runs

Create an evaluation run

const run = await client.evaluation.runs.create({
  container: "my-container",
  evaluators: ["evaluator-id"],
});

maniac evaluation runs create \
  --container my-container \
  --evaluators '["evaluator-id"]'

List evaluation runs

const runs = await client.evaluation.runs.list({
  container: "my-container",
});

maniac evaluation runs list --container my-container

Retrieve an evaluation run

const run = await client.evaluation.runs.retrieve("run-id");

maniac evaluation runs retrieve run-id

Datasets

Create a dataset

const dataset = await client.datasets.create({
  name: "my-dataset",
  container: "my-container",
  size: 100,
});

maniac datasets create \
  --name my-dataset \
  --container my-container \
  --size 100

List datasets

const datasets = await client.datasets.list({
  container: "my-container",
});

maniac datasets list --container my-container

Retrieve a dataset

const dataset = await client.datasets.retrieve("dataset-id");

maniac datasets retrieve dataset-id

Optimization Runs

Create an optimization run

const run = await client.optimization.runs.create({
  container: "my-container",
  base_models: ["qwen/qwen3-14b"],
  evals: ["evaluator-id"],
  methods: [{ type: "sft" }],
});

maniac optimization runs create \
  --container my-container \
  --base-models '["qwen/qwen3-14b"]' \
  --evals '["evaluator-id"]' \
  --methods '[{"type": "sft"}]'

OpenAI Compatibility

Maniac's inference endpoint is fully compatible with the OpenAI client. Point it at https://platform.maniac.ai/api/v1 and prefix your container label with maniac::

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://platform.maniac.ai/api/v1",
  apiKey: process.env.MANIAC_API_KEY,
});

const response = await client.chat.completions.create({
  model: "maniac:my-container",
  messages: [{ role: "user", content: "Hello!" }],
});

Error Handling

import Maniac, {
  AuthenticationError,
  RateLimitError,
  NotFoundError,
} from "maniac-js";

const client = new Maniac();

try {
  await client.containers.retrieve("nonexistent");
} catch (e) {
  if (e instanceof NotFoundError) {
    console.log("Container not found");
  } else if (e instanceof AuthenticationError) {
    console.log("Invalid API key");
  } else if (e instanceof RateLimitError) {
    console.log(`Rate limited, retry after ${e.retryAfter}s`);
  }
}

All exceptions extend ManiacError. The full hierarchy:

• ManiacError
  • APIError — generic API error (has statusCode and code)
  • AuthenticationError — 401/403
  • RateLimitError — 429 (has retryAfter)
  • NotFoundError — 404
  • BadRequestError — 400/422
  • APIConnectionError — network failure

CLI Global Options

Every command supports --json for raw JSON output and --api-key / --base-url overrides:

maniac --api-key sk-... containers list --json

Run maniac --help or maniac <command> --help for full option details.