Metadata-Version: 2.4
Name: krow-agent-sdk
Version: 0.8.12
Summary: Krow Agent SDK — extend the Krow agent engine with custom plugins, ACTs, tools, hints, gates and more.
Project-URL: Homepage, https://krow.cn
Project-URL: Documentation, https://github.com/aullik5/krow/blob/main/docs/sdk/quickstart.md
Project-URL: Repository, https://github.com/aullik5/krow
Project-URL: Issues, https://github.com/aullik5/krow/issues
Project-URL: DesignDoc, https://github.com/aullik5/krow/blob/main/docs/sdk/pypi-subpackage-design.md
Author-email: Krow Team <support@krow.cn>
License: Proprietary
License-File: LICENSE
Keywords: agent,krow,llm,mcp,plugin,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: aiosqlite>=0.20
Requires-Dist: anyio>=4.3
Requires-Dist: certifi>=2024.0
Requires-Dist: httpx[http2]>=0.26
Requires-Dist: loguru>=0.7
Requires-Dist: markdown-it-py>=2.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic-settings>=2.2
Requires-Dist: pydantic>=2.7
Requires-Dist: python-dotenv>=1.0
Requires-Dist: requests>=2.31
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: watchdog>=4.0
Provides-Extra: all
Requires-Dist: beautifulsoup4>=4.12; extra == 'all'
Requires-Dist: chardet>=5.0; extra == 'all'
Requires-Dist: docx-revisions>=0.1.4; extra == 'all'
Requires-Dist: ebooklib>=0.18; extra == 'all'
Requires-Dist: fastapi>=0.110; extra == 'all'
Requires-Dist: ifaddr>=0.2.0; extra == 'all'
Requires-Dist: jieba>=0.42.1; extra == 'all'
Requires-Dist: jinja2>=3.0.0; extra == 'all'
Requires-Dist: json5>=0.9.0; extra == 'all'
Requires-Dist: lxml>=5.0; extra == 'all'
Requires-Dist: markdown>=3.6; extra == 'all'
Requires-Dist: matplotlib>=3.8; extra == 'all'
Requires-Dist: mobi>=0.3.3; extra == 'all'
Requires-Dist: networkx>=3.2; extra == 'all'
Requires-Dist: numpy>=1.26; extra == 'all'
Requires-Dist: olefile>=0.47; extra == 'all'
Requires-Dist: openpyxl>=3.1; extra == 'all'
Requires-Dist: pandas>=2.0; extra == 'all'
Requires-Dist: pathspec>=0.12; extra == 'all'
Requires-Dist: pdfplumber>=0.10; extra == 'all'
Requires-Dist: pillow>=9.0.0; extra == 'all'
Requires-Dist: protobuf>=4.25; extra == 'all'
Requires-Dist: pymupdf>=1.24; extra == 'all'
Requires-Dist: pypdf>=4.2; extra == 'all'
Requires-Dist: python-docx>=1.1; extra == 'all'
Requires-Dist: python-louvain>=0.16; extra == 'all'
Requires-Dist: python-pptx>=0.6.23; extra == 'all'
Requires-Dist: pyyaml>=6.0; extra == 'all'
Requires-Dist: reportlab>=4.0; extra == 'all'
Requires-Dist: svglib>=1.5; extra == 'all'
Requires-Dist: tabulate>=0.9; extra == 'all'
Requires-Dist: uvicorn>=0.29; extra == 'all'
Requires-Dist: websockets<15.0,>=11.0.0; extra == 'all'
Requires-Dist: wsproto>=1.2; extra == 'all'
Requires-Dist: xlrd>=2.0; extra == 'all'
Requires-Dist: zeroconf>=0.131; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: hatchling>=1.21; extra == 'dev'
Requires-Dist: pytest-timeout>=2.3; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: knowledge
Requires-Dist: beautifulsoup4>=4.12; extra == 'knowledge'
Requires-Dist: jieba>=0.42.1; extra == 'knowledge'
Requires-Dist: networkx>=3.2; extra == 'knowledge'
Requires-Dist: python-louvain>=0.16; extra == 'knowledge'
Provides-Extra: office
Requires-Dist: beautifulsoup4>=4.12; extra == 'office'
Requires-Dist: chardet>=5.0; extra == 'office'
Requires-Dist: docx-revisions>=0.1.4; extra == 'office'
Requires-Dist: ebooklib>=0.18; extra == 'office'
Requires-Dist: jinja2>=3.0.0; extra == 'office'
Requires-Dist: json5>=0.9.0; extra == 'office'
Requires-Dist: lxml>=5.0; extra == 'office'
Requires-Dist: markdown>=3.6; extra == 'office'
Requires-Dist: matplotlib>=3.8; extra == 'office'
Requires-Dist: mobi>=0.3.3; extra == 'office'
Requires-Dist: numpy>=1.26; extra == 'office'
Requires-Dist: olefile>=0.47; extra == 'office'
Requires-Dist: openpyxl>=3.1; extra == 'office'
Requires-Dist: pandas>=2.0; extra == 'office'
Requires-Dist: pdfplumber>=0.10; extra == 'office'
Requires-Dist: pillow>=9.0.0; extra == 'office'
Requires-Dist: pymupdf>=1.24; extra == 'office'
Requires-Dist: pypdf>=4.2; extra == 'office'
Requires-Dist: python-docx>=1.1; extra == 'office'
Requires-Dist: python-pptx>=0.6.23; extra == 'office'
Requires-Dist: pyyaml>=6.0; extra == 'office'
Requires-Dist: reportlab>=4.0; extra == 'office'
Requires-Dist: svglib>=1.5; extra == 'office'
Requires-Dist: tabulate>=0.9; extra == 'office'
Requires-Dist: xlrd>=2.0; extra == 'office'
Provides-Extra: remote
Requires-Dist: fastapi>=0.110; extra == 'remote'
Requires-Dist: ifaddr>=0.2.0; extra == 'remote'
Requires-Dist: pathspec>=0.12; extra == 'remote'
Requires-Dist: protobuf>=4.25; extra == 'remote'
Requires-Dist: uvicorn>=0.29; extra == 'remote'
Requires-Dist: websockets<15.0,>=11.0.0; extra == 'remote'
Requires-Dist: wsproto>=1.2; extra == 'remote'
Requires-Dist: zeroconf>=0.131; extra == 'remote'
Description-Content-Type: text/markdown

