README

Bases: Plugin, PluginProtocol

              flowchart TD
              liblaf.cherries.plugins.Comet[Comet]
              liblaf.cherries.core.plugin._plugin.Plugin[Plugin]
              liblaf.cherries.core._protocol.PluginProtocol[PluginProtocol]
              liblaf.cherries.core.assets._protocol.AssetPluginProtocol[AssetPluginProtocol]
              liblaf.cherries.core.metrics._protocol.MetricPluginProtocol[MetricPluginProtocol]
              liblaf.cherries.core.others._protocol.OtherPluginProtocol[OtherPluginProtocol]
              liblaf.cherries.core.params._protocol.ParamPluginProtocol[ParamPluginProtocol]

                              liblaf.cherries.core.plugin._plugin.Plugin --> liblaf.cherries.plugins.Comet
                
                liblaf.cherries.core._protocol.PluginProtocol --> liblaf.cherries.plugins.Comet
                                liblaf.cherries.core.assets._protocol.AssetPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.metrics._protocol.MetricPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.others._protocol.OtherPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.params._protocol.ParamPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                



              click liblaf.cherries.plugins.Comet href "" "liblaf.cherries.plugins.Comet"
              click liblaf.cherries.core.plugin._plugin.Plugin href "" "liblaf.cherries.core.plugin._plugin.Plugin"
              click liblaf.cherries.core._protocol.PluginProtocol href "" "liblaf.cherries.core._protocol.PluginProtocol"
              click liblaf.cherries.core.assets._protocol.AssetPluginProtocol href "" "liblaf.cherries.core.assets._protocol.AssetPluginProtocol"
              click liblaf.cherries.core.metrics._protocol.MetricPluginProtocol href "" "liblaf.cherries.core.metrics._protocol.MetricPluginProtocol"
              click liblaf.cherries.core.others._protocol.OtherPluginProtocol href "" "liblaf.cherries.core.others._protocol.OtherPluginProtocol"
              click liblaf.cherries.core.params._protocol.ParamPluginProtocol href "" "liblaf.cherries.core.params._protocol.ParamPluginProtocol"
            

Send run metadata, parameters, and metrics to Comet.

Attributes:

Parameters:

• name (PluginName, default: <dynamic> ) –
• run (Run) –
• disabled (bool, default: False ) –

disabled: bool = field(default=False)

experiment: CometExperiment

name: PluginName = field(
    default=Factory(_default_name, takes_self=True),
    kw_only=True,
)

run: Run = field(repr=False)

end(exc: BaseException | None = None) -> None

49
50
51
52
53

@override
@core.impl(after=("Git",))
def end(self, exc: BaseException | None = None) -> None:
    """End the active Comet experiment after Git finalization."""
    self.experiment.end()

