Registry / llm-agents / kosong

kosong

JSON →
library0.56.0pypypi✓ verified 22d ago

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.

pip install kosong
INSTALL
IMPORT
SIG · KOSONG
K
kosong
llm-agentspythonv0.56.0
Install
9.9s avg
Import
1030ms
Disk
110MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.56.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
glibc
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✓ —
✓ 10.1s
py 3.13
✓ —
✓ 9.8s
py 3.9
✕ build_error
✕ build_error
110MB installed
● package 110MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

generate
from kosong import generate
import kosong
ChatProvider
from kosong import ChatProvider
Message
from kosong import Message

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())
kosong --version
Debug
Known issues
breakingThe `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`.
affects: All versions after the repository move (approx. last 4 months as of current date)
gotchaKosong 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.
affects: All versions
gotchaWhen 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.
affects: All versions
gotchaDefining 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`.
affects: All versions
Upgrade
Version history
0.56.0latest on PyPI · released Aug 3, 2026
Audit
Dependencies
pydanticrequiredRequired for defining tool parameters using `BaseModel` for `CallableTool2`.
Agent activity
19 hits · last 30 days
node
16
OpenAI (training)
1
Resources