# krow-agent-sdk

> 让外部团队基于 Krow Agent 引擎扩展垂直场景应用，无需修改 Krow 主仓。

## 安装

```bash
pip install krow-agent-sdk              # 最小核心（13 项依赖）
pip install "krow-agent-sdk[office]"    # +24 项 docx/pptx/excel/pdf/Pillow 等
pip install "krow-agent-sdk[knowledge]" # +4 项 networkx/jieba 等
pip install "krow-agent-sdk[remote]"    # +8 项 fastapi/uvicorn/websockets 等
pip install "krow-agent-sdk[all]"       # 一站式全装
```

> **当前发布状态**（2026-05-14）：M1-M4 工程实现 ✅ 全部完成（PR #235 / #265 / #279 / #281），
> 但**正式上 PyPI 仍待商业流程定稿**（详 [`roadmap.md`](https://github.com/aullik5/krow/blob/main/docs/sdk/roadmap.md) Step 2）。
> 现阶段外部用户走 monorepo 路径：`pip install -e ".[sdk]"`，或用 dev wheel：
>
> ```bash
> python -m build --wheel packages/krow-agent-sdk
> pip install packages/krow-agent-sdk/dist/krow_agent_sdk-*.whl
> ```
>
> 详细路线 → [设计文档 §5](https://github.com/aullik5/krow/blob/main/docs/sdk/pypi-subpackage-design.md#5-渐进迁移路线4-阶段)。

## 5 分钟上手

```python
from krow_agent_sdk import AgentBuilder

agent = (
    AgentBuilder()
    .with_krow_api_key("sk-...")                # Krow Cloud API key（任何 sk- 前缀 + ≥20 字符；推荐 sk-user-）
    .with_project_root("/path/to/your/project") # 项目根（agent 写文件的边界）
    .with_chat_model("qwen3.6-plus")            # chat 类别（可选；6 类按需指定）
    .with_vision_model("qwen2.5-vl-72b-instruct")  # vision (VLM) 类别（可选）
    .build()
)

result = agent.run("帮我把 docs/ 下的 5 篇论文整理成 PPT")
print(result.final_output)  # AgentV3Result 顶层的最终输出文本
agent.shutdown()
```

### 流式输出（实时事件 + 最终结果）

```python
for item in agent.run_stream("帮我把 docs/ 下的 5 篇论文整理成 PPT"):
    if item.kind == "event":
        print(f"[{item.event.type}] {item.event.payload.get('summary', '')}")
    elif item.kind == "result":
        print("DONE:", item.result.final_output)
    elif item.kind == "error":
        raise item.error
agent.shutdown()
```

`run_stream` 返回 `Iterator[StreamItem]`，3 种 kind：`event`（实时事件）/ `result`（最终结果）/ `error`（后台异常）。
默认订阅 `macro_react.* / progressive.* / planner.* / react.* / llm.* / agent.task_*`，可用 `topics=` 自定义（必须含 1 个终止 topic 防 stream 永挂）。

完整文档（含所有 plugin 协议 + 真实业务范例）→ [`docs/sdk/quickstart.md`](https://github.com/aullik5/krow/blob/main/docs/sdk/quickstart.md)。

## 能力一览

| 维度 | 说明 |
|---|---|
| **Plugin 协议（10+）** | `ACTPlugin` / `ToolPlugin` / `HintPlugin` / `GatePlugin` / `EventListenerPlugin` / `ObservabilityPlugin` / `MCPServerPlugin`（form-A/B/C）/ `SecurityPlugin` / `DomainPackPlugin` / `VisualAdapter` |
| **AgentBuilder API** | `.with_krow_api_key` / `.with_project_root` / 6 个 `.with_<category>_model`（chat / reasoning / vision / image_gen / image_edit / text_encoder）/ `.with_replay_store` / `.with_*_plugin` 等链式构造 |
| **Agent 执行 API** | `agent.run(...)` 阻塞同步 / `agent.run_stream(...)` 流式 yield 事件 / `agent.event_bus.subscribe(...)` 自定义订阅 |
| **LLM Record/Replay** | `krow_agent_sdk.replay.LLMReplayStore` 让 plugin 测试零网络成本 |
| **诊断 / Read-only API** | `krow_agent_sdk.data` / `krow_agent_sdk.diagnostics` 内省 Agent 状态 |
| **Headless Docker** | `FROM krow-headless` 直接拿到 SDK runtime |

## 版本号

SDK 版本号 = Krow 主仓 `config/version.py:get_version()` 动态读取（**始终一致**）。
当前主线版本：**0.8.x**。

发布 tag 约定（参考，最终以 GitHub Releases 为准）：
- `sdk-v0.8.x` — 公开 SDK wheel（PyPI `krow-agent-sdk`）
- `runtime-v0.8.x` — 私有 runtime wheel（私有 index `krow-agent-sdk-runtime`）
- `v0.8.x-lite` / `v0.8.x-full` — 桌面应用 release（与 SDK 同步号）

详 [`docs/sdk/roadmap.md`](https://github.com/aullik5/krow/blob/main/docs/sdk/roadmap.md) Step 2。

## 反馈

- Issues: <https://github.com/aullik5/krow/issues>
- 商务/SDK 接入: <support@krow.cn>

## License

Proprietary © Krow Team. All rights reserved.

> 正式上 PyPI 前，license 决策最终确认 — 详见 [`docs/sdk/EULA.md`](https://github.com/aullik5/krow/blob/main/docs/sdk/EULA.md) + [`source-protection-design.md`](https://github.com/aullik5/krow/blob/main/docs/sdk/source-protection-design.md) §10。
