Metadata-Version: 2.4
Name: coastline-recommender
Version: 0.2.3
Summary: Coastline: a context-aware recommender system for fine-tuning LLMs
Keywords: llm,fine-tuning,gpu,datacenter,recommender,throughput,energy-efficiency,carbon,sustainability,mlops
Author: Radu Nicolae, Daniele Lotito, Alexandru Iosup
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pandas>=2.0.0,<3
Requires-Dist: pyarrow>=13.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer>=0.9.0
Requires-Dist: tqdm>=4.66.0
Requires-Dist: cachetools>=5.3.0
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: kavier>=0.5.3,<0.6
Requires-Dist: ado-autoconf>=1.7,<2
Requires-Dist: scikit-learn==1.7.2 ; extra == 'ml'
Requires-Dist: xgboost==3.1.3 ; extra == 'ml'
Requires-Dist: lightgbm==4.6.0 ; extra == 'ml'
Requires-Dist: catboost==1.2.10 ; extra == 'ml'
Requires-Dist: torch>=2.0.0 ; extra == 'ml'
Requires-Dist: tabpfn==8.0.3 ; extra == 'ml'
Requires-Dist: matplotlib>=3.5 ; extra == 'plot'
Maintainer: AtLarge Research
Maintainer-email: AtLarge Research <info@atlarge-research.com>
Requires-Python: >=3.11, <3.14
Project-URL: Homepage, https://github.com/atlarge-research/coastline-recommender
Project-URL: Repository, https://github.com/atlarge-research/coastline-recommender
Project-URL: Issues, https://github.com/atlarge-research/coastline-recommender/issues
Project-URL: Documentation, https://atlarge-research.github.io/coastline-recommender/
Provides-Extra: autoconf
Provides-Extra: ml
Provides-Extra: plot
Description-Content-Type: text/markdown

# Coastline

A context-aware recommender system for fine-tuning LLMs.

[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/atlarge-research/coastline-recommender/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-site-green.svg)](https://atlarge-research.github.io/coastline-recommender/)
[![PyPI](https://img.shields.io/pypi/v/coastline-recommender.svg)](https://pypi.org/project/coastline-recommender/)

Coastline makes context-, objective-, and policy-aware infrastructure recommendations for LLM fine-tuning
workloads. It accounts for infrastructure constraints, workload demands, and user objectives, and recommends
best-fit configurations as part of an LLM fine-tuning ecosystem. Coastline predicts performance with
physics-driven simulation (Kavier) and machine-learning models. Every candidate configuration is cross-checked
through a feasibility module (IBM AutoConf) before being output to the user.

Built with PriorLabs-TabPFN. See the TabPFN section below.

## Install

```bash
pip install coastline-recommender          # Kavier, AutoConf, the CLI, and the dashboard
pip install "coastline-recommender[ml]"    # adds the data-driven predictors
```

Python 3.11 to 3.13. The import name is `coastline`.

## Quick start

From a clone of this repository:

```bash
uv sync
uv run coastline recommend-job
uv run coastline explain --model mistral-7b-v0.1 --method lora --gpu-model NVIDIA-A100-SXM4-80GB \
  --tokens 2048 --batch-size 8
uv run coastline --help
```

`coastline recommend-job` recommends a configuration for the job declared in
`config/coastline_functionality/experiment.yaml`. The subcommands are `recommend-job`, `recommend-trace`,
`simulate`, `explain`, and `utils`. Each documents its flags with `--help`. `uv run coastline-ui` serves the
dashboard at <http://127.0.0.1:8000>.

## Documentation

<https://atlarge-research.github.io/coastline-recommender/>. Build it locally with
`uv run --group docs mkdocs serve`.

## Development

`uv sync` installs the dev tools. CI runs these gates on every pull request
([ci.yml](https://github.com/atlarge-research/coastline-recommender/blob/main/.github/workflows/ci.yml)):

```bash
uv run pre-commit run --all-files --show-diff-on-failure      # ruff check, ruff format, whitespace
uv run mypy                                                   # strict, on the packages listed in pyproject.toml
uv run --all-extras pytest --cov
uv run --all-extras pytest -m ml_isolated -p no:cacheprovider FILE  # native ML backends, one file per process
uv run --group docs mkdocs build --strict
```

Run `uv run pre-commit install` once per clone to get the hooks on commit.

## TabPFN

Built with PriorLabs-TabPFN.

The `tabpfn` predictor and the model file `portfolio/tabpfn.pkl` (in
`src/coastline/sdk/predictors/performance/data_driven/`) contain TabPFN v2 weights. TabPFN v2 is described in
Hollmann et al., "Accurate predictions on small data with a tabular foundation model", Nature 637, 319-326
(2025), [doi:10.1038/s41586-024-08328-6](https://doi.org/10.1038/s41586-024-08328-6).
The weights are licensed under the Prior Labs License v1.2; a copy is in
[LICENSE-TabPFN.txt](https://github.com/atlarge-research/coastline-recommender/blob/main/LICENSE-TabPFN.txt). The
model file is in the repository and its Zenodo archive, and left out of the PyPI wheel.

## Citation

See [CITATION.cff](https://github.com/atlarge-research/coastline-recommender/blob/main/CITATION.cff).

## License

MIT. See [LICENSE](https://github.com/atlarge-research/coastline-recommender/blob/main/LICENSE). The TabPFN weights
are under the Prior Labs License v1.2, in
[LICENSE-TabPFN.txt](https://github.com/atlarge-research/coastline-recommender/blob/main/LICENSE-TabPFN.txt).
