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
10 changes: 7 additions & 3 deletions .github/workflows/publish-pypi.yml
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,9 @@ jobs:
name: Publish ${{ needs.resolve.outputs.tag }}
needs: resolve
runs-on: ubuntu-latest
defaults:
run:
working-directory: release-source
environment:
name: pypi-${{ needs.resolve.outputs.family }}
permissions:
Expand All @@ -91,13 +94,14 @@ jobs:
uses: actions/checkout@v4
with:
ref: ${{ needs.resolve.outputs.tag }}
path: release-source
fetch-depth: 0
persist-credentials: false
- name: Check out release tooling from the workflow commit
uses: actions/checkout@v4
with:
ref: ${{ github.workflow_sha }}
path: .release-tools
path: release-tools
persist-credentials: false
- name: Set up Python
uses: actions/setup-python@v5
Expand All @@ -107,7 +111,7 @@ jobs:
env:
RELEASE_TAG: ${{ needs.resolve.outputs.tag }}
RELEASE_LINE: ${{ needs.resolve.outputs.release_line }}
run: python .release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --default-branch master
run: python ../release-tools/scripts/check_release_line.py --line "$RELEASE_LINE" --tag "$RELEASE_TAG" --default-branch master
- name: Verify annotated tag and commit
shell: bash
env:
Expand Down Expand Up @@ -142,7 +146,7 @@ jobs:
uses: actions/upload-artifact@v4
with:
name: ${{ needs.resolve.outputs.distribution }}-${{ needs.resolve.outputs.version }}
path: dist/release/python/${{ needs.resolve.outputs.family }}/*
path: release-source/dist/release/python/${{ needs.resolve.outputs.family }}/*
if-no-files-found: error
- name: Publish wheel and source distribution to PyPI
shell: bash
Expand Down
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,15 @@ Forge package families are versioned independently. Python, Rust, and C++ implem

## Unreleased

## forge-tool 2.0.1 - 2026-11-20

Family tag: `forge-tool-v2.0.1`

- Support Python 3.11 in the standalone Tool package and its optional Arrow/Dora binding; the complete Forge workspace still requires Python 3.12.
- Replace Python 3.12-only type aliases and generic-function syntax with `typing.TypeAlias` and `TypeVar`, without changing the ToolEndpoint wire protocol or execution lifecycle. Runtime type inspection now uses `typing.get_args(alias)` rather than `alias.__value__`.
- Add a Python 3.11 syntax guard to the existing test suite and validate the built wheel in a separate Python 3.11 environment.
- Keep release tooling in a sibling checkout so family builds retain the clean-source check without rejecting CI's own tooling checkout.

## forge-msgs 2.1.0 - 2026-11-12

Family tag: `forge-msgs-v2.1.0`
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,14 +35,14 @@ packages, for example a separate `forge_robots` repository.
## Status

Forge tracks six package families: Common, Msgs, Robot, Policy, Kinematics, and Tool.
Common is `2.1.0`; Msgs is `2.1.0`; Robot, Policy, Kinematics and Tool remain
Common and Msgs are `2.1.0`; Tool is `2.0.1`; Robot, Policy and Kinematics remain
at the coordinated Dora 1.x `2.0.0` baseline. Families can receive independent minor and patch releases.
Package versions within one family remain synchronized across languages;
capabilities may differ, and language-neutral interface versions are tracked
separately.

The Python Msgs compressed-image codec requires Pillow `>=13.0.0,<14`.
Msgs still supports Python 3.11; the complete workspace requires Python 3.12.
Common, Msgs, and Tool support Python 3.11; the complete workspace requires Python 3.12.
Consumers pinning Pillow below 13 must update their dependency constraints.
Raw RGB/depth payloads and the Arrow wire schema are unchanged.

Expand Down
4 changes: 2 additions & 2 deletions README_zh.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,12 @@ Forge 是面向 Dora 数据流的机器人基础框架,提供公共消息 sche
## 版本状态

Forge 按 Common、Msgs、Robot、Policy、Kinematics、Tool 六个包家族维护。
Common 为 `2.1.0`,Msgs 为 `2.1.0`;Robot、Policy、Kinematics、Tool 保持 Dora 1.x 对齐的 `2.0.0` 基线。
Common 和 Msgs 为 `2.1.0`,Tool 为 `2.0.1`;Robot、Policy、Kinematics 保持 Dora 1.x 对齐的 `2.0.0` 基线。
各家族可独立发布次版本和修订版本;同一家族跨语言包版本保持一致,
实际能力允许不同,语言无关接口版本另行跟踪。

Python Msgs 的压缩图像编解码要求 Pillow `>=13.0.0,<14`。
Msgs 继续支持 Python 3.11;完整工作区要求 Python 3.12。
Common、Msgs 和 Tool 支持 Python 3.11;完整工作区要求 Python 3.12。
固定使用 Pillow 13 以下版本的使用方需要更新依赖约束。
原始 RGB/深度数据及 Arrow 线协议保持不变。

Expand Down
2 changes: 1 addition & 1 deletion RELEASING.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ msgs = "2.1.0"
robot = "2.0.0"
policy = "2.0.0"
kinematics = "2.0.0"
tool = "2.0.0"
tool = "2.0.1"

[interfaces]
msgs = 1
Expand Down
19 changes: 11 additions & 8 deletions packages/tool/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ 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
Expand All @@ -47,13 +47,16 @@ Dora-capable Operator or Adapter node:
pip install 'forge-tool[dora]'
```

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-v2.0.0/interfaces/forge_tool/README.md)
- [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/ARCHITECTURE.md)
- [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/PROTOCOL.md)
- [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-v2.0.0/interfaces/forge_msgs/tool.v1.yaml)
- [Tool documentation index](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.0.1/interfaces/forge_tool/README.md)
- [Architecture](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.0.1/interfaces/forge_tool/ARCHITECTURE.md)
- [ToolEndpoint Wire protocol](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.0.1/interfaces/forge_tool/PROTOCOL.md)
- [Canonical `ToolMessage` Arrow schema](https://github.com/PhyAgentOS/forge/blob/forge-msgs-v2.1.0/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-v2.0.0/LICENSE).
Apache-2.0. See the release [LICENSE](https://github.com/PhyAgentOS/forge/blob/forge-tool-v2.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 = "2.0.0"
version = "2.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
32 changes: 32 additions & 0 deletions scripts/tests/test_publish_workflow.py
Original file line number Diff line number Diff line change
Expand Up @@ -95,3 +95,35 @@ def test_manual_release_rejects_wrong_line_before_remote_lookup(tmp_path, tag, l
)
assert result.returncode == 1
assert message in result.stderr


def test_release_tooling_checkout_preserves_clean_source_guard(tmp_path, monkeypatch):
workflow = yaml.safe_load((ROOT / ".github/workflows/publish-pypi.yml").read_text())
job = workflow["jobs"]["publish"]
checkouts = [step for step in job["steps"] if step.get("uses", "").startswith("actions/checkout@")]
source = tmp_path / checkouts[0]["with"].get("path", ".")
tooling = tmp_path / checkouts[1]["with"]["path"]
source.mkdir(parents=True, exist_ok=True)
subprocess.run(["git", "init", "-q", str(source)], check=True)
(source / "versions.toml").write_text('[packages]\ntool = "2.0.1"\n')
subprocess.run(["git", "-C", str(source), "add", "versions.toml"], check=True)
subprocess.run(
["git", "-C", str(source), "-c", "user.name=Release Test",
"-c", "user.email=release-test@example.invalid", "-c", "commit.gpgsign=false",
"commit", "-qm", "Release fixture"],
check=True,
)
tooling.mkdir(parents=True, exist_ok=True)
(tooling / "helper.py").write_text("# Release tooling from the workflow revision.\n")

working_directory = tmp_path / job.get("defaults", {}).get("run", {}).get("working-directory", ".")
monkeypatch.syspath_prepend(str(ROOT / "scripts"))
import build_python_distributions as builder

monkeypatch.setattr(builder, "ROOT", working_directory)
builder._check_release_context("tool", None)

# Unexpected source files must still block a release.
(source / "unexpected.py").write_text("# Unreviewed source change.\n")
with pytest.raises(builder.BuildError, match="clean Git working tree"):
builder._check_release_context("tool", None)
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,7 +6,7 @@ msgs = "2.1.0"
robot = "2.0.0"
policy = "2.0.0"
kinematics = "2.0.0"
tool = "2.0.0"
tool = "2.0.1"

[interfaces]
msgs = 1
Loading