Metadata-Version: 2.4
Name: qiaotong-agent-kit
Version: 0.5.0
Summary: Agent-safe tools for Qiaotong bridge finite element modeling
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: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: qtmodel<2.7.0,>=2.6.0
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.27; python_version >= "3.10" and extra == "mcp"

# qiaotong-agent-kit

桥通有限元软件的 Agent 工具适配层。该包与 `qtmodel` 独立发行：工程模型、
截面几何和截面特性算法仍由 `qtmodel` 提供，本包只负责为 Agent 暴露稳定、
可发现、JSON 可序列化的受控工具。

## 安装

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

如需 MCP stdio 服务（Python 3.10 及以上）：

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

`qiaotong-agent-kit 0.5.x` 明确适配 `qtmodel>=2.6.0,<2.7.0`。
安装包会由 pip 自动解析这一兼容范围，并内置脱敏后的桥型规则和匿名参考证据；
不需要复制开发机上的 `qtmodels` 目录，也不会发布原始模型脚本、模型名或文件路径。
如果环境中已有不兼容版本，pip 会升级/降级到受支持的 `2.6.x`；被强制装入不兼容
`qtmodel` 时，Agent 服务会给出明确的版本错误而不是继续建模。

## Python 调用

```python
from qiaotong_agent_kit import SectionToolService

service = SectionToolService()
result = service.invoke("calculate_parameter_section_property", {
    "sec_type": "矩形",
    "sec_info": {"w": 2.0, "h": 1.0},
})
print(result["property"]["Ax"])
```

## JSON-lines 子进程协议

```bash
qiaotong-agent-kit list-tools
qiaotong-agent-kit serve
```

`serve` 从标准输入逐行接收：

```json
{"id": 1, "tool": "calculate_parameter_section_property", "arguments": {"sec_type": "矩形", "sec_info": {"w": 2, "h": 1}}}
```

并逐行返回：

```json
{"id": 1, "ok": true, "result": {}}
```

本地截面计算和连续梁计划不需要打开桥通。读取、审查、建模和恢复工具会连接
桥通 HTTP 服务。

## 脱敏参考规则库

Agent 应先查询规则，再生成建模计划：

```python
from qiaotong_agent_kit import QiaotongToolService

service = QiaotongToolService()
catalog = service.invoke("get_modeling_rule_catalog")
rule = service.invoke("get_modeling_rule", {"bridge_type": "连续梁桥"})
evidence = service.invoke("search_reference_evidence", {
    "bridge_type": "连续梁桥",
    "spans": "30+40+30",
    "standard": "JTG D60-2015",
    "limit": 3,
})
```

规则资源随 wheel 发布，包含十类桥型的建模规则和 62 个匿名参考记录的技术统计。
参考结果只用于归纳结构、阶段和荷载规律；其中不包含原始 `build_model.py`，也不允许
从匿名编号反推项目或桥梁名称。

## 连续梁一键建模

用户只需要提供三个工程输入：规范、跨度和桥型。例如：

```python
from qiaotong_agent_kit import QiaotongToolService

service = QiaotongToolService()
plan = service.invoke("plan_continuous_beam", {
    "design_code": "JTG D60-2015",
    "spans": "2×30+40+2×30",
    "bridge_type": "预应力混凝土连续梁",
})
```

计划会自动生成材料、参数化混凝土箱梁/箱型钢梁截面、沿桥向网格、逐跨结构组、支承、一次成桥阶段、
规范移动荷载和运营分析设置；预应力混凝土桥还会生成按拉应力侧分区的顶/底板概念钢束。
桥通自重随一次成桥阶段激活的结构组自动计入，不再建立独立的自重工况。
连续梁截面规则会显式记录顶、底板宽度，并在计划校核时强制要求顶板宽度大于底板宽度。

整体坐标固定为：

- 主梁沿整体 `+X`；
- 横桥向为整体 `+Y`；
- 竖向及桥塔正方向为整体 `+Z`；
- 主梁单元 I 端在小 X 侧、J 端在大 X 侧；
- 单元局部轴遵循桥通源码
  `FrameElement.UpdateLocalOrientation`，Agent 只负责节点顺序和 beta 角。

