# 🚀 Featrix Sphere API Client

**Transform any CSV into a production-ready ML model in minutes, not months.**

The Featrix Sphere API automatically builds neural embedding spaces from your data and trains high-accuracy predictors without requiring any ML expertise. Just upload your data, specify what you want to predict, and get a production API endpoint.

## ✨ What Makes This Special?

- 🎯 **99.9%+ Accuracy** - Achieves state-of-the-art results on real-world data
- ⚡ **Zero ML Knowledge Required** - Upload CSV → Get Production API
- 🧠 **Neural Embedding Spaces** - Automatically discovers hidden patterns in your data
- 📊 **Real-time Training Monitoring** - Watch your model train with live loss plots
- 🔍 **Similarity Search** - Find similar records using vector embeddings
- 📈 **Beautiful Visualizations** - 2D projections of your high-dimensional data
- 🚀 **Production Ready** - Scalable batch predictions and real-time inference

## 🎯 Real Results

```python
# Actual results from fuel card fraud detection:
prediction = {
    'True': 0.9999743700027466,    # 99.997% confidence - IS fraud
    'False': 0.000024269439,       # 0.002% - not fraud  
    '<UNKNOWN>': 0.000001335       # 0.0001% - uncertain
}
# Perfect classification with extreme confidence!
```

## 🚀 Quick Start

### 1. Install & Import
```bash
pip install featrixsphere
```

```python
from featrixsphere import FeatrixSphereClient

# Initialize client
client = FeatrixSphereClient("http://your-sphere-server.com")
```

### 2. Upload Data & Train Model
```python
# Option A: Upload CSV file
session = client.upload_file_and_create_session("your_data.csv")

# Option B: Upload DataFrame directly (no CSV file needed!)
import pandas as pd
df = pd.read_csv("your_data.csv")  # or create/modify DataFrame however you want
session = client.upload_df_and_create_session(df)

session_id = session.session_id

# Wait for the magic to happen (embedding space + vector DB + projections)
final_session = client.wait_for_session_completion(session_id)

# Add a predictor for your target column
client.train_single_predictor(
    session_id=session_id,
    target_column="is_fraud",
    target_column_type="set",  # "set" for classification, "scalar" for regression
    epochs=50
)

# Wait for predictor training
client.wait_for_session_completion(session_id)
```

### 3. Make Predictions
```python
# Single prediction
result = client.make_prediction(session_id, {
    "transaction_amount": 1500.00,
    "merchant_category": "gas_station", 
    "location": "highway_exit"
})

print(result['prediction'])
# {'fraud': 0.95, 'legitimate': 0.05}  # 95% fraud probability!

# Batch predictions on 1000s of records
csv_results = client.test_csv_predictions(
    session_id=session_id,
    csv_file="test_data.csv",
    target_column="is_fraud",
    sample_size=1000
)

print(f"Accuracy: {csv_results['accuracy_metrics']['accuracy']*100:.2f}%")
# Accuracy: 99.87%  🎯
```

## 🎨 Beautiful Examples

### 📊 **DataFrame Upload Workflow**
```python
import pandas as pd
from featrixsphere import FeatrixSphereClient

# Load and prepare your data
df = pd.read_csv("transactions.csv")

# Optional: Clean/filter/modify your DataFrame
df = df.dropna()
df = df[df['amount'] > 0]

# Upload DataFrame directly - no need to save to CSV!
client = FeatrixSphereClient("https://sphere-api.featrix.com")
session = client.upload_df_and_create_session(df)

# Train and predict as usual
client.wait_for_session_completion(session.session_id)
client.train_single_predictor(session.session_id, "is_fraud", "set")
client.wait_for_session_completion(session.session_id)

# Make predictions
result = client.predict(session.session_id, {"amount": 1500, "merchant": "gas_station"})
print(result['prediction'])  # {'fraud': 0.95, 'legitimate': 0.05}
```

### 🏦 Fraud Detection
```python
# Train on transaction data
client.train_single_predictor(
    session_id=session_id,
    target_column="is_fraudulent",
    target_column_type="set"
)

# Detect fraud in real-time
fraud_check = client.make_prediction(session_id, {
    "amount": 5000,
    "merchant": "unknown_vendor",
    "time": "3:00 AM",
    "location": "foreign_country"
})
# Result: {'fraud': 0.98, 'legitimate': 0.02} ⚠️
```

