Skip to content

Predictive Studio

Train predictive models on a client’s own data — and score records with them — entirely inside MemberJunction. Member retention/renewal, lapse and lead scoring, and any other tabular yes/no-or-number question, answered by a model trained on their data.

Predictive Studio is core MJ, not an OpenApp. It is composed onto existing MJ substrates (entities/RunView, Record Set Processing, Remote Operations, Agents, vectors) plus a self-managing Python ML sidecar — rather than re-implementing batching, audit, training, or inference. This folder is the three npm packages that make that work.

Start here, then read the Predictive Studio Guide for the full architecture, the data model (MJ: ML Models / Experiments / …), the dashboard, and end-to-end walkthroughs. The design record is plans/predictive-studio.md.

Predictive Studio is one pipeline split across four layers. The first three live in TypeScript (this folder); the model-compute layer is a bundled Python service.

flowchart LR
    subgraph DATA["1 · Data"]
        D["Entities · Queries · External entities<br/>Vector sets · Feature Pipelines"]
    end
    subgraph FEATURE["2 · Feature"]
        F["AsOfFeatureAssembler<br/>(rows as of each decision date · typed columns · leakage exclusions)"]
    end
    subgraph MODEL["3 · Model (compute)"]
        M["MLSidecar → Python FastAPI<br/>xgboost · lightgbm · scikit-learn"]
    end
    subgraph INFER["4 · Inference"]
        I["MLModelInferenceProcessor<br/>(Record Set Processing work type)"]
    end
    D --> F --> M --> I
    M -. "immutable, versioned" .-> ML["MJ: ML Models"]
    ML --> I
LayerWhat happensLives in
1 · DataPull the training/scoring rows from MJ’s existing substrates@memberjunction/predictive-studio (feature-assembly/data-access)
2 · FeatureAssemble typed columns identically for training and scoring, reading every feature as of each Prediction Unit row’s decision date and keeping excluded fields out (AsOfFeatureAssembler); FeatureAssemblyExecutor still assembles score rows for models trained before Prediction Units@memberjunction/predictive-studio (feature-assembly)
3 · ModelThe CPU-bound protocol-driven training (/trainer) and inference (/predict) — Node orchestrates, Python computes@memberjunction/predictive-studio-sidecar (+ bundled Python)
4 · InferenceBatch + single-record scoring as a Record Set Processing work type, ephemeral or write-back@memberjunction/predictive-studio (scoring)

The cardinal correctness rule runs through all four: one feature-assembly code path per generation of model, used identically for training and scoring, plus encoding that is fit inside every training fit and only applied at scoring — so there is no train/serve skew by construction. Training itself is honest by construction: every pipeline trains under a versioned Prediction Unit (what a row is, its decision date, its label) and Evaluation Protocol (the locked holdout, the baselines, the gate), and the run stores a three-outcome decision (model, keep-simple-baseline, no-signal) with its reason.

PackageWhat it isRead
@memberjunction/predictive-studio-coreThe shared type contracts — the sidecar /trainer and /predict shapes, the Prediction Unit and Evaluation Protocol shapes, the gate and the trust verdict, the declarative pipeline spec, the visual FeatureStep DAG, the Model Development Agent’s ModelingPlanSpec, plus the zod runtime validators and the metric-direction helper. Defined once; imported by everything; importing (almost) nothing.Core/README.md
@memberjunction/predictive-studio-sidecarA self-managing TypeScript wrapper (MLSidecar) around a bundled Python FastAPI ML service. new MLSidecar(); await s.Start() and you have a live training/inference service — no Docker required (managed child-process spawn on an ephemeral port; remote-URL mode for scaled deployments).Sidecar/README.md
@memberjunction/predictive-studioThe server-side engine — AsOfFeatureAssembler, FeatureAssemblyExecutor, TrainingEngine, MLModelInferenceProcessor, ExperimentOrchestrator, plus feature-pipeline discovery, maintenance, and the Actions + Remote Operations invocation surfaces.Engine/README.md
predictive-studio-core (types — runtime deps: zod, @memberjunction/global)
│ imported by
├── predictive-studio-sidecar → MLSidecar + bundled Python service
└── predictive-studio (Engine) → the four engines + Actions + Remote Operations
│ which also depends on
└── predictive-studio-sidecar (MLSidecar)

Per root CLAUDE.md rule 5, types are imported directly from -core — never re-exported through -sidecar or the Engine.

One-time setup (fresh clone). Predictive Studio’s packages depend on other workspace packages, so build them together, never one by one (a per-package tsc on a fresh clone fails with TS2307 Cannot find module '@memberjunction/core'):

Terminal window
pnpm install # repo root
pnpm run build # repo root: builds PS and everything it depends on, in dependency order
pnpm --filter @memberjunction/predictive-studio-sidecar run setup:python

setup:python needs CPython 3.11 or 3.12 (numpy 1.26.4 has no wheels for 3.13+); it tries python3.11, python3.12, python3, python and stops with the list it probed if none fits. Pass -- --python <path> after the setup:python command to choose one. On macOS also brew install libomp (XGBoost/LightGBM). To run the sidecar or its tests on another interpreter, set PREDICTIVE_STUDIO_PYTHON=<path to python>.

The sidecar on its own, in TypeScript (the engine builds the TrainerRequest from a Training Snapshot for you):

import { MLSidecar } from '@memberjunction/predictive-studio-sidecar';
const sidecar = new MLSidecar(); // managed mode — spawns the bundled Python service
await sidecar.Start();
const trained = await sidecar.RunTrainer(/* TrainerRequest from @memberjunction/predictive-studio-core */);
const { predictions } = await sidecar.Predict(/* PredictRequest */);
await sidecar.Stop();

For the full path — pipeline bound to a Prediction Unit and an Evaluation Protocol → TrainingEngine → stored gate decision → immutable MJ: ML Models row (when the gate ships one) → MLModelInferenceProcessor scoring, plus the experiment search and the Studio dashboard — see the Engine README and the guide.

PackageCommandCovers
Core / Sidecar / Enginenpm run test (per package)Vitest unit tests — all seams mocked, no DB, no live process
Sidecar (Python)npm run test:python (after setup:python)pytest — the trainer contract, route and algorithms, /predict over legacy and ps-predictor/v2 artifacts, and the anti-skew encoding and preprocessing golden tests
Engine (live)npm run test:integration with PS_INTEGRATION=1A Prediction Unit pipeline trained end to end through the real managed Python sidecar trainer; skips gracefully if the venv is missing