coloph-toolset 0.1.0__tar.gz

coloph_toolset-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+on: [push, pull_request]
+permissions:
+  contents: read
+jobs:
+  minimum-dependencies:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.12'
+      - run: uv run --isolated --python 3.12 --with pydantic==2.12.0 --with annotated-types==0.7.0 python -m pytest
+  contracts:
+    strategy:
+      matrix:
+        python: ['3.11', '3.12', '3.13', '3.14']
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv run mypy
+      - run: uv run python -m ruff check .
+      - run: uv run python -m ruff format --check .
+      - run: uv build
+      - run: uv run python scripts/smoke_wheel.py

coloph_toolset-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+on:
+  push:
+    tags: ['v*']
+permissions:
+  contents: write
+  id-token: write
+jobs:
+  release:
+    environment:
+      name: pypi
+      url: https://pypi.org/p/coloph-toolset
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: '3.12'
+      - run: uv sync --locked
+      - run: uv run pytest
+      - run: uv run mypy
+      - run: uv run python -m ruff check .
+      - run: uv run python -m ruff format --check .
+      - run: uv build
+      - run: uv run python scripts/smoke_wheel.py
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - run: uv run python scripts/release.py
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.ref_name }}

coloph_toolset-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+build/

coloph_toolset-0.1.0/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 0.1.0
+
+- Add lazy function declarations and parameter inspection.
+- Generate JSON Schema and argument models from the same retained annotations.
+- Preserve supported constraints, nullable required inputs, defaults, and hidden argument projections.
+- Reject unsupported signatures and metadata before application dispatch.
+- Add the standalone shipping-quote example and clean wheel smoke coverage.
+
+Execution remains application-owned in this release.

coloph_toolset-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# Contributing
+
+## Local checks
+
+```sh
+uv sync --locked
+uv run pytest
+uv run mypy
+uv run python -m ruff check .
+uv run python -m ruff format --check .
+uv build
+uv run python scripts/smoke_wheel.py
+```
+
+Keep fixes and tests within the current milestone. Add contract tests for changes in public behavior.
+Preserve every project under `examples/`. Each project needs source, a README, dependency metadata, and automated smoke coverage.
+Examples must use public imports and work without a Coloph checkout or private services.
+
+## Release
+
+This package initially distributes wheels and source archives through GitHub Releases. It does not require a PyPI publishing credential.
+
+1. Update the version and changelog.
+2. Run all local checks and the clean wheel smoke.
+3. Review and commit the changes.
+4. Push the reviewed commit to the public default branch.
+5. Wait for CI on the exact release commit.
+6. Create an immutable `vX.Y.Z` tag on that commit.
+7. Push the tag. The release workflow reruns tests and publishes the wheel and source archive.
+8. Validate the published artifacts in a clean environment.
+
+The package version, tag, and release notes must match. Never move an existing release tag.
+Coloph can adopt a release only after the public default branch and release contain its tested commit.
+Record the release and Coloph dependency pin in the owning Coloph issue.
+
+When PyPI distribution is introduced, the release process must publish the same tested artifacts and version there.

coloph_toolset-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 golergka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

