# Структура проекта и уровни API

## Два уровня API

В библиотеке есть два основных уровня API.

### Низкоуровневое typed API

Низкоуровневое API — основной слой проекта. Оно строится вокруг типизированных parameter blocks, links, families и compiled models:

- `gamlss-core` задает базовые абстракции: link functions, parameter markers, `ParameterBlock`, `ParameterBlocks`, objective/model traits и compiled model evaluation;
- `gamlss-family` содержит распределения, likelihoods, score helpers и CDF/quantile utilities;
- `gamlss-special` содержит special functions и общие численные helpers для likelihood/CDF/quantile кода;
- `gamlss-spline` содержит spline/Fourier predictors, penalties и metadata;
- `gamlss-transform` содержит target transforms и persisted transform state;
- `gamlss-diagnostics` содержит post-fit diagnostics поверх fitted distributional models.

Этот уровень рассчитан на код, где важны compile-time guarantees, явный layout параметров, отсутствие строковых lookup-ов в hot path и минимальные зависимости. Именно typed API является базовой поверхностью для integration layers, optimizer adapters и более высокоуровневых builders.

### Высокоуровневое API

Высокоуровневое API — convenience layer для более компактного описания модели. Сейчас оно представлено optional crate-ом `gamlss-formula`, который доступен из facade crate `gamlss` при включенной feature `formula`.

`gamlss-formula` принимает runtime specifications и curated builder descriptions, затем компилирует их в typed core models. Этот слой предназначен для удобных workflows, но он не является заменой низкоуровневому API и не обязан зеркалировать все combinations of families, links, penalties и custom parameterizations, доступные напрямую через `gamlss-core` и соседние crate-ы.

## Facade crate `gamlss`

Crate `gamlss` — основная точка входа для большинства пользователей. Он реэкспортирует основные workspace crate-ы:

- [`core`](crate::core) для typed ядра;
- [`family`](crate::family) для distributions и likelihoods;
- [`special`](crate::special) для special functions и численных helpers;
- [`spline`](crate::spline) для spline predictors и penalties;
- [`transform`](crate::transform) для target preprocessing;
- [`diagnostics`](crate::diagnostics) для post-fit diagnostics;
- `formula` для experimental formula/builder API, если включена feature `formula`.

Также facade crate предоставляет [`prelude`](crate::prelude), где собраны наиболее часто используемые типы.

## Поток данных

Типичный низкоуровневый workflow выглядит так:

1. Пользователь выбирает distribution family из `gamlss-family`.
2. Для каждого параметра распределения создается свой `ParameterBlock` с parameter marker, link function, design/predictor и penalty.
3. Несколько блоков объединяются в `ParameterBlocks`, который задает общий layout beta-вектора.
4. `gamlss-core` компилирует family, blocks, response и optional weights в objective/model object.
5. Внешний optimizer работает с objective/gradient surface, не владея modeling logic.
6. После fit-а пользователь вызывает prediction и diagnostics helpers.

Высокоуровневый builder слой должен в итоге приводить к той же compiled typed модели, а не выполнять отдельную интерпретацию формулы в hot path.

## Границы зависимостей

`gamlss-core` намеренно остается легким и независимым от optimizer crates, dataframe libraries и тяжелых matrix backends. Более тяжелые integrations должны жить за optional features или в отдельных integration crate-ах.

Это разделение позволяет использовать core abstractions в разных окружениях: от небольших embedded-style numeric loops до более крупных ML pipelines с собственными matrix backends и optimizer stacks.
