qiaotong-agent-kit 0.2.0__tar.gz

qiaotong_agent_kit-0.2.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: qiaotong-agent-kit
+Version: 0.2.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<3.0,>=2.5.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
+```
+
+安装包会自动安装 `qtmodel>=2.5.0`，并内置脱敏后的桥型规则和匿名参考证据；
+不需要复制开发机上的 `qtmodels` 目录，也不会发布原始模型脚本、模型名或文件路径。
+
+## 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": "预应力混凝土连续梁",
+})
+```
+
+计划会自动生成材料、等效箱形截面、沿桥向网格、逐跨结构组、支承、结构自重、
+规范移动荷载和运营分析设置，并把所有默认值写入 `assumptions` 和 `warnings`。
+
+整体坐标固定为：
+
+- 主梁沿整体 `+X`；
+- 横桥向为整体 `+Y`；
+- 竖向及桥塔正方向为整体 `+Z`；
+- 主梁单元 I 端在小 X 侧、J 端在大 X 侧；
+- 单元局部轴遵循桥通源码
+  `FrameElement.UpdateLocalOrientation`，Agent 只负责节点顺序和 beta 角。
+
+真正写入模型前应先向用户展示计划。`build_continuous_beam` 的
+`confirm_replace=true` 只是危险操作确认，不是第四个工程参数。写入过程会先保存当前
+模型快照，失败时自动恢复；成功后返回快照路径和读回审查结果。自动生成的是概念/
+初始分析模型，当前不会自动设计预应力束，也不会替代正式设计复核。
+
+当前支持 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 可据此统一实施审批策略。

qiaotong_agent_kit-0.2.0/README.md

@@ -0,0 +1,148 @@
+# 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
+```
+
+安装包会自动安装 `qtmodel>=2.5.0`，并内置脱敏后的桥型规则和匿名参考证据；
+不需要复制开发机上的 `qtmodels` 目录，也不会发布原始模型脚本、模型名或文件路径。
+
+## 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": "预应力混凝土连续梁",
+})
+```
+
+计划会自动生成材料、等效箱形截面、沿桥向网格、逐跨结构组、支承、结构自重、
+规范移动荷载和运营分析设置，并把所有默认值写入 `assumptions` 和 `warnings`。
+
+整体坐标固定为：
+
+- 主梁沿整体 `+X`；
+- 横桥向为整体 `+Y`；
+- 竖向及桥塔正方向为整体 `+Z`；
+- 主梁单元 I 端在小 X 侧、J 端在大 X 侧；
+- 单元局部轴遵循桥通源码
+  `FrameElement.UpdateLocalOrientation`，Agent 只负责节点顺序和 beta 角。
+
+真正写入模型前应先向用户展示计划。`build_continuous_beam` 的
+`confirm_replace=true` 只是危险操作确认，不是第四个工程参数。写入过程会先保存当前
+模型快照，失败时自动恢复；成功后返回快照路径和读回审查结果。自动生成的是概念/
+初始分析模型，当前不会自动设计预应力束，也不会替代正式设计复核。
+
+当前支持 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 可据此统一实施审批策略。