coloph_toolset-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: coloph-toolset
+Version: 0.1.0
+Summary: Declare Python tools once, export their schemas, and validate their arguments.
+Project-URL: Repository, https://github.com/golergka/coloph-toolset
+Project-URL: Issues, https://github.com/golergka/coloph-toolset/issues
+Project-URL: Changelog, https://github.com/golergka/coloph-toolset/blob/main/CHANGELOG.md
+Author: golergka
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: annotated-types<1,>=0.7
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+# coloph-toolset
+
+Declare Python tools once. Export their JSON Schema and validate arguments before your application calls the function.
+
+Version 0.1 provides declarations and validation. It does not manage execution, transactions, authorization, or model providers.
+Later releases add catalogs and adapters. The [roadmap](docs/roadmap.md) describes that sequence.
+
+## Install
+
+```sh
+uv add coloph-toolset
+```
+
+The package requires Python 3.11 or later and Pydantic 2.12 or later within major version 2.
+No Coloph installation, database, credentials, HTTP framework, or agent framework is required.
+
+## Declare and validate
+
+```python
+from typing import Annotated
+from pydantic import Field, ValidationError
+from coloph_toolset import tool, tool_for
+
+
+@tool()
+def shipping_quote(
+    ctx,
+    quantity: Annotated[int, "Number of parcels", Field(gt=0)],
+    destination: Annotated[str | None, "Country code, or null for collection"],
+    insured: Annotated[bool, "Include insurance"] = False,
+) -> dict[str, object]:
+    return {"quantity": quantity, "destination": destination, "insured": insured}
+
+
+declaration = tool_for(shipping_quote)
+schema = declaration.json_schema()
+arguments = declaration.validate_arguments({"quantity": "2", "destination": None})
+result = shipping_quote(None, **arguments)
+
+try:
+    declaration.validate_arguments({"quantity": 0, "destination": None})
+except ValidationError as error:
+    print(error.errors(include_url=False))
+```
+
+Validation never calls the function. Calling the Python function directly does not apply validation.
+The application owns execution and must use validated arguments at its dispatch boundary.
+
+## Context and restricted arguments
+
+The declaration expects a required first parameter named `ctx`.
+Its type is application-owned and its annotation is not evaluated. Context never appears in the argument schema.
+
+```python
+@tool(model_hidden_args=("internal",))
+def inspect_order(ctx, order: str, internal: bool = False):
+    return ctx.lookup(order, internal=internal)
+
+
+public = tool_for(inspect_order)
+public.validate_arguments({"order": "demo"})
+# An external "internal" argument raises ValidationError.
+operator_schema = public.json_schema(include_hidden=True)
+```
+
+Hidden arguments require valid defaults. Only trusted application code can select `include_hidden=True`.
+Argument projection is not an authorization system.
+
+## Contracts and examples
+
+- [Argument contract and API](docs/contracts.md)
+- [Standalone shipping-quote project](examples/01-tool-declarations/README.md)
+- [Development and release procedure](CONTRIBUTING.md)
+- [Changes](CHANGELOG.md)
+
+Every milestone adds a project under `examples/`. CI runs all preserved examples against the current library.
+
+## Development
+
+```sh
+uv sync --locked
+uv run pytest
+uv run mypy
+uv run python -m ruff check .
+uv run python -m ruff format --check .
+uv build
+uv run python scripts/smoke_wheel.py
+```
+
+MIT licensed.

coloph_toolset-0.1.0/README.md

@@ -0,0 +1,90 @@
+# coloph-toolset
+
+Declare Python tools once. Export their JSON Schema and validate arguments before your application calls the function.
+
+Version 0.1 provides declarations and validation. It does not manage execution, transactions, authorization, or model providers.
+Later releases add catalogs and adapters. The [roadmap](docs/roadmap.md) describes that sequence.
+
+## Install
+
+```sh
+uv add coloph-toolset
+```
+
+The package requires Python 3.11 or later and Pydantic 2.12 or later within major version 2.
+No Coloph installation, database, credentials, HTTP framework, or agent framework is required.
+
+## Declare and validate
+
+```python
+from typing import Annotated
+from pydantic import Field, ValidationError
+from coloph_toolset import tool, tool_for
+
+
+@tool()
+def shipping_quote(
+    ctx,
+    quantity: Annotated[int, "Number of parcels", Field(gt=0)],
+    destination: Annotated[str | None, "Country code, or null for collection"],
+    insured: Annotated[bool, "Include insurance"] = False,
+) -> dict[str, object]:
+    return {"quantity": quantity, "destination": destination, "insured": insured}
+
+
+declaration = tool_for(shipping_quote)
+schema = declaration.json_schema()
+arguments = declaration.validate_arguments({"quantity": "2", "destination": None})
+result = shipping_quote(None, **arguments)
+
+try:
+    declaration.validate_arguments({"quantity": 0, "destination": None})
+except ValidationError as error:
+    print(error.errors(include_url=False))
+```
+
+Validation never calls the function. Calling the Python function directly does not apply validation.
+The application owns execution and must use validated arguments at its dispatch boundary.
+
+## Context and restricted arguments
+
+The declaration expects a required first parameter named `ctx`.
+Its type is application-owned and its annotation is not evaluated. Context never appears in the argument schema.
+
+```python
+@tool(model_hidden_args=("internal",))
+def inspect_order(ctx, order: str, internal: bool = False):
+    return ctx.lookup(order, internal=internal)
+
+
+public = tool_for(inspect_order)
+public.validate_arguments({"order": "demo"})
+# An external "internal" argument raises ValidationError.
+operator_schema = public.json_schema(include_hidden=True)
+```
+
+Hidden arguments require valid defaults. Only trusted application code can select `include_hidden=True`.
+Argument projection is not an authorization system.
+
+## Contracts and examples
+
+- [Argument contract and API](docs/contracts.md)
+- [Standalone shipping-quote project](examples/01-tool-declarations/README.md)
+- [Development and release procedure](CONTRIBUTING.md)
+- [Changes](CHANGELOG.md)
+
+Every milestone adds a project under `examples/`. CI runs all preserved examples against the current library.
+
+## Development
+
+```sh
+uv sync --locked
+uv run pytest
+uv run mypy
+uv run python -m ruff check .
+uv run python -m ruff format --check .
+uv build
+uv run python scripts/smoke_wheel.py
+```
+
+MIT licensed.

