diff --git a/CHANGELOG.md b/CHANGELOG.md index 294ac9e..2707eef 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,14 @@ Forge package families are versioned independently. Implementations of the same ## Unreleased +## forge-tool 1.0.1 - 2026-11-20 + +Family tag: `forge-tool-v1.0.1` + +- Backport Python 3.11 support to the standalone Tool package and its optional Arrow/Dora binding. Preserve the Forge 1.x carrier dependency (`forge-msgs>=1.2.0,<2`) and Dora 0.4 runtime line; the complete workspace still requires Python 3.12. +- Replace Python 3.12-only aliases and generic-function syntax with `typing.TypeAlias` and `TypeVar` without changing the ToolEndpoint wire protocol or execution lifecycle. Runtime alias inspection uses `typing.get_args(alias)` instead of `alias.__value__`. +- Add a Python 3.11 syntax guard and validate the built wheel in an isolated Python 3.11 environment. + ## forge-tool 1.0.0 - 2026-08-27 Protected tag: `forge-tool-v1.0.0` diff --git a/README.md b/README.md index 0882468..88e32e6 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # Forge +[English](README.md) | [简体中文](README_zh.md) + Forge is a small robotics framework core for Dora dataflows. It provides shared message schemas, Python and Rust message implementations, reusable node runner helpers for robot drivers and policy nodes, and typed tool endpoint contracts. @@ -31,8 +33,8 @@ packages, for example a separate `forge_robots` repository. ## Status Forge tracks six independently versioned package families: Common, Msgs, Robot, -Policy, Kinematics, and Tool. Current releases are Common `1.0.1`, Msgs `1.3.0`, Robot -`1.0.1`, Policy `1.0.1`, Kinematics `1.0.1`, and Tool `0.1.0`. Implementations of one +Policy, Kinematics, and Tool. Current releases are Common `1.0.1`, Msgs `1.3.1`, Robot +`1.0.1`, Policy `1.0.1`, Kinematics `1.0.1`, and Tool `1.0.1`. Implementations of one family across Python, Rust, C++, and the language-neutral interface remain synchronized; unrelated families may release at different rates. @@ -49,7 +51,7 @@ requires its next major version. See [`RELEASING.md`](RELEASING.md) for package-family boundaries, protected GitLab tags, and validation procedures. -Forge ToolEndpoint v1alpha1 is the first tagged/public Tool contract and is released as +Forge ToolEndpoint v1alpha1 was first published as Tool `0.1.0` with its carrier in Msgs `1.2.0`. Compatible deployments must use matching Gateway and provider revisions. Earlier untagged prototypes are incompatible, and mixed deployments are not supported as backward compatible. @@ -84,7 +86,7 @@ forge/ ## Requirements -- Python 3.12 or newer for the workspace +- Python 3.12 or newer for the workspace; standalone Common, Msgs, and Tool packages support Python 3.11 - Rust toolchain with edition 2024 support - A C++20-capable compiler and CMake 3.20 or newer for C++ packages; `cpp/forge_msgs` and its dependents require C++20 @@ -97,6 +99,15 @@ forge/ ## Installation +For a standalone Python 3.11 node on the legacy Forge 1.x line: + +```bash +python -m pip install "forge-tool[dora]==1.0.1" +``` + +This keeps `forge-msgs>=1.2.0,<2`; the concrete node supplies its Dora runtime. +`stable/1.x` retains Dora 0.4 compatibility, while `master` maintains Forge 2.x. + Clone the repository and install the default Python workspace: ```bash diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 0000000..befdaba --- /dev/null +++ b/README_zh.md @@ -0,0 +1,60 @@ +# Forge + +[English](README.md) | [简体中文](README_zh.md) + +Forge 是面向 Dora 数据流的机器人基础框架,提供跨语言消息 schema、机器人和策略节点运行器,以及类型化 ToolEndpoint 契约。具体机器人驱动和硬件 SDK 集成由下游节点提供。 + +## 版本状态 + +本分支 `stable/1.x` 维护兼容 Dora 0.4 的 Forge 1.x;`master` 维护 Forge 2.x。 +六个包家族独立发布:Common `1.0.1`、Msgs `1.3.1`、Robot `1.0.1`、Policy `1.0.1`、Kinematics `1.0.1`、Tool `1.0.1`。 + +Common、Msgs 和 Tool 独立包支持 Python 3.11;完整源码工作区仍要求 Python 3.12。 +Tool `1.0.1` 通过兼容的类型声明支持 Python 3.11,线协议与执行生命周期保持不变。 +运行时检查类型别名使用 `typing.get_args(alias)`,不再访问 `alias.__value__`。 +Msgs `1.3.1` 的图像编解码要求 Pillow `>=13.0.0,<14`。 + +## Python 3.11 节点安装 + +在节点自己的 Python 3.11 环境中安装发布包: + +```bash +python -m pip install "forge-tool[dora]==1.0.1" +``` + +`[dora]` 引入 Arrow 消息载体依赖 `forge-msgs>=1.2.0,<2`,不安装 Dora 运行时。 +具体节点负责安装与部署匹配的 Dora 版本;本分支的节点运行器使用 `dora-rs==0.4.1`。 +不需要 Arrow 绑定时,可以只安装无运行时依赖的基础包: + +```bash +python -m pip install "forge-tool==1.0.1" +``` + +支持 Python 3.11 不代表已验证所有 Isaac Sim/RoboDojo 集成,仍需在目标节点环境验证仿真器、驱动和运行时依赖。 + +## 源码开发与测试 + +源码工作区使用 Python 3.12 或更新版本,以及 `uv`: + +```bash +uv sync --locked --all-packages --all-extras --dev +uv run python scripts/check_release_versions.py +uv run ruff check . +uv run pytest packages/msgs/tests packages/policy/tests packages/robot/tests packages/kinematics/tests packages/tool/tests +uv run python scripts/build_python_distributions.py +``` + +Python 3.11 节点应使用独立虚拟环境安装发布包,不要直接同步包含 Python 3.12 包的完整工作区。 +Rust 需要支持 edition 2024 的工具链;C++ 需要 C++20、CMake 3.20 及 Apache Arrow C++。 + +## 文档导航 + +| 内容 | 入口 | +| --- | --- | +| ToolEndpoint、协议与 Python 用法 | [Tool 文档](interfaces/forge_tool/README.md) · [Python 包指南](packages/tool/README.md) | +| 权威消息 schema | [forge_msgs 接口](interfaces/forge_msgs/) | +| 完整仓库布局、C++/Rust 构建与 API 示例 | [英文开发指南](README.md) | +| 各包更新记录 | [CHANGELOG](CHANGELOG.md) | +| 独立版本、打包与家族标签发布规则 | [RELEASING](RELEASING.md) | + +发布使用不可变的家族标签,例如 `forge-tool-v1.0.1`。不同主版本的依赖约束与运行时应分别维护。 diff --git a/RELEASING.md b/RELEASING.md index b813f3a..66904df 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -9,11 +9,11 @@ Forge is a Monorepo with independently versioned logical package families. Imple ```toml [packages] common = "1.0.1" -msgs = "1.3.0" +msgs = "1.3.1" robot = "1.0.1" policy = "1.0.1" kinematics = "1.0.1" -tool = "0.1.0" +tool = "1.0.1" ``` The root `pyproject.toml` is a virtual uv workspace, not a published `forge` Python distribution. Its project version is workspace tooling metadata and is not a package-family release version. diff --git a/packages/tool/README.md b/packages/tool/README.md index 82d5205..74f8a8e 100644 --- a/packages/tool/README.md +++ b/packages/tool/README.md @@ -34,26 +34,29 @@ handling therefore does not imply a complete caller-to-provider Action or Sessio ## Installation -Python 3.12 or newer is required. Install the current Tool release from PyPI: +Python 3.11 or newer is required. Install the current Tool release from PyPI: ```bash -pip install forge-tool +pip install 'forge-tool>=1.0.1,<2' ``` Install the optional Arrow carrier integration when embedding an endpoint in a Dora-capable Operator or Adapter node: ```bash -pip install 'forge-tool[dora]' +pip install 'forge-tool[dora]>=1.0.1,<2' ``` -From a Forge source checkout, run code through the repository workspace instead of -syncing the package subproject in isolation: +The complete Forge source workspace still requires Python 3.12 or newer. From a +source checkout, run code through that workspace: ```bash uv run python your_endpoint.py ``` +For Python 3.11, install the standalone Tool distribution into a separate environment; +the workspace also includes packages that require Python 3.12. + The base package has no runtime dependencies. `import forge_tool` does not import `forge_msgs` or PyArrow. The optional extra adds the carrier stack, not `dora-rs`; the concrete node package remains responsible for its Dora dependency. @@ -413,10 +416,10 @@ Explicitly import from `forge_tool.dora`: ## Protocol documentation -- [Tool documentation index](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v1.0.0/interfaces/forge_tool/README.md) -- [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v1.0.0/interfaces/forge_tool/ARCHITECTURE.md) -- [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v1.0.0/interfaces/forge_tool/PROTOCOL.md) -- [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-v1.2.0/interfaces/forge_msgs/tool.v1.yaml) +- [Tool documentation index](https://github.com/PhyAgentOS/forge/blob/forge-tool-v1.0.1/interfaces/forge_tool/README.md) +- [Architecture](https://github.com/PhyAgentOS/forge/blob/forge-tool-v1.0.1/interfaces/forge_tool/ARCHITECTURE.md) +- [ToolEndpoint Wire protocol](https://github.com/PhyAgentOS/forge/blob/forge-tool-v1.0.1/interfaces/forge_tool/PROTOCOL.md) +- [Canonical `ToolMessage` Arrow schema](https://github.com/PhyAgentOS/forge/blob/forge-msgs-v1.3.1/interfaces/forge_msgs/tool.v1.yaml) ## Development @@ -428,4 +431,4 @@ uv run pytest packages/tool/tests ## License -Apache-2.0. See the release [LICENSE](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v1.0.0/LICENSE). +Apache-2.0. See the release [LICENSE](https://github.com/PhyAgentOS/forge/blob/forge-tool-v1.0.1/LICENSE). diff --git a/packages/tool/pyproject.toml b/packages/tool/pyproject.toml index e670c69..5d592c9 100644 --- a/packages/tool/pyproject.toml +++ b/packages/tool/pyproject.toml @@ -1,9 +1,9 @@ [project] name = "forge-tool" -version = "1.0.0" +version = "1.0.1" description = "Typed endpoint contracts for Forge query, action, and session tools." readme = "README.md" -requires-python = ">=3.12" +requires-python = ">=3.11" license = "Apache-2.0" license-files = ["LICENSE"] authors = [ diff --git a/packages/tool/src/forge_tool/dora.py b/packages/tool/src/forge_tool/dora.py index 6060c74..503ae9c 100644 --- a/packages/tool/src/forge_tool/dora.py +++ b/packages/tool/src/forge_tool/dora.py @@ -5,6 +5,7 @@ import asyncio import logging from collections.abc import Awaitable, Callable +from typing import TypeAlias import pyarrow as pa from forge_msgs import ToolMessage, ToolMessageSizeError @@ -26,8 +27,8 @@ _MIN_BINDING_MESSAGE_BYTES = 1_024 _DEFAULT_CARRIER_OVERHEAD_BYTES = 65_536 -type _ToolArrowValue = pa.RecordBatch | pa.Table | pa.StructArray -type DoraEventSink = Callable[[pa.RecordBatch], Awaitable[None]] +_ToolArrowValue: TypeAlias = pa.RecordBatch | pa.Table | pa.StructArray +DoraEventSink: TypeAlias = Callable[[pa.RecordBatch], Awaitable[None]] def _message_envelope(message: ToolMessage) -> ToolEnvelope: diff --git a/packages/tool/src/forge_tool/endpoint/models.py b/packages/tool/src/forge_tool/endpoint/models.py index ce55fbc..30b3d72 100644 --- a/packages/tool/src/forge_tool/endpoint/models.py +++ b/packages/tool/src/forge_tool/endpoint/models.py @@ -5,12 +5,12 @@ import math from collections.abc import Mapping from dataclasses import dataclass, field -from typing import Any, Literal +from typing import Any, Literal, TypeAlias -type ToolSemantics = Literal["query", "action", "session"] -type EndpointState = Literal["ready", "busy", "degraded", "unavailable"] -type ExecutionPhase = Literal[ +ToolSemantics: TypeAlias = Literal["query", "action", "session"] +EndpointState: TypeAlias = Literal["ready", "busy", "degraded", "unavailable"] +ExecutionPhase: TypeAlias = Literal[ "accepted", "running", "stopping", @@ -20,7 +20,7 @@ "stopped", "unknown", ] -type ToolEventType = Literal[ +ToolEventType: TypeAlias = Literal[ "progress", "heartbeat", "executor_completed", @@ -28,18 +28,18 @@ "cancelled", "stopped", ] -type ToolResultStatus = Literal[ +ToolResultStatus: TypeAlias = Literal[ "succeeded", "failed", "cancelled", "stopped", "unknown", ] -type ToolResultResponseStatus = Literal["pending", "available", "not_found"] -type ToolControlCommand = Literal["cancel", "stop"] -type EndpointRegistryOperation = Literal["register", "unregister"] -type EndpointRegistryResponseStatus = Literal["accepted", "rejected"] -type ToolControlStatus = Literal[ +ToolResultResponseStatus: TypeAlias = Literal["pending", "available", "not_found"] +ToolControlCommand: TypeAlias = Literal["cancel", "stop"] +EndpointRegistryOperation: TypeAlias = Literal["register", "unregister"] +EndpointRegistryResponseStatus: TypeAlias = Literal["accepted", "rejected"] +ToolControlStatus: TypeAlias = Literal[ "accepted", "rejected", "terminal", diff --git a/packages/tool/src/forge_tool/handler.py b/packages/tool/src/forge_tool/handler.py index ad12ee7..d41c9b7 100644 --- a/packages/tool/src/forge_tool/handler.py +++ b/packages/tool/src/forge_tool/handler.py @@ -6,7 +6,7 @@ from collections import OrderedDict from collections.abc import Awaitable, Callable, Mapping from dataclasses import dataclass, field -from typing import cast +from typing import TypeAlias, cast from .endpoint import ( ActionToolEndpoint, @@ -40,7 +40,7 @@ validate_message_envelope, ) -type ToolEventSink = Callable[[ToolEnvelope], Awaitable[None]] +ToolEventSink: TypeAlias = Callable[[ToolEnvelope], Awaitable[None]] _REQUIRED_METHODS = { "query": ("query",), diff --git a/packages/tool/src/forge_tool/wire/envelope.py b/packages/tool/src/forge_tool/wire/envelope.py index 75397b4..cc1abb8 100644 --- a/packages/tool/src/forge_tool/wire/envelope.py +++ b/packages/tool/src/forge_tool/wire/envelope.py @@ -5,7 +5,7 @@ import math from collections.abc import Mapping from dataclasses import dataclass, field -from typing import Any, Literal +from typing import Any, Literal, TypeAlias from .errors import ToolProtocolError @@ -13,7 +13,7 @@ MAX_SAFE_JSON_INTEGER = 9_007_199_254_740_991 MAX_JSON_DEPTH = 64 -type ToolMessageType = Literal[ +ToolMessageType: TypeAlias = Literal[ "endpoint.register", "endpoint.unregister", "endpoint.registry.response", diff --git a/packages/tool/src/forge_tool/wire/messages.py b/packages/tool/src/forge_tool/wire/messages.py index a63f69b..bba0d9f 100644 --- a/packages/tool/src/forge_tool/wire/messages.py +++ b/packages/tool/src/forge_tool/wire/messages.py @@ -3,7 +3,7 @@ from __future__ import annotations from collections.abc import Mapping -from typing import Any, cast +from typing import Any, TypeVar, cast from ..endpoint import ( EndpointRegistryResponse, @@ -24,6 +24,8 @@ from .envelope import ToolEnvelope, _is_blank, _json_value from .errors import ToolProtocolError +_T = TypeVar("_T") + def _error(message: str, path: str) -> ToolProtocolError: return ToolProtocolError( @@ -59,7 +61,7 @@ def _fields( raise _error("; ".join(details), path) -def _construct[T](factory: type[T], path: str, **values: Any) -> T: +def _construct(factory: type[_T], path: str, **values: Any) -> _T: try: return factory(**values) except (TypeError, ValueError) as error: diff --git a/packages/tool/tests/test_python_compatibility.py b/packages/tool/tests/test_python_compatibility.py new file mode 100644 index 0000000..12b55e9 --- /dev/null +++ b/packages/tool/tests/test_python_compatibility.py @@ -0,0 +1,19 @@ +"""Keep the package's minimum Python syntax covered by the workspace CI.""" + +import ast +from pathlib import Path + +import pytest + +import forge_tool + +_SOURCE_ROOT = Path(forge_tool.__file__).resolve().parent + + +@pytest.mark.parametrize( + "source", + sorted(_SOURCE_ROOT.rglob("*.py")), + ids=lambda source: str(source.relative_to(_SOURCE_ROOT)), +) +def test_source_supports_python_311(source: Path) -> None: + ast.parse(source.read_text(encoding="utf-8"), filename=str(source), feature_version=(3, 11)) diff --git a/packages/tool/tests/test_wire.py b/packages/tool/tests/test_wire.py index fad1d13..f0030b7 100644 --- a/packages/tool/tests/test_wire.py +++ b/packages/tool/tests/test_wire.py @@ -63,7 +63,7 @@ def _tool_envelope(**overrides: object) -> ToolEnvelope: def test_message_type_literal_matches_runtime_registry() -> None: - assert set(get_args(ToolMessageType.__value__)) == TOOL_MESSAGE_TYPES + assert set(get_args(ToolMessageType)) == TOOL_MESSAGE_TYPES def test_generic_invoke_envelope_round_trips_as_deterministic_utf8_json() -> None: diff --git a/uv.lock b/uv.lock index 53260e9..0da3384 100644 --- a/uv.lock +++ b/uv.lock @@ -389,7 +389,7 @@ requires-dist = [ [[package]] name = "forge-tool" -version = "1.0.0" +version = "1.0.1" source = { editable = "packages/tool" } [package.optional-dependencies] diff --git a/versions.toml b/versions.toml index 43704e0..6e1012d 100644 --- a/versions.toml +++ b/versions.toml @@ -6,4 +6,4 @@ msgs = "1.3.1" robot = "1.0.1" policy = "1.0.1" kinematics = "1.0.1" -tool = "1.0.0" +tool = "1.0.1"