diff --git a/README.md b/README.md index eca2e5fc846..2df75017d02 100644 --- a/README.md +++ b/README.md @@ -190,6 +190,18 @@ cd trl/ pip install -e .[dev] ``` +## Experimental + +A minimal incubation area is available under `trl.experimental` for unstable / fast-evolving features. Anything there may change or be removed in any release without notice. + +Example: + +```python +from trl.experimental.new_trainer import NewTrainer +``` + +Read more in the [Experimental docs](https://huggingface.co/docs/trl/main/en/experimental). + ## Citation ```bibtex diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml index c6ac9728729..a49630fc27e 100644 --- a/docs/source/_toctree.yml +++ b/docs/source/_toctree.yml @@ -11,6 +11,8 @@ title: Dataset Formats - local: paper_index title: Paper Index + - local: experimental + title: Experimental - local: how_to_train title: Training FAQ - local: logging diff --git a/docs/source/experimental.md b/docs/source/experimental.md new file mode 100644 index 00000000000..27016bf2ae7 --- /dev/null +++ b/docs/source/experimental.md @@ -0,0 +1,51 @@ +# Experimental Features + +The `trl.experimental` namespace provides a minimal, clearly separated space for fast iteration on new ideas. + + + +**Stability contract:** Anything under `trl.experimental` may change or be removed in *any* release (including patch versions) without prior deprecation. Do not rely on these APIs for production workloads. + + + +## Current Experimental Features + +The following modules are currently available under [`trl.experimental`](https://github.com/huggingface/trl/tree/main/trl/experimental). +This list is not exhaustive and may change at any time. + +### Nothing here yet + +... + +## Usage + +```python +from trl.experimental.new_trainer import NewTrainer +``` + +To silence the runtime notice: + +```bash +export TRL_EXPERIMENTAL_SILENCE=1 +``` + +## Promotion Path (Simple) + +1. **Prototype outside the main repo:** Start development in your own fork or a separate repository to iterate quickly. +2. **Experimental inclusion:** Once it’s ready for early users, move the idea into `trl.experimental.`. +3. **Improve:** Add tests, a short doc/example, and demonstrate the usage. +4. **Promote:** Once the API proves stable and there is clear interest or adoption from the community, move it into `trl.` (stable module). + +## FAQ + +**Why not just use branches?** +Because branches are not shipped to users; experimental code inside the package lets early adopters try things and give feedback. + +**Can these APIs change or vanish without warning?** +Yes. Anything inside `trl.experimental` can change or disappear in *any* release. + +**Should I use this in production?** +Only if you are fine with updating your code quickly when things change. + +**Will maintainers promptly fix issues in `trl.experimental`?** +Not necessarily. The experimental module is a playground for new ideas, and maintainers may not prioritize bug fixes or feature requests there. Issues may remain unresolved until (or unless) the feature graduates to the stable API. diff --git a/trl/experimental/__init__.py b/trl/experimental/__init__.py new file mode 100644 index 00000000000..28f8f42eaf2 --- /dev/null +++ b/trl/experimental/__init__.py @@ -0,0 +1,34 @@ +# Copyright 2020-2025 The HuggingFace Team. All rights reserved. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Experimental submodule for TRL. + +This submodule contains unstable or incubating features. Anything here may change (or be removed) in any release +without deprecation. Use at your own risk. + +To silence this notice set environment variable TRL_EXPERIMENTAL_SILENCE=1. +""" + +import os +import warnings + + +if not os.environ.get("TRL_EXPERIMENTAL_SILENCE"): + warnings.warn( + "You are importing from 'trl.experimental'. APIs here are unstable and may change or be removed without " + "notice. Silence this warning by setting environment variable TRL_EXPERIMENTAL_SILENCE=1.", + UserWarning, + stacklevel=2, + )