Featrix Cheatsheet¶

Minimal copy-paste patterns for AI agents.

Setup¶

from featrixsphere.api import FeatrixSphere
featrix = FeatrixSphere()

Train Model + Predictor¶

# From CSV
fm = featrix.create_foundational_model(data_file="data.csv")
fm.wait_for_training()

# Binary classification
predictor = fm.create_binary_classifier(target_column="is_fraud", rare_label_value="fraud")
predictor.wait_for_training()

# Multi-class classification
predictor = fm.create_multi_classifier(target_column="category")
predictor.wait_for_training()

# Regression
predictor = fm.create_regressor(target_column="price")
predictor.wait_for_training()

Predict¶

# Single
result = predictor.predict({"col1": "value", "col2": 123})
print(result.predicted_class, result.confidence)

# Batch
results = predictor.batch_predict([{"col1": "a"}, {"col1": "b"}])

# From CSV
results = predictor.predict_csv_file("test.csv")

Resume Existing¶

fm = featrix.foundational_model("session-id-here")
predictor = featrix.predictor("predictor-id", "session-id")

Deploy¶

endpoint = predictor.create_api_endpoint(name="my_api")
print(endpoint.url, endpoint.api_key)

Feedback¶

featrix.prediction_feedback(result.prediction_uuid, ground_truth="actual_value")

Similarity Search¶

vdb = fm.create_vector_database()
similar = vdb.similarity_search({"col1": "query"}, k=10)

Explainability¶

result = predictor.predict(record, feature_importance=True)
print(result.feature_importance)

Pick an Intent¶

Single highest-leverage knob. Full reference: intents.md.

# Binary
fm.create_binary_classifier(target_column="...", intent="catch_everything")            # recall ≥ 85%
fm.create_binary_classifier(target_column="...", intent="catch_everything_aggressive") # recall ≥ 95%
fm.create_binary_classifier(target_column="...", intent="only_alert_when_confident")   # precision-first
fm.create_binary_classifier(target_column="...", intent="rank")                        # AUC only, no threshold
fm.create_binary_classifier(target_column="...", intent="predict_probabilities")       # calibrated P(y=1|x)
fm.create_binary_classifier(target_column="...", intent="balanced")                    # default

# Multi-class
fm.create_multi_classifier(target_column="...", intent="balanced")     # macro-F1 (default)
fm.create_multi_classifier(target_column="...", intent="accuracy")     # raw top-1
fm.create_multi_classifier(target_column="...", intent="top_k_hit", k=3)
fm.create_multi_classifier(target_column="...", intent="rank_classes") # no argmax

# Regression
fm.create_regressor(target_column="...", intent="balanced")                # MSE / R² (default)
fm.create_regressor(target_column="...", intent="minimize_typical_error")  # Huber / MAE
fm.create_regressor(target_column="...", intent="minimize_worst_case")     # tail-weighted / RMSE
fm.create_regressor(target_column="...", intent="minimize_relative_error") # log-MSE / sMAPE (targets ≥ 0)

Tune the Floor / Target¶

# catch_everything family — override recall floor
fm.create_binary_classifier(
    target_column="is_fraud",
    intent="catch_everything",
    recall_floor=0.92,  # default 0.85 (catch_everything) / 0.95 (aggressive)
)

# only_alert — recall_floor (sweep constraint) + precision_target (autotuner objective) are independent
fm.create_binary_classifier(
    target_column="should_review",
    intent="only_alert_when_confident",
    recall_floor=0.4,        # accept recall as low as 40%
    precision_target=0.85,   # but push the model toward 85% precision
)

Cost-Sensitive (Fraud/Churn)¶

predictor = fm.create_binary_classifier(
    target_column="is_fraud",
    rare_label_value="fraud",
    intent="minimize_cost",   # auto-picked when cost_* is set, but be explicit
    cost_false_negative=5000,
    cost_false_positive=10
)

Ignore Columns¶

fm = featrix.create_foundational_model(
    data_file="data.csv",
    ignore_columns=["id", "timestamp", "notes"]
)

Check Result Properties¶

result.predicted_class    # "fraud" or "legitimate"
result.prediction         # raw value (float for regression)
result.confidence         # 0.0 to 1.0
result.probabilities      # {"fraud": 0.9, "legitimate": 0.1}
result.prediction_uuid    # for feedback
result.guardrails         # {"col": "warning"} if input unusual
result.feature_importance # {"col": 0.5, ...} if requested

Check Model Properties¶

fm.status      # "training", "done", "error"
fm.columns     # ["col1", "col2", ...]
fm.dimensions  # embedding size

predictor.status    # "training", "done", "error"
predictor.accuracy  # 0.0 to 1.0
predictor.auc       # ROC-AUC score

Error Handling¶

try:
    fm.wait_for_training(max_wait_time=3600)
except TimeoutError:
    print("Training timed out")
except RuntimeError as e:
    print(f"Training failed: {e}")