{"id":5284,"library":"kosong","title":"Kosong","description":"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.","status":"active","version":"0.49.0","language":"en","source_language":"en","source_url":"https://github.com/MoonshotAI/kimi-cli/tree/main/packages/kosong","tags":["LLM","AI Agent","abstraction layer","chatbots","tools","moonshotai"],"install":[{"cmd":"pip install kosong","lang":"bash","label":"Install with pip"}],"dependencies":[{"reason":"Required for defining tool parameters using `BaseModel` for `CallableTool2`.","package":"pydantic","optional":false}],"imports":[{"symbol":"generate","correct":"import kosong\nkosong.generate(...)"},{"symbol":"step","correct":"import kosong\nkosong.step(...)"},{"symbol":"StepResult","correct":"from kosong import StepResult"},{"note":"Chat providers are typically under `kosong.chat_provider`.","wrong":"from kosong.kimi import Kimi","symbol":"Kimi","correct":"from kosong.chat_provider.kimi import Kimi"},{"symbol":"Message","correct":"from kosong.message import Message"},{"symbol":"CallableTool2","correct":"from kosong.tooling import CallableTool2"},{"symbol":"ToolOk","correct":"from kosong.tooling import ToolOk"},{"symbol":"ToolReturnValue","correct":"from kosong.tooling import ToolReturnValue"},{"symbol":"SimpleToolset","correct":"from kosong.tooling.simple import SimpleToolset"}],"quickstart":{"code":"import asyncio\nimport os\nfrom pydantic import BaseModel\n\nimport kosong\nfrom kosong import StepResult\nfrom kosong.chat_provider.kimi import Kimi\nfrom kosong.message import Message\nfrom kosong.tooling import CallableTool2, ToolOk, ToolReturnValue\nfrom kosong.tooling.simple import SimpleToolset\n\nclass AddToolParams(BaseModel):\n    a: int\n    b: int\n\nclass AddTool(CallableTool2[AddToolParams]):\n    name: str = \"add\"\n    description: str = \"Add two integers.\"\n    params: type[AddToolParams] = AddToolParams\n\n    async def __call__(self, params: AddToolParams) -> ToolReturnValue:\n        return ToolOk(output=str(params.a + params.b))\n\nasync def main() -> None:\n    # Initialize a Kimi chat provider using environment variables for API key\n    kimi = Kimi(\n        base_url=os.environ.get(\"KIMI_BASE_URL\", \"https://api.moonshot.ai/v1\"),\n        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\n        model=\"kimi-k2-turbo-preview\",\n    )\n    \n    # Create a toolset and add the AddTool\n    toolset = SimpleToolset()\n    toolset += AddTool()\n    \n    # Define message history\n    history = [\n        Message(role=\"user\", content=\"Please add 2 and 3 with the add tool.\"),\n    ]\n    \n    # Run an agent step\n    print(\"Running agent step...\")\n    result: StepResult = await kosong.step(\n        chat_provider=kimi,\n        system_prompt=\"You are a precise math tutor.\",\n        toolset=toolset,\n        history=history,\n    )\n    \n    # Print the generated message and awaited tool results\n    print(f\"Generated message: {result.message}\")\n    print(f\"Tool results: {await result.tool_results()}\")\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n","lang":"python","description":"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."},"warnings":[{"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`.","message":"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.","severity":"breaking","affected_versions":"All versions after the repository move (approx. last 4 months as of current date)"},{"fix":"Ensure your development environment uses Python 3.12 or a newer compatible version.","message":"Kosong requires Python 3.12 or higher. Attempting to install or run with older Python versions will result in an error.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `await result.tool_results()` to correctly retrieve tool execution results after a `kosong.step` call that involves tools.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Install `pydantic` (`pip install pydantic`) and define tool parameters by subclassing `pydantic.BaseModel`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}