# Purpose of the Kosong Package in MoonshotAI/Kimi-Code: LLM Abstraction Layer Explained

> Discover the purpose of the Kosong package in MoonshotAI/Kimi-Code. This LLM abstraction layer unifies API interactions with OpenAI, Anthropic, Gemini, and Kimi for a seamless developer experience.

- Repository: [Moonshot AI/kimi-code](https://github.com/MoonshotAI/kimi-code)
- Tags: internals
- Published: 2026-08-14

---

**The `@moonshot-ai/kosong` package serves as the core LLM abstraction layer that unifies interactions with OpenAI, Anthropic, Google Gemini, and Kimi's own backend behind a single provider-agnostic API.**

The **kosong package** is a foundational component of the [MoonshotAI/kimi-code](https://github.com/MoonshotAI/kimi-code) repository that eliminates vendor lock-in by collapsing diverse LLM SDKs into a type-safe, uniform interface. It enables the Kimi Code CLI, server, and SDKs to switch between language models without code changes. By centralizing message formatting, capability detection, and error handling, the package ensures consistent behavior across heterogeneous AI providers.

## What Is the Kosong Package?

At its heart, **kosong** (published as `@moonshot-ai/kosong`) implements a provider-agnostic abstraction over large language model services. Implemented in TypeScript under the `packages/kosong/` directory, it exposes a clean surface area through [`src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/index.ts) while keeping provider-specific adapters isolated in `src/providers/`. This architecture allows the rest of the Kimi Code ecosystem to treat every LLM—whether OpenAI's GPT-4o, Anthropic's Claude, or Kimi's own models—as interchangeable backends that share a common contract for generation, streaming, and tool use.

## Core Responsibilities and Architecture

The package is organized around six distinct responsibilities, each mapped to specific source modules within the repository.

### Unified Message Model

All inter-provider communication normalizes to a rich message schema defined in **[`src/message.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/message.ts)**. This module exports TypeScript interfaces for text, images, audio, and tool call parts, ensuring that a message constructed for OpenAI can be transparently routed to Anthropic or Kimi without transformation boilerplate. The barrel file [`src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/index.ts) re-exports these types as the canonical message API for downstream consumers.

### Provider Interface and Adapters

Each LLM vendor implements a concrete **`ChatProvider`** interface defined in [`src/provider.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/provider.ts). The package ships with dedicated adapters located in `src/providers/`:

- **[`src/providers/kimi.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/providers/kimi.ts)** – Wraps the Kimi backend with support for Kimi-specific options like `thinking: { keep: true }`.
- **[`src/providers/anthropic.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/providers/anthropic.ts)** – Adapts Claude's API for tool calling and streaming.
- **[`src/providers/openai-legacy.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/providers/openai-legacy.ts)** – Handles legacy OpenAI chat completion endpoints.

These adapters are intentionally excluded from the root barrel file to prevent type bundle pollution, as noted in the comments within [`src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/index.ts).

### Model Capability Catalog

To prevent runtime errors from unsupported features, [`src/catalog.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/catalog.ts) and **[`src/capability.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/capability.ts)** maintain a matrix mapping model identifiers to their supported capabilities—such as tool use, streaming, and token limits. This catalog acts as a source of truth that the `generate` function consults before dispatching requests, ensuring that a caller requesting tool calls from a non-tool model receives an immediate, descriptive error rather than a provider-side failure.

### Token Usage Tracking

Accurate billing and observability require aggregating token counts across request-response cycles. The package exports **`addUsage`**, **`emptyUsage`**, **`grandTotal`**, and **`inputTotal`** from [`src/usage.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/usage.ts) to accumulate consumption statistics. These utilities normalize disparate provider reporting formats into a unified `Usage` object returned with every generation result.

### Error Normalization

Rather than leaking vendor-specific SDK errors, **[`src/errors.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/errors.ts)** defines a hierarchical error taxonomy covering rate limits, quota exhaustion, context overflows, and authentication failures. By catching provider-specific exceptions and re-throwing normalized equivalents, kosong allows calling code to handle failures generically—for example, retrying on any provider's rate limit without custom catch blocks for each SDK.

### Generation Orchestration

The high-level **`generate`** function exported from [`src/generate.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/generate.ts) serves as the primary entry point. It orchestrates the entire request lifecycle: selecting the provider, validating capabilities against the catalog, managing streaming callbacks, handling tool call loops, and aggregating usage statistics. The function returns a typed `GenerateResult` containing the completion text, message history, and token consumption metrics.

## Implementation Details by Source File

The following table maps critical files in the `packages/kosong/src/` directory to their architectural roles:

| File | Responsibility |
|------|----------------|
| [`src/index.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/index.ts) | Central barrel file re-exporting the public API (messages, providers, capabilities, errors, usage) |
| [`src/generate.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/generate.ts) | Core orchestration logic implementing the `generate` function for chat completions |
| [`src/provider.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/provider.ts) | Base `ChatProvider` interface and factory types |
| [`src/message.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/message.ts) | Unified message part definitions (text, image, tool call, etc.) |
| [`src/capability.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/capability.ts) | Model capability flags and "unknown" fallback definitions |
| [`src/catalog.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/catalog.ts) | Model ID to capability mapping and remote catalog resolution |
| [`src/usage.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/usage.ts) | Token aggregation utilities (`addUsage`, `grandTotal`, etc.) |
| [`src/errors.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/errors.ts) | Normalized error hierarchy for LLM failures |
| [`src/providers/kimi.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/providers/kimi.ts) | Kimi backend adapter with native option support |
| [`src/providers/anthropic.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/providers/anthropic.ts) | Anthropic Claude adapter |
| [`src/providers/openai-legacy.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/providers/openai-legacy.ts) | Legacy OpenAI completions adapter |

## Usage Examples

### Basic Chat Completion with OpenAI

The following example demonstrates creating a provider instance and generating a response using standard OpenAI credentials:

```typescript
import { createProvider, generate } from '@moonshot-ai/kosong';

// Factory auto-detects provider type from the 'type' field
const provider = createProvider({
  type: 'openai',
  apiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini',
});

// Simple generation call returns typed result with usage stats
const result = await generate(provider, [
  { role: 'user', content: 'Explain the purpose of the kosong package.' },
]);

console.log(result.completion); // Formatted response text
console.log(result.usage);      // Aggregated token counts

```

### Streaming and Tool Calls with Anthropic

For interactive applications, provide callback hooks to consume streaming chunks and tool invocations in real time:

```typescript
import { createProvider, generate } from '@moonshot-ai/kosong';

const provider = createProvider({
  type: 'anthropic',
  apiKey: process.env.ANTHROPIC_API_KEY,
  model: 'claude-3-5-sonnet-20240620',
});

const callbacks = {
  onChunk: chunk => process.stdout.write(chunk.delta?.content ?? ''),
  onToolCall: tool => console.log('Tool called:', tool.name),
};

await generate(
  provider,
  [{ role: 'user', content: 'What is the current date?' }],
  callbacks
);

```

### Kimi Backend with Provider-Specific Options

Access Kimi-exclusive features by passing provider-specific configuration to the factory:

```typescript
import { createProvider, generate } from '@moonshot-ai/kosong';

const provider = createProvider({
  type: 'kimi',
  apiKey: process.env.KIMI_API_KEY,
  model: 'kimi-1.5-large',
  thinking: { keep: true }, // Kimi-specific extended reasoning option
});

const result = await generate(provider, [
  { role: 'user', content: 'List the steps to bake a cake.' }
]);

console.log(result.completion);

```

## Summary

- **Kosong** (`@moonshot-ai/kosong`) is the provider-agnostic LLM abstraction layer at the core of MoonshotAI/kimi-code.
- It normalizes message models, capabilities, errors, and token usage across OpenAI, Anthropic, Google, and Kimi backends.
- Provider adapters in `src/providers/` implement a common `ChatProvider` interface while isolating vendor-specific logic.
- The **`generate`** function in [`src/generate.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/generate.ts) serves as the unified entry point for all chat completions, handling streaming, tool calls, and usage aggregation.
- Token tracking utilities (`addUsage`, `grandTotal`) and normalized error hierarchies ([`src/errors.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/errors.ts)) ensure consistent observability and error handling.

## Frequently Asked Questions

### What is the primary purpose of the kosong package in Kimi Code?

The kosong package provides a **unified interface for multiple LLM providers**, allowing the Kimi Code platform to interact with OpenAI, Anthropic, Google Gemini, and Kimi's own models through a single API. It handles the normalization of message formats, capability detection, and error handling so that upstream components remain agnostic to the underlying vendor SDK.

### How does kosong handle provider-specific features?

While the core API remains consistent, kosong exposes provider-specific options through the `createProvider` factory function. For example, when using the Kimi backend via [`src/providers/kimi.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/providers/kimi.ts), you can pass Kimi-exclusive parameters like `thinking: { keep: true }` directly in the provider configuration. These options are typed as `KimiOptions` and processed by the respective adapter without affecting the generic `generate` contract.

### What functions does kosong provide for tracking token usage?

The package exports several aggregation utilities from [`src/usage.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/usage.ts): **`emptyUsage`** initializes a zeroed usage object, **`addUsage`** combines two usage records, **`inputTotal`** sums prompt tokens, and **`grandTotal`** calculates the complete token consumption across all categories. These functions normalize disparate provider reporting formats into a consistent `Usage` structure attached to every `GenerateResult`.

### How does kosong normalize errors across different LLM providers?

Rather than exposing raw SDK exceptions, kosong defines a comprehensive error hierarchy in **[`src/errors.ts`](https://github.com/MoonshotAI/kimi-code/blob/main/src/errors.ts)**. It catches provider-specific failures—such as Anthropic's rate limits or OpenAI's context overflows—and re-throws them as standardized error types (e.g., `RateLimitError`, `ContextOverflowError`). This allows calling code to implement generic retry and error-handling logic without importing vendor-specific error classes.