coloph_toolset-0.1.0/docs/contracts.md

@@ -0,0 +1,81 @@
+# Argument contract
+
+## Declaration lifetime
+
+`@tool()` attaches a `Tool` at `fn.tool` and returns the original function.
+`tool_for(fn)` reads that declaration. `Tool(fn, ...)` also works without a decorator for application integration.
+
+Signature structure is validated at construction. Parameter annotations are resolved lazily on first inspection.
+Schema construction validates defaults and rejects unsupported metadata. A malformed declaration raises `DeclarationError`, the exported name for `TypeError`.
+Applications must build their argument models during startup before they accept calls.
+
+Annotations are trusted developer code. String annotations resolve in the original function's global namespace, including through `functools.wraps`.
+Function-local forward names must be available in that namespace or use evaluated annotations.
+Context and return annotations are not resolved. Schema inspection never calls the body.
+Do not mutate a function's signature, annotations, defaults, or declaration after registration.
+
+## Supported signatures and types
+
+- Plain synchronous functions with named external arguments. Positional-only external arguments and variadic arguments are rejected.
+- A required injected context named `ctx` as the first positional parameter.
+- `bool`, `int`, `float`, and `str`.
+- Homogeneous string or integer `Literal` choices.
+- Lists of supported scalar or literal values. Nested lists and nullable list elements are not supported in 0.1.
+- Nullable forms of those types, including a nullable list.
+- `Annotated` descriptions and the constraint metadata listed next.
+
+Async functions, generators, bound methods, arbitrary callable objects, unconstrained `Any`, mixed unions, and nested models are not supported in 0.1.
+These declarations fail explicitly. Async execution belongs to a later milestone.
+
+## Metadata
+
+One string in `Annotated` supplies the argument description.
+Supported Pydantic `Field` options are `description`, `title`, `examples`, `gt`, `ge`, `lt`, `le`, `multiple_of`, `min_length`, `max_length`, `pattern`, and `strict`.
+Direct `annotated_types.Gt`, `Ge`, `Lt`, `Le`, `MultipleOf`, `MinLen`, and `MaxLen` metadata also works, as does `pydantic.Strict`.
+Constraints must apply to the annotated type. Duplicate descriptions and unsupported metadata raise `DeclarationError`.
+Literal choices cannot carry additional value constraints in 0.1. Their containing list can carry list constraints.
+
+Function signatures own defaults. `Field` defaults, default factories, aliases, serializers, validators, schema overrides, and exclusion controls are rejected.
+This keeps validation, parameter names, and exported schemas aligned.
+
+Applications can pass exact marker classes through `metadata_types=(MyMarker,)`.
+The declaration retains these markers in `ToolParam.metadata` and removes them from the validation annotation.
+Markers are descriptive data only. They cannot implement Pydantic validators or change JSON Schema through this interface.
+
+## Validation and defaults
+
+`Tool.validate_arguments(object, include_hidden=False)` returns normalized values in a new dictionary.
+It raises `pydantic.ValidationError` for invalid input. `error.errors()` provides field locations, codes, messages, and input values.
+Applications own error presentation and any redaction of submitted values.
+
+Pydantic 2's default coercion rules apply. Numeric strings can become numbers. Accepted boolean strings can become booleans.
+Strings do not automatically accept numbers. `Field(strict=True)` disables coercion for its annotated type.
+This policy is identical through `validate_arguments()` and the generated argument model.
+
+Omission uses the declared default. Explicit null requires a nullable annotation.
+A nullable argument without a default is still required. Unknown arguments are forbidden.
+Defaults are validated even for hidden arguments. Validation supplies independent list values, so one call cannot mutate another call's validated defaults.
+
+Hidden arguments are absent from the default schema and rejected as external input.
+`include_hidden=True` creates the full contract for trusted application callers.
+The restricted result contains only visible arguments. The application owns how it supplies private values during execution.
+
+## Public inspection API
+
+- `Tool.params`: ordered `ToolParam` records with the validation annotation, default, description, scalar type, choices, repeated/nullable flags, and application metadata.
+- `ToolParam.required`: whether the signature has no default.
+- `Tool.description` and `Tool.summary`: full docstring and first line, or an empty string.
+- `Tool.argument_model(include_hidden=False, name=None, descriptions=None)`: a Pydantic model for that projection.
+- `Tool.json_schema(include_hidden=False)`: a fresh validation schema.
+- `annotation_with_description(fn, parameter, description)`: a description override that retains the original annotation for adapter signatures.
+
+Description overrides accept real parameter names only. They do not change validation.
+Treat generated model classes and parameter metadata as read-only.
+
+## Boundaries
+
+Importing `coloph_toolset` does not import Pydantic until annotation/schema work needs it.
+The package does not replace stdout or read environment files.
+It has no KB names, reference registry, credentials, database connections, workflow state, or agent framework dependency.
+
+The [Pydantic field contract](https://docs.pydantic.dev/latest/concepts/fields/) describes the underlying constraint and default behavior.

coloph_toolset-0.1.0/docs/roadmap.md

@@ -0,0 +1,19 @@
+# Extraction milestones
+
+The extraction plan tracks six sequential releases.
+
+1. Declarations, canonical argument validation, and the shipping-quote example.
+2. Catalogs, lazy trees, CLI generation, and a task CLI example.
+3. Invocation, typed context, results, sync/async execution, and a runtime example.
+4. An optional HTTP adapter and a standalone service example.
+5. An optional Pydantic AI adapter and a deterministic agent example.
+6. Hierarchical discovery, documentation gates, terminal controls, and a hierarchical agent example.
+
+Each milestone adds a project under `examples/` and preserves every previous project.
+CI runs all examples against the current package. Pins to obsolete releases do not replace current-version coverage.
+
+Version 0.1 does not promise CLI or HTTP parity in Coloph before those adapters migrate.
+Coloph retains reference resolution, authorization, workflow policy, resource management, and output behavior until their respective extraction milestones.
+
+The 0.x public API can change in a minor release. Release notes must describe required migrations.
+Patch releases preserve documented contracts. The package must remain useful at every milestone.

coloph_toolset-0.1.0/examples/01-tool-declarations/README.md

@@ -0,0 +1,25 @@
+# Shipping quote
+
+This standalone project uses only the public package and its Pydantic dependency.
+It exports a schema, normalizes valid arguments, calls a function, and displays structured validation errors.
+
+From this directory:
+
+```sh
+uv run shipping_quote.py
+```
+
+The project installs the public wheel. No Coloph source, database, credentials, or environment file is needed.
+The valid example returns a quote of 1,000 cents for two parcels.
+The rejected examples show a quantity constraint, a missing nullable argument, and an attempt to supply a hidden argument.
+
+To use a locally built current wheel:
+
+```sh
+uv venv .venv
+uv pip install --python .venv/bin/python ../../dist/coloph_toolset-0.1.0-py3-none-any.whl
+uv run --no-project --python .venv/bin/python shipping_quote.py
+```
+
+The repository's `scripts/smoke_wheel.py` installs the current wheel into a temporary environment and runs this project outside the checkout.
+Repository CI also runs this project's tests against the current library, so the release URL cannot hide a compatibility regression.

coloph_toolset-0.1.0/examples/01-tool-declarations/pyproject.toml

@@ -0,0 +1,8 @@
+[project]
+name = "toolset-shipping-quote-example"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["coloph-toolset"]
+
+[dependency-groups]
+dev = ["pytest>=8,<10"]

coloph_toolset-0.1.0/examples/01-tool-declarations/shipping_quote.py

@@ -0,0 +1,57 @@
+"""A standalone tool declaration with schema export and input validation."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated, Literal
+
+from pydantic import Field, ValidationError
+
+from coloph_toolset import tool, tool_for
+
+
+@tool(model_hidden_args=("account_discount",))
+def shipping_quote(
+    ctx,
+    quantity: Annotated[int, "Number of parcels", Field(gt=0, le=100)],
+    destination: Annotated[str | None, "Country code, or null for collection"],
+    service: Annotated[Literal["standard", "express"], "Delivery service"] = "standard",
+    insured: Annotated[bool, "Include insurance"] = False,
+    account_discount: Annotated[bool, "Private account discount"] = False,
+) -> dict[str, object]:
+    """Calculate a shipping quote without external services."""
+    unit_cost = 0 if destination is None else (1200 if service == "express" else 500)
+    total = quantity * unit_cost + (200 if insured else 0)
+    if account_discount:
+        total = total * 9 // 10
+    return {"amount_cents": total, "currency": "USD", "parcels": quantity}
+
+
+def main() -> None:
+    declaration = tool_for(shipping_quote)
+    arguments = declaration.validate_arguments({"quantity": "2", "destination": "AR"})
+    rejected = []
+    for value in (
+        {"quantity": 0, "destination": "AR"},
+        {"quantity": 2},
+        {"quantity": 2, "destination": None, "account_discount": True},
+    ):
+        try:
+            declaration.validate_arguments(value)
+        except ValidationError as error:
+            rejected.append(error.errors(include_url=False))
+    print(
+        json.dumps(
+            {
+                "schema": declaration.json_schema(),
+                "arguments": arguments,
+                "quote": shipping_quote(None, **arguments),
+                "rejected": rejected,
+            },
+            indent=2,
+        )
+    )
+
+
+if __name__ == "__main__":
+    main()

coloph_toolset-0.1.0/examples/01-tool-declarations/test_shipping_quote.py

@@ -0,0 +1,36 @@
+"""Executable example contract, included in the cumulative example test suite."""
+
+import importlib.util
+import json
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+
+from coloph_toolset import tool_for
+
+spec = importlib.util.spec_from_file_location("shipping_quote", Path(__file__).with_name("shipping_quote.py"))
+assert spec and spec.loader
+module = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(module)
+
+
+def test_quote_and_rejections(capsys):
+    module.main()
+    output = json.loads(capsys.readouterr().out)
+    assert output["quote"]["amount_cents"] == 1000
+    assert output["arguments"]["quantity"] == 2
+    assert [errors[0]["type"] for errors in output["rejected"]] == [
+        "greater_than",
+        "missing",
+        "extra_forbidden",
+    ]
+    assert "account_discount" not in output["schema"]["properties"]
+
+
+def test_collection_and_insurance():
+    declaration = tool_for(module.shipping_quote)
+    values = declaration.validate_arguments({"quantity": 1, "destination": None, "insured": True})
+    assert module.shipping_quote(None, **values)["amount_cents"] == 200
+    with pytest.raises(ValidationError):
+        declaration.validate_arguments({"quantity": 101, "destination": "AR"})

coloph_toolset-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "coloph-toolset"
+version = "0.1.0"
+description = "Declare Python tools once, export their schemas, and validate their arguments."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "golergka"}]
+dependencies = ["pydantic>=2.12,<3", "annotated-types>=0.7,<1"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/golergka/coloph-toolset"
+Issues = "https://github.com/golergka/coloph-toolset/issues"
+Changelog = "https://github.com/golergka/coloph-toolset/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = ["pytest>=8,<10", "ruff>=0.11,<1", "mypy>=1.15,<2", "build>=1.2,<2"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/coloph_toolset"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src/coloph_toolset"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "examples"]
+addopts = "-ra"

coloph_toolset-0.1.0/scripts/release.py

@@ -0,0 +1,33 @@
+"""Publish tested artifacts only when the tag matches package metadata."""
+
+import os
+import subprocess
+import tomllib
+from pathlib import Path
+
+root = Path(__file__).resolve().parents[1]
+version = tomllib.loads((root / "pyproject.toml").read_text())["project"]["version"]
+tag = os.environ["RELEASE_TAG"]
+if tag != f"v{version}":
+    raise SystemExit(f"Tag {tag!r} does not match package version {version!r}")
+artifacts = sorted((root / "dist").iterdir())
+if {file.name for file in artifacts} != {
+    f"coloph_toolset-{version}-py3-none-any.whl",
+    f"coloph_toolset-{version}.tar.gz",
+}:
+    raise SystemExit("The release must contain exactly the matching wheel and source archive")
+subprocess.run(
+    [
+        "gh",
+        "release",
+        "create",
+        tag,
+        *map(str, artifacts),
+        "--verify-tag",
+        "--title",
+        f"coloph-toolset {version}",
+        "--notes-file",
+        str(root / "CHANGELOG.md"),
+    ],
+    check=True,
+)