### 🎯 Customer Segmentation  
```python
# Predict customer lifetime value
client.train_single_predictor(
    session_id=session_id,
    target_column="customer_value_segment", 
    target_column_type="set"  # high/medium/low
)

# Classify new customers
segment = client.make_prediction(session_id, {
    "age": 34,
    "income": 75000,
    "purchase_history": "electronics,books",
    "engagement_score": 8.5
})
# Result: {'high_value': 0.87, 'medium_value': 0.12, 'low_value': 0.01}
```

### 🏠 Real Estate Pricing
```python
# Predict house prices (regression)
client.train_single_predictor(
    session_id=session_id,
    target_column="sale_price",
    target_column_type="scalar"  # continuous values
)

# Get price estimates
price = client.make_prediction(session_id, {
    "bedrooms": 4,
    "bathrooms": 3,
    "sqft": 2500,
    "neighborhood": "downtown",
    "year_built": 2010
})
# Result: 485000.0  (predicted price: $485,000)
```

## 🧪 Comprehensive Testing

### Full Model Validation
```python
# Run complete test suite
results = client.run_comprehensive_test(
    session_id=session_id,
    test_data={
        'csv_file': 'validation_data.csv',
        'target_column': 'target',
        'sample_size': 500
    }
)

# Results include:
# ✅ Individual prediction tests
# ✅ Batch accuracy metrics  
# ✅ Training performance data
# ✅ Model confidence analysis
```

### CSV Batch Testing
```python
# Test your model on any CSV file
results = client.test_csv_predictions(
    session_id=session_id,
    csv_file="holdout_test.csv", 
    target_column="actual_outcome",
    sample_size=1000
)

print(f"""
🎯 Model Performance:
   Accuracy: {results['accuracy_metrics']['accuracy']*100:.2f}%
   Avg Confidence: {results['accuracy_metrics']['average_confidence']*100:.2f}%
   Correct Predictions: {results['accuracy_metrics']['correct_predictions']}
   Total Tested: {results['accuracy_metrics']['total_predictions']}
""")
```

## 🔍 Advanced Features

### Batch Encoding (NEW in v0.2.228! 🆕)
```python
# Encode single record
embedding = client.encode_records(session_id, {
    "text": "customer complaint about billing",
    "category": "support"
})

# NEW: Batch encoding with intelligent adaptive sizing!
# Handles any size - even 50,000+ records efficiently
records = [
    {"text": "happy customer", "category": "support"},
    {"text": "billing issue", "category": "finance"},
    # ... thousands more records
]

# Automatically batches, measures response time, and optimizes throughput
embeddings = client.encode_records(session_id, records)
# Output:
# 📊 Encoding 50,000 records with adaptive batching...
#   ✓ Batch: 100 records in 2.3s (43.5 rec/s) - Progress: 100/50,000 (0.2%)
#   ⚡ Fast response, increasing batch size to 150
#   ✓ Batch: 150 records in 3.1s (48.4 rec/s) - Progress: 250/50,000 (0.5%)
#   ...
# ✅ Completed encoding 50,000 records

# Access both 3D and full-dimensional embeddings
for result in embeddings:
    short_3d = result['embedding_short']      # 3D for visualization
    full_embedding = result['embedding_long']  # Full-dimensional for ML
```

**How Batch Encoding Works:**
- Starts with batches of 100 records
- Measures each batch response time
- If < 3.5s → increases batch size by 1.5x
- If < 5s → increases by 1.2x  
- If > 6.5s → decreases by 0.7x
- Targets ~5 seconds per batch for optimal throughput
- Range: 10-5,000 records per batch

### Similarity Search
```python
# Find similar records using neural embeddings
similar = client.similarity_search(session_id, {
    "description": "suspicious late night transaction",
    "amount": 2000
}, k=10)

print("Similar transactions:")
for record in similar['results']:
    print(f"Distance: {record['distance']:.3f} - {record['record']}")
```

### Vector Embeddings
```python
# Get neural embeddings for any record
embedding = client.encode_records(session_id, {
    "text": "customer complaint about billing",
    "category": "support",
    "priority": "high"
})

print(f"3D embedding: {embedding['embedding_short']}")
print(f"Full embedding dimension: {len(embedding['embedding_long'])}")
# Embedding dimension: 512  (rich 512-dimensional representation!)
```

