Metadata-Version: 2.4
Name: klynx
Version: 0.0.14
Summary: A sophisticated, universal agentic AI coding framework built on LangGraph and LiteLLM.
Author-email: QZX <qzx480@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/qzx/klynx
Project-URL: Bug Tracker, https://github.com/qzx/klynx/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: litellm>=1.40.0
Requires-Dist: langchain-core>=0.2.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: openai>=1.30.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.0.0
Requires-Dist: playwright>=1.40.0
Requires-Dist: textual>=0.70.0
Requires-Dist: pyte>=0.8.2
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Dynamic: license-file

# klynx

`klynx` 是面向代码任务的 Agent 库，默认循环为 `think -> act -> feedback`。  
从本版本开始，除了 `create_agent(...)`，还提供 `create_builder(...)` 进行声明式编排。

## 安装

```bash
pip install -e libs/kbase -e libs/klynx
```

如需浏览器工具：

```bash
playwright install chromium
```

## 顶层导出

```python
from klynx import (
    create_agent,
    create_builder,
    KlynxAgent,
    KlynxGraphBuilder,
    ComposableAgentRuntime,
    setup_model,
    list_models,
    set_tavily_api,
    run_terminal_agent_stream,
    run_terminal_ask_stream,
)
```

## 方式一：`create_agent(...)`（兼容入口）

`create_agent(...)` 仍然可用，适合快速启动默认 Agent。

```python
import os
from klynx import create_agent, setup_model

model = setup_model("deepseek", "deepseek-chat", os.getenv("DEEPSEEK_API_KEY", ""))
agent = create_agent(
    working_dir=".",
    model=model,
    max_iterations=30,
    memory_dir="",
    load_project_docs=False,
)
```

## 方式二：`create_builder(...)`（推荐）

### 最小示例：注入默认 `klynx_loop`

```python
import os
import klynx

model = klynx.setup_model("deepseek", "deepseek-chat", os.getenv("DEEPSEEK_API_KEY", ""))

builder = klynx.create_builder(name="demo")
builder.add_node("klynx_loop")
builder.set_entry_point("klynx_loop")

runtime = builder.build(
    working_dir=".",
    model=model,
    max_iterations=20,
    memory_dir="",
    load_project_docs=False,
)

for event in runtime.invoke("请分析当前仓库结构", thread_id="demo"):
    print(event)
```

### 组合自定义节点

```python
def post_node(runtime, payload):
    return [{"type": "summary", "content": "[post] 已完成默认 loop"}]

builder = klynx.create_builder()
builder.add_node("klynx_loop")
builder.add_node("post", post_node)
builder.add_edge("klynx_loop", "post")
builder.set_entry_point("klynx_loop")
runtime = builder.build(working_dir=".", model=model)
```

### 批量连边 `add_edges`

```python
builder.add_edges(
    [
        ("klynx_loop", "post"),
        ("post", "finalize"),
    ]
)
```

## `klynx_loop` 可复用配置说明

`builder.add_node("klynx_loop")` 复用默认主循环能力，支持与 `create_agent(...)` 等价的关键参数：

- `working_dir`
- `model`
- `max_iterations`
- `memory_dir`
- `load_project_docs`
- `tool_protocol_mode` / `tool_call_mode`
- `skills` / `skills_root`
- `tool_virtual_root`
- `allow_shell_commands`
- `checkpointer` / `store` / `hooks`
- `max_tools_per_step` / `max_reads_per_file_per_step` / `max_retry_per_tool_per_step`
- `tui_stall_threshold` / `full_tui_echo`
- `append_system_prompt`
- `mcp_json_path`（可选）

## `react_once`（无 loop 的 ReAct 子图）

`react_once` 只执行一次 Think + Act，然后输出完整结果事件并结束，后续控制流由你的程序接管。

```python
builder = klynx.create_builder()
builder.add_node("react_once")
builder.set_entry_point("react_once")
runtime = builder.build(working_dir=".", model=model)

for event in runtime.invoke("请先思考并调用一次必要工具", thread_id="react-once-demo"):
    print(event)
```

## 工具管理（`add_tools`）

`create_agent(...)` 与 Builder runtime 都支持：

```python
runtime.add_tools("group:core")
runtime.add_tools("group:interactive")
runtime.add_tools("group:network_and_extra")
runtime.add_tools("none")  # 禁用全部当前工具
```

也支持外部工具与外部工具组注册（接口同默认 Agent）。

## 直接问答 `ask(...)`

默认 Agent 与 Builder runtime 都支持流式 `ask(...)`：

```python
for event in runtime.ask("解释一下这个仓库的核心模块", thread_id="ask-demo"):
    print(event)
```

## 示例

新增 Builder 示例：

- `tutorials/examples/builder_klynx_loop_example.py`

其他示例：

- `tutorials/examples/basic_agent_example.py`
- `tutorials/examples/plan_act_agent.py`
- `tutorials/examples/toolbox_management_example.py`
