Metadata-Version: 2.4
Name: qiaotong-agent-kit
Version: 0.20.0
Summary: Agent-safe model read and write tools for Qiaotong bridge software
Author: Qiaotong Agent Kit Maintainers
Keywords: bridge,finite-element,agent,qtmodel,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Requires-Python: <4,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: qtmodel<2.9.0,>=2.8.2
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == "mcp"
Requires-Dist: mcp-types<3,>=2; extra == "mcp"

# qiaotong-agent-kit

`qiaotong-agent-kit` 是面向桥通软件当前有限元模型的 Agent 工具层。0.20.0
开始只保留模型读取与受控写入，不包含整桥自动生成、CAD/DXF 导入、建模规则库、
求解结果或任意 Python 脚本执行。

## 环境要求

- Python 3.10 或更高版本（低于 Python 4）
- `qtmodel>=2.8.2,<2.9.0`
- 需要 MCP 服务时安装可选依赖 `mcp`

安装基础库：

```bash
python -m pip install qiaotong-agent-kit
```

安装 MCP 支持：

```bash
python -m pip install "qiaotong-agent-kit[mcp]"
```

## 功能范围

模型读取包括：

- 模型摘要、工程信息和规范配置；
- 节点、单元、截面、材料和板厚；
- 边界、节点局部坐标系和节点/单元荷载；
- 结构组、施工阶段、荷载工况和荷载组合；
- 服务端筛选、游标分页和可重绑定的冻结节点选择集。

模型写入采用统一 operation 注册表，覆盖节点、材料、板厚、参数截面、梁/杆/索/板
单元、边界、局部坐标系及荷载的创建、修改和删除。所有提交遵循：

1. 查询 operation 的精确 Schema；
2. 只读生成写入计划并绑定 `model_revision`；
3. 用户确认后提交计划；
4. 整批作为一条桥通原生命令执行，失败自动 Undo；
5. 成功后可使用返回的 `undo_transaction` 撤回最新事务。

## Python 调用

```python
from qiaotong_agent_kit import QiaotongToolService

service = QiaotongToolService()

status = service.invoke("get_connection_status")
summary = service.invoke("get_bridge_model_summary")

nodes = service.invoke("query_bridge_nodes", {
    "bbox": [0.0, -5.0, -5.0, 100.0, 5.0, 5.0],
    "limit": 20,
})
```

模型写入示例：

```python
operation = {
    "operation": "create_node",
    "node_id": 101,
    "x": 10.0,
    "y": 0.0,
    "z": 0.0,
}

schema = service.invoke(
    "get_bridge_model_write_operation_schema",
    {"operation": operation["operation"]},
)

plan = service.invoke(
    "plan_bridge_model_batch",
    {"operations": [operation]},
)

receipt = service.invoke("commit_bridge_model_batch", {
    "plan_id": plan["plan_id"],
    "model_revision": plan["model_revision"],
    "confirm_commit": True,
})
```

撤回最新事务：

```python
service.invoke("undo_bridge_model_transaction", {
    "transaction": receipt["undo_transaction"],
    "confirm_undo": True,
})
```

## MCP 服务

默认模型读写服务：

```bash
qiaotong-model-mcp
```

只读服务：

```bash
qiaotong-readonly-mcp
```

通用 MCP 宿主配置示例：

```json
{
  "command": "python",
  "args": ["-m", "qiaotong_agent_kit.interfaces.mcp_server"]
}
```

当前模型模式和完整模式均只发布模型读写工具。只读模式不发布
`commit_bridge_model_batch` 和 `undo_bridge_model_transaction`。

## 包结构

```text
qiaotong_agent_kit/
├─ application/
│  ├─ bridge_model.py       # 模型查询、写入事务和桥通适配门面
│  └─ service.py            # Agent 工具目录与调用服务
├─ contracts/
│  └─ tool_schema.py        # 与 MCP 框架无关的工具元数据
├─ infrastructure/
│  └─ qiaotong_api/         # 外部桥通 API 连接与 qtmodel 版本兼容性
├─ interfaces/
│  ├─ cli.py                # JSON-lines 命令行接口
│  └─ mcp_server.py         # MCP stdio 服务
├─ model_write/
│  ├─ operations/           # 单项模型写 operation
│  ├─ registry.py           # operation 注册、规划与排序
│  └─ references.py         # 批内引用协议
└─ support/
   └─ privacy.py            # 输出和错误信息脱敏
```

`infrastructure/qiaotong_api` 是 Agent Kit 的基础设施边界，不是外部 `qtmodel`
包的副本。使用这个名称可以避免 `qiaotong_agent_kit.infrastructure.qtmodel`
与顶层 `qtmodel` 运行库产生导入和认知混淆。

## 依赖原则

基础安装只声明源码直接使用的 `qtmodel`。MCP 相关包仅在安装 `[mcp]` extra
时引入。包内不再携带规则资源、DXF 解析器或与某个特定宿主软件绑定的逻辑。
