fairseq2.recipes.cli¶
Classes¶
- class fairseq2.recipes.cli.Cli(name, origin_module, *, version, description=None)[source]¶
Bases:
object
Represents the entry point of a command line program.
- Parameters:
- class fairseq2.recipes.cli.CliGroup(name, origin_module, *, help=None)[source]¶
Bases:
object
Represents a command group of a command line program.
- add_command(name, handler, *, help=None, origin_module=None)[source]¶
Add a command.
- Parameters:
name (str) – The name of the command.
handler (CliCommandHandler) – The handler of the command.
origin_module (str | None) – The name of origin Python module of the command.
help (str | None) – The help text of the command.
- Return type:
- class fairseq2.recipes.cli.CliCommand(name, handler, origin_module, *, help=None)[source]¶
Bases:
object
Represents a command of a command line program.
- class fairseq2.recipes.cli.CliCommandHandler[source]¶
Bases:
ABC
Represents the handler of a command of a command line program.
- final class fairseq2.recipes.cli.RecipeCommandHandler(loader, preset_configs, default_preset, *, extra_sweep_keys=None)[source]¶
Bases:
CliCommandHandler
,Generic
[ConfigT
]Runs a recipe over command line.
- Parameters:
loader (RecipeLoader[ConfigT]) – The recipe loader.
preset_configs (ConfigProvider[ConfigT]) – The registry containing the preset recipe configurations.
default_preset (str) – The name of the default preset.
extra_sweep_keys (Set[Hashable] | None) – The recipe specific configuration keys to include in the sweep directory name.
Examples¶
Creating a Custom CLI¶
To create a custom CLI, you’ll need to:
Create a CLI group
Add commands to the group
Register your CLI extension
Here’s a complete example:
from fairseq2.recipes.cli import Cli, CliCommandHandler, RecipeCommandHandler
def setup_custom_cli(cli: Cli) -> None:
# Create a new command group
group = cli.add_group(
"custom",
help="Custom recipes and utilities"
)
# Add a command using RecipeCommandHandler
custom_handler = RecipeCommandHandler(
loader=load_custom_recipe, # this is the recipe entrypoint callback function
preset_configs=custom_presets, # this is the preset configs registry
default_preset="default", # this is the default preset name
sweep_allowed_keys=["model", "dataset"] # Optional
)
group.add_command(
name="custom_command",
handler=custom_handler,
help="Run custom recipe"
)
You can find more examples in our recipe examples:
fairseq2.recipes.lm.instruction_finetune
fairseq2.recipes.wav2vec2.train
Recipe Command Handler¶
The RecipeCommandHandler
class provides a standardized way to handle recipe commands. It automatically sets up:
Configuration management (presets, files, overrides)
Output directory handling
Logging setup
Environment setup for distributed training
Example implementation:
from dataclasses import dataclass
from pathlib import Path
from typing import Callable
@dataclass
class CustomConfig:
param1: str
param2: int
def load_custom_recipe(config: CustomConfig, output_dir: Path) -> Callable[[], None]:
def run_recipe() -> None:
# Recipe implementation
pass
return run_recipe
# Create preset configs
custom_presets = ConfigRegistry(CustomConfig)
custom_presets.register("default", CustomConfig(param1="value", param2=42))
CLI Initialization Process¶
The CLI system is initialized in the following order:
Cli
instance is created infairseq2.recipes.main()
Core CLI groups are registered in
fairseq2.recipes._setup_cli()
Extension CLI groups are registered via
fairseq2.recipes._setup_cli_extensions()
To add your own CLI extension:
Create a Python package for your extension
Create an entry point in your package’s
setup.py
:
setup(
name="my_fairseq2_extension",
entry_points={
"fairseq2.cli": [
"custom = my_extension.cli:setup_custom_cli"
]
}
)