Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
19 changes: 15 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
60 changes: 60 additions & 0 deletions README_zh.md
Original file line number Diff line number Diff line change
@@ -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`。不同主版本的依赖约束与运行时应分别维护。
4 changes: 2 additions & 2 deletions RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
23 changes: 13 additions & 10 deletions packages/tool/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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

Expand All @@ -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).
4 changes: 2 additions & 2 deletions packages/tool/pyproject.toml
Original file line number Diff line number Diff line change
@@ -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 = [
Expand Down
5 changes: 3 additions & 2 deletions packages/tool/src/forge_tool/dora.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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:
Expand Down
22 changes: 11 additions & 11 deletions packages/tool/src/forge_tool/endpoint/models.py
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand All @@ -20,26 +20,26 @@
"stopped",
"unknown",
]
type ToolEventType = Literal[
ToolEventType: TypeAlias = Literal[
"progress",
"heartbeat",
"executor_completed",
"executor_failed",
"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",
Expand Down
4 changes: 2 additions & 2 deletions packages/tool/src/forge_tool/handler.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -40,7 +40,7 @@
validate_message_envelope,
)

type ToolEventSink = Callable[[ToolEnvelope], Awaitable[None]]
ToolEventSink: TypeAlias = Callable[[ToolEnvelope], Awaitable[None]]

_REQUIRED_METHODS = {
"query": ("query",),
Expand Down
4 changes: 2 additions & 2 deletions packages/tool/src/forge_tool/wire/envelope.py
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,15 @@
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

TOOL_ENDPOINT_PROTOCOL = "forge.tool.endpoint/v1alpha1"
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",
Expand Down
6 changes: 4 additions & 2 deletions packages/tool/src/forge_tool/wire/messages.py
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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(
Expand Down Expand Up @@ -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:
Expand Down
19 changes: 19 additions & 0 deletions packages/tool/tests/test_python_compatibility.py
Original file line number Diff line number Diff line change
@@ -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))
2 changes: 1 addition & 1 deletion packages/tool/tests/test_wire.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 1 addition & 1 deletion uv.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion versions.toml
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Loading