Skip to content

About

Self-hosted app where a data science team agrees, field by field, on how to prepare a tabular dataset for ML, then exports model-ready data, trains models and tracks runs in MLflow.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🌲 Rainforest

Rainforest is a self-hosted web app for preparing wide, mixed-type tabular data for machine learning, on your own or as a team. Upload a CSV or Parquet file, and Rainforest profiles every column and suggests how to prepare it, with the evidence for each suggestion. You review the fields, agree on the decisions and freeze them as a versioned baseline. Rainforest then builds model-ready Parquet from the baseline, trains models on it, and logs every run to MLflow.

Reviewing a field: its profile, distribution and suggested settings, with the reasons

Why use it

Much of a tabular model's quality is decided while its data is prepared: which columns to keep, what a missing value means, how to encode a code. Those choices usually live in one person's notebook. When someone else picks the data up, or the model is retrained a year later, nobody can say exactly how the data was prepared, or why.

Rainforest makes data preparation reviewed, recorded and repeatable:

  • Every field gets looked at. Each column gets a profile, its distribution, its strongest associations and a suggested decision, so the 150th field of a wide file gets the same care as the first.
  • Suggestions explain themselves. Each one names its evidence, such as 97% of values are missing. Fields that could leak the target are flagged before they reach a model.
  • Agreement is part of the process. Several people assess the same fields without seeing each other's choices, so nobody anchors on the first opinion. What they agree on is adopted, and only the disagreements need a discussion.
  • A baseline exports the same way every time. A finalized baseline is frozen. Every export and model run records the baseline it came from, and every change to the team's decisions is logged with who made it.
  • Preparation matches the model. Trees baselines never scale or log-transform, and leave missing values for the model to route. Linear and Neural baselines get their own defaults.
  • Exports are leakage-safe. The rows are split first. The preprocessing is fitted on the training rows only, then applied to every row.
  • Training is in the same place. Train and compare models on an export without writing code, and open any run in MLflow. You can also download the export, its fitted preprocessor and the trained models for your own code.
  • It runs on your own hardware. Docker Compose runs the app, Postgres and MLflow on a machine you control, and your data stays there.

Rainforest is built for data science teams who need to agree on, and record, how a dataset is prepared. It works solo too: you are the owner and the only assessor, and you still get the suggestions, the leak checks, the frozen baselines and the tracked runs.

How it works

Upload → Assess → Team review → Finalize baseline → Experiment → Export → Train

The screenshots below use the real datasets that ship with Rainforest.

1. Upload

Upload a CSV or Parquet file, or add one of the sample datasets. Rainforest loads it into Postgres, profiles every column and suggests a decision for each field. The Datasets page shows where each dataset stands and what is waiting on you. A team whose data lives in Postgres, S3 or MongoDB can instead save a connection and pull a table, query, file or collections into a dataset with Pull from…, then pull again later (see Pulled datasets).

The Datasets page: cards for the work waiting on you, then every dataset with its stage, targets, assessment progress and best model

Home: the work waiting on you, the queue's state and the latest finished runs

2. Assess

An owner sets up the dataset's baseline: its model type, targets and assessors. Each assessor then works through the fields on their own, keeping, dropping or retyping each one and checking its settings. Fields · Focus, at the top of this page, walks the fields one at a time with keyboard shortcuts. Fields · Table filters the fields and changes many at once.

Fields · Table: the Unreviewed preset, with bulk actions for every matching field

An assessment is private until everyone has submitted. The owner sees each assessor's progress, never their choices.

The Baseline tab while assessing: your own progress, each assessor's progress, and what happens next

3. Team review

When the last assessor submits, the fields everyone agreed on are adopted. The rest form a review queue, with every assessor's choice and notes side by side and a discussion. An owner settles each field, then finalizes.

Team review: three assessors disagree on whether to keep the weight field, with their notes and a discussion beside the team decision

4. Finalize, experiment and train

Finalizing freezes the decisions as a numbered baseline version, such as Trees v1. An owner changes it later by starting a new version. Anyone who can contribute to the project can start an experiment from the baseline, and adjust the experiment's copy without touching the baseline. An export splits the rows, fits the preprocessing on the training rows and writes Parquet. You train a chain of models on it, one per target, and compare the runs with their metrics, charts and MLflow links.

