# Known Issues

# Известные проблемы и расхождения с документацией

Список вещей, которые не работают как задокументировано в других местах репозитория (корневой `README.md`, `make_docs/`), или которые могут удивить при первом использовании. Составлен по фактическому чтению кода на момент написания этой документации.

## Баги

### `ComponentsObject.update_wear()` / `.predict_fix()` падают с `AttributeError`

`src/mlumina/components_wear/components_object.py:163` и `:272` вызывают несуществующий метод `self._get_wear_dict()`. Реально определён `_get__dict()` (строка 74, с двойным подчёркиванием). Воспроизводится в штатном примере `examples/components_wear/example.py:33`. Подробности и обходной путь — [components-wear.md](/books/mlumina/page/components-wear#известная-поломка-updatewear--predictfix).

## Расхождения корневого `README.md` с кодом

Примеры кода в разделе "Использования фреймворка MLumina" корневого `README.md` местами не соответствуют реальному API:

| В README | В коде |
|---|---|
| `from mlumina import hello; hello()` | `src/mlumina/__init__.py` пуст, функции `hello` не существует |
| `YoloImageModel(model_path="yolov8n.pt")` | `YoloImageModel(model)` — принимает готовый объект `ultralytics.YOLO`, не путь |
| `model.predict_parallel(image_paths=..., batch_size=...)` | метод называется `predict_ray(images, num_workers=2, **kwargs)` |
| `from mlumina.interpolation_tables import InterpolationTable, evaluate_models_parallel` | класс называется `TableInterpolator`; функции `evaluate_models_parallel` нет — ближайшие аналоги `compare_multiple_models`/`compare_multiple_models_ray` |
| `graph.calculate_parallel()` | метода нет; есть `simulate_objects`, `simulate_objects_ray`, `simulate_objects_bn` |

Раздел README про XGBoost (`xgboost_load_dataset`, `XGBoostModel`, `XGBoostTuningModel`) — единственный, полностью совпадающий с кодом.

## `make_docs/` (Sphinx) не отражает текущий код

`make_docs/source/introduction/what_is_mlumina.rst` описывает MLumina как открытый мультимодальный AutoML-фреймворк с эволюционным поиском пайплайнов, поддержкой классификации/регрессии/временных рядов и сохранением/загрузкой найденных решений. В коде ничего из этого нет — библиотека представляет собой набор независимых обёрток и утилит (см. [README](/books/mlumina/page/overview)). Единственный фрагмент кода в этом файле (`TableInterpolator`) — рабочий и совпадает с реальным API. Большинство разделов, на которые ссылается `make_docs/source/index.rst` (`basics/`, `advanced/`, `examples/`, `benchmarks/`, `api/`, `contribution`, `about`, `faq/`), физически не созданы.

## Прочие несостыковки/ограничения кода

- **`mlumina/__main__.py`** — пустой стаб, `python -m mlumina` ничего не делает; в `pyproject.toml` нет `[project.scripts]`, т.е. CLI-команды у пакета нет.
- **`run.sh`** ссылается на `examples/isppr/examples.py` — такой директории (`examples/isppr/`) в репозитории нет.
- **`mlumina.core`** имеет побочные эффекты при импорте: `init_config(MLuminaConfig)` и `setup_logging()` вызываются на уровне `__init__.py`. Это требует, чтобы `configs/settings.yaml` (или файл по пути из `MLUMINA_SETTINGS_PATH`) существовал и был валиден, а `data.train_file`/`data.eval_file` из него — реально существующими файлами (тип `pydantic.FilePath`), иначе любой `import mlumina.core` (и транзитивно многое другое) упадёт при инициализации конфига.
- **`mlumina.scheduler.main`** тоже имеет побочный эффект при импорте: создаёт `Scheduler()` (подключение к Ray) и вызывает блокирующий `scheduler.start()` (запуск `uvicorn`). Модуль нельзя просто импортировать — только запускать как процесс.
- **`YoloImageModel.predict_ray`/`train_ray`/`tune_optuna`** внутри Ray-воркеров всегда создают `YOLO("yolov8n.pt")` как базовую архитектуру перед загрузкой переданных весов — корректно работает только для yolov8n-совместимых моделей, независимо от того, какая модель была реально обёрнута.
- **`xgboost_load_dataset`** — параметры по умолчанию (`target="elapsed_time_sec"`, `categorical_cols=["vcd", "nom_point"]`) специфичны для датасета из `examples/xgboost/`, а не универсальны.
- **`examples/`** в основном не проверяются автоматически: в `run.sh` рабочей (раскомментированной) остаётся только строка с `example_objects_simulate_ray.py`; остальные примеры нужно перед использованием проверять вручную.