Metadata-Version: 2.4
Name: coastline-recommender
Version: 0.1.0
Summary: Context-aware GPU/datacenter configuration recommender for LLM fine-tuning
Author: Radu Nicolae
License: MIT License
        
        Copyright (c) 2026 Radu Nicolae
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/atlarge-research/coastline
Project-URL: Repository, https://github.com/atlarge-research/coastline
Project-URL: Issues, https://github.com/atlarge-research/coastline/issues
Keywords: llm,fine-tuning,gpu,datacenter,recommender,throughput,energy-efficiency,carbon,sustainability,mlops
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=13.0.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: scikit-learn==1.7.2
Requires-Dist: fastapi>=0.104.0
Requires-Dist: uvicorn[standard]>=0.24.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: typer>=0.9.0
Requires-Dist: rich>=13.0.0
Requires-Dist: inquirerpy>=0.3.4
Requires-Dist: tqdm>=4.66.0
Requires-Dist: cachetools>=5.3.0
Requires-Dist: kavier<0.5,>=0.4
Provides-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"
Provides-Extra: autoconf
Requires-Dist: ado-autoconf<2,>=1.7; extra == "autoconf"
Provides-Extra: plot
Requires-Dist: matplotlib>=3.5; extra == "plot"
Requires-Dist: seaborn>=0.13.0; extra == "plot"
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# Coastline

Context-aware recommender for **GPU / datacenter configurations** for LLM fine-tuning: it grid-searches configs for a workload, filters infeasible ones, predicts **throughput + power**, and ranks them on a performance↔energy score. Throughput comes from **Kavier** (analytical physics) or a data-driven model (TabPFN, CatBoost, …); energy from Kavier-power or the OpenDC simulator.

**Accuracy** (throughput MdAPE, 15% holdout): default `intelligent` = cache hit (0%) → Kavier (6.2%), never a weak model. Available ML predictors (bring your own trained artifacts): TabPFN 2.1%, XGBoost 7.2%, CatBoost 8.4%, LightGBM 9.1%. Weaker linear/GP/MLP baselines are opt-in.

## Install

```bash
python -m venv .venv && source .venv/bin/activate
pip install coastline-recommender                 # core engine (Kavier physics path)
pip install "coastline-recommender[autoconf]"     # + AutoConf OOM-feasibility safeguard
pip install "coastline-recommender[ml]"           # + heavy ML backends (TabPFN, XGBoost, …)
```

For development from a checkout: `pip install -e ".[dev]"` (plus `pip install -e ./common` for the shared `coastline_common` models).