qiaotong_agent_kit-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qiaotong-agent-kit"
+version = "0.2.0"
+description = "Agent-safe tools for Qiaotong bridge finite element modeling"
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{name = "Qiaotong Agent Kit Maintainers"}]
+keywords = ["bridge", "finite-element", "agent", "qtmodel", "mcp"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = [
+    "qtmodel>=2.5.0,<3.0",
+]
+
+[project.optional-dependencies]
+mcp = ["mcp>=1.27,<2; python_version >= '3.10'"]
+
+[project.scripts]
+qiaotong-agent-kit = "qiaotong_agent_kit.cli:main"
+qiaotong-mcp = "qiaotong_agent_kit.mcp_server:main"
+qiaotong-readonly-mcp = "qiaotong_agent_kit.mcp_server:readonly_main"
+qiaotong-model-mcp = "qiaotong_agent_kit.mcp_server:model_main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+qiaotong_agent_kit = ["resources/modeling_rules/*.json"]

qiaotong_agent_kit-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

qiaotong_agent_kit-0.2.0/src/qiaotong_agent_kit/__init__.py

@@ -0,0 +1,22 @@
+"""桥通 Agent 的独立工具适配包。"""
+
+from .adapter import QtModelSectionAdapter
+from .bridge_model import BridgeModelService, QtModelBridgeAdapter
+from .continuous_beam import ContinuousBeamPlanner, validate_continuous_beam_plan
+from .modeling_rules import ModelingRuleLibrary
+from .service import QiaotongToolService, SectionToolService
+from .tool_schema import ToolDefinition
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "QtModelSectionAdapter",
+    "QtModelBridgeAdapter",
+    "BridgeModelService",
+    "ContinuousBeamPlanner",
+    "validate_continuous_beam_plan",
+    "ModelingRuleLibrary",
+    "SectionToolService",
+    "QiaotongToolService",
+    "ToolDefinition",
+]

qiaotong_agent_kit-0.2.0/src/qiaotong_agent_kit/adapter.py

@@ -0,0 +1,160 @@
+"""qtmodel 的窄接口适配器。
+
+Agent 不直接接触 mdb 全局门面。本适配器只调用 qtmodel 的公开、确定性接口；
+唯一连接桥通的方法在名称和返回元数据中均明确标识。
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+from qtmodel.core.section_db import SectionDB
+from qtmodel.core.section_geometry import SectionGeometryDB
+from qtmodel.core.section_property_solver import SectionPropertySolver
+
+
+def _package_version(name: str) -> str:
+    try:
+        return version(name)
+    except PackageNotFoundError:
+        return "editable"
+
+
+class QtModelSectionAdapter:
+    """面向 Agent 的无状态截面适配器。"""
+
+    @staticmethod
+    def capabilities() -> Dict[str, Any]:
+        return {
+            "agent_kit_version": _package_version("qiaotong-agent-kit"),
+            "qtmodel_version": _package_version("qtmodel"),
+            "coordinate_unit": "m",
+            "thickness_unit": "m",
+            "area_unit": "m²",
+            "inertia_unit": "m⁴",
+            "local_section_property": {
+                "calculated": [
+                    "Ax", "CentY", "CentZ", "Iy", "Iz", "Iyz", "PeriO",
+                    "PeriI", "bounding_box", "control_points",
+                ],
+                "not_calculated": [
+                    "Ay", "Az", "Ix", "ShearCenterY", "ShearCenterZ",
+                    "Hys", "Hzs", "Sys", "Szs",
+                ],
+                "requires_bridge": False,
+            },
+        }
+
+    @staticmethod
+    def list_section_types() -> Dict[str, Any]:
+        return {
+            "section_types": list(SectionDB.supported_types()),
+            "count": len(SectionDB.supported_types()),
+        }
+
+    @staticmethod
+    def get_section_schema(sec_type: str) -> Dict[str, Any]:
+        schema = SectionDB.get_schema(sec_type)
+        schema["geometry_source"] = SectionGeometryDB.get_source_info(schema["sec_type"])
+        schema["local_property_solver"] = {
+            "method": "calculate_parameter_section_property",
+            "requires_bridge": False,
+            "units": {"length": "m", "area": "m²", "inertia": "m⁴"},
+        }
+        return schema
+
+    @staticmethod
+    def parameter_section_shape(
+            sec_type: str,
+            sec_info: Mapping[str, Any],
+            name: str = "",
+    ) -> Dict[str, Any]:
+        kwargs = SectionDB.build_parameter_section_kwargs(sec_type, sec_info)
+        shape = SectionGeometryDB.generate(
+            kwargs["sec_type"],
+            kwargs["sec_info"],
+            name=name or f"{kwargs['sec_type']}预览",
+            symmetry=kwargs.get("symmetry", True),
+            chamfer_info=kwargs.get("chamfer_info"),
+            box_num=kwargs.get("box_num", 3),
+            box_height=kwargs.get("box_height", 2),
+        )
+        return shape.to_dict()
+
+    @staticmethod
+    def calculate_parameter_section_property(
+            sec_type: str,
+            sec_info: Mapping[str, Any],
+            mat_combine: Optional[Sequence[float]] = None,
+            reference_role: str = "main",
+    ) -> Dict[str, Any]:
+        if mat_combine is not None and len(mat_combine) != 5:
+            raise ValueError("mat_combine 必须包含5个组合材料参数")
+        kwargs = SectionDB.build_parameter_section_kwargs(sec_type, sec_info)
+        shape = SectionGeometryDB.generate(
+            kwargs["sec_type"],
+            kwargs["sec_info"],
+            symmetry=kwargs.get("symmetry", True),
+            chamfer_info=kwargs.get("chamfer_info"),
+            box_num=kwargs.get("box_num", 3),
+            box_height=kwargs.get("box_height", 2),
+        )
+        result = SectionPropertySolver.calculate_detailed(
+            shape,
+            elastic_modulus_ratio=(float(mat_combine[0]) if mat_combine else None),
+            reference_role=reference_role,
+        )
+        data = result.to_dict()
+        data["shape"] = shape.to_dict()
+        data["requires_bridge"] = False
+        return data
+
+    @staticmethod
+    def calculate_custom_loop_property(
+            loop_segments: Sequence[Mapping[str, Any]],
+            secondary_loop_segments: Optional[Sequence[Mapping[str, Any]]] = None,
+            elastic_modulus_ratio: Optional[float] = None,
+            reference_role: str = "main",
+    ) -> Dict[str, Any]:
+        sec_type = "自定义组合截面" if secondary_loop_segments else "自定义线圈截面"
+        shape = SectionGeometryDB.generate(
+            sec_type,
+            loop_segments=list(loop_segments),
+            secondary_loop_segments=(
+                list(secondary_loop_segments) if secondary_loop_segments else None
+            ),
+        )
+        result = SectionPropertySolver.calculate_detailed(
+            shape,
+            elastic_modulus_ratio=elastic_modulus_ratio,
+            reference_role=reference_role,
+        )
+        data = result.to_dict()
+        data["shape"] = shape.to_dict()
+        data["requires_bridge"] = False
+        return data
+
+    @staticmethod
+    def calculate_custom_line_property(
+            sec_lines: Sequence[Sequence[float]],
+    ) -> Dict[str, Any]:
+        shape = SectionGeometryDB.generate("自定义线宽截面", sec_lines=list(sec_lines))
+        result = SectionPropertySolver.calculate_detailed(shape)
+        data = result.to_dict()
+        data["shape"] = shape.to_dict()
+        data["requires_bridge"] = False
+        return data
+
+    @staticmethod
+    def get_bridge_section_property(index: int) -> Dict[str, Any]:
+        """读取桥通当前模型中的完整截面特性；需要桥通 HTTP 服务。"""
+        from qtmodel.odb.odb_model_section import OdbModelSection
+
+        prop = OdbModelSection.get_section_property(int(index))
+        return {
+            "property": prop.to_dict(),
+            "units": prop.units(),
+            "requires_bridge": True,
+        }
+
+
+__all__ = ["QtModelSectionAdapter"]