Featrix Skills Reference for AI Agents

Quick-reference guide for AI agents using Featrix. Each skill is a complete, copy-paste workflow.

Installation

pip install featrixsphere

Core Pattern

All Featrix workflows follow this pattern:

from featrixsphere.api import FeatrixSphere
featrix = FeatrixSphere()

# 1. Create Foundational Model (learns data structure)
fm = featrix.create_foundational_model(data_file="data.csv")
fm.wait_for_training()

# 2. Create Predictor (trains on target)
predictor = fm.create_binary_classifier(target_column="target")
predictor.wait_for_training()

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

---

Skill: Binary Classification

When to use: Predicting yes/no, true/false, fraud/legitimate, churn/retain

from featrixsphere.api import FeatrixSphere
featrix = FeatrixSphere()

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

predictor = fm.create_binary_classifier(
    target_column="is_fraud",
    rare_label_value="fraud"  # Specify the minority class
)
predictor.wait_for_training()

# Predict
result = predictor.predict({"amount": 500, "merchant": "gas_station"})
print(f"Class: {result.predicted_class}")
print(f"Confidence: {result.confidence:.1%}")
print(f"Probabilities: {result.probabilities}")

With cost optimization (for asymmetric costs like fraud):

predictor = fm.create_binary_classifier(
    target_column="is_fraud",
    rare_label_value="fraud",
    cost_false_negative=5000,  # Cost of missing fraud
    cost_false_positive=10     # Cost of false alarm
)

---

Skill: Multi-class Classification

When to use: Predicting one of several categories (sentiment, product category, risk tier)

from featrixsphere.api import FeatrixSphere
featrix = FeatrixSphere()

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

predictor = fm.create_multi_classifier(target_column="category")
predictor.wait_for_training()

result = predictor.predict({"description": "laptop computer", "price": 999})
print(f"Category: {result.predicted_class}")
print(f"All probabilities: {result.probabilities}")

---

Skill: Regression (Numeric Prediction)

When to use: Predicting numbers (price, revenue, quantity, age)

from featrixsphere.api import FeatrixSphere
featrix = FeatrixSphere()

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

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

result = predictor.predict({"bedrooms": 3, "sqft": 1500, "location": "suburban"})
print(f"Predicted price: ${result.prediction:,.0f}")

---

Skill: Batch Prediction

When to use: Predicting many records at once

import pandas as pd
from featrixsphere.api import FeatrixSphere

featrix = FeatrixSphere()
fm = featrix.foundational_model("existing-session-id")
predictor = fm.list_predictors()[0]

# From list of dicts
records = [
    {"col1": "a", "col2": 1},
    {"col1": "b", "col2": 2},
    {"col1": "c", "col2": 3}
]
results = predictor.batch_predict(records, show_progress=True)

# From DataFrame
df = pd.read_csv("test_data.csv")
results = predictor.batch_predict(df, show_progress=True)

# From CSV file
results = predictor.predict_csv_file("test_data.csv", show_progress=True)

# Process results
for r in results:
    print(f"{r.predicted_class}: {r.confidence:.1%}")

---

Skill: Similarity Search

When to use: Finding similar records, recommendations, deduplication

from featrixsphere.api import FeatrixSphere
featrix = FeatrixSphere()

fm = featrix.create_foundational_model(data_file="products.csv")
fm.wait_for_training()

# Create vector database
vdb = fm.create_vector_database()

# Add records (if not in training data)
vdb.add_records([
    {"name": "Widget A", "category": "tools", "price": 29.99},
    {"name": "Widget B", "category": "tools", "price": 34.99}
])

# Search
query = {"name": "Socket Wrench", "category": "tools"}
similar = vdb.similarity_search(query, k=5)

for match in similar:
    print(f"Similarity: {match['similarity']:.3f}")
    print(f"Record: {match['record']}")

---

Skill: Feature Importance / Explainability

When to use: Understanding why a prediction was made

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

print(f"Prediction: {result.predicted_class}")
print("Top contributors:")
for feature, importance in sorted(
    result.feature_importance.items(),
    key=lambda x: abs(x[1]),
    reverse=True
)[:5]:
    direction = "+" if importance > 0 else ""
    print(f"  {feature}: {direction}{importance:.3f}")

---

Skill: Send Feedback (Ground Truth)

When to use: After you know the actual outcome, to improve future models

# After prediction
result = predictor.predict(transaction)
prediction_uuid = result.prediction_uuid  # Save this!

# Later, when you know the truth
featrix.prediction_feedback(
    prediction_uuid=prediction_uuid,
    ground_truth="fraud"  # or "legitimate", or actual numeric value
)

---

Skill: Deploy to Production API

When to use: Creating a REST endpoint for predictions

# Create endpoint
endpoint = predictor.create_api_endpoint(
    name="fraud_detector_v1",
    description="Real-time fraud detection"
)

print(f"URL: {endpoint.url}")
print(f"API Key: {endpoint.api_key}")

# Use endpoint
result = endpoint.predict(
    {"amount": 500, "merchant": "gas_station"},
    api_key=endpoint.api_key
)

# Raw HTTP (from any language)
import requests
response = requests.post(
    f"{endpoint.url}/predict",
    headers={"X-API-Key": endpoint.api_key},
    json={"amount": 500, "merchant": "gas_station"}
)

---

Skill: Resume Existing Model

When to use: Working with a previously trained model

from featrixsphere.api import FeatrixSphere
featrix = FeatrixSphere()

