<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->

# API Reference — Building Machine Learning Detections

## Agent Tools

| Tool | Description |
|---|---|
| Train Model | `train_model(data_path, model_type, target_col)` — Train an ML detection model on security telemetry. |
| Evaluate Model | `evaluate_model(model_path, test_data)` — Evaluate model performance metrics. |
| Predict | `predict(model_path, input_data)` — Run inference on new telemetry data. |

## CLI Usage

```bash
# Train model
node agent.js train --data-path data/auth_logs.json --model-type isolation_forest --target-col is_anomaly
```

```bash
# Evaluate
node agent.js evaluate --model-path models/auth_anomaly.pkl --test-data data/test_set.json
```

```bash
# Predict
node agent.js predict --model-path models/auth_anomaly.pkl --input-data data/live_events.json
```

## Output Format

All commands return JSON with the following structure:

```json
{
  "action": "<command_name>",
  "...": "command-specific fields"
}
```

## Error Handling

- Invalid input returns `{"error": "description"}` with non-zero exit code
- JSON parsing errors are caught and reported with context
- Missing required arguments trigger argparse help display
