npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@nia-teams/ai

v0.1.2

Published

Composable AI wire protocols.

Readme

@nia-teams/ai

English | 简体中文 · Back to Repository Root

TypeScript clients for Anthropic, OpenAI, and Gemini HTTP wire protocols, including withFallback, image generation, and structured JSON decisions. Implements ILLMClient for @nia-teams/agent-core and works standalone.

npm install @nia-teams/ai

AI coding assistants can load node_modules/@nia-teams/ai/skills/ai/SKILL.md (skills/ai/SKILL.md).


Contents


Four HTTP Protocols

Major model providers define mutually incompatible HTTP formats that differ in how model reasoning state is carried across multi-turn tool calls:

| protocol | Client Class | HTTP Endpoint | Multi-Turn Reasoning & Protocol Specifics | | --- | --- | --- | --- | | "anthropic" | AnthropicClient | POST {baseURL}/v1/messages | Top-level system array, content-block messages (thinking, redacted_thinking, tool_use, tool_result), thinking.signature replay, 4-breakpoint cache_control, defer_loading, and mid-conversation tool reference updates. | | "openai-completions" | OpenAIClient | POST {baseURL}/chat/completions | Role-based messages[] and tool_calls[] with configurable reasoning parameter formats (reasoning_effort, reasoning, thinking, enable_thinking). | | "openai-responses" | ResponsesClient | POST {baseURL}/responses | Flat item array input[] (message, reasoning, function_call, function_call_output) that round-trips encrypted reasoning items (reasoning.encrypted_content) across tool turns. | | "gemini" | GeminiClient | POST {baseURL}/v1beta/models/{model}:streamGenerateContent?alt=sse | Native contents[] / parts[] (functionCall, functionResponse) and systemInstruction, replaying parts[].thoughtSignature and stripping JSON Schema keywords rejected by the native endpoint (additionalProperties, $schema, default). |

@nia-teams/ai unifies these four protocols behind ILLMClient and AgentMessage, does not read API key, auth token, organization, or baseURL environment variables, and holds no model registry or global connection pool.


Quick Start

Save as agent.ts and run with tsx:

DEEPSEEK_API_KEY=sk-... npx tsx agent.ts
import { createClient } from "@nia-teams/ai";

const client = createClient({
  protocol: "openai-completions",
  baseURL: "https://api.deepseek.com",
  model: "deepseek-v4-pro",
  apiKey: process.env.DEEPSEEK_API_KEY!,
  supportsThinking: true,
  reasoningFormat: "thinking_object",
  defaults: {
    enableThinking: true,
    maxOutputTokens: 8192,
  },
});

const response = await client.chat({
  systemPrompt: "Answer in two sentences.",
  messages: [
    {
      type: "event",
      eventType: "user_message",
      content: "Explain optimistic concurrency control.",
      timestamp: new Date(),
    },
  ],
  onStreamDelta: (delta) => {
    if (delta.type === "text") process.stdout.write(delta.content);
  },
});

console.log("\nStop reason:", response.stopReason, "Usage:", response.usage);

Protocol Clients & Options

LLMChatRequest.toolChoice accepts auto (the default) or none. All four clients keep tool definitions in the request when none disables tool calls.

Use createClient({ protocol, ... }) or instantiate AnthropicClient, OpenAIClient, ResponsesClient, or GeminiClient. All clients accept explicit apiKey, model, and optional baseURL, extraHeaders, defaults (ChatDefaults), and logger.

1. Anthropic Messages (anthropic)

import { AnthropicClient } from "@nia-teams/ai";

const anthropic = new AnthropicClient({
  apiKey: process.env.DEEPSEEK_API_KEY!,
  model: "deepseek-v4-pro",
  baseURL: "https://api.deepseek.com/anthropic", // defaults to https://api.anthropic.com; SDK appends /v1/messages
  extraHeaders: { "X-Custom-Header": "value" },
  supportsMidConversationTools: false,
  defaults: {
    enableThinking: true,
    thinkingType: "adaptive", // "enabled" (fixed budget_tokens) | "adaptive"
    effort: "high",         // maps to output_config.effort
    maxOutputTokens: 16_384,
  },
});
  • Prompt Cache breakpoints: Places up to four cache_control: { type: "ephemeral" } breakpoints across the root payload, system prompt, the last non-deferred tool definition, and the second-to-last user message without mutating input arrays. Cache breakpoints and defer_loading are capabilities of the official Anthropic endpoint; compatible endpoints (such as DeepSeek) may ignore them.
  • Adjacent same-role merging: The client adapter merges consecutive same-role blocks to keep tool_use / tool_result pairing and cache breakpoint positions fixed.

