ffs — The Featrix Foundation Shell

Transform any CSV into a production-ready ML predictor from the command line.

Install

pip install featrix-shell

Setup

ffs login            # save API key to ./.featrix (project-local)
ffs login --global   # save API key to ~/.featrix (user-wide)
ffs whoami           # verify identity and connection
ffs upgrade          # upgrade featrix-shell and featrixsphere

Configuration

ffs looks for a .featrix file starting from the current directory and walking up to $HOME. This lets you use different API keys per project:

~/work/client-a/.featrix    <- ffs uses this key when you're in client-a/
~/work/client-b/.featrix    <- ffs uses this key when you're in client-b/
~/.featrix                  <- fallback for everything else

Search order:

1. FEATRIX_API_KEY environment variable (always wins)
2. .featrix in current directory
3. .featrix in each parent directory up to $HOME
4. ~/.featrix

The file is JSON:

{"api_key": "fx_..."}

CLI

ffs [global-options] <command> [subcommand] [options] [args]

Global Options

--server URL          API server (default: https://sphere-api.featrix.com)
--cluster NAME        Compute cluster
--json                Output raw JSON
--quiet               Minimal output

Getting help

ffs help                     List every command (also: ffs ?, ffs -h)
ffs help COMMAND             Help for one command, e.g. ffs help foundation predict
ffs COMMAND --help           The same thing

Authentication

ffs login [--global]                        Save API key (project-local or ~/.featrix)
ffs whoami                                  Show current user/org/connection
ffs upgrade                                 Upgrade featrix-shell and featrixsphere

Foundation (Foundational Models / Embedding Spaces)

ffs foundation create --name NAME --data FILE|URL [--epochs N] [--ignore-columns COL,COL] [--priority urgent|regular|low]
ffs foundation list [--prefix PREFIX]
ffs foundation show MODEL_ID
ffs foundation columns MODEL_ID
ffs foundation card MODEL_ID
ffs foundation wait MODEL_ID [--poll-interval N] [--timeout N]
ffs foundation jobs MODEL_ID
ffs foundation extend MODEL_ID --data FILE [--epochs N]
ffs foundation encode MODEL_ID RECORD_JSON [--short]
ffs foundation predict MODEL_ID COLUMN RECORD_JSON [--predictor-id ID] [--foundation] [--explain]
ffs foundation predict MODEL_ID COLUMN --file FILE
ffs foundation publish MODEL_ID [--name NAME] [--max-wait-time N] [--poll-interval N]
ffs foundation unpublish MODEL_ID
ffs foundation deprecate MODEL_ID --message MSG --expires DATE
ffs foundation cancel MODEL_ID --yes [--reason TEXT]
ffs foundation delete MODEL_ID

Predictors

ffs predictor create MODEL_ID --target-column COL --type {classifier,regressor} [--labels FILE] [--name NAME] [--epochs N] [--priority urgent|regular|low] [--fine-tune auto|frozen|progressive|wild_style] [--keep-duplicates] [--no-keep-duplicates]
ffs predictor list MODEL_ID
ffs predictor show MODEL_ID
ffs predictor cancel MODEL_ID --yes [--reason TEXT]

--fine-tune controls whether the foundation encoder keeps learning while the predictor trains. auto (the default) lets the server decide from the data: it unfreezes the encoder (progressive) when raw features measurably beat the frozen encoder, and keeps it frozen otherwise (small datasets stay frozen). --keep-duplicates trains on every row, counting exact duplicate rows as extra weight; --no-keep-duplicates trains on distinct rows only.

--priority urgent puts the job ahead of the organization's other pending jobs. It does not preempt one that is already running.

A predictor's status is its training job's status: queued means the job has not started, and only done means there is a model to predict with.

API Endpoints

An endpoint answers with one serving model; other versions can shadow it (same traffic, graded on the same ground truth, never answering). Retrains of auto-trained models shadow and are promoted automatically when they prove better.

ffs endpoint list                                                   List your endpoints
ffs endpoint create MODEL_ID --name NAME [--target COL] [--api-key KEY] [--description TEXT]
                                                                    Create an endpoint served by one of MODEL_ID's predictors
ffs endpoint bind MODEL_NAME                                        Serve a published model through an endpoint
ffs endpoint show ENDPOINT_ID                                       Serving model, shadows, serving-vs-shadow comparison
ffs endpoint stats ENDPOINT_ID                                      Calls made to the endpoint's predict URL
ffs endpoint shadow ENDPOINT_ID PREDICTOR_ID                        Evaluate a predictor on live traffic without serving it
ffs endpoint promote ENDPOINT_ID PREDICTOR_ID --yes                 Make a shadow the serving model now
ffs endpoint stop-shadowing ENDPOINT_ID PREDICTOR_ID                Stop mirroring traffic to a shadow
ffs endpoint regenerate-key ENDPOINT_ID --yes                       Rotate the API key
ffs endpoint revoke-key ENDPOINT_ID --yes                           Remove the API key (disables the endpoint)
ffs endpoint delete ENDPOINT_ID --yes                               Delete the endpoint

Events

ffs events list [--limit N] [--offset N]           List event groups registered for your org
ffs events show EVENT_GROUP_ID                     Show a group's live event count and last-trained info

Read-only queries over event groups fed by the separate featrixevents library (apps post events; ffs only queries them).

Jobs

ffs jobs list [--prefix NAME]                                        List sessions with jobs queued/running, org-wide
ffs jobs cancel-queued [MODEL_ID] --yes [--prefix NAME] [--reason TEXT]  Cancel queued (not yet running) jobs

PredictionNetworks

ffs network register NAME --spec-file FILE     Register or update a network's spec ({nodes, edges})
ffs network show NAME                          Show a registered network's spec
ffs network list                                List networks registered for your org
ffs network predict NAME RECORD_JSON            Run a network against one record
ffs network predict NAME --file FILE

Predict

ffs predict MODEL_ID '{"col": "val"}'                          Single prediction (JSON)
ffs predict MODEL_ID --file FILE [--target-column COL]         Batch (CSV, JSON, Parquet)
ffs predict MODEL_ID '{"col": "val"}' --explain                Include feature importance

Predictions fail loudly rather than returning empty results. A predictor is only servable once its train_single_predictor job has finished: while that job is queued (shown as queued, not ready), running, or after it died, the server answers with every field null. ffs predict and ffs foundation predict turn that into an error naming the job and its status — run ffs foundation jobs MODEL_ID for the full picture.

ffs foundation predict uses a trained predictor for the target column when there is one and the foundation model's probes otherwise; --foundation forces the foundation model either way. It never silently swaps one for the other.

Vector Database (not yet implemented)

ffs vectordb create MODEL_ID [--name NAME] [--records FILE]
ffs vectordb search MODEL_ID RECORD_JSON [-k N]

Server

ffs server health

Quick Start

# Login
ffs login

# Create a foundational model from CSV
ffs foundation create --name "customers" --data customers.csv

# Wait for foundation training
ffs foundation wait MODEL_ID

# Train a classifier on a target column
ffs predictor create MODEL_ID --target-column churned --type classifier

# Wait for predictor training (same wait command)
ffs foundation wait MODEL_ID

# Single prediction
ffs predict MODEL_ID '{"age": 35, "income": 50000}'

# Batch prediction from file
ffs predict MODEL_ID --file new_customers.csv

Architecture

• MODEL_ID = session_id in the Featrix Sphere API
• Wraps the featrixsphere OO API (FeatrixSphere, FoundationalModel)
• Built with Click + Rich