# Training plans

{{% notice style="note" title="Limited access" icon="lock" %}}
{{% include file="include/restricted_access.md" hidefirstheading="true"  %}}
{{% /notice %}}

## What a training plan is

A **training plan** is a packaged answer to one question — *is this RADIUS session unusual for its APN?*,
*is this part defective?* — built and validated by the platform team and published in a catalogue. It bundles:

- the **algorithm** and the whole training recipe: how the data is cleaned, split, transformed, trained and
  evaluated;
- the **container image** that runs that recipe;
- the **data it needs**: which source types it accepts (a file, a time series, or either) and, for time
  series, the columns it expects to find;
- the **configuration** you must supply when you create a trainer — an APN, for example;
- the **minimum amount of data** below which a training is refused rather than producing a meaningless model;
- and, implicitly, the **inference contract** of the model it produces and the **rule** it creates to call it.

You do not modify a plan. You create a [trainer](../trainers/) that runs it, and the plan's own pages below tell
you what to feed it and what comes out.

## Listing the catalogue

```bash
curl --request GET \
     --header "X-ApiKey: <your-api-key>" \
     https://api.opengate.es/ai/trainingPlans
```

The catalogue is platform-wide, not per organization, and read-only through the API. Each entry:

```json
{
  "identifier": "6f1c2a4e-…",
  "name": "RADIUS anomalies per APN (Isolation Forest)",
  "description": "Detects anomalous data sessions of the subscriptions of one APN",
  "modelType": "anomaly",
  "modelFormat": "isolation-forest",
  "source": ["file", "timeserie"],
  "configFields": ["apn"],
  "columnData": [
    { "name": "APN", "type": "STRING", "description": "Access point name of the session" },
    { "name": "sbytes", "type": "LONG", "description": "Bytes sent by the device" }
  ],
  "minDataToTrain": { "value": 15000, "unit": "ITEMS" },
  "image": { "name": "trainingplan-if-radius-anomalies-per-apn", "tag": "1.0.0" }
}
```

| Field | Meaning | How you use it |
|---|---|---|
| `identifier` | The plan's id | `imageExecution.trainingPlan.identifier` when creating a trainer |
| `name`, `description` | What the plan does, for people | The console shows them in the plan picker |
| `modelType` | The family of problem: `anomaly`, `classification`… | Groups plans in the console |
| `modelFormat` | The algorithm: `isolation-forest`, `autoencoder`, `pytorch`… | Informative; it also names the registered model |
| `source` | The data source types the plan accepts: `file`, `timeserie` or both | Decides whether `source.path` or `source.timeserie` is allowed in the trainer |
| `configFields` | The configuration keys the plan needs | Every one of them must appear in `imageExecution.configuration` |
| `columnData` | The columns the plan expects in its input | For a time-series source, map each of them to a column of your time series |
| `minDataToTrain` | The minimum amount of data: a number of `ITEMS` (rows, images per class) or of `DAYS` | Below it, the training fails with an explicit message instead of producing a bad model |
| `image` | The container image and tag the scheduler runs | Informative |

## The plans available

{{% children sort="weight" description="true" %}}

The three plans share the same lifecycle, described in [How it works](../how_it_works/): what differs between
them is the data they take, the request their inferencer answers, and the rule they create.

| | RADIUS · Isolation Forest | RADIUS · Autoencoder | Image anomaly detection |
|---|---|---|---|
| Source types | file, time series | file, time series | file (a folder) |
| Input | RADIUS session records of one APN | RADIUS session records of one APN | Photos in `correct/` and `incorrect/` folders |
| Configuration | `apn` | `apn` | — |
| Inference request | `sbytes`, `dbytes`, `spkts`, `dpkts`, `dur` | `sbytes`, `dbytes`, `spkts`, `dpkts`, `dur` | `image_route`, `generate_heat_map` |
| Inference answer | `prediction`, `anomaly_score`, `explanation` | `prediction`, `anomaly_score`, `explanation` | `predictions`, `anomaly_score`, `heatmap_path` |
| Rule triggers on | GPRS presence turning `STOP` | GPRS presence turning `STOP` | A new `imagePathToCheck` value |
| Alarm | `deviceWithAnomaly` | `deviceWithAnomaly` | `imageWithAnomaly` |

## API specification

{{< openapi src="training_plans.yaml" >}}