An experiment's split plan says where each part's rows come from, so a whole source can be held out as the test set. Build training data from several datasets with a composition (see Data composition).

The split plan builder: parts, the sources that feed them, and the overlap check

An experiment's runs: four tree models compared on the test split, beside the chosen XGBoost run's metrics and confusion matrix

Watch the queue

Every background step is a job on one queue: processing, exports, training runs, analyses, refreshes. Jobs shows what is running with its progress, what waits and in which order, and what finished; an admin or a project's owner can stop, pause, reorder and reprioritize jobs, and anyone can stop their own. Home opens on the work waiting on you and the queue's state.

The Jobs page: a running export with its progress, the queued jobs in order, and the finished ones with their outcome

Register, serve and score

A finished run, or the runs of a batch, becomes a version of a registered model: a self-contained copy that outlives its run, export and dataset. An endpoint serves a version at POST /predict/<slug> for callers with a key, and you can switch it to another version or roll back. A version can also score a whole dataset or file in the background, make a new dataset from the result, and be evaluated against labelled data. Each endpoint has monitoring: calls, errors, latency, the classes it answers and how far live inputs have drifted.

The Models page: registered models with their latest version, endpoints and tags

An endpoint: its version, keys, a form to try it, and monitoring of its requests

Notebooks

On Kubernetes, every member gets a JupyterLab of their own, with a rainforest Python client already connected, the app's data mounted read-only and a Python environment that matches the one models are trained with. See Notebooks.

Notebooks: a running Lab with its CPU, memory and storage, and the Labs you can start

Find things and keep order

Tag datasets, compositions and models with free words and filter the lists by them. A Lineage panel on a dataset, a composition, an export, a run, a version or an endpoint shows what it came from and what was made from it. Settings › Storage (admins) shows what the data volume holds by kind and the largest items, and Clean up… removes exports and old scoring results nothing uses, after a dry run lists them. Settings › API tokens makes the tokens scripts use. Ctrl/Cmd+K searches datasets, models, endpoints, jobs and runs.

Settings · Storage: the data volume by kind, the largest items with what uses them, the retention settings and the last clean-ups

Explore at any point

Explore shows a dataset's correlations, a 2-D map of its rows coloured by the target, a test of each field against the target, and feature importance. A feature study asks which fields a model needs, and writes what it finds on the fields as evidence, which you can apply as a bulk change. Fields · SQL is a read-only SQL console over the data and the decisions.

Explore · Study: a feature study ranking the fields by permutation importance, with a suggestion and the evidence beside each

What's included

  • Type inference for every column: numeric, categorical, binary, text, date, identifier or constant, with a confidence and the reasons.
  • Several targets at once. Each target is predicted as classes, a number or bands, and each model in the chain also learns from the predictions for the targets before it.
  • Models: LightGBM, XGBoost (CPU or NVIDIA GPU), scikit-learn's histogram GBM and random forest, logistic and ridge regression, and an MLP, with cross-validation and parameter sweeps.
  • Batches: one model per class of a target, each calibrated and thresholded, or a search over a model's settings with a ranked leaderboard (see Batches).
  • Serving: a registry of models and versions, each a self-contained copy of finished runs; endpoints that answer POST /predict/<slug> with a key, switch versions and roll back; batch scoring that can make a dataset; evaluations and comparisons on labelled data; and request monitoring (see Serving).
  • Compositions and split plans that build training data from several datasets and hold a whole source out as a test set, with a check for rows shared between parts (see Data composition).
  • Class policy, sentinels, data quality and dataset compare for cleaning a target's classes and missing-value codes, and for setting one dataset against another.
  • Derived fields computed from a dataset's own fields, such as a ratio or a grouping of codes.
  • Notebooks on Kubernetes: a JupyterLab per member with the rainforest client (see Notebooks).
  • Tags, lineage and storage: free-word tags on datasets, compositions and models; a lineage panel on the things made from each other; a storage report and a safe clean-up.
  • API tokens for scripts and notebooks, acting as their owner.
  • Sign-in by picking a profile, or with OIDC for teams, and projects with four roles (owner, contributor, reviewer, viewer) and instance admins.

Quick start

You need Docker with Compose v2, make, at least 6 GB of free RAM, and disk space of about 2–3× the files you upload. See Sizing.

git clone https://github.com/LikelyCause/rainforest.git && cd rainforest
cp .env.example .env    # then set POSTGRES_PASSWORD
make up                 # builds and starts everything; the first build takes a few minutes

