Metadata-Version: 2.4
Name: krow-agent-sdk
Version: 0.9.0.4
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-sdk-docs
Project-URL: Quickstart, https://github.com/aullik5/krow-sdk-docs/blob/main/docs/quickstart.md
Project-URL: AdvancedGuide, https://github.com/aullik5/krow-sdk-docs/blob/main/docs/advanced-development-guide.md
Project-URL: Repository, https://github.com/aullik5/krow-sdk-docs
Project-URL: Issues, https://github.com/aullik5/krow-sdk-docs/issues
Project-URL: Discussions, https://github.com/aullik5/krow-sdk-docs/discussions
Project-URL: Roadmap, https://github.com/aullik5/krow-sdk-docs/blob/main/docs/roadmap.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: cairocffi>=1.6; extra == 'all'
Requires-Dist: cairosvg>=2.7; 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: ontology
Requires-Dist: beautifulsoup4>=4.12; extra == 'ontology'
Requires-Dist: jieba>=0.42.1; extra == 'ontology'
Requires-Dist: networkx>=3.2; extra == 'ontology'
Requires-Dist: python-louvain>=0.16; extra == 'ontology'
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'
Provides-Extra: visual
Requires-Dist: cairocffi>=1.6; extra == 'visual'
Requires-Dist: cairosvg>=2.7; extra == 'visual'
Requires-Dist: lxml>=5.0; extra == 'visual'
Requires-Dist: pillow>=9.0.0; extra == 'visual'
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[ontology]"  # +4 项 networkx/jieba (wiki + graph + extractive 推理管线)
# pip install "krow-agent-sdk[knowledge]" # DEPRECATED alias, 0.10 移除
pip install "krow-agent-sdk[remote]"    # +8 项 fastapi/uvicorn/websockets 等
pip install "krow-agent-sdk[all]"       # 一站式全装
```

> **当前发布状态**（2026-05-15）：✅ **已上 PyPI 主站** — `pip install krow-agent-sdk` 即可装。
> SDK 当前为 v0.8.x（Beta，API 稳定但持续迭代）；详细路线 → [`roadmap.md`](https://github.com/aullik5/krow-sdk-docs/blob/main/docs/roadmap.md)。
>
> **License 状态**：本包受 [End User License Agreement (EULA)](https://github.com/aullik5/krow-sdk-docs/blob/main/docs/EULA.md) v1.1 DRAFT 约束，
> 装包即同意（详见装机 site-packages 内的 `LICENSE` 文件全文）。EULA EFFECTIVE 版本（含真律师签字）正在 review 中，
> 重大变更会以 30 天提前通知方式告知现有用户。
>
> **完整公开文档** → <https://github.com/aullik5/krow-sdk-docs>（quickstart / plugin 协议 / EULA / roadmap）

## 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 协议 + 真实业务范例）→ [`quickstart.md`](https://github.com/aullik5/krow-sdk-docs/blob/main/docs/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 同步号）

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

## 反馈

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

## License

Proprietary © Krow Team. All rights reserved.

License terms: see the [`LICENSE`](https://github.com/aullik5/krow-sdk-docs/blob/main/LICENSE) file in this distribution
(also bundled in the wheel — `python -c "import krow_agent_sdk, pathlib; print(pathlib.Path(krow_agent_sdk.__file__).parent.parent / 'krow_agent_sdk-*.dist-info' / 'licenses' / 'LICENSE')"` to locate locally) and the authoritative source [`EULA.md`](https://github.com/aullik5/krow-sdk-docs/blob/main/docs/EULA.md). EULA is currently **v1.1 DRAFT** with external counsel sign-off pending; published in good faith per industry best practices + AI-assisted legal analysis. Material changes (if any) from the future EFFECTIVE version will be communicated with at least 30 days' notice.