2. OpenAI Chat Completions (openai-completions)

import { OpenAIClient } from "@nia-teams/ai";

const openai = new OpenAIClient({
  apiKey: process.env.DASHSCOPE_API_KEY!,
  model: "qwen3.8-max",
  baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1", // defaults to https://api.openai.com/v1
  supportsThinking: true,
  supportsReasoningEffort: true,
  reasoningFormat: "enable_thinking", // "openai" | "reasoning_object" | "thinking_object" | "enable_thinking" | "thinking_budget" | "chat_template_kwargs"
  includeUsageCost: false,   // set true on endpoints that accept usage: { include: true }
});

omitDisabledThinking: true selects omission-based disable semantics for thinking_object endpoints; the default sends { type: "disabled" }.

  • reasoningFormat:
    • "openai": top-level reasoning_effort
    • "reasoning_object": reasoning: { effort } or { enabled }
    • "thinking_object": thinking: { type: "enabled" | "disabled" | "adaptive" }; fixed thinking includes budget_tokens only when thinkingBudget is configured (request overrides defaults). No budget is inferred.
    • "enable_thinking": top-level enable_thinking: boolean; the toggle is independent of effort: "none" (that unsupported effort value is omitted).
    • "thinking_budget": top-level thinking_budget when enabled and configured.
    • "chat_template_kwargs": chat_template_kwargs: { enable_thinking: boolean }.

3. OpenAI Responses (openai-responses)

ResponsesClient sends function tools with strict: false and preserves the supplied JSON Schema.

import { ResponsesClient } from "@nia-teams/ai";

const responses = new ResponsesClient({
  apiKey: process.env.MOONSHOT_API_KEY!,
  model: "kimi-k3.1-pro",
  baseURL: "https://api.moonshot.ai/v1", // defaults to https://api.openai.com/v1
  supportsThinking: true,
  promptCacheKey: "session-1", // sets request body prompt_cache_key
  defaults: {
    effort: "high",
    maxOutputTokens: 16_384,
  },
});

4. Google Gemini GenerateContent (gemini)

import { GeminiClient } from "@nia-teams/ai";

const gemini = new GeminiClient({
  apiKey: process.env.GEMINI_API_KEY!,
  model: "gemini-3.8-flash",
  baseURL: "https://generativelanguage.googleapis.com",
  authHeader: "x-goog-api-key", // default "x-goog-api-key"; set "bearer" for Bearer gateways
  defaults: {
    enableThinking: true,
    thinkingBudget: 8192,
    maxOutputTokens: 65_536,
  },
});

Three-Tier Fallback (withFallback)

withFallback(primary, options) wraps an ILLMClient instance (or lazy factory () => ILLMClient | Promise<ILLMClient>):

import { createClient, withFallback } from "@nia-teams/ai";

const primary = createClient({
  protocol: "openai-completions",
  baseURL: "https://api.deepseek.com",
  model: "deepseek-v4-pro",
  apiKey: process.env.DEEPSEEK_API_KEY!,
});

const resilientClient = withFallback(primary, {
  // 1. Network & rate limits: HTTP 5xx, 429, connection reset, or timeout
  network: [
    () =>
      createClient({
        protocol: "openai-completions",
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1",
        model: "qwen3.8-max",
        apiKey: process.env.DASHSCOPE_API_KEY!,
      }),
  ],

  // 2. Content policy error: switches on OpenAI-compatible invalid_prompt errors
  policyViolation: () =>
    createClient({
      protocol: "openai-responses",
      baseURL: "https://api.moonshot.ai/v1",
      model: "kimi-k3.1-pro",
      apiKey: process.env.MOONSHOT_API_KEY!,
    }),

  // 3. Refusal: retries once when stopReason === "refusal"
  refusal: () =>
    createClient({
      protocol: "anthropic",
      baseURL: "https://api.z.ai/api/anthropic",
      model: "glm-5.3",
      apiKey: process.env.ZHIPU_API_KEY!,
    }),
});

