tpcp 2.1.2__tar.gz → 2.2.0__tar.gz

{tpcp-2.1.2 → tpcp-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: tpcp
-Version: 2.1.2
+Version: 2.2.0
 Summary: Pipeline and Dataset helpers for complex algorithm evaluation.
 Author: Arne Küderle, Robert Richer, Raul C. Sîmpetru, Björn Eskofier
 Author-email: Arne Küderle <arne.kuederle@fau.de>, Robert Richer <robert.richer@fau.de>, Raul C. Sîmpetru <raul.simpetru@fau.de>, Björn Eskofier <bjoern.eskofier@fau.de>
@@ -29,7 +29,6 @@ Description-Content-Type: text/markdown
 [![Documentation Status](https://readthedocs.org/projects/tpcp/badge/?version=latest)](https://tpcp.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/mad-lab-fau/tpcp/branch/main/graph/badge.svg?token=ZNVT5LNYHO)](https://codecov.io/gh/mad-lab-fau/tpcp)
 [![Test and Lint](https://github.com/mad-lab-fau/tpcp/actions/workflows/test-and-lint.yml/badge.svg?branch=main)](https://github.com/mad-lab-fau/tpcp/actions/workflows/test-and-lint.yml)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/tpcp)
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.04953/status.svg)](https://doi.org/10.21105/joss.04953)
 
@@ -47,6 +46,11 @@ Or add it to your project with [uv](https://docs.astral.sh/uv/):
 uv add tpcp
 ```
 
+If you want to install the bundled tpcp agent skills into the current project's `.agent` folder, run:
+```bash
+tpcp install-skills
+```
+
 ## Why?
 
 Evaluating Algorithms - in particular when they contain machine learning - is hard.

{tpcp-2.1.2 → tpcp-2.2.0}/README.md

@@ -4,7 +4,6 @@
 [![Documentation Status](https://readthedocs.org/projects/tpcp/badge/?version=latest)](https://tpcp.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/mad-lab-fau/tpcp/branch/main/graph/badge.svg?token=ZNVT5LNYHO)](https://codecov.io/gh/mad-lab-fau/tpcp)
 [![Test and Lint](https://github.com/mad-lab-fau/tpcp/actions/workflows/test-and-lint.yml/badge.svg?branch=main)](https://github.com/mad-lab-fau/tpcp/actions/workflows/test-and-lint.yml)
-[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 ![PyPI - Downloads](https://img.shields.io/pypi/dm/tpcp)
 [![DOI](https://joss.theoj.org/papers/10.21105/joss.04953/status.svg)](https://doi.org/10.21105/joss.04953)
 
@@ -22,6 +21,11 @@ Or add it to your project with [uv](https://docs.astral.sh/uv/):
 uv add tpcp
 ```
 
+If you want to install the bundled tpcp agent skills into the current project's `.agent` folder, run:
+```bash
+tpcp install-skills
+```
+
 ## Why?
 
 Evaluating Algorithms - in particular when they contain machine learning - is hard.

{tpcp-2.1.2 → tpcp-2.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tpcp"
-version = "2.1.2"
+version = "2.2.0"
 description = "Pipeline and Dataset helpers for complex algorithm evaluation."
 authors = [
     { name = "Arne Küderle", email = "arne.kuederle@fau.de" },
@@ -29,6 +29,9 @@ attrs = ["attrs>=22.1.0"]
 Homepage = "https://github.com/mad-lab-fau/tpcp"
 Repository = "https://github.com/mad-lab-fau/tpcp"
 
+[project.scripts]
+tpcp = "tpcp._cli:main"
+
 [project.entry-points.pytest11]
 tpcp_snapshots = "tpcp.testing._regression_utils"
 
@@ -53,6 +56,9 @@ dev = [
 [tool.uv]
 default-groups = "all"
 
+[tool.uv.build-backend]
+data = { data = "skills" }
+
 [tool.uv.sources]
 torch = { index = "torch_cpu" }
 

tpcp-2.2.0/skills/tpcp/tpcp-basics/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: tpcp-basics
+description: Use when implementing or reviewing core tpcp classes, especially Algorithms and Pipelines, parameter definitions, action methods, result attributes, cloning, and nested parameter handling.
+---
+
+# tpcp Basics
+
+Read `../tpcp-builder/SKILL.md` first for the global guardrails.
+Also load `../tpcp-datasets/SKILL.md` for custom datasets and `../tpcp-optimization/SKILL.md` for `self_optimize`.
+
+## Build Pattern
+
+- Subclass `Algorithm`, `Pipeline`, or `OptimizablePipeline`.
+- Declare any useful class-level parameter annotations.
+- In `__init__`, assign each arg directly to `self`.
+- Algorithms should accept simple/raw inputs, not whole dataset objects.
+- Action methods compute results, store them on `*_` attrs, and return `self`.
+- Pipelines consume one dataset datapoint/group, not an entire dataset split.
+
+## Parameters
+
+- In tpcp, all init args are parameters.
+- If a value should be tunable/trainable/searchable, expose it in `__init__`.
+- Use `set_params(...)` for programmatic updates, including nested updates like `algo__threshold=...`.
+- Nested parameter annotations belong on the current class, e.g. `algorithm__threshold: OptimizableParameter[float]`.
+
+## Action Methods
+
+- Custom algorithms should set `_action_methods` to their action name(s), e.g. `"detect"`.
+- Pipelines already use `run`/`safe_run`.
+- Prefer `@make_action_safe`.
+- `safe_run()` checks:
+  - returns `self`
+  - writes at least one `*_` result
+  - does not modify parameters
+
+## Cloning
+
+- Clone before each per-datapoint execution of a nested algorithm.
+- Clone before mutating a nested algorithm/object inside `run` or `self_optimize`.
+- `clone()` copies parameters but drops results and other non-parameter attrs.
+- tpcp clones nested tpcp objects recursively and deep-copies other objects.
+- Unlike `sklearn.clone`, tpcp keeps fitted sklearn estimator state because trained models are treated as parameters.
+
+## Mutable Defaults
+
+- Wrap defaults like `list`, `dict`, `np.ndarray`, `pd.DataFrame`, tpcp objects, sklearn estimators, or custom class instances in `cf(...)`.
+- For dataclasses/attrs, use their own factories instead of `cf(...)`.
+
+## Common Mistakes
+
+- Doing parameter validation or derived-parameter setup in `__init__`.
+- Giving a parameter a trailing `_`; that suffix is reserved for results.
+- Forgetting to clone a nested algorithm before calling it.
+- Running one algorithm instance repeatedly and expecting older results to remain.
+- Storing learned templates/models on ad-hoc attrs instead of init parameters.
+
+## Minimal Pattern
+
+```python
+class MyPipe(Pipeline[MyDataset]):
+    algo: Parameter[MyAlgo]
+    output_: pd.DataFrame
+
+    def __init__(self, algo: MyAlgo = cf(MyAlgo())):
+        self.algo = algo
+
+    def run(self, datapoint: MyDataset):
+        algo = self.algo.clone()
+        algo = algo.detect(datapoint.signal, datapoint.sampling_rate_hz)
+        self.output_ = algo.events_
+        return self
+```
+
+## Source of Truth
+
+- `https://tpcp.readthedocs.io/en/latest/guides/general_concepts.html`
+- `https://tpcp.readthedocs.io/en/latest/guides/algorithms_pipelines_datasets.html`
+- `https://tpcp.readthedocs.io/en/latest/auto_examples/algorithms/_01_algorithms_qrs_detection.html`
+- API docs for `Algorithm`, `Pipeline`, `make_action_safe`, and `clone`

tpcp-2.2.0/skills/tpcp/tpcp-builder/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: tpcp-builder
+description: Use when building, reviewing, or refactoring code that subclasses tpcp Dataset, Algorithm, Pipeline, or uses tpcp optimization/validation. Gives the global rules, main pitfalls, and points to focused tpcp skills for basics, datasets, and optimization.
+---
+
+# tpcp Builder
+
+Read this first, then load the focused sibling skill(s) you need:
+
+- Basics: `../tpcp-basics/SKILL.md`
+- Datasets: `../tpcp-datasets/SKILL.md`
+- Optimization: `../tpcp-optimization/SKILL.md`
+
+## Mental Model
+
+- `Dataset`: index + lazy access to actual data.
+- `Algorithm`: reusable step with one or more action methods.
+- `Pipeline`: glue code that runs on exactly one dataset datapoint/group.
+- Optimization in tpcp means "data-driven changes to init parameters", including model training.
+
+## Non-Negotiable Rules
+
+- Every `__init__` argument must be stored unchanged on `self` under the same name.
+- Do not validate, coerce, derive, or mutate parameters in `__init__`; do that in `run`/action methods.
+- Do not use `*args` in tpcp object `__init__`.
+- Parameter names must not contain `__` or end with `_`.
+- Any mutable default or nested object default must use `cf(...)` or a dataclass/attrs factory.
+- Results live on attributes ending with `_`.
+- Action methods and `self_optimize` must return `self` (or `(self, info)` for `self_optimize_with_info`).
+- Algorithms should take the simplest raw inputs they need; pipelines are the place that consume dataset datapoints.
+- `run`/action methods must not modify parameters.
+- Clone nested algorithms/objects before running or mutating them.
+- Never optimize on test data.
+- Any value that training/search changes must be an exposed init parameter.
+
+## Highest-Risk Pitfalls
+
+- Shared mutable defaults create silent cross-instance state and can cause train-test leakage.
+- Reusing one nested algorithm instance across datapoints overwrites results and leaks fitted state.
+- Building a non-deterministic dataset index breaks splits, caching, and reproducibility.
+- Passing a multi-row/multi-group dataset into `Pipeline.run` violates the intended interface.
+- Storing learned state outside init parameters makes `clone()` drop it and breaks optimization semantics.
+- Marking `PureParameter` incorrectly can invalidate optimization shortcuts; default to plain `Parameter` unless sure.
+
+## Safe Defaults
+
+- Prefer `pipeline.safe_run(datapoint)` over `pipeline.run(datapoint)`.
+- Prefer `@make_action_safe` on custom action methods.
+- Prefer `@make_optimize_safe` and `Optimize(...)` for `self_optimize` pipelines.
+- Prefer `GridSearch`/`GridSearchCV`/`OptunaSearch` for brute-force or black-box search.
+
+## Quick Triage
+
+If behavior is strange, check these first:
+
+1. Mutable default or shared nested object?
+2. Missing `clone()` before nested `run`/`detect`/`self_optimize`?
+3. Dataset `create_index()` deterministic and sorted?
+4. `run` touching parameters instead of only writing `*_` results?
+5. `self_optimize` changing non-optimizable params or non-parameter attrs?
+
+## Source of Truth
+
+- Concepts: `https://tpcp.readthedocs.io/en/latest/guides/general_concepts.html`
+- Dataset/algorithm/pipeline model: `https://tpcp.readthedocs.io/en/latest/guides/algorithms_pipelines_datasets.html`
+- Evaluation and leakage rules: `https://tpcp.readthedocs.io/en/latest/guides/algorithm_evaluation.html`
+- Optimization rules: `https://tpcp.readthedocs.io/en/latest/guides/optimization.html`

tpcp-2.2.0/skills/tpcp/tpcp-datasets/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: tpcp-datasets
+description: Use when implementing or reviewing tpcp Dataset classes, dataset indexes, grouping, subsetting, data accessors, and split/group label behavior for validation workflows.
+---
+
+# tpcp Datasets
+
+Read `../tpcp-builder/SKILL.md` first for global guardrails.
+Also load `../tpcp-basics/SKILL.md` when the dataset feeds a custom pipeline.
+
+## Required Shape
+
+- Subclass `Dataset[...]`.
+- `__init__` must include `groupby_cols=None, subset_index=None` at the end of the signature and forward both to `super().__init__(...)`.
+- Implement `create_index()` to return the full metadata index as a `pd.DataFrame`.
+- Keep actual file/data loading out of `create_index()`; load lazily in properties/methods.
+
+## Index Rules
+
+- `create_index()` must be deterministic. tpcp calls it twice and will error if outputs differ.
+- Sort the final index explicitly; do not rely on filesystem order or `set` iteration.
+- Index columns should be valid Python identifiers. Invalid names break ergonomics around `get_subset`, `group_label`, and `group_labels`.
+- If you use a typed named-tuple group label generic, its field names and order must match index columns exactly.
+
+## Data Accessors
+
+- Properties that expose actual data should usually require a single row via `assert_is_single(...)`.
+- Properties that expose group-level data should require a single current group via `assert_is_single_group(...)`.
+- Think carefully about what counts as a datapoint in your project before designing accessors.
+
+## Grouping and Iteration
+
+- Ungrouped dataset length = row count.
+- Grouped dataset length = unique group count.
+- Grouping changes what "one datapoint" means for iteration and splitting.
+- `group_labels` follow current grouping; `index_as_tuples()` always reflects raw rows.
+
+## Subsetting and Splits
+
+- `get_subset(...)` accepts exactly one selector mode at a time.
+- Use `groupby(...)` when train/test splitting should happen on a higher level than raw rows.
+- Use `create_string_group_labels(...)` for `GroupKFold` and similar sklearn splitters.
+- If the dataset is already grouped, `create_string_group_labels(...)` columns must be a subset of `groupby_cols`.
+
+## Common Mistakes
+
+- Non-deterministic index creation.
+- Loading full signals/dataframes in `create_index()`.
+- Forgetting `groupby_cols`/`subset_index` in custom dataset init.
+- Accessing per-recording data from a subset that still contains multiple rows/groups.
+- Splitting raw rows when the real independence unit is participant/session/day.
+
+## Minimal Pattern
+
+```python
+class MyDataset(Dataset[MyGroupLabel]):
+    def __init__(self, root: Path, groupby_cols=None, subset_index=None):
+        self.root = root
+        super().__init__(groupby_cols=groupby_cols, subset_index=subset_index)
+
+    def create_index(self) -> pd.DataFrame:
+        return build_index(self.root).sort_values(["participant", "recording"]).reset_index(drop=True)
+
+    @property
+    def signal(self) -> pd.DataFrame:
+        self.assert_is_single(None, "signal")
+        return load_signal(...)
+```
+
+## Source of Truth
+
+- `https://tpcp.readthedocs.io/en/latest/auto_examples/datasets/_01_datasets_basics.html`
+- `https://tpcp.readthedocs.io/en/latest/guides/algorithms_pipelines_datasets.html`
+- API docs for `Dataset`

tpcp-2.2.0/skills/tpcp/tpcp-multiprocessing/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: tpcp-multiprocessing
+description: Use when working on tpcp code that uses n_jobs, joblib parallelism, tpcp.parallel, caching in parallel workers, or when debugging multiprocessing, serialization, or global state issues in tpcp.
+---
+
+# tpcp Multiprocessing
+
+Read the official `Multiprocessing Caveats` guide first:
+`https://tpcp.readthedocs.io/en/latest/guides/multiprocessing_caveats.html`
+
+## Use this skill when
+
+- `validate`, `cross_validate`, `Scorer`, or an optimizer uses `n_jobs`
+- global config seems missing in workers
+- runtime monkey-patching/decorators/caches behave differently in parallel
+- joblib raises pickle or `__main__`-related errors
+- heavy imports make parallel runs unexpectedly slow
+
+## Main Caveats
+
+- Worker processes do not automatically inherit runtime global state changes from the parent process.
+- Joblib `loky` workers are reused, so worker-side global mutations can leak into later jobs.
+- Serialization is often the real failure point, not the parallel API itself.
+- Objects defined in `__main__`, lambdas, nested classes/functions, and runtime-replaced globals are high risk.
+- Heavy optional imports can dominate worker startup cost.
+
+## tpcp-Specific Guidance
+
+- For global state restoration, use `tpcp.parallel.delayed` together with `register_global_parallel_callback(...)`.
+- Assume runtime-applied decorators or caches are not visible in workers unless explicitly restored there.
+- If tests require a clean worker pool, shut down the reusable loky executor explicitly.
+- If debugging cost outweighs the speedup, fall back to `n_jobs=1`.
+
+## Fast Triage
+
+1. Missing config only in workers: global-state problem, use `tpcp.parallel`.
+2. Error mentions `__main__`: move code to an importable module.
+3. Works once, fails later: suspect process-pool reuse and leaked worker state.
+4. Parallel is slower than serial: inspect import cost and serialization overhead.
+
+## Source of Truth
+
+- `https://tpcp.readthedocs.io/en/latest/guides/multiprocessing_caveats.html`
+- API docs for `tpcp.parallel`
+- GitHub issue `#119`

tpcp-2.2.0/skills/tpcp/tpcp-optimization/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: tpcp-optimization
+description: Use when implementing or reviewing tpcp self_optimize logic, parameter annotations, Optimize/GridSearch/GridSearchCV usage, and validation workflows that must avoid train-test leakage.
+---
+
+# tpcp Optimization
+
+Read `../tpcp-builder/SKILL.md` first for the global guardrails.
+Also load `../tpcp-basics/SKILL.md` for cloning/parameter rules and `../tpcp-datasets/SKILL.md` for split semantics.
+
+## Pick the Right Tool
+
+- Use `self_optimize` only for algorithm-specific training logic.
+- Do not re-implement brute-force search inside `self_optimize`.
+- Use `Optimize(pipeline)` for pipelines that implement `self_optimize`.
+- Use `GridSearch` for brute-force search without inner CV.
+- Use `GridSearchCV` when hyperparameter search itself needs CV.
+- Use `DummyOptimize` if you need a non-optimizable baseline on the same CV folds.
+
+## Parameter Semantics
+
+- `OptimizableParameter`: changed by `self_optimize`.
+- `HyperParameter`: changes how `self_optimize` behaves but is not changed by it.
+- `PureParameter`: does not affect `self_optimize`; only use when you are certain.
+- If unsure, prefer plain `Parameter` over `PureParameter`.
+
+## Hard Rules for `self_optimize`
+
+- Return `self`, or `(self, info)` from `self_optimize_with_info`.
+- Modify only parameters marked as optimizable on the current class.
+- Do not store learned state on non-parameter attrs.
+- Any learned model/template/weights must survive `clone()`, so they must be represented as parameters.
+- Clone nested algorithms before training/mutating them.
+- Prefer `@make_optimize_safe`; `Optimize(...)` also applies equivalent checks.
+
+## Evaluation Rules
+
+- Never search/tune/train on the final test data.
+- Outer evaluation measures the whole training procedure, not one already-trained instance.
+- `cross_validate(...)` expects an optimizer object, not a bare pipeline.
+- For grouped or stratified splits, create explicit group/label arrays or use `DatasetSplitter`.
+- In custom scorers, call `pipeline.safe_run(datapoint)`.
+
+## Common Mistakes
+
+- Putting black-box parameter search into `self_optimize` instead of `GridSearch`/`OptunaSearch`.
+- Forgetting to annotate optimizable params, causing safety checks to fail.
+- Changing non-optimizable params during `self_optimize`.
+- Marking a parameter as `PureParameter` even though it affects training.
+- Training a nested algorithm in place and then reusing it across folds/datapoints.
+- Calling `self_optimize` directly in user-facing code instead of using `Optimize(...)`.
+
+## Minimal Pattern
+
+```python
+class MyPipeline(OptimizablePipeline[MyDataset]):
+    model: Parameter[MyAlgo]
+    model__weights: OptimizableParameter[np.ndarray]
+
+    def __init__(self, model: MyAlgo = cf(MyAlgo())):
+        self.model = model
+
+    def self_optimize(self, dataset: MyDataset, **kwargs):
+        model = self.model.clone()
+        self.model = model.self_optimize(...)
+        return self
+```
+
+## Source of Truth
+
+- `https://tpcp.readthedocs.io/en/latest/guides/optimization.html`
+- `https://tpcp.readthedocs.io/en/latest/guides/algorithm_evaluation.html`
+- `https://tpcp.readthedocs.io/en/latest/guides/algorithm_validation_tpcp.html`
+- `https://tpcp.readthedocs.io/en/latest/auto_examples/parameter_optimization/_02_optimizable_pipelines.html`
+- `https://tpcp.readthedocs.io/en/latest/auto_examples/parameter_optimization/_03_gridsearch_cv.html`
+- API docs for `Optimize`, `GridSearch`, `GridSearchCV`, and `make_optimize_safe`

{tpcp-2.1.2 → tpcp-2.2.0}/src/tpcp/__init__.py

@@ -24,7 +24,7 @@ from tpcp._parameters import (
 )
 from tpcp._pipeline import OptimizablePipeline, Pipeline
 
-__version__ = "2.1.2"
+__version__ = "2.2.0"
 
 
 __all__ = [

{tpcp-2.1.2 → tpcp-2.2.0}/src/tpcp/_algorithm.py

@@ -14,9 +14,17 @@ class Algorithm(BaseTpcpObject):
 
     All type-specific algorithm classes should inherit from this class and need to
 
-    1. overwrite `_action_method` with the name of the actual action method of this class type
+    1. overwrite `_action_methods` with the name of the actual action method of this class type
     2. implement a stub for the action method
 
+    Examples
+    --------
+    >>> class MyAlgorithm(Algorithm):
+    ...     _action_methods = "detect"
+    ...
+    ...     def detect(self, data):
+    ...         return self
+
     If you want to create an optimizable algorithm, add a `self_optimize` or (`self_optimize_with_info`) method to your
     class.
     We do not provide a separate base class for that, as we can make no assumptions about the call signature of your

tpcp-2.2.0/src/tpcp/_cli.py

@@ -0,0 +1,95 @@
+"""CLI helpers for tpcp."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+import sysconfig
+from pathlib import Path
+
+
+def _find_distributed_skills_dir() -> Path:
+    repo_skills = Path(__file__).resolve().parents[2] / "skills" / "tpcp"
+    if repo_skills.is_dir():
+        return repo_skills
+
+    installed_skills = Path(sysconfig.get_paths()["data"]) / "tpcp"
+    if installed_skills.is_dir():
+        return installed_skills
+
+    raise FileNotFoundError(
+        "Could not locate the distributed tpcp skills. "
+        "Expected either a repository checkout at `skills/tpcp` or installed package data at "
+        f"`{installed_skills}`."
+    )
+
+
+def install_skills(project_dir: Path, *, force: bool = False) -> list[Path]:
+    """Install the distributed tpcp skills into the project's `.agent` folder."""
+    source_dir = _find_distributed_skills_dir()
+    destination_dir = project_dir / ".agent"
+    destination_dir.mkdir(parents=True, exist_ok=True)
+
+    skill_dirs = sorted(p for p in source_dir.iterdir() if p.is_dir())
+    if not force:
+        conflicts = [
+            destination_dir / skill_dir.name for skill_dir in skill_dirs if (destination_dir / skill_dir.name).exists()
+        ]
+        if conflicts:
+            conflict_names = ", ".join(sorted(p.name for p in conflicts))
+            raise FileExistsError(
+                "The following skills already exist in the destination: "
+                f"{conflict_names}. Re-run with `--force` to replace them."
+            )
+
+    installed = []
+    for skill_dir in skill_dirs:
+        target = destination_dir / skill_dir.name
+        if target.exists():
+            if target.is_dir():
+                shutil.rmtree(target)
+            else:
+                target.unlink()
+        shutil.copytree(skill_dir, target)
+        installed.append(target)
+
+    return installed
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the tpcp CLI."""
+    parser = argparse.ArgumentParser(prog="tpcp")
+    subparsers = parser.add_subparsers(dest="command")
+
+    install_parser = subparsers.add_parser(
+        "install-skills",
+        help="Copy the distributed tpcp skills into the current project's `.agent` folder.",
+    )
+    install_parser.add_argument(
+        "--project-dir",
+        type=Path,
+        default=Path.cwd(),
+        help="Project directory that should receive the `.agent` folder. Defaults to the current working directory.",
+    )
+    install_parser.add_argument(
+        "--force",
+        action="store_true",
+        help="Replace already installed tpcp skills in the destination.",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "install-skills":
+        installed = install_skills(args.project_dir.resolve(), force=args.force)
+        if installed:
+            print(f"Installed {len(installed)} skill(s) into {args.project_dir.resolve() / '.agent'}.")
+        else:
+            print("No new skills installed.")
+        return 0
+
+    parser.print_help()
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{tpcp-2.1.2 → tpcp-2.2.0}/src/tpcp/_dataset.py

@@ -474,7 +474,7 @@ class _Dataset(BaseTpcpObject, Generic[GroupLabelT]):
 
     def create_group_labels(self, label_cols: Union[str, list[str]]) -> list[str]:
         warnings.warn(
-            "The method `create_string_group_labels` is deprecated and will be removed in a future version. "
+            "The method `create_group_labels` is deprecated and will be removed in a future version. "
             "Use `create_string_group_labels` instead.",
             DeprecationWarning,
             stacklevel=1,

{tpcp-2.1.2 → tpcp-2.2.0}/src/tpcp/_pipeline.py

@@ -17,6 +17,7 @@ class Pipeline(Algorithm, Generic[DatasetT]):
     """Baseclass for all custom pipelines.
 
     To create your own custom pipeline, subclass this class and implement `run`.
+    The `run` method is expected to operate on exactly one dataset datapoint/group.
     """
 
     _action_methods: ClassVar[tuple[str, str]] = ("safe_run", "run")
@@ -30,6 +31,10 @@ class Pipeline(Algorithm, Generic[DatasetT]):
         .. note::
             It is usually preferred to use `safe_run` on custom pipelines instead of `run`, as `safe_run` can
             catch certain implementation errors of the run method.
+            However, neither `run` nor `safe_run` verify that `datapoint` actually represents only a single
+            datapoint/group.
+            Pipeline implementations should enforce this through dataset accessors and/or explicit
+            `assert_is_single(...)`/`assert_is_single_group(...)` checks.
 
         Parameters
         ----------
@@ -50,6 +55,7 @@ class Pipeline(Algorithm, Generic[DatasetT]):
 
         It is preferred to use this method over `run`, as it can catch some simple implementation errors of custom
         pipelines.
+        It does not validate that the provided dataset instance contains only a single datapoint/group.
 
         The following things are checked:
 
@@ -81,7 +87,7 @@ class OptimizablePipeline(Pipeline[DatasetT]):
 
     OptimizablePipelines are expected to implement a concrete way to train internal models or optimize parameters.
     This should not be a reimplementation of GridSearch or similar methods.
-    For this :class:`tpcp.pipelines.GridSearch` should be used directly.
+    For this :class:`tpcp.optimize.GridSearch` should be used directly.
 
     It is important that `self_optimize` only modifies input parameters of the pipeline that are marked as
     `OptimizableParameter`.