# ML Experiment Tracking

Use this reference when the task involves `MLNotionHelper`, experiment databases, metrics, plots, and artifacts.

## Initialize

```python
import os
from notionhelper import MLNotionHelper

ml_helper = MLNotionHelper(os.environ["NOTION_TOKEN"])
```

`MLNotionHelper` extends `NotionHelper`, so all base methods are available.

## Create an Experiment Database

```python
config = {
    "Run Name": "xgboost-baseline",
    "model": "xgboost",
    "learning_rate": 0.05,
    "use_features_v2": True,
}
metrics = {
    "sMAPE": 12.4,
    "MAE": 8.1,
}

data_source_id = ml_helper.create_ml_database(
    parent_page_id=parent_page_id,
    db_title="Forecast Experiments",
    config=config,
    metrics=metrics,
    file_property_name="Artifacts",
)
```

The first key in `config` becomes the title property. The schema infers booleans as checkbox, numbers as number, and other values as rich text. It also adds `Run Status` and a Files & Media artifact property.

## Log an Experiment

```python
page_id = ml_helper.log_ml_experiment(
    data_source_id=data_source_id,
    config=config,
    metrics=metrics,
    plots=["/absolute/path/residuals.png"],
    target_metric="sMAPE",
    higher_is_better=False,
    file_paths=["/absolute/path/model.pkl", "/absolute/path/metrics.json"],
    file_property_name="Artifacts",
)
```

The logger:

- Checks recent runs with `get_data_source_pages_as_dataframe(..., limit=100)`.
- Compares `target_metric` to the historical best.
- Creates a new page in the experiment data source.
- Embeds plot images into the page body.
- Uploads artifact files and attaches them to the Files & Media property.

## Practical Notes

- Ensure `target_metric` exists in `metrics` and the existing DataFrame column.
- Use `higher_is_better=True` for scores like accuracy and AUC; use `False` for losses/errors.
- Use existing local file paths for `plots` and `file_paths`; missing files are skipped.
- Be aware that the current implementation prints debug/status messages from some ML helper methods.