# Get existing Foundational Model
fm = featrix.foundational_model("20250115-143022_abc123")

# List its predictors
predictors = fm.list_predictors()
for p in predictors:
    print(f"{p.id}: {p.target_column} ({p.target_type})")

# Get specific predictor
predictor = featrix.predictor(
    predictor_id="sp_xyz789",
    foundational_model_id="20250115-143022_abc123"
)

# Make predictions
result = predictor.predict({"col1": "value"})

---

Skill: Handle Warnings / Guardrails

When to use: Input data might be unusual or out-of-distribution

result = predictor.predict(record)

if result.guardrails:
    print("Input warnings:")
    for column, warning in result.guardrails.items():
        print(f"  {column}: {warning}")
    # Proceed with caution - prediction may be unreliable

if result.ignored_query_columns:
    print(f"Unknown columns ignored: {result.ignored_query_columns}")

---

Skill: Check Training Progress

When to use: Monitoring long-running training jobs

fm = featrix.create_foundational_model(data_file="large_data.csv")

# Non-blocking status check
while not fm.is_ready():
    info = fm.refresh()
    print(f"Status: {info.get('status')}")
    time.sleep(30)

# Or blocking with progress
fm.wait_for_training(
    max_wait_time=7200,      # 2 hours max
    poll_interval=30,         # Check every 30s
    show_progress=True        # Print updates
)

---

Skill: Ignore Columns

When to use: Exclude IDs, timestamps, or irrelevant columns

fm = featrix.create_foundational_model(
    data_file="data.csv",
    ignore_columns=[
        "customer_id",      # IDs leak information
        "transaction_id",
        "created_at",       # Timestamps often leak
        "updated_at",
        "notes"             # Free text you don't want
    ]
)

---

Skill: Separate Labels File

When to use: Labels are in a different file than features

# Features in one file, labels in another
fm = featrix.create_foundational_model(data_file="features.csv")
fm.wait_for_training()

predictor = fm.create_binary_classifier(
    target_column="is_churn",
    labels_file="labels.csv"  # Must have matching row count
)
predictor.wait_for_training()

---

Skill: Get Model Card

When to use: Understanding what the model learned, for documentation

model_card = fm.get_model_card()

print("Columns:", model_card['columns'])
print("Excluded:", model_card['excluded_columns'])
print("Warnings:", model_card['warnings'])
print("Quality metrics:", model_card['quality_metrics'])

---

Skill: Visualize Embedding Space

When to use: Understanding data structure, creating figures

# In Jupyter notebook
notebook = featrix.get_notebook()

# Training loss curve
fig = notebook.training_loss(fm)

# 3D embedding space (interactive)
fig = notebook.embedding_space_3d(fm, color_by="category")

# Training animation
notebook.training_movie(fm)

---

Skill: Publish Model for Production

When to use: Protecting model from garbage collection, sharing across team

# Publish (protected from deletion)
fm.publish(org_id="my_company", name="fraud_model_v1")

# Later, unpublish
fm.unpublish()

# Mark as deprecated (warns users but still works)
fm.deprecate(
    warning_message="Use fraud_model_v2 instead",
    expiration_date="2025-06-01"
)

# Delete (marks for garbage collection)
fm.delete()

---

Skill: Configure Webhooks

When to use: Getting notified about training, drift, errors

predictor.configure_webhooks(
    training_started="https://slack.com/webhook/...",
    training_finished="https://slack.com/webhook/...",
    alert_drift="https://pagerduty.com/webhook/...",
    alert_performance_degradation="https://pagerduty.com/webhook/...",
    webhook_secret="my-secret-for-verification"
)

---

Error Handling Pattern

from featrixsphere.api import FeatrixSphere
import requests

featrix = FeatrixSphere()

try:
    fm = featrix.create_foundational_model(data_file="data.csv")
    fm.wait_for_training(max_wait_time=3600)

    predictor = fm.create_binary_classifier(target_column="target")
    predictor.wait_for_training()

    result = predictor.predict(record)

except TimeoutError:
    print("Training exceeded time limit")
except RuntimeError as e:
    print(f"Training failed: {e}")
except ValueError as e:
    print(f"Invalid input: {e}")
except requests.HTTPError as e:
    print(f"API error: {e}")

---

Quick Reference: Object Methods

FeatrixSphere

• create_foundational_model(...) - Train new model
• foundational_model(session_id) - Get existing model
• predictor(predictor_id, foundational_model_id) - Get existing predictor
• prediction_feedback(prediction_uuid, ground_truth) - Send feedback
• list_sessions(name_prefix) - Find models

FoundationalModel

• wait_for_training() - Block until ready
• is_ready() - Check status
• create_binary_classifier(target_column, ...) - Train classifier
• create_multi_classifier(target_column, ...) - Train multi-class
• create_regressor(target_column, ...) - Train regressor
• create_vector_database() - Create similarity search DB
• list_predictors() - Get all predictors
• get_model_card() - Get documentation
• publish(org_id, name) - Protect from deletion

Predictor

• wait_for_training() - Block until ready
• predict(record, feature_importance=False) - Single prediction
• batch_predict(records) - Multiple predictions
• predict_csv_file(path) - Predict from file
• create_api_endpoint(name) - Deploy to production
• configure_webhooks(...) - Set up alerts

PredictionResult

• .predicted_class - Predicted label
• .confidence - Confidence score (0-1)
• .probabilities - Full distribution
• .prediction_uuid - ID for feedback
• .guardrails - Input warnings
• .feature_importance - Explainability (if requested)