# Featrix — LLM/AI Agent Integration Guide

> This file helps AI agents understand how to install, configure, and program against the Featrix platform.

## What is Featrix?

Featrix is a machine learning platform that transforms tabular data (CSV files) into embedding spaces (called "foundations") and trains predictive neural functions on top of them — all without writing ML code.

## Installation

```bash
pip install featrix-shell
```

## Authentication Setup

You need a Featrix API key. Set it as an environment variable:

```bash
export FEATRIX_API_KEY="your-api-key-here"
```

Or persist it:

```bash
echo "FEATRIX_API_KEY=your-api-key-here" >> ~/.featrix
```

### Where to get an API key

1. Sign up at https://app.featrix.com
2. Navigate to Settings → API Keys
3. Create a new API key and copy it

## Quick Start — End to End

```bash
# 1. Create a foundation (embedding space) from your CSV data
ffs model create --name "my-data" --data my_data.csv

# 2. Wait for training to complete
ffs model wait <MODEL_ID>

# 3. Create a predictor (neural function) targeting a column
ffs predictor create <MODEL_ID> --target my_target_column --type set

# 4. Wait for predictor training
ffs model wait <MODEL_ID>

# 5. Make a prediction
ffs predict <MODEL_ID> '{"column_a": "value1", "column_b": 42}'

# 6. Batch predict from CSV
ffs predict <MODEL_ID> --file test_data.csv --target my_target_column
```

## Core Concepts

| Concept | Description |
|---------|-------------|
| **Foundation** (Embedding Space) | A neural model trained on your tabular data that learns relationships between all columns |
| **Predictor** (Neural Function) | A model trained on top of a foundation to predict a specific target column |
| **Prediction Types** | `set` (classification) or `scalar` (regression) |

## Key Commands

### Foundations

| Command | Description |
|---------|-------------|
| `ffs model create --name NAME --data FILE.csv` | Create a foundation from CSV data |
| `ffs model create --name NAME --data f1.csv,f2.csv` | Create from multiple CSVs (up to 3) |
| `ffs model list` | List all foundations |
| `ffs model show MODEL_ID` | Inspect a foundation |
| `ffs model columns MODEL_ID` | View columns and types |
| `ffs model wait MODEL_ID` | Block until training completes |
| `ffs model delete MODEL_ID` | Delete a foundation |

### Predictors

| Command | Description |
|---------|-------------|
| `ffs predictor create MODEL_ID --target COL --type set` | Create a classifier |
| `ffs predictor create MODEL_ID --target COL --type scalar` | Create a regressor |
| `ffs predictor list MODEL_ID` | List predictors for a foundation |
| `ffs predictor show MODEL_ID` | Inspect predictor details |
| `ffs predictor metrics MODEL_ID --predictor-id ID` | View predictor metrics |

### Predictions

| Command | Description |
|---------|-------------|
| `ffs predict MODEL_ID '{"col": "val"}'` | Single prediction (JSON input) |
| `ffs predict MODEL_ID --file data.csv --target COL` | Batch prediction from CSV |
| `ffs predict explain MODEL_ID '{"col": "val"}' --target COL` | Explain a prediction |

### Vector Database / Similarity Search

| Command | Description |
|---------|-------------|
| `ffs vectordb create MODEL_ID --name "search"` | Create vector DB from foundation |
| `ffs vectordb search MODEL_ID '{"col": "val"}' -k 10` | Find similar records |
| `ffs vectordb add MODEL_ID --records data.csv` | Add records to vector DB |

## Global Options

| Flag | Description |
|------|-------------|
| `--json` | Output raw JSON (useful for programmatic parsing) |
| `--quiet` | Minimal output |
| `--server URL` | Custom API server URL |

## Common Patterns for AI Agents

### Pattern 1: Train and predict from CSV

```bash
ffs model create --name "customers" --data customers.csv
ffs model wait <ID>
ffs predictor create <ID> --target churn --type set
ffs model wait <ID>
ffs predict <ID> --file new_customers.csv --target churn --json
```

### Pattern 2: Explore data relationships

```bash
ffs model create --name "explore" --data data.csv
ffs model wait <ID>
ffs model columns <ID>
ffs model encode <ID> '{"feature_a": 10}' --short
```

### Pattern 3: Similarity search

```bash
ffs model create --name "products" --data products.csv
ffs model wait <ID>
ffs vectordb create <ID> --name "product_search"
ffs vectordb search <ID> '{"category": "electronics", "price": 299}' -k 5
```

## Requirements

- Python 3.8+
- `pip install featrix-shell`
- A valid Featrix API key

## Links

- Web App: https://app.featrix.com
- Documentation: https://docs.featrix.com
- GitHub: https://github.com/featrix/ffs-ai-shell

## Notes for AI Agents

- All commands return structured output with `--json` flag
- `ffs model wait` is blocking — use it in sequential scripts
- Foundation training time depends on dataset size (minutes to hours)
- Predictions require both a trained foundation AND a trained predictor
- Column names in prediction JSON must match the training data columns
- Missing columns in prediction input are handled gracefully by the model