Kosong

Kosong is an LLM abstraction layer designed for modern AI agent applications. It unifies message structures, asynchronous tool orchestration, and pluggable chat providers so you can build agents with ease and avoid vendor lock-in.

Kosong means "empty" in Malay and Indonesian.

Installation

Kosong requires Python 3.12 or higher. We recommend using uv as the package manager.

Init your project with:

uv init --python 3.12  # or higher

Then add Kosong as a dependency:

uv add kosong

To enable chat providers other than Kimi (e.g. Anthropic and Google Gemini), install the optional extra:

uv add 'kosong[contrib]'

Examples

Simple chat completion

import asyncio

import kosong
from kosong.chat_provider.kimi import Kimi
from kosong.message import Message


async def main() -> None:
    kimi = Kimi(
        base_url="https://api.moonshot.ai/v1",
        api_key="your_kimi_api_key_here",
        model="kimi-k2-turbo-preview",
    )

    history = [
        Message(role="user", content="Who are you?"),
    ]

    result = await kosong.generate(
        chat_provider=kimi,
        system_prompt="You are a helpful assistant.",
        tools=[],
        history=history,
    )
    print(result.message)
    print(result.usage)


asyncio.run(main())

Streaming output

import asyncio

import kosong
from kosong.chat_provider import StreamedMessagePart
from kosong.chat_provider.kimi import Kimi
from kosong.message import Message


async def main() -> None:
    kimi = Kimi(
        base_url="https://api.moonshot.ai/v1",
        api_key="your_kimi_api_key_here",
        model="kimi-k2-turbo-preview",
    )

    history = [
        Message(role="user", content="Who are you?"),
    ]

    def output(message_part: StreamedMessagePart):
        print(message_part)

    result = await kosong.generate(
        chat_provider=kimi,
        system_prompt="You are a helpful assistant.",
        tools=[],
        history=history,
        on_message_part=output,
    )
    print(result.message)
    print(result.usage)


asyncio.run(main())

Tool calling with `kosong.step`

import asyncio

from pydantic import BaseModel

import kosong
from kosong import StepResult
from kosong.chat_provider.kimi import Kimi
from kosong.message import Message
from kosong.tooling import CallableTool2, ToolOk, ToolReturnValue
from kosong.tooling.simple import SimpleToolset


class AddToolParams(BaseModel):
    a: int
    b: int


class AddTool(CallableTool2[AddToolParams]):
    name: str = "add"
    description: str = "Add two integers."
    params: type[AddToolParams] = AddToolParams

    async def __call__(self, params: AddToolParams) -> ToolReturnValue:
        return ToolOk(output=str(params.a + params.b))


async def main() -> None:
    kimi = Kimi(
        base_url="https://api.moonshot.ai/v1",
        api_key="your_kimi_api_key_here",
        model="kimi-k2-turbo-preview",
    )

    toolset = SimpleToolset()
    toolset += AddTool()

    history = [
        Message(role="user", content="Please add 2 and 3 with the add tool."),
    ]

    result: StepResult = await kosong.step(
        chat_provider=kimi,
        system_prompt="You are a precise math tutor.",
        toolset=toolset,
        history=history,
    )
    print(result.message)
    print(await result.tool_results())


asyncio.run(main())

Builtin Demo

Kosong comes with a builtin demo agent that you can run locally. To start the demo, run:

export KIMI_BASE_URL="https://api.moonshot.ai/v1"
export KIMI_API_KEY="your_kimi_api_key"

uv run python -m kosong kimi --with-bash

Development

To set up a development environment, clone the repository and install the dependencies:

git clone https://github.com/MoonshotAI/kosong.git
cd kosong
uv sync --all-extras

make check  # run lint and type checks
make test   # run tests
make format # format code

Metadata

Release files for kosong 0.56.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kosong 0.56.0
File	Size	Uploaded
kosong-0.56.0.tar.gz	50.1 kB	Aug 3, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for kosong 0.56.0
File	Interpreter	ABI	Platform	Reset
kosong-0.56.0-py3-none-any.whl 69.9 kB Aug 3, 2026	Python 3	none	any	Details

Total release size: 120.0 kB

Release files / kosong-0.56.0.tar.gz

Download URL	kosong-0.56.0.tar.gz
Size	50.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`e4a7de17d18edf61ba483b12f1d8386ef00102abcc5b3237e2517af3b222fd32`
BLAKE2b-256 checksum How to use checksums	`8dce1e9988d34fd6b03020bf645141560fc8d6102af22471ef307dce62c3c268`
Upload date	Aug 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / kosong-0.56.0-py3-none-any.whl

Download URL	kosong-0.56.0-py3-none-any.whl
Size	69.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`49b01f7806c4b452e073994b7ce951605ae77672d7cfbad653c054307c7c7274`
BLAKE2b-256 checksum How to use checksums	`c3c099ca162b581e20421672e3857c474f529ed91f7fe7bded3274f89926479e`
Upload date	Aug 3, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`