coastline-recommender 0.1.0

Context-aware GPU/datacenter configuration recommender for LLM fine-tuning

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

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

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.

coastline-recommend --config examples/batch_config.yaml \
                    --input examples/workloads.csv --output recommendations.csv

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

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

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).

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.