- **Kavier** — declared dependency, pulled from PyPI (`kavier>=0.4,<0.5`). For Kavier dev: `pip install -e ../kavier`.
- **AutoConf** — the OOM-feasibility safeguard (IBM's open-source `ado`, on public PyPI as `ado-autoconf`). Install it with the extra: `pip install "coastline-recommender[autoconf]"`. Without it the recommender refuses by default; `COASTLINE_ALLOW_RULES_FALLBACK=1` degrades to divisibility-only feasibility (no OOM check).

  > **NOTE — install AutoConf via the extra, not `pip install autoconf`.** The bare PyPI name `autoconf` is an UNRELATED package; the OOM checker is `ado-autoconf`, pulled in by `coastline-recommender[autoconf]`. If you don't need the OOM check, use `feasibility: rules` (the divisibility-only path that needs no AutoConf at all).

## API & CLI map

| Entry point | Shape | Returns | When to use |
|---|---|---|---|
| `coastline(throughput_estim=...)(workload)` | single `WorkloadSpec` / dict / CSV path | `list[Recommendation]` | Low-latency single-workload queries; best for scripting or direct Python use |
| `coastline.recommend(batch, ...)` | DataFrame / list[dict] / dict | `pd.DataFrame` (input rows + predictions) | Batch processing — one or many workloads, per-row column overrides, `top_k` shortlists |
| `coastline-recommend --config C --input I --output O` | CSV → CSV (driven by YAML config) | output CSV (one row per workload) | Production batch; config declares safeguards (`feasibility`, `max_slowdown`) |
| `coastline-enrich-trace` | fine-tuning trace CSV | enriched CSV | Add Coastline predictions to an existing trace |
| `coastline-plot-trace` | enriched trace CSV | HTML / PNG plots | Visualise a trace after enrichment |
| `make gui` | — | FastAPI dashboard on `:8000` | Interactive UI + REST API for exploration and integration testing (dev checkout) |

See `docs/usage.py` (batch API walkthrough), `docs/demo_usage/` (facade + CSV examples), and `examples/` (config + workload CSVs) for runnable examples.

## Use it — Python facade

```python
import coastline

rec = coastline(throughput_estim="Kavier")     # or "tabpfn", "intelligent", a model name
results = rec(
    {"llm_model": "mistral-7b-v0.1", "fine_tuning_method": "lora",
     "gpu_model": "NVIDIA-A100-SXM4-80GB", "tokens_per_sample": 1024, "batch_size": 32},
    total_gpus=[1, 2, 4, 8], preset="balanced",   # multi-objective weighting
)
print(results[0])     # best-ranked Recommendation
```

First arg is a `WorkloadSpec`, a dict of its fields, or a CSV path. `preset` (`balanced`/`performance`/`energy`) or explicit `alpha`/`beta` set the trade-off; pass `context=SystemContext(...)` or let one be derived from the workload + `max_gpus`.

## Use it — batch CSV → CSV

Feed a config (strategy + predictors + grid + **safeguards**) and an input CSV of workloads; get one recommended config per row.

```bash
coastline-recommend --config examples/batch_config.yaml \
                    --input examples/workloads.csv --output recommendations.csv
```
```python
import coastline
coastline.recommend_csv("examples/batch_config.yaml", "workloads.csv", "out.csv")
```

Input columns are flexible (`model_name`/`llm_model`, `method`/`peft`, …); remap arbitrary headers via `input.columns`. Two config-driven safeguards: `predictors.feasibility: autoconf` (OOM-aware) and `strategy.max_slowdown` (never recommend a config slower than N× the fastest feasible one). See `examples/batch_config.yaml`.

## Use it — CLI / API

```bash
make recommend          # python -m coastline_recommender.engine --config config/coastline_functionality/config.yaml
make gui                # FastAPI dashboard on http://127.0.0.1:8000 (dev checkout)
coastline-recommend --help   # batch CSV→CSV console entry
```

## Architecture

| Package            | Role | Shipped in the wheel |
|--------------------|------|----------------------|
| `coastline`        | Public facade + batch CSV→CSV + CLI (the deployment surface) | yes |
| `coastline_recommender` | Engine — grid → feasibility → simulate → rank pipeline + predictors | yes |
| `coastline_common` | Shared models (`WorkloadSpec`, `SystemContext`, `Recommendation`) | yes |
| `coastline_recommender/.../data_driven/trainer` | Offline ML-model training | yes |
| `benchmark`        | Predictor evaluation suite | no (dev only) |
| `api`              | FastAPI service | no (dev only) |

The published wheel ships only the three `coastline*` packages (the engine). The
`api`, `benchmark`, `scripts`, and `models` directories are development/research
tooling and are excluded from the distribution.

## Test

```bash
make test         # full suite
make recq         # recommendation quality vs the ground-truth trace
```

## Docker

One image, multiple entrypoints. AutoConf OOM feasibility is enforced by default (installed from PyPI via the `autoconf` extra).

```bash
docker compose up --build api                # serve the dashboard on :8000
docker compose run --rm recommender          # one-shot recommendation
docker compose --profile dev run --rm dev    # run the test suite in a container
```

## External dependencies (not vendored)

- **Kavier** — analytical throughput/power model; PyPI dependency (`kavier>=0.4,<0.5`). Dev override: `pip install -e ../kavier`.
- **OpenDC** — optional Java simulator for the `energy: opendc` path; point `OPENDC_BIN_PATH` at a built runner. Not needed for the default Kavier-power energy.
- **ML pickles** — the data-driven predictors load trained artifacts from a `models/` directory next to the install root; these are **not bundled** in the published wheel. Retrain them with the trainer package, or point the predictors at your own artifacts (e.g. `TABPFN_MODEL_PATH` for TabPFN). The default Kavier (physics) path needs no pickles.
