# Migrating to the New FeatrixSphere API

## One Import, That's It

```python
from featrixsphere.api import FeatrixSphere
```

Everything else is returned by methods. No other imports needed.

## Before and After

**Old:**
```python
from featrixsphere import FeatrixSphereClient

client = FeatrixSphereClient()
session = client.upload_df_and_create_session(df, name="my_model")
client.wait_for_training(session.session_id)
client.train_single_predictor(session.session_id, target_column="target", target_column_type="binary")
result = client.predict(session.session_id, {"feature1": "value1"})
```

**New:**
```python
from featrixsphere.api import FeatrixSphere

featrix = FeatrixSphere()
fm = featrix.create_foundational_model(name="my_model", df=df)
fm.wait_for_training()
predictor = fm.create_binary_classifier(target_column="target")
predictor.wait_for_training()
result = predictor.predict({"feature1": "value1"})
print(result.predicted_class, result.confidence)
```

---

## Key Changes

| Old Way | New Way |
|---------|---------|
| Pass `session_id` everywhere | Methods return objects that know their IDs |
| `train_single_predictor()` | `fm.create_binary_classifier()` or `fm.create_regressor()` |
| `client.predict(session_id, ...)` | `predictor.predict(record)` |

---

## Common Tasks

### Create a model and predictor

```python
from featrixsphere.api import FeatrixSphere

featrix = FeatrixSphere()
fm = featrix.create_foundational_model(name="my_model", df=df)
fm.wait_for_training()

predictor = fm.create_binary_classifier(target_column="churned")
predictor.wait_for_training()
```

### Make predictions

```python
result = predictor.predict({"age": 35, "plan": "premium"})
print(result.predicted_class)
print(result.confidence)
```

### Batch predictions

```python
results = predictor.batch_predict(records)
for r in results:
    print(r.predicted_class, r.confidence)
```

### Load existing model

```python
fm = featrix.foundational_model("session-id-here")
predictors = fm.list_predictors()
predictor = predictors[0]
```

### Feature importance

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

### Prediction feedback

```python
result = predictor.predict(record)
# Later, when you know the true answer:
featrix.prediction_feedback(result.prediction_uuid, ground_truth="1")
```

### Embeddings

```python
embeddings = fm.encode(records)
```

### Vector search

```python
vdb = fm.create_vector_database(name="search", records=records)
similar = vdb.similarity_search(query_record, k=5)
```

---

## Projects

Scope your work to a project. The project is verified when you set it:

```python
# Set project at construction time
featrix = FeatrixSphere(project="my-project")

# Or set it later
featrix.set_current_project("my-project")
print(featrix.current_project)  # Full project info dict

# All subsequent creates are automatically scoped to this project
fm = featrix.create_foundational_model(name="model", data_file="data.csv")

# Clear when done
featrix.clear_current_project()
```

Projects are organizational tags, not access boundaries. A predictor in one project can reference a Foundational Model from another project — useful for sharing base models across teams.

---

## On-Premises

Same API, just point to your server:

```python
featrix = FeatrixSphere("https://your-server.com")
```

---

## Questions?

Contact support@featrix.ai