log_asset(
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None

55
56
57
58
59
60
61
62
63
64

@override
@core.impl
def log_asset(
    self,
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None:
    """Reserve the asset hook for future Comet artifact support."""

log_metric(
    name: str, value: float, *, step: int, time: datetime
) -> None

67
68
69
70
71

@override
@core.impl
def log_metric(self, name: str, value: float, *, step: int, time: datetime) -> None:
    """Log one metric to Comet."""
    return self.experiment.log_metric(name, value, step=step)

log_metrics(
    metrics: dict[str, float], *, step: int, time: datetime
) -> None

73
74
75
76
77
78
79

@override
@core.impl
def log_metrics(
    self, metrics: dict[str, float], *, step: int, time: datetime
) -> None:
    """Log multiple metrics to Comet."""
    return self.experiment.log_metrics(metrics, step=step)

log_other(name: str, value: Any) -> None

81
82
83
84
85

@override
@core.impl
def log_other(self, name: str, value: Any) -> None:
    """Log one metadata value to Comet."""
    return self.experiment.log_other(name, value)

log_others(others: dict[str, Any]) -> None

87
88
89
90
91

@override
@core.impl
def log_others(self, others: dict[str, Any]) -> None:
    """Log multiple metadata values to Comet."""
    return self.experiment.log_others(others)

log_param(name: str, value: Any) -> None

93
94
95
96
97

@override
@core.impl
def log_param(self, name: str, value: Any) -> None:
    """Log one parameter to Comet."""
    return self.experiment.log_parameter(name, value)

log_params(params: dict[str, Any]) -> None

 99
100
101
102
103

@override
@core.impl
def log_params(self, params: dict[str, Any]) -> None:
    """Log multiple parameters to Comet."""
    return self.experiment.log_parameters(params)

start() -> None

33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

@override
@core.impl
def start(self) -> None:
    """Start a Comet experiment for the owning run."""
    try:
        exp: comet.CometExperiment = comet.start(
            project_name=self.run.project_name,
            experiment_config=comet.ExperimentConfig(
                disabled=self.disabled, name=self.run.run_name, tags=self.run.tags
            ),
        )
    except ValueError:
        logger.exception("")
    else:
        self.run.log_other("cherries/comet/url", exp.url)

Bases: Plugin, PluginProtocol

              flowchart TD
              liblaf.cherries.plugins.Git[Git]
              liblaf.cherries.core.plugin._plugin.Plugin[Plugin]
              liblaf.cherries.core._protocol.PluginProtocol[PluginProtocol]
              liblaf.cherries.core.assets._protocol.AssetPluginProtocol[AssetPluginProtocol]
              liblaf.cherries.core.metrics._protocol.MetricPluginProtocol[MetricPluginProtocol]
              liblaf.cherries.core.others._protocol.OtherPluginProtocol[OtherPluginProtocol]
              liblaf.cherries.core.params._protocol.ParamPluginProtocol[ParamPluginProtocol]

                              liblaf.cherries.core.plugin._plugin.Plugin --> liblaf.cherries.plugins.Git
                
                liblaf.cherries.core._protocol.PluginProtocol --> liblaf.cherries.plugins.Git
                                liblaf.cherries.core.assets._protocol.AssetPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.metrics._protocol.MetricPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.others._protocol.OtherPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.params._protocol.ParamPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                



              click liblaf.cherries.plugins.Git href "" "liblaf.cherries.plugins.Git"
              click liblaf.cherries.core.plugin._plugin.Plugin href "" "liblaf.cherries.core.plugin._plugin.Plugin"
              click liblaf.cherries.core._protocol.PluginProtocol href "" "liblaf.cherries.core._protocol.PluginProtocol"
              click liblaf.cherries.core.assets._protocol.AssetPluginProtocol href "" "liblaf.cherries.core.assets._protocol.AssetPluginProtocol"
              click liblaf.cherries.core.metrics._protocol.MetricPluginProtocol href "" "liblaf.cherries.core.metrics._protocol.MetricPluginProtocol"
              click liblaf.cherries.core.others._protocol.OtherPluginProtocol href "" "liblaf.cherries.core.others._protocol.OtherPluginProtocol"
              click liblaf.cherries.core.params._protocol.ParamPluginProtocol href "" "liblaf.cherries.core.params._protocol.ParamPluginProtocol"
            

Record Git metadata and optionally commit dirty experiment outputs.

Attributes:

Parameters:

• name (PluginName, default: <dynamic> ) –
• run (Run) –
• commit (bool, default: False ) –
• verify (bool, default: False ) –

commit: bool = field(default=False, kw_only=True)

name: PluginName = field(
    default=Factory(_default_name, takes_self=True),
    kw_only=True,
)

repo: Repo | None

run: Run = field(repr=False)

verify: bool = field(default=False, kw_only=True)

end(exc: BaseException | None = None) -> None

30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

@override
@core.impl(before=("Comet",))
def end(self, exc: BaseException | None = None) -> None:
    """Commit dirty changes if configured and log the final Git SHA."""
    if self.repo is None:
        return
    if self.commit and self.repo.is_dirty(untracked_files=True):
        message: str = self._make_commit_message()
        try:
            self.repo.git.add(all=True)
            subprocess.run(["git", "status"], check=False)
            self.repo.git.commit(message=message, no_verify=not self.verify)
        except git.GitCommandError:
            logger.exception("")
    self.run.log_other("cherries/git/sha", self.repo.head.commit.hexsha)

log_asset(
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None

 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

def log_asset(
    self,
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None:
    """Record an existing artifact path.

    Args:
        path: Existing file or directory to record.
        metadata: Optional artifact metadata, usually including `type`.
        report: Whether the path is the primary user-facing artifact.
            Companion files are logged with `report=False`.
    """
    ...

log_metric(
    name: str, value: float, *, step: int, time: datetime
) -> None

12
13
14
15
16

def log_metric(
    self, name: str, value: float, *, step: int, time: datetime.datetime
) -> None:
    """Record one metric sample."""
    ...

log_metrics(
    metrics: dict[str, float], *, step: int, time: datetime
) -> None

18
19
20
21
22

def log_metrics(
    self, metrics: dict[str, float], *, step: int, time: datetime.datetime
) -> None:
    """Record a batch of already-flattened metric samples."""
    ...

log_other(name: str, value: Any) -> None

7
8
9

def log_other(self, name: str, value: Any) -> None:
    """Record one flattened metadata value."""
    ...

log_others(others: dict[str, Any]) -> None

11
12
13

def log_others(self, others: dict[str, Any]) -> None:
    """Record multiple already-flattened metadata values."""
    ...

log_param(name: str, value: Any) -> None

7
8
9

def log_param(self, name: str, value: Any) -> None:
    """Record one flattened parameter value."""
    ...

log_params(params: dict[str, Any]) -> None

11
12
13

def log_params(self, params: dict[str, Any]) -> None:
    """Record multiple already-flattened parameter values."""
    ...

start() -> None

18
19
20

def start(self) -> None:
    """Start a run."""
    raise NotImplementedError

Bases: Plugin, PluginProtocol

              flowchart TD
              liblaf.cherries.plugins.Local[Local]
              liblaf.cherries.core.plugin._plugin.Plugin[Plugin]
              liblaf.cherries.core._protocol.PluginProtocol[PluginProtocol]
              liblaf.cherries.core.assets._protocol.AssetPluginProtocol[AssetPluginProtocol]
              liblaf.cherries.core.metrics._protocol.MetricPluginProtocol[MetricPluginProtocol]
              liblaf.cherries.core.others._protocol.OtherPluginProtocol[OtherPluginProtocol]
              liblaf.cherries.core.params._protocol.ParamPluginProtocol[ParamPluginProtocol]

                              liblaf.cherries.core.plugin._plugin.Plugin --> liblaf.cherries.plugins.Local
                
                liblaf.cherries.core._protocol.PluginProtocol --> liblaf.cherries.plugins.Local
                                liblaf.cherries.core.assets._protocol.AssetPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.metrics._protocol.MetricPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.others._protocol.OtherPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.params._protocol.ParamPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                



              click liblaf.cherries.plugins.Local href "" "liblaf.cherries.plugins.Local"
              click liblaf.cherries.core.plugin._plugin.Plugin href "" "liblaf.cherries.core.plugin._plugin.Plugin"
              click liblaf.cherries.core._protocol.PluginProtocol href "" "liblaf.cherries.core._protocol.PluginProtocol"
              click liblaf.cherries.core.assets._protocol.AssetPluginProtocol href "" "liblaf.cherries.core.assets._protocol.AssetPluginProtocol"
              click liblaf.cherries.core.metrics._protocol.MetricPluginProtocol href "" "liblaf.cherries.core.metrics._protocol.MetricPluginProtocol"
              click liblaf.cherries.core.others._protocol.OtherPluginProtocol href "" "liblaf.cherries.core.others._protocol.OtherPluginProtocol"
              click liblaf.cherries.core.params._protocol.ParamPluginProtocol href "" "liblaf.cherries.core.params._protocol.ParamPluginProtocol"
            

Copy the entrypoint, logs, and artifacts into .cherries/runs/.

Attributes:

Parameters:

• name (PluginName, default: <dynamic> ) –
• run (Run) –

folder: Path

log_file: Path

name: PluginName = field(
    default=Factory(_default_name, takes_self=True),
    kw_only=True,
)

run: Run = field(repr=False)

end(exc: BaseException | None = None) -> None

22
23
24
25
26
27
28

def end(self, exc: BaseException | None = None) -> None:
    """End a run.

    Args:
        exc: Exception raised by the experiment, if any.
    """
    raise NotImplementedError

log_asset(
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None

49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

@override
@core.impl
def log_asset(
    self,
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None:
    """Copy `path` under the snapshot's `assets/` directory."""
    if path.is_relative_to(self.run.working_dir):
        target: Path = self.folder / path.relative_to(self.run.working_dir)
    else:
        target: Path = self.folder / "assets" / path.name
    self._copy(path, target)

log_metric(
    name: str, value: float, *, step: int, time: datetime
) -> None

12
13
14
15
16

def log_metric(
    self, name: str, value: float, *, step: int, time: datetime.datetime
) -> None:
    """Record one metric sample."""
    ...

log_metrics(
    metrics: dict[str, float], *, step: int, time: datetime
) -> None

18
19
20
21
22

def log_metrics(
    self, metrics: dict[str, float], *, step: int, time: datetime.datetime
) -> None:
    """Record a batch of already-flattened metric samples."""
    ...

log_other(name: str, value: Any) -> None

7
8
9

def log_other(self, name: str, value: Any) -> None:
    """Record one flattened metadata value."""
    ...

log_others(others: dict[str, Any]) -> None

11
12
13

def log_others(self, others: dict[str, Any]) -> None:
    """Record multiple already-flattened metadata values."""
    ...

log_param(name: str, value: Any) -> None

7
8
9

def log_param(self, name: str, value: Any) -> None:
    """Record one flattened parameter value."""
    ...

log_params(params: dict[str, Any]) -> None

11
12
13

def log_params(self, params: dict[str, Any]) -> None:
    """Record multiple already-flattened parameter values."""
    ...

start() -> None

42
43
44
45
46
47

@override
@core.impl
def start(self) -> None:
    """Configure local logging and copy the entrypoint."""
    self._config_logging()
    self._copy(self.run.entrypoint, self.folder / "src" / self.run.entrypoint.name)

Bases: Plugin, PluginProtocol

              flowchart TD
              liblaf.cherries.plugins.Logging[Logging]
              liblaf.cherries.core.plugin._plugin.Plugin[Plugin]
              liblaf.cherries.core._protocol.PluginProtocol[PluginProtocol]
              liblaf.cherries.core.assets._protocol.AssetPluginProtocol[AssetPluginProtocol]
              liblaf.cherries.core.metrics._protocol.MetricPluginProtocol[MetricPluginProtocol]
              liblaf.cherries.core.others._protocol.OtherPluginProtocol[OtherPluginProtocol]
              liblaf.cherries.core.params._protocol.ParamPluginProtocol[ParamPluginProtocol]

                              liblaf.cherries.core.plugin._plugin.Plugin --> liblaf.cherries.plugins.Logging
                
                liblaf.cherries.core._protocol.PluginProtocol --> liblaf.cherries.plugins.Logging
                                liblaf.cherries.core.assets._protocol.AssetPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.metrics._protocol.MetricPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.others._protocol.OtherPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                
                liblaf.cherries.core.params._protocol.ParamPluginProtocol --> liblaf.cherries.core._protocol.PluginProtocol
                



              click liblaf.cherries.plugins.Logging href "" "liblaf.cherries.plugins.Logging"
              click liblaf.cherries.core.plugin._plugin.Plugin href "" "liblaf.cherries.core.plugin._plugin.Plugin"
              click liblaf.cherries.core._protocol.PluginProtocol href "" "liblaf.cherries.core._protocol.PluginProtocol"
              click liblaf.cherries.core.assets._protocol.AssetPluginProtocol href "" "liblaf.cherries.core.assets._protocol.AssetPluginProtocol"
              click liblaf.cherries.core.metrics._protocol.MetricPluginProtocol href "" "liblaf.cherries.core.metrics._protocol.MetricPluginProtocol"
              click liblaf.cherries.core.others._protocol.OtherPluginProtocol href "" "liblaf.cherries.core.others._protocol.OtherPluginProtocol"
              click liblaf.cherries.core.params._protocol.ParamPluginProtocol href "" "liblaf.cherries.core.params._protocol.ParamPluginProtocol"
            

Initialize Python logging and mirror metrics to the run log.

Attributes:

Parameters:

• name (PluginName, default: <dynamic> ) –
• run (Run) –

log_file: Path

name: PluginName = field(
    default=Factory(_default_name, takes_self=True),
    kw_only=True,
)

run: Run = field(repr=False)

end(exc: BaseException | None = None) -> None

22
23
24
25
26
27
28

def end(self, exc: BaseException | None = None) -> None:
    """End a run.

    Args:
        exc: Exception raised by the experiment, if any.
    """
    raise NotImplementedError

log_asset(
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None

 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

def log_asset(
    self,
    path: Path,
    *,
    metadata: Mapping[str, Any] | None = None,
    report: bool = True,
) -> None:
    """Record an existing artifact path.

    Args:
        path: Existing file or directory to record.
        metadata: Optional artifact metadata, usually including `type`.
        report: Whether the path is the primary user-facing artifact.
            Companion files are logged with `report=False`.
    """
    ...

log_metric(
    name: str, value: float, *, step: int, time: datetime
) -> None

39
40
41
42
43

@override
@core.impl
def log_metric(self, name: str, value: float, *, step: int, time: datetime) -> None:
    """Write one metric to the Python logger."""
    logger.info("step: %s, %s: %s", step, name, value)

log_metrics(
    metrics: Mapping[str, float],
    *,
    step: int,
    time: datetime,
) -> None

45
46
47
48
49
50
51

@override
@core.impl
def log_metrics(
    self, metrics: Mapping[str, float], *, step: int, time: datetime
) -> None:
    """Write multiple metrics to the Python logger."""
    logger.info("step: %s, %s", step, metrics)

log_other(name: str, value: Any) -> None

7
8
9

def log_other(self, name: str, value: Any) -> None:
    """Record one flattened metadata value."""
    ...

log_others(others: dict[str, Any]) -> None

11
12
13

def log_others(self, others: dict[str, Any]) -> None:
    """Record multiple already-flattened metadata values."""
    ...

log_param(name: str, value: Any) -> None

7
8
9

def log_param(self, name: str, value: Any) -> None:
    """Record one flattened parameter value."""
    ...

log_params(params: dict[str, Any]) -> None

11
12
13

def log_params(self, params: dict[str, Any]) -> None:
    """Record multiple already-flattened parameter values."""
    ...

start(*args, **kwargs) -> None

33
34
35
36
37

@override
@core.impl
def start(self, *args, **kwargs) -> None:
    """Initialize `liblaf.logging` for the run log file."""
    liblaf.logging.init(file=self.log_file, force=True)