真正写入模型前应先向用户展示计划。`build_continuous_beam` 的
`confirm_replace=true` 只是危险操作确认，不是第四个工程参数。写入过程会先保存当前
模型快照，失败时自动恢复；成功后返回快照路径和读回审查结果。自动生成的是概念/
初始分析模型，钢束数量、曲线、锚固和张拉参数仍须结合计算结果做正式设计复核。

Agent 建模还执行以下强制规则：

- 连续梁主梁优先采用箱梁截面，且箱梁顶板宽度必须大于底板宽度；
- 所有线圈型截面在计算或写入前都必须通过拓扑校验：任意两条有限边只允许在双方共同端点相交，禁止非端点交叉、T 形相交、共线重叠和零长度边；
- 变截面组的梁高及其他所有非线性参数，以 I/J 端中数值较小的一端为参考点；
- 自动生成模型必须且只能包含“一次成桥”施工阶段；
- 不创建“自重”或“结构自重”荷载工况；
- 荷载组合中的施工阶段“合计/合计值”仅在一次成桥阶段存在时有效；
- 钢束布置于常见弯矩拉应力侧，沿顶板或底板，控制线不得重合或相交；
- Agent 只能生成当前已安装 `qtmodel` 中真实存在的 `mdb/odb/cdb/bridge` 公开函数，且函数名、位置参数、关键字参数、必填参数和可校验类型必须与运行时签名一致。

可调用 `select_smaller_end_reference` 直接生成桥通非线性 `parameter_info` 值，
调用 `validate_tendon_layout` 在写入前检查钢束控制线。参数化线圈截面的预览和特性计算
会自动执行拓扑校验；自定义线圈可先调用 `validate_section_loop_topology`。生成建模命令时，
先用 `get_qtmodel_api_catalog` 查询当前版本的真实函数，再将全部命令一次性传给
`validate_qtmodel_commands`；只有返回 `valid=true` 才能输出或执行命令。校验过程本身不会
执行任何 qtmodel 命令。

```python
catalog = service.invoke("get_qtmodel_api_catalog", {
    "namespace": "mdb", "query": "add_nodes"
})
check = service.invoke("validate_qtmodel_commands", {
    "commands": [{
        "namespace": "mdb",
        "function": "add_nodes",
        "kwargs": {"node_data": [[1, 0.0, 0.0, 0.0]]},
    }]
})
assert check["valid"] and not check["execution_performed"]
```

当前支持 JTG D60-2015、JTG 3362-2018、CJJ 11-2019、TB 10002-2017、
TB 10092-2017，以及预应力混凝土连续箱梁和钢连续箱梁。可调用
`list_continuous_beam_defaults` 获取机器可读清单。

## 在 QpyIDE 中配置 MCP

推荐把只读与建模能力拆成两个 MCP 入口：

```text
qiaotong-readonly-mcp  # 截面、计划、模型摘要和审查，不暴露写模型工具
qiaotong-model-mcp     # 包含建模与快照恢复，QpyIDE 应对工具调用弹出确认
```

QpyIDE 的 Agent 应遵循以下调用顺序：

1. 调用 `plan_continuous_beam`，把假设、警告、节点/单元/支点数量展示给用户；
2. 用户确认后调用 `build_continuous_beam`；
3. 检查返回的 `audit`，有 error 时不发起计算；
4. 需要撤销时，使用返回的 `snapshot_path` 调用 `restore_model_snapshot`。

模型审查无 error 后，QpyIDE 可先请求用户确认并调用 `solve_current_model`。求解完成后，
使用 `get_bridge_result` 提取明确范围的结果：

- `deformation`：节点变形；
- `element_force`：单元内力；
- `element_stress`：单元应力；
- `reaction`：节点反力。

运营阶段查询使用 `stage_id=-1` 并必须指定 `case_name`；`ids` 必须明确给出，默认最多
返回 500 行，避免自然语言误操作导出整个大型模型。

检查当前打开模型时，可用 `audit_bridge_model` 做全局拓扑/支承/坐标审查；对“检查
第 N 号单元截面是否正常”这类问题，使用 `inspect_bridge_element` 一次读取该单元的
I/J 节点、材料截面号、截面数据、截面特性和按源码计算的局部坐标系。

CLI 和 `list-tools` 输出为每个工具提供 `mutates_model`、`risk_level`、
`requires_confirmation`、`undoable` 元数据，QpyIDE 可据此统一实施审批策略。
