Kosong

0.49.0 · active · verified Mon Apr 13

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. It requires Python 3.12 or higher. The current version is 0.49.0 and it is actively maintained as part of the MoonshotAI `kimi-cli` monorepo, suggesting a consistent release cadence tied to that project.

Warnings

breaking The `kosong` project's development has moved to a monorepo structure. The original `MoonshotAI/kosong` GitHub repository is archived, and ongoing development can be found under `MoonshotAI/kimi-cli/tree/main/packages/kosong`. While PyPI distribution remains `kosong`, this change affects direct repository interaction or contribution.
Fix: Refer to the `kimi-cli` monorepo for the latest source code, issues, and contribution guidelines: `https://github.com/MoonshotAI/kimi-cli/tree/main/packages/kosong`.
gotcha Kosong requires Python 3.12 or higher. Attempting to install or run with older Python versions will result in an error.
Fix: Ensure your development environment uses Python 3.12 or a newer compatible version.
gotcha When using `kosong.step` with tools, the tool outputs are typically handled asynchronously. You must `await result.tool_results()` to fetch the collected tool outputs from a `StepResult`. Failing to `await` this call will result in an unresolved coroutine object instead of the actual tool outputs.
Fix: Always use `await result.tool_results()` to correctly retrieve tool execution results after a `kosong.step` call that involves tools.
gotcha Defining custom tools with `CallableTool2` (and similar tool abstractions) relies on `pydantic.BaseModel` for parameter serialization and validation. Ensure `pydantic` is installed and parameter models correctly inherit from `BaseModel`.
Fix: Install `pydantic` (`pip install pydantic`) and define tool parameters by subclassing `pydantic.BaseModel`.

Install

pip install kosong Install with pip

Imports

generate
```
import kosong
kosong.generate(...)
```
step
```
import kosong
kosong.step(...)
```
StepResult
```
from kosong import StepResult
```
Kimi
```
from kosong.chat_provider.kimi import Kimi
```
Chat providers are typically under `kosong.chat_provider`.
Message
```
from kosong.message import Message
```

CallableTool2

from kosong.tooling import CallableTool2

ToolOk
```
from kosong.tooling import ToolOk
```

ToolReturnValue

from kosong.tooling import ToolReturnValue

SimpleToolset

from kosong.tooling.simple import SimpleToolset

Quickstart

This quickstart demonstrates how to use `kosong.step` with a `Kimi` chat provider and a custom tool (`AddTool`). It shows the setup of a `SimpleToolset`, message history, and how to execute an agent step, including retrieving asynchronous tool results. Remember to set your `KIMI_API_KEY` environment variable.

import asyncio
import os
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:
    # Initialize a Kimi chat provider using environment variables for API key
    kimi = Kimi(
        base_url=os.environ.get("KIMI_BASE_URL", "https://api.moonshot.ai/v1"),
        api_key=os.environ.get("KIMI_API_KEY", "your_kimi_api_key_here"), # Replace with your Kimi API key or set KIMI_API_KEY env var
        model="kimi-k2-turbo-preview",
    )
    
    # Create a toolset and add the AddTool
    toolset = SimpleToolset()
    toolset += AddTool()
    
    # Define message history
    history = [
        Message(role="user", content="Please add 2 and 3 with the add tool."),
    ]
    
    # Run an agent step
    print("Running agent step...")
    result: StepResult = await kosong.step(
        chat_provider=kimi,
        system_prompt="You are a precise math tutor.",
        toolset=toolset,
        history=history,
    )
    
    # Print the generated message and awaited tool results
    print(f"Generated message: {result.message}")
    print(f"Tool results: {await result.tool_results()}")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →