@cogitx-ai/model-sdk

A lightweight JavaScript/TypeScript SDK for CogitX chat models.

• Base URL: user-provided (required)
• Endpoint: POST /{apiVersion}/chat/completions (default apiVersion: v1)
• Model: user-provided (required per request unless set in client options)
• Supports standard chat completions and tool-calling loops.
• Includes timeout/abort support, retries, validation, and observability hooks.

Installation

npm install @cogitx-ai/model-sdk

Import styles

ESM:

import { CogitxClient } from "@cogitx-ai/model-sdk";

CommonJS:

const { CogitxClient } = require("@cogitx-ai/model-sdk");

Quick start

import { CogitxClient } from "@cogitx-ai/model-sdk";

const client = new CogitxClient({
  baseUrl: "BASE_URL", // required
  apiVersion: "v1", // optional
  model: "MODEL_NAME", // optional client-level default
  temperature: 0.2, // optional default
  maxTokens: 256, // optional default
  topP: 0.9, // optional
  topK: 50, // optional
  timeoutMs: 15000, // optional request timeout
  retryPolicy: { maxRetries: 2 } // optional retry override
});

const response = await client.createChatCompletion({
  message: "Say hello in one sentence."
});

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

Chat completion

Use createChatCompletion for one API call.

const response = await client.createChatCompletion({
  sessionId: "workflow-session-123",
  history: [
    { role: "system", content: "You are concise." }
  ],
  messages: [
    { role: "user", content: "What can you do?" }
  ],
  temperature: 0.3,
  maxTokens: 200,
  topP: 0.9,
  topK: 50,
  minP: 0.0,
  presencePenalty: 0.0,
  frequencyPenalty: 0.0,
  repetitionPenalty: 1.05,
  n: 1,
  stream: false,
  stop: null,
  ignoreEos: false,
  skipSpecialTokens: true
});

Abort, timeout and retries

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 3000);

try {
  const response = await client.createChatCompletion({
    message: "Give me a short summary",
    timeoutMs: 10000,
    signal: controller.signal,
    retryPolicy: {
      maxRetries: 3,
      baseDelayMs: 250,
      maxDelayMs: 3000
    }
  });

  console.log(response.choices[0]?.message?.content);
} finally {
  clearTimeout(timeout);
}

Observability hooks

const client = new CogitxClient({
  baseUrl: "BASE_URL",
  hooks: {
    onRequest(ctx) {
      console.log("request", ctx.attempt, ctx.url, ctx.payload.model);
    },
    onResponse(ctx) {
      console.log("response", ctx.status, `${ctx.durationMs}ms`);
    },
    onRetry(ctx) {
      console.log("retry", ctx.nextAttempt, "in", ctx.delayMs, "ms", ctx.reason);
    },
    onError(ctx) {
      console.error("error", ctx.error.name, ctx.error.message, "retryable:", ctx.retryable);
    }
  }
});

Error model

The SDK throws structured errors:

• CogitxValidationError: invalid request input before API call
• CogitxTimeoutError: request timed out
• CogitxAbortError: caller aborted request
• CogitxNetworkError: network layer failure
• CogitxApiError: non-2xx API response with status, body, requestId?, code?

Full model-parameter example

SDK input is camelCase only. The SDK maps these to API keys internally.

const response = await client.createChatCompletion({
  model: "MODEL_NAME",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Explain transformers in 2 lines" }
  ],
  temperature: 0.7,
  topP: 0.9,
  topK: 50,
  minP: 0.0,
  maxTokens: 200,
  presencePenalty: 0.0,
  frequencyPenalty: 0.0,
  repetitionPenalty: 1.05,
  n: 1,
  stream: false,
  stop: null,
  ignoreEos: false,
  skipSpecialTokens: true
});

Parameters

• Constructor (new CogitxClient(...))
  • baseUrl: API base URL (required)
  • apiVersion?: API version path segment (defaults to v1)
  • model?: client-level default model (optional)
  • temperature?: default temperature
  • maxTokens?: default max tokens
  • topP?, topK?, minP?
  • presencePenalty?, frequencyPenalty?, repetitionPenalty?
  • n?, stream?, stop?, ignoreEos?, skipSpecialTokens?
  • timeoutMs?: default timeout in milliseconds
  • retryPolicy?: default retry behavior
  • hooks?: request lifecycle observability callbacks
  • headers?: extra request headers
  • fetchImpl?: custom fetch implementation
• Per-call (createChatCompletion(...) and runWithTools(...))
  • message?: single user message shorthand
  • messages?: current turn messages
  • history?: prior messages to prepend
  • sessionId?: session identifier sent to the model as session_id
  • model?: required here if not set in client options
  • temperature?, and all generation controls above as call overrides
  • timeoutMs?, signal?, retryPolicy?, requestId?

Tool calling (two-step flow)

runWithTools automates:

1. Send user message + tool schemas
2. If tool calls are returned:
   • execute the matching handler
   • send tool result back to the model
   • continue until final assistant content (or max rounds)

import { CogitxClient, type ChatTool } from "@cogitx-ai/model-sdk";

const client = new CogitxClient({
  baseUrl: "BASE_URL",
  apiVersion: "v1"
});

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

const result = await client.runWithTools({
  message: "What is the weather in Bengaluru?",
  tools,
  toolHandlers: {
    async get_weather(args) {
      const { city } = args as { city: string };
      return { city, forecast: "Sunny", tempC: 30 };
    }
  }
});

console.log(result.response.choices[0]?.message?.content);

Build

npm install
npm run build

Run browser sample

npm run build
npm run demo

Then open:

• http://localhost:8080/examples/sample-js-page.html

License

© 2026 CogitX AI (Brand of STYAVENT INNOVATION PRIVATE LIMITED). All rights reserved. This software is proprietary and confidential. See LICENSE.txt for full license terms.