Important

Set POSTGRES_PASSWORD before the first make up. Postgres reads it only when it creates its data volume, so changing it later has no effect.

Open http://localhost:8080 (or the Docker host's address; UI_PORT sets the port) and pick the Admin profile. MLflow is at /mlflow/; MLFLOW_BROWSE_URL points every MLflow link at another address instead.

Warning

The default sign-in mode doesn't authenticate: anyone who reaches the page can pick any profile, an admin's included. Use it alone or on a trusted network. Teams should use OIDC; see Sign-in.

Try it

This uses the Concrete strength sample, which predicts a concrete's strength from its mix, with you as the only assessor.

  1. On Datasets, choose Add a sample ▾ → Real datasets and add Concrete strength. Open it when it's ready.
  2. At Set up the first baseline, keep the defaults (Trees, the suggestions, the target strength_mpa, and you as the only assessor) and choose Start Trees baseline v1.
  3. In Fields, step through the fields and read Why these suggestions. Press A to accept a suggestion and move on.
  4. Choose Submit assessment at the top right, then Finalize Trees v1. With one assessor there is nothing to settle.
  5. Choose New experiment from v1, name it, and choose Export for trees models.
  6. On Train, choose Train (LightGBM is the default). The run appears on Runs, with a link to it in MLflow.

The empty Datasets page also offers a generated 50k × 150 demo, and you can upload your own CSV or Parquet file.

Deploying

Setup Use when How
Solo / demo One person, or a trusted network make up with the defaults
Team with OIDC Several people, real sign-in RAINFOREST_AUTH_MODE=oidc and your provider's settings in .env; see the checklist
Reference Keycloak Trying OIDC (development only) make up-keycloak; see Reference Keycloak
GPU XGBoost on an NVIDIA GPU make up-gpu; see GPU
Kubernetes One release per team on a cluster, with Postgres and MLflow in the release or external, and notebook Labs the Helm chart in deploy/chart/rainforest; see deploy/README.md

On Compose everything is configured in .env; on Kubernetes, in the chart's values. Configuration lists every setting. The stack runs six containers (and the optional Keycloak and MongoDB profiles):

Service What it does
ui nginx serving the React app; proxies /api/ to the API and /mlflow/ to MLflow
api FastAPI: the app's API; queues background jobs; keeps files on the appdata volume
worker The API's image running the queued jobs (profiling, exports, training, analyses, scoring, builds), one process each; the container that gets the GPU
serve The API's image answering POST /predict/<slug> from versions' bundles; nginx routes /predict/ to it
db Postgres 16: app metadata (meta.*), each dataset's rows (raw.ds_<id>), and MLflow's runs
mlflow MLflow tracking server, with model artifacts on the mlartifacts volume

Useful commands:

Command Purpose
make up / make down Start everything / stop it, keeping the data
make logs Follow the API's and the job worker's logs
make train EXPORT=<id> Train on an export from the command line (MODEL=, DEVICE= optional)
make psql Open psql as the database owner
make test-db Run the API tests against a throwaway Postgres
make lint / make format Lint, or format, the API and the UI
make clean Stop everything and delete all data volumes

The Makefile has the rest.

Documentation

License

Rainforest is released under the MIT License.

The five sample datasets under Add a sample ▾ → Real datasets come from the UCI Machine Learning Repository and are used under CC BY 4.0:

Dataset Rows × columns Targets Source
Diabetes readmission 101,766 × 50 readmitted (3 classes) Clore, Cios, DeShazo & Strack (2014), doi:10.24432/C5230J
Student grades 649 × 33 G1, G2, G3 (grades 0–20) Cortez (2008), doi:10.24432/C5TG7T
Student dropout 4,424 × 37 Target (dropout, enrolled, graduate) Realinho, Vieira Martins, Machado & Baptista (2021), doi:10.24432/C5MC89
Steel plate faults 1,941 × 34 seven yes/no fault types Buscema, Terzi & Tastle (2010), doi:10.24432/C5J88N
Concrete strength 1,030 × 9 strength_mpa (a number) Yeh (1998), doi:10.24432/C5PK67

About

Self-hosted app where a data science team agrees, field by field, on how to prepare a tabular dataset for ML, then exports model-ready data, trains models and tracks runs in MLflow.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages