apheris-foundry-sdk 0.2.0__tar.gz

apheris_foundry_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+## v0.2.0 (2026-07-16)
+
+### Feat
+
+- add SDK PyPI publishing safeguards (#41) [50c9c](https://github.com//apheris/apheris-foundry-sdk/commit/50c9c693c1388d7e1df67ecfe3a493b488ed7470)
+- accept Path/FilePath/DirectoryPath and their list[] forms as input (#39) [da412](https://github.com//apheris/apheris-foundry-sdk/commit/da412350e7d23db54319effde7863c86bb9ff022)
+- **[EN-6143](https://apheris.atlassian.net/browse/EN-6143)**: add netflow compatibility skill and harness pack (#32) [d028e](https://github.com//apheris/apheris-foundry-sdk/commit/d028efa92f56152dc1096aaaa16cc6f97830f343)
+
+## v0.1.1 (2026-07-15)
+
+### Fix
+
+- raise pydantic floor to >=2.4.0 to clear regex-DoS advisory (#35) [e5280](https://github.com//apheris/apheris-foundry-sdk/commit/e528051b3b33a401392d1a8d994344050b5031ac)
+
+## v0.1.0 (2026-07-15)
+
+### Feat
+
+- --overwrite deletes and recreates the output directory (#31) [b1088](https://github.com//apheris/apheris-foundry-sdk/commit/b1088a3767fe7cf2d57f36bdc594d1087e97cbbc)
+- tiered input provenance (none/metadata/content) (#23) [9f463](https://github.com//apheris/apheris-foundry-sdk/commit/9f463359856608f2adcd272e761bda6a27475ed4)
+- error.json, cancellation, --dry-run, and --log-level (#22) [8c9b7](https://github.com//apheris/apheris-foundry-sdk/commit/8c9b77fbac51f057572fa904cd9f5e266d62a05a)
+- write config.json and result.json artifacts (#21) [eb1c1](https://github.com//apheris/apheris-foundry-sdk/commit/eb1c1985aa5b2522638d1f26736fbad1f4ce0573)
+- describe --json self-description (#20) [b6e0a](https://github.com//apheris/apheris-foundry-sdk/commit/b6e0a654ec883b02f81d279343210588d7bc621f)
+- --config flag merged into task parameters (#19) [7da3e](https://github.com//apheris/apheris-foundry-sdk/commit/7da3e28ac376d84eaa264c35a964b42b3ba7421f)
+- nested params as dotted flags, JSON flags for complex fields (#18) [711ca](https://github.com//apheris/apheris-foundry-sdk/commit/711ca1c91355b2ba4c9ef7510d4a61b149a84490)
+- built-in --input and --output directory flags (#17) [1c5d5](https://github.com//apheris/apheris-foundry-sdk/commit/1c5d55edabf835da6021b6ddc69ac43ce6b5631f)
+- typed task parameters from any pydantic model (#16) [55c86](https://github.com//apheris/apheris-foundry-sdk/commit/55c86c3083bce2fb89883642924c8a000837352b)
+- add base CLI prototype (#15) [fb1c4](https://github.com//apheris/apheris-foundry-sdk/commit/fb1c4df29e251a4a746ec418a6ad63c24223e0f8)
+- EN-6069 migrate apheris-foundry-setup skill (+ k8s orchestrator mapping fixes) (#8) [59d9f](https://github.com//apheris/apheris-foundry-sdk/commit/59d9f53d225ff3c19e2b9a5236778fff4cc1c90d)

apheris_foundry_sdk-0.2.0/LICENSE

@@ -0,0 +1,51 @@
+Apheris Foundry Software License
+Copyright © 2025-2026 apheris AI GmbH, Kolonnenstr. 8, 10827 Berlin, Germany ("Licensor" or "Apheris"). All rights reserved.
+Definitions:
+"Software" means the Apheris Foundry software made available by Licensor to Licensee, in whole or in part and in any form of delivery, including the Foundry modules and container (e.g. Docker) images, the Foundry command-line interface (CLI), Python packages and wheel (.whl) distributions, workflow definitions and configuration files, the Foundry Hub orchestration service, and any accompanying libraries, scripts, skills, and documentation, together with any updates, patches, and new versions provided by Licensor.
+"Commercial Agreement" means the order form, master subscription or services agreement, evaluation or design-partner agreement, memorandum of understanding, or other written agreement between Licensor and Licensee that governs Licensee's access to and use of the Software.
+"Component" means any separately delivered part of the Software, for example an individual module image, the CLI, or a wheel file.
+License Grant:
+Subject to Licensee's compliance with this License and the Commercial Agreement, Licensor grants Licensee a non-exclusive, non-transferable, and non-sublicensable right to install, run, and use the Software for Licensee's internal business purposes, solely to the extent, for the term, in the scope, and against the fees (if any) set out in the Commercial Agreement.
+Where the Commercial Agreement so provides, use may be granted free of charge, for example for evaluation, design-partner, or limited-time access. Free-of-charge use is not the default and applies only where expressly stated in writing by Licensor.
+If no Commercial Agreement is in place, Licensee's use is limited to internal evaluation of Software lawfully obtained from Licensor, on a non-production and revocable basis, until a Commercial Agreement is concluded or access is withdrawn.
+Restrictions:
+Except as expressly permitted in the Commercial Agreement, Licensee shall not:
+Redistribute, publish, sublicense, sell, rent, lease, or otherwise make the Software or any Component available to any third party, in whole or in part, with or without modification;
+Pledge or encumber the rights granted under this License, or make them subject to any rights of third parties;
+Reverse engineer, decompile, disassemble, or otherwise attempt to derive the source code, model weights, or underlying structure of the Software, except to the extent this restriction cannot be excluded under applicable mandatory law;
+Use the Software, its outputs, or any model weights to train, fine-tune, distil, or develop any model, product, or service that competes with Licensor's products or services, or attempt model extraction, model inversion, or membership-inference attacks against the Software or its models;
+Modify, adapt, translate, or create derivative works of the Software, other than configuration expressly contemplated by the Software or permitted in the Commercial Agreement;
+Remove, obscure, or alter any copyright, license, or other proprietary notice in or on the Software.
+Licensee must reproduce and retain all copyright and ownership notices in all permitted copies or substantial portions of the Software. Licensee acknowledges that breach of these restrictions may cause Licensor irreparable harm for which monetary damages would be inadequate, and that Licensor is entitled to seek injunctive or other equitable relief in addition to any other remedy.
+Notices and Delivery of this License:
+This License governs each Component whether it is delivered together with the Component, embedded within it, or referenced by it. Licensor may include this License, or a short notice referring to it, within each Component, for example as a LICENSE file inside a container image or wheel package, as CLI output, or as accompanying documentation. The absence of a License file next to a given Component does not waive or limit this License.
+Third-Party and Open-Source Components:
+The Software may include third-party or open-source components licensed under their own terms. Those terms are set out in the applicable NOTICE or third-party license files delivered with the Software and govern those components. Nothing in this License limits Licensee's rights, or extends Licensor's rights, under those third-party terms.
+Research and Non-Clinical Use:
+The Software and its outputs are provided for internal research and development only. They are not a medical device and are not intended for diagnosis, treatment, or any use that requires regulatory clearance or approval. Outputs are predictions that may be inaccurate or incomplete, and Licensee is solely responsible for independently validating them before relying on them. Licensee is responsible for controlling how its users, and any agents or automated tools it operates, interact with the Software and with Licensee's own data, including any sensitive sequences or other confidential inputs.
+Models, Weights, and Outputs:
+Rights in any machine-learning models, model weights, and outputs made available through or produced using the Software are governed by the Commercial Agreement. Except as expressly stated there, this License grants no rights in any models, weights, or outputs.
+Feedback:
+Any suggestions, ideas, or other feedback that Licensee provides regarding the Software belong exclusively to Licensor. Licensee assigns to Licensor all rights in such feedback to the extent assignable and, to the extent any right cannot be assigned, grants Licensor a perpetual, irrevocable, worldwide, royalty-free license to use it without restriction and without obligation to Licensee.
+Confidentiality:
+The Software, including its non-public components, structure, and performance characteristics, is confidential information of Licensor. Licensee shall protect it with at least reasonable care, shall not disclose it to third parties, and shall use it only as permitted under this License and the Commercial Agreement. This obligation does not apply to information that is or becomes public through no fault of Licensee, or that Licensee is required to disclose by law or court order, provided that Licensee gives Licensor reasonable prior notice where lawful.
+Compliance, Export Control, and Data Protection:
+Licensee shall comply with all applicable export control and sanctions laws and shall not export, re-export, or use the Software in violation of them. Licensee represents that any data it inputs into the Software has been lawfully obtained and that its use of such data, including any personal data under the EU General Data Protection Regulation and other applicable data protection law, complies with applicable law.
+No Transfer of Ownership:
+This License does not convey any ownership in the Software. The Software, and all intellectual property rights in it, remain the sole and exclusive property of Licensor and its licensors. All rights not expressly granted are reserved.
+Assignment:
+Licensor may assign or transfer this License, in whole or in part, including in connection with a merger, acquisition, financing, or sale of assets. Licensee may not assign or transfer this License or any rights under it, whether by operation of law, change of control, or otherwise, without Licensor's prior written consent. Any purported assignment in violation of this section is void.
+Term and Termination:
+This License is effective until terminated and, where use is tied to a Commercial Agreement, runs co-terminously with that agreement. During the term of an active Commercial Agreement, Licensor will not terminate this License for convenience. Either party may terminate for cause on 30 days' written notice if the other materially breaches this License or the Commercial Agreement and fails to cure the breach within that period. Where no Commercial Agreement is in place, or for free-of-charge or evaluation use, either party may terminate at any time and Licensor may withdraw access at any time. On termination, all rights granted to Licensee end immediately, and Licensee shall cease all use of the Software and delete or destroy all copies in its possession or control, except for copies retained in routine backups or as required by applicable law, which remain subject to this License.
+Disclaimer and Liability:
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. IN NO EVENT SHALL LICENSOR OR ITS AFFILIATES BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, EXCEPT IN CASE OF INTENT OR GROSS NEGLIGENCE OR IN CASE OF HARM TO LIFE, BODY, OR HEALTH.
+In addition, the Licensor is liable for breaches of cardinal obligations, that is, essential duties whose fulfilment enables proper performance of this License and on which Licensee may reasonably rely. In cases of ordinary negligence, such liability is limited to foreseeable, typical damages at the time of conclusion. Indirect or consequential damages are compensable only if foreseeable when using the Software as intended. Any monetary limitation or cap on liability is as set out in the Commercial Agreement; where use is free of charge and no Commercial Agreement applies, Licensor's aggregate liability is limited to the maximum extent permitted by applicable law. Mandatory statutory liability, for example under product liability law, remains unaffected.
+Survival:
+Termination does not affect any provision that by its nature should survive, including Restrictions, Research and Non-Clinical Use, Models, Weights, and Outputs, Feedback, Confidentiality, Compliance, Export Control, and Data Protection, No Transfer of Ownership, Assignment, Disclaimer and Liability, Precedence, and Governing Law.
+Precedence:
+If there is a conflict between this License and the Commercial Agreement, the Commercial Agreement prevails to the extent of the conflict.
+Severability:
+If a provision of this License should be held invalid, this shall not affect the validity of the remaining provisions.
+Governing Law:
+This License shall be governed by and construed in accordance with the laws of the Federal Republic of Germany, without regard to its conflict of law principles.
+For licensing inquiries, please contact support@apheris.com.

apheris_foundry_sdk-0.2.0/MANIFEST.in

@@ -0,0 +1,35 @@
+include CHANGELOG.md
+include LICENSE
+include README.md
+include pyproject.toml
+
+recursive-include docs *.md
+recursive-include src/apheris_foundry_sdk *.py
+recursive-include src/apheris_foundry_sdk py.typed
+
+prune .agents
+prune .codex
+prune .github
+prune customer-packs
+prune scripts
+prune skills
+prune tests
+prune coverage_html_report
+
+exclude .coverage
+exclude .coverage_threshold
+exclude .coveragerc
+exclude .cz.yaml
+exclude .editorconfig
+exclude .flake8
+exclude .gitignore
+exclude .pre-commit-config.yaml
+exclude .python-version
+exclude coverage.xml
+exclude pixi.lock
+exclude pixi.toml
+
+global-exclude *.py[cod]
+global-exclude __pycache__
+global-exclude scm_file_list.json
+global-exclude scm_version.json

apheris_foundry_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: apheris-foundry-sdk
+Version: 0.2.0
+Summary: Reference Python SDK for Apheris Foundry per-module CLIs.
+Author: Apheris
+License-Expression: LicenseRef-Apheris-Foundry-Software-License
+Project-URL: License, https://www.apheris.com/docs/hub/hub-license.html
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: pydantic<3,>=2.4.0
+Requires-Dist: pyyaml>=6
+Dynamic: license-file
+
+# Apheris Foundry SDK
+
+Reference Python SDK for building Apheris Foundry per-module CLIs.
+
+## Usage
+
+Declare a task — a plain function plus a pydantic config model — and foundry
+builds a typed CLI for it. See the [usage guide](docs/usage.md) to get started.
+
+## Development
+
+This project uses [pixi](https://pixi.sh) to manage the toolchain and environments.
+
+```bash
+pixi run install-dev   # install the git hooks (pre-commit + commit-msg)
+pixi run test          # run the test suite
+pixi run lint          # check formatting and lint with ruff
+pixi run fix           # auto-fix formatting and lint issues
+pixi run build         # build the wheel and sdist
+```
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/); the
+commit-msg hook enforces this via commitizen.
+
+## Project structure
+
+```text
+src/apheris_foundry_sdk/   # SDK package
+tests/         # test suite
+docs/          # usage guide
+```
+
+## License
+
+This package is licensed under the [Apheris Foundry Software License](https://www.apheris.com/docs/hub/hub-license.html). The full license text is also included in every published distribution as `LICENSE`.
+
+## Support
+
+Contact [support@apheris.com](mailto:support@apheris.com) for access and deployment assistance.

apheris_foundry_sdk-0.2.0/README.md

@@ -0,0 +1,39 @@
+# Apheris Foundry SDK
+
+Reference Python SDK for building Apheris Foundry per-module CLIs.
+
+## Usage
+
+Declare a task — a plain function plus a pydantic config model — and foundry
+builds a typed CLI for it. See the [usage guide](docs/usage.md) to get started.
+
+## Development
+
+This project uses [pixi](https://pixi.sh) to manage the toolchain and environments.
+
+```bash
+pixi run install-dev   # install the git hooks (pre-commit + commit-msg)
+pixi run test          # run the test suite
+pixi run lint          # check formatting and lint with ruff
+pixi run fix           # auto-fix formatting and lint issues
+pixi run build         # build the wheel and sdist
+```
+
+Commits follow [Conventional Commits](https://www.conventionalcommits.org/); the
+commit-msg hook enforces this via commitizen.
+
+## Project structure
+
+```text
+src/apheris_foundry_sdk/   # SDK package
+tests/         # test suite
+docs/          # usage guide
+```
+
+## License
+
+This package is licensed under the [Apheris Foundry Software License](https://www.apheris.com/docs/hub/hub-license.html). The full license text is also included in every published distribution as `LICENSE`.
+
+## Support
+
+Contact [support@apheris.com](mailto:support@apheris.com) for access and deployment assistance.

apheris_foundry_sdk-0.2.0/docs/usage.md

@@ -0,0 +1,114 @@
+# Usage guide
+
+Build a per-module CLI by declaring tasks. A task is a plain function plus a
+pydantic config model — no foundry base class.
+
+## Define a task
+
+```python
+from pydantic import BaseModel, DirectoryPath, Field
+from apheris_foundry_sdk import run_foundry_cli, task
+
+
+class PredictConfig(BaseModel):
+    model: str = Field("default", description="Model identifier")
+    precision: str = "fp32"
+
+
+class PredictResult(BaseModel):
+    model: str
+
+
+@task("predict", description="Run a prediction")
+def predict(input: list[DirectoryPath], output: DirectoryPath, config: PredictConfig) -> PredictResult:
+    return PredictResult(model=config.model)
+
+
+def main() -> int:
+    return run_foundry_cli(module_name="apheris-example", module_version="0.1.0")
+```
+
+Every task takes three arguments and returns a model — the signature is checked
+when the task is declared:
+
+- `input` — annotate it with the shape you want; `--input` follows:
+
+  | Annotation | `--input` | task receives |
+  |------------|-----------|---------------|
+  | `DirectoryPath` | one directory | a `Path` |
+  | `FilePath` | one file | a `Path` |
+  | `Path` | one file or directory | a `Path` |
+  | `list[DirectoryPath]` | repeatable directories | a `list[Path]` |
+  | `list[FilePath]` | repeatable files | a `list[Path]` |
+  | `list[Path]` | repeatable files or directories | a `list[Path]` |
+
+  The kind (`FilePath`/`DirectoryPath`/`Path`) maps to what `--input` accepts;
+  the `list[...]` form makes it repeatable. Anything else (a union, a `tuple`)
+  is rejected at declaration. click validates each path exists and is the right
+  kind — a file given to a directory-only task (or vice versa) is a precondition
+  error (exit 4). A single-input task rejects a repeated `--input` as a usage
+  error, rather than silently keeping the last.
+- `output: DirectoryPath` — the `--output` directory (foundry creates it).
+- `config: <BaseModel>` — your config model; each field becomes a flag.
+- returns a pydantic `BaseModel` (written to `result.json`), or `None` for a
+  side-effect-only task.
+
+## Run it
+
+```console
+$ apheris-example predict --input ./in --output ./run --model demo
+```
+
+- Config fields become flags: `--model`, `--precision`, etc. Nested models use
+  dotted flags (`--optimizer.lr`); complex fields take inline JSON.
+- `--config` sets values in bulk from a JSON/YAML file or inline JSON; explicit flags win.
+- `--overwrite` deletes and recreates a non-empty output directory (only one this tool
+  created), so the artifacts reflect the latest run alone.
+- `--dry-run` validates and writes `config.json`, without running the task.
+- `--log-level debug` prints a stack trace on failure.
+
+## Inspect a task
+
+```console
+$ apheris-example describe            # module + its tasks
+$ apheris-example predict describe    # one task; add --json for machine output
+```
+
+`describe` needs no `--input`/`--output` — only running the task does.
+
+## Artifacts
+
+Each run writes to the output directory:
+
+- `config.json` — the resolved config.
+- `result.json` — the returned model (dumped to JSON) plus a provenance block.
+- `error.json` — written instead when the task fails.
+
+## Input provenance
+
+`result.json` records where each input came from. How much is recorded is a per-task
+choice, declared at `@task` — hashing every byte on every run is costly for large
+input roots, so it's opt-in:
+
+```python
+@task("predict", input_provenance="metadata")
+def predict(...): ...
+```
+
+| Tier | Records | Cost |
+|------|---------|------|
+| `none` (default) | path only | no traversal |
+| `metadata` | digest over each file's path/size/mtime | stat only |
+| `content` | digest over each file's bytes | reads everything |
+
+## Exit codes
+
+| Code | Category | Meaning |
+|------|----------|---------|
+| 0 | success | ran successfully |
+| 1 | internal | unexpected/uncaught error |
+| 2 | usage | bad invocation or config |
+| 3 | input-data | invalid input data |
+| 4 | precondition | a required resource is missing |
+| 5 | output | could not write output |
+| 130 | cancelled | interrupted (SIGINT/SIGTERM) |

apheris_foundry_sdk-0.2.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=80", "wheel", "setuptools_scm[toml]>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apheris-foundry-sdk"
+description = "Reference Python SDK for Apheris Foundry per-module CLIs."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Apheris" }]
+license = "LicenseRef-Apheris-Foundry-Software-License"
+license-files = ["LICENSE"]
+dependencies = ["click>=8.1", "pydantic>=2.4.0,<3", "pyyaml>=6"]
+classifiers = [
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dynamic = ["version"]
+
+[project.urls]
+License = "https://www.apheris.com/docs/hub/hub-license.html"
+
+[tool.setuptools_scm]
+
+[tool.setuptools.package-data]
+apheris_foundry_sdk = ["py.typed"]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["apheris_foundry_sdk*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "A001",
+    "A002",
+    "ANN401",
+    "COM812",
+    "S311",
+    "PLR0912",
+    "PLR0913",
+    "PLR0915",
+    "C901",
+    "D",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "S101", # Allow asserts in tests
+    "FBT001", # Boolean traps are not relevant here
+    "ANN", # Test methods and local fixtures don't need full annotations
+    "ARG001", # Test task fixtures keep SDK-required signatures
+    "PLR2004", # Asserting against literal exit codes/values is the point in tests
+]
+"customer-packs/foundry-module-local-harness/tasks/example-module-mock/run.py" = [
+    "INP001", # Standalone container entrypoint, not a package module
+]

apheris_foundry_sdk-0.2.0/setup.cfg

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

apheris_foundry_sdk-0.2.0/src/apheris_foundry_sdk/__init__.py

@@ -0,0 +1,43 @@
+"""Apheris Foundry SDK: reference toolkit for per-module CLIs."""
+
+from __future__ import annotations
+
+from apheris_foundry_sdk.cli import (
+    FoundryGroup,
+    build_click_app,
+    build_task_command,
+    run_foundry_cli,
+)
+from apheris_foundry_sdk.constants import ModuleInfo
+from apheris_foundry_sdk.errors import (
+    CancelledError,
+    FoundryError,
+    InputDataError,
+    InternalError,
+    OutputError,
+    PreconditionError,
+    UsageError,
+)
+from apheris_foundry_sdk.registry import Registry, default_registry, tasks
+from apheris_foundry_sdk.task import task
+from apheris_foundry_sdk.version import __version__
+
+__all__ = [
+    "CancelledError",
+    "FoundryError",
+    "FoundryGroup",
+    "InputDataError",
+    "InternalError",
+    "ModuleInfo",
+    "OutputError",
+    "PreconditionError",
+    "Registry",
+    "UsageError",
+    "__version__",
+    "build_click_app",
+    "build_task_command",
+    "default_registry",
+    "run_foundry_cli",
+    "task",
+    "tasks",
+]

apheris_foundry_sdk-0.2.0/src/apheris_foundry_sdk/cli/__init__.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from .app import build_click_app, build_task_command
+from .contract import FoundryGroup
+from .entrypoint import run_foundry_cli
+
+__all__ = [
+    "FoundryGroup",
+    "build_click_app",
+    "build_task_command",
+    "run_foundry_cli",
+]

apheris_foundry_sdk-0.2.0/src/apheris_foundry_sdk/cli/app.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import click
+
+from apheris_foundry_sdk.constants import ModuleInfo
+from apheris_foundry_sdk.describe import describe_module, describe_task
+
+from .contract import FoundryGroup
+from .format import format_module, format_task
+from .runner import run_task
+from .types import JSON, ExplicitBool, build_path, click_type_for
+
+if TYPE_CHECKING:
+    from apheris_foundry_sdk.registry import Registry, TaskSpec
+
+
+def build_click_app(module: ModuleInfo, registry: Registry) -> click.Group:
+    """Build the branded ``apheris-<module>`` command group.
+
+    Wires up the group-level ``--version``/``--help``, a module-level ``describe``,
+    and each task's pre-built sub-command (each of which also has ``describe``). The
+    module is stored on the click context so ``describe`` can read its name.
+    """
+
+    @click.group(cls=FoundryGroup, name=module.name, context_settings={"help_option_names": ["--help"]})
+    @click.version_option(
+        version=f"{module.version} cli-contract {module.cli_contract_version}",
+        prog_name=module.name,
+        message="%(prog)s %(version)s",
+    )
+    @click.pass_context
+    def app(ctx: click.Context) -> None:
+        ctx.obj = module
+
+    @app.command(name="describe")
+    @click.option("--json", "as_json", is_flag=True, help="Emit the machine-readable JSON description.")
+    def module_describe(as_json: bool) -> None:  # noqa: FBT001 - Click injects flags positionally.
+        payload = describe_module(registry, module.name, module.version, module.cli_contract_version)
+        click.echo(json.dumps(payload, indent=2, sort_keys=True) if as_json else format_module(payload))
+
+    for spec in registry.tasks().values():
+        app.add_command(spec.command)
+    return app
+
+
+def build_task_command(spec: TaskSpec) -> FoundryGroup:
+    """Build the task's command (a :class:`FoundryGroup`).
+
+    Built once at registration and stored on the spec. It is a group (not a bare
+    command) so it can carry its own ``describe`` sub-command while still running
+    the task itself via ``invoke_without_command``. As a :class:`FoundryGroup` it
+    carries the error contract whether run standalone or under the module group.
+    """
+    params: list[click.Parameter] = [*_foundry_options(spec), *_param_options(spec)]
+
+    @click.pass_context
+    def callback(ctx: click.Context, **kwargs: Any) -> int | None:
+        if ctx.invoked_subcommand is not None:
+            return None
+        return run_task(spec, module_from_context(ctx, spec), kwargs)
+
+    group = FoundryGroup(
+        spec.name,
+        params=params,
+        callback=callback,
+        help=spec.description,
+        invoke_without_command=True,
+        context_settings={"help_option_names": ["--help"]},
+    )
+
+    @group.command(name="describe")
+    @click.option("--json", "as_json", is_flag=True, help="Emit the machine-readable JSON description.")
+    @click.pass_context
+    def task_describe(ctx: click.Context, as_json: bool) -> None:  # noqa: FBT001 - Click injects flags positionally.
+        payload = describe_task(spec, module_from_context(ctx, spec).name)
+        click.echo(json.dumps(payload, indent=2, sort_keys=True) if as_json else format_task(payload))
+
+    return group
+
+
+def module_from_context(ctx: click.Context, spec: TaskSpec) -> ModuleInfo:
+    """The module a task runs under, taken from the click context.
+
+    ``build_click_app`` stores the real :class:`ModuleInfo` on the context. A task
+    command run on its own (no module group above it) has none, so fall back to a
+    module named after the task itself.
+    """
+    root = ctx.find_root()
+    if isinstance(root.obj, ModuleInfo):
+        return root.obj
+    return ModuleInfo(name=spec.name, version="0.0.0")
+
+
+def _at_most_once(_ctx: click.Context, _param: click.Parameter, values: tuple[Any, ...]) -> Any:
+    """Unwrap a repeatable flag to a single value, rejecting more than one."""
+    if len(values) > 1:
+        msg = "--input may only be given once for this task"
+        raise click.UsageError(msg)
+    return values[0] if values else None
+
+
+def _foundry_options(spec: TaskSpec) -> list[click.Parameter]:
+    """The built-in flags: ``--input`` (file or directory, repeatable for a list), ``--output``, ``--config``."""
+    noun = spec.input.noun
+    return [
+        # --input/--output are required, but not via click's required=True: that fires
+        # during parsing even for `<task> describe`, which needs neither. The runner
+        # enforces presence only when the task actually runs.
+        click.Option(
+            ["--input", "input"],
+            type=build_path(is_file=spec.input.is_file, is_dir=spec.input.is_dir, must_exist=True),
+            multiple=True,
+            callback=_at_most_once if not spec.input.multiple else None,
+            default=(),
+            help=f"Input {noun} (repeatable)." if spec.input.multiple else f"Input {noun}.",
+        ),
+        click.Option(
+            ["--output", "output"],
+            # Output dir need not exist (the runner creates it); must be writable.
+            type=build_path(is_file=False, is_dir=True, must_exist=False, writable=True),
+            default=None,
+            help="Output directory (required).",
+        ),
+        click.Option(
+            ["--overwrite"],
+            type=ExplicitBool(),
+            default=None,
+            required=False,
+            help="Delete and recreate a non-empty output directory (only if this tool created it).",
+        ),
+        click.Option(
+            ["--dry-run", "dry_run"],
+            type=ExplicitBool(),
+            default=None,
+            required=False,
+            help="Validate inputs and config and write config.json, without running the task.",
+        ),
+        click.Option(
+            ["--log-level", "log_level"],
+            type=click.Choice(["info", "debug"]),
+            default="info",
+            required=False,
+            help="Log level; 'debug' prints a stack trace on failure ('info' is the default).",
+        ),
+        click.Option(
+            ["--config"],
+            type=str,
+            default=None,
+            required=False,
+            help="Parameter values as inline JSON or a path to a JSON file; flags override config.",
+        ),
+    ]
+
+
+def _param_options(spec: TaskSpec) -> list[click.Parameter]:
+    """One flag per config field, from the params introspected at registration."""
+    options: list[click.Parameter] = []
+    for param in spec.params.values():
+        # Scalar leaves get a typed flag (repeatable for a list); complex-but-JSON-able
+        # leaves (dict, list of models, unions) get a single inline-JSON flag.
+        multiple = param.scalar and param.repeatable
+        options.append(
+            click.Option(
+                [param.flag, param.dest],
+                type=click_type_for(param.element) if param.scalar else JSON(),
+                multiple=multiple,
+                default=() if multiple else None,
+                required=False,
+                help=param.description or ("" if param.scalar else "Inline JSON value."),
+            ),
+        )
+    return options