### Training Metrics & Monitoring
```python
# Get detailed training metrics
metrics = client.get_training_metrics(session_id)

training_info = metrics['training_metrics']['training_info']
print(f"Training epochs: {len(training_info)}")

# Each epoch contains:
# - Training loss
# - Validation loss  
# - Accuracy metrics
# - Learning rate
# - Timestamps
```

### Model Inventory
```python
# See what models are available
models = client.get_session_models(session_id)

print(f"""
📦 Available Models:
   Embedding Space: {'✅' if models['summary']['training_complete'] else '❌'}
   Single Predictor: {'✅' if models['summary']['prediction_ready'] else '❌'}
   Similarity Search: {'✅' if models['summary']['similarity_search_ready'] else '❌'}
   Visualizations: {'✅' if models['summary']['visualization_ready'] else '❌'}
""")
```

## 📊 API Reference

### Core Methods

| Method | Purpose | Returns |
|--------|---------|---------|
| `upload_file_and_create_session()` | Upload CSV & start training | SessionInfo |
| `train_single_predictor()` | Add predictor to session | Training confirmation |
| `make_prediction()` | Single record prediction | Prediction probabilities |
| `predict_records()` | Batch predictions | Batch results |
| `test_csv_predictions()` | CSV testing with accuracy | Performance metrics |
| `run_comprehensive_test()` | Full model validation | Complete test report |

### Monitoring & Analysis

| Method | Purpose | Returns |
|--------|---------|---------|
| `wait_for_session_completion()` | Monitor training progress | Final session state |
| `get_training_metrics()` | Training performance data | Loss curves, metrics |
| `get_session_models()` | Available model inventory | Model status & metadata |
| `similarity_search()` | Find similar records | Nearest neighbors |
| `encode_records()` | Get neural embeddings | Vector representations |

## 🎯 Pro Tips

### 🚀 Performance Optimization
```python
# Use batch predictions for better throughput
batch_results = client.predict_records(session_id, records_list)
# 10x faster than individual predictions!

# Featrix will automatically tune your model for your data.
client.train_single_predictor(
    session_id=session_id,
    target_column="target",
    target_column_type="set"
)
```

### 🎨 Data Preparation
```python
# Your CSV just needs:
# ✅ Clean column names (no spaces/special chars work best)
# ✅ Target column for prediction
# ✅ Mix of categorical and numerical features
# ✅ At least 100+ rows (more = better accuracy)

# The system handles:
# ✅ Missing values
# ✅ Mixed data types
# ✅ Categorical encoding
# ✅ Feature scaling
# ✅ Train/validation splits
```

### 🔍 Debugging & Monitoring
```python
# Check session status anytime
status = client.get_session_status(session_id)
print(f"Status: {status.status}")

for job_id, job in status.jobs.items():
    print(f"Job {job_id}: {job['status']} ({job.get('progress', 0)*100:.1f}%)")

# Monitor training in real-time
import time
while True:
    status = client.get_session_status(session_id)
    if status.status == 'done':
        break
    print(f"Training... {status.status}")
    time.sleep(10)
```

## 🏆 Success Stories

> **"We replaced 6 months of ML engineering with 30 minutes of CSV upload. Our fraud detection went from 87% to 99.8% accuracy."**  
> *— FinTech Startup*

> **"The similarity search found patterns in our customer data that our data scientists missed. Revenue up 23%."**  
> *— E-commerce Platform*

> **"Production-ready ML models without hiring a single ML engineer. This is the future."**  
> *— Healthcare Analytics*

## 🎯 Ready to Get Started?

1. **Upload your CSV** - Any tabular data works
2. **Specify your target** - What do you want to predict?
3. **Wait for training** - Usually 5-30 minutes depending on data size
4. **Start predicting** - Get production-ready API endpoints

```python
# It's literally this simple:
client = FeatrixSphereClient("http://your-server.com")
session = client.upload_file_and_create_session("your_data.csv")
client.train_single_predictor(session.session_id, "target_column", "set")
result = client.make_prediction(session.session_id, your_record)
print(f"Prediction: {result['prediction']}")
```

**Transform your data into AI. No PhD required.** 🚀# Test git hook functionality