Trigger rules and boundaries:

  • policyViolation protocol scope: Matches providerCode === "invalid_prompt" returned by OpenAI-compatible protocols (openai-completions and openai-responses); network and refusal apply to all four protocols.
  • No partial-stream splicing: Once primary emits any stream delta via onStreamDelta, network and policyViolation skip retries and rethrow the original error.
  • Cancellation passthrough: request.signal cancellations rethrow without entering fallback tiers.
  • Fallback model attribution: Responses from a backup client set response.usedFallbackModel = backupClient.getModelName().

Reasoning Replay & Cross-Protocol Continuity

  • LLMChatResponse retains reasoning, reasoningSignature (Anthropic signature / Gemini thoughtSignature), and reasoningDetails (OpenAI Responses encrypted reasoning items).
  • Once persisted on AssistantMessage, same-protocol turns replay signatures; on cross-protocol switches, the target adapter strips or degrades incompatible signature fields.

Tool Input Repair & On-Demand Loading

  • Tool argument JSON repair: When tool arguments contain syntax defects such as trailing commas or unclosed quotes, repairToolInputJson performs deterministic repair; if still invalid JSON, the call carries malformedError (MalformedToolArgumentsError) for AgentRuntime to return to the model.
  • Anthropic on-demand tool loading:
    • supportsDeferLoading: true: Maps ToolDefinition.deferLoading: true to defer_loading: true (see Anthropic Tool Search docs).
    • supportsMidConversationTools: true: Enables mid-conversation tool reference additions and removals via SystemInjectionMessage (Anthropic beta).

Response Structure, Token Usage & Timings

client.chat() returns LLMChatResponse:

  • content: string | null
  • toolCalls: LLMToolCall[] | undefined (id, name, arguments, optional malformedError)
  • stopReason: "end_turn" | "tool_use" | "max_tokens" | "refusal" | "error"
  • usage: { promptTokens, completionTokens, contextTokens?, reasoningTokens?, cachedTokens?, cacheCreationTokens?, usdCost? }
  • timings (streaming Anthropic calls): { ttftMs, generateMs, outputTokensPerSec? }
  • upstreamRequestId / upstreamCompletionId / usedFallbackModel

Image Generation & Editing (generateImage)

import { generateImage } from "@nia-teams/ai";

// 1. OpenAI Images endpoint (/v1/images/generations & /v1/images/edits)
const generated = await generateImage({
  protocol: "openai-images",
  model: "gpt-image-2",
  apiKey: process.env.OPENAI_API_KEY!,
  prompt: "Isometric cloud server topology on dark background",
});

// 2. Multimodal Chat Completions image output (modalities: ["image", "text"])
const edited = await generateImage({
  protocol: "chat-multimodal",
  model: "google/gemini-3.1-flash-image",
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY!,
  prompt: "Highlight the primary database node in amber",
  referenceImage: { buffer: generated.imageBuffer, mime: generated.mime },
  aspectRatio: "16:9",
  imageSize: "2K",
});

Structured JSON Decisions (createDecisionClient)

Evaluates named questions over any ILLMClient with timeout control (DecisionTimeoutError, default 15_000ms):

import { createClient, createDecisionClient } from "@nia-teams/ai";

const client = createClient({
  protocol: "openai-completions",
  baseURL: "https://api.deepseek.com",
  model: "deepseek-flash",
  apiKey: process.env.DEEPSEEK_API_KEY!,
});

const decision = createDecisionClient({ client, timeoutMs: 10_000 });

const res = await decision.decide({
  state: { action: "DROP TABLE users", environment: "production" },
  questions: {
    requiresHumanApproval: {
      type: "boolean",
      description: "True if this operation is destructive in production",
    },
  },
});

console.log(res.answers.requiresHumanApproval); // true

Subpath Exports

| Subpath | Exports | Loads Provider SDKs | | --- | --- | --- | | @nia-teams/ai | createClient, protocol clients, withFallback, generateImage, createDecisionClient, repairToolInputJson, createProxyDispatcher | Yes (@anthropic-ai/sdk, openai, undici) | | @nia-teams/ai/protocol | AgentMessage union, ILLMClient, LLMChatRequest, LLMChatResponse, MalformedToolArgumentsError, renderAiPostContext | No | | @nia-teams/ai/adapters | Wire formatters AnthropicAdapter, OpenAIAdapter, GeminiAdapter, mergeSystemInjectionsIntoFollowingMessage | No |

License

MIT