{
  "openapi": "3.0.3",
  "info": {
    "title": "Luviner AI API",
    "description": "13 specialized neural engines for time-series anomaly detection, classification, and synthetic industrial failure data generation. No GPU required. Sub-millisecond inference.",
    "version": "1.0.0",
    "contact": {
      "name": "Luviner",
      "email": "info@luviner.com",
      "url": "https://luviner.com"
    }
  },
  "servers": [
    {
      "url": "https://luviner.com/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/engines": {
      "get": {
        "summary": "List all 13 AI engines",
        "description": "Returns the catalog of all available Luviner neural engines with their specializations, tier, and best-use-cases.",
        "operationId": "listEngines",
        "tags": ["Catalog"],
        "responses": {
          "200": {
            "description": "Array of engine objects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Engine"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/failure-modes": {
      "get": {
        "summary": "List 12 industrial failure types",
        "description": "Returns all available failure modes for synthetic data generation: mechanical, thermal, electrical, and process faults.",
        "operationId": "listFailureModes",
        "tags": ["Catalog"],
        "responses": {
          "200": {
            "description": "Array of failure mode objects",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/FailureMode"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/train/anomaly": {
      "post": {
        "summary": "Train anomaly detector",
        "description": "Train a one-class anomaly detector on NORMAL data only. The model learns what normal looks like — any future input deviating from normal is flagged as anomalous. Returns a model_id for inference.",
        "operationId": "trainAnomaly",
        "tags": ["Training"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrainAnomalyRequest"
              },
              "example": {
                "data": [[0.1, 0.2, 0.3], [0.15, 0.22, 0.28], [0.12, 0.19, 0.31]],
                "engine": "v4",
                "epochs": 30
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Training result with model_id",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TrainResult"
                }
              }
            }
          }
        }
      }
    },
    "/train/classifier": {
      "post": {
        "summary": "Train multi-class classifier",
        "description": "Train a supervised classifier on labeled data. Returns a model_id and accuracy score.",
        "operationId": "trainClassifier",
        "tags": ["Training"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TrainClassifierRequest"
              },
              "example": {
                "data": [[0.1, 0.2], [0.9, 0.8], [0.15, 0.18], [0.85, 0.9]],
                "labels": [0, 1, 0, 1],
                "engine": "lnn",
                "epochs": 50,
                "class_names": ["healthy", "faulty"]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Training result with model_id and accuracy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClassifierTrainResult"
                }
              }
            }
          }
        }
      }
    },
    "/predict/anomaly": {
      "post": {
        "summary": "Score samples for anomalies",
        "description": "Score one or more samples using a trained anomaly detector. Returns per-sample anomaly scores and binary predictions.",
        "operationId": "predictAnomaly",
        "tags": ["Inference"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PredictAnomalyRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Anomaly scores and predictions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AnomalyResult"
                }
              }
            }
          }
        }
      }
    },
    "/predict": {
      "post": {
        "summary": "Classify samples",
        "description": "Classify one or more samples using a trained classifier. Returns per-sample predictions with confidence scores.",
        "operationId": "predict",
        "tags": ["Inference"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PredictRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Classification results",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClassifyResult"
                }
              }
            }
          }
        }
      }
    },
    "/root-cause": {
      "post": {
        "summary": "Anomaly root cause analysis",
        "description": "Explain WHY a sample is anomalous — identifies which input features contributed most to the anomaly score.",
        "operationId": "rootCause",
        "tags": ["Inference"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RootCauseRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Root cause attribution",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RootCauseResult"
                }
              }
            }
          }
        }
      }
    },
    "/synthetic/generate": {
      "post": {
        "summary": "Generate synthetic failure data",
        "description": "Generate realistic synthetic anomaly data for a specific industrial failure mode. Supports 12 failure types across mechanical, thermal, electrical, and process categories. Faults evolve progressively over time for realism.",
        "operationId": "generateSynthetic",
        "tags": ["Synthetic Data"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateSyntheticRequest"
              },
              "example": {
                "failure_mode": "bearing_degradation",
                "n_features": 4,
                "n_samples": 100,
                "severity": 1.0,
                "seed": 42
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated samples with metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SyntheticResult"
                }
              }
            }
          }
        }
      }
    },
    "/synthetic/dataset": {
      "post": {
        "summary": "Generate mixed labeled dataset",
        "description": "Generate a complete labeled dataset with multiple failure types plus normal data. Perfect for training multi-class fault classifiers.",
        "operationId": "generateDataset",
        "tags": ["Synthetic Data"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GenerateDatasetRequest"
              },
              "example": {
                "failure_modes": ["bearing_degradation", "thermal_runaway", "electrical_fault"],
                "n_features": 4,
                "n_samples_per_class": 50,
                "include_normal": true
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mixed dataset with labels",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DatasetResult"
                }
              }
            }
          }
        }
      }
    },
    "/models/{modelId}": {
      "get": {
        "summary": "Get model info",
        "operationId": "getModel",
        "tags": ["Models"],
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Model metadata"
          }
        }
      },
      "delete": {
        "summary": "Delete model",
        "operationId": "deleteModel",
        "tags": ["Models"],
        "parameters": [
          {
            "name": "modelId",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          }
        ],
        "responses": {
          "200": {
            "description": "Model deleted"
          }
        }
      }
    },
    "/usage": {
      "get": {
        "summary": "View API usage stats",
        "description": "Returns current month's API call count, plan limits, and feature access.",
        "operationId": "getUsage",
        "tags": ["Account"],
        "responses": {
          "200": {
            "description": "Usage statistics",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UsageResult"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API token from your Luviner dashboard (Settings > API Access)"
      }
    },
    "schemas": {
      "Engine": {
        "type": "object",
        "properties": {
          "key": { "type": "string", "example": "v4" },
          "name": { "type": "string", "example": "Vivi 4" },
          "tier": { "type": "string", "enum": ["base", "premium"] },
          "best_for": { "type": "string" },
          "strengths": { "type": "array", "items": { "type": "string" } }
        }
      },
      "FailureMode": {
        "type": "object",
        "properties": {
          "key": { "type": "string", "example": "bearing_degradation" },
          "name": { "type": "string", "example": "Bearing Degradation" },
          "category": { "type": "string", "enum": ["mechanical", "thermal", "electrical", "process"] },
          "description": { "type": "string" },
          "default_parameters": { "type": "object" }
        }
      },
      "TrainAnomalyRequest": {
        "type": "object",
        "required": ["data"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "type": "array", "items": { "type": "number" } },
            "description": "2D array of NORMAL samples (min 5 rows)"
          },
          "engine": { "type": "string", "default": "v4", "description": "Engine key from /engines" },
          "hidden_size": { "type": "integer", "default": 48 },
          "n_layers": { "type": "integer", "default": 2 },
          "epochs": { "type": "integer", "default": 30 },
          "contamination": { "type": "number", "default": 0.05 }
        }
      },
      "TrainClassifierRequest": {
        "type": "object",
        "required": ["data", "labels"],
        "properties": {
          "data": {
            "type": "array",
            "items": { "type": "array", "items": { "type": "number" } }
          },
          "labels": {
            "type": "array",
            "items": { "type": "integer" }
          },
          "engine": { "type": "string", "default": "lnn" },
          "hidden_size": { "type": "integer", "default": 48 },
          "n_layers": { "type": "integer", "default": 2 },
          "epochs": { "type": "integer", "default": 50 },
          "class_names": { "type": "array", "items": { "type": "string" } }
        }
      },
      "TrainResult": {
        "type": "object",
        "properties": {
          "model_id": { "type": "string", "example": "f329f1f4" },
          "engine": { "type": "string" },
          "n_features": { "type": "integer" },
          "n_samples_trained": { "type": "integer" },
          "hidden_size": { "type": "integer" },
          "status": { "type": "string", "example": "ready" }
        }
      },
      "ClassifierTrainResult": {
        "type": "object",
        "properties": {
          "model_id": { "type": "string" },
          "engine": { "type": "string" },
          "accuracy": { "type": "number" },
          "n_features": { "type": "integer" },
          "n_classes": { "type": "integer" },
          "total_params": { "type": "integer" }
        }
      },
      "PredictAnomalyRequest": {
        "type": "object",
        "required": ["model_id", "samples"],
        "properties": {
          "model_id": { "type": "string" },
          "samples": {
            "type": "array",
            "items": { "type": "array", "items": { "type": "number" } }
          }
        }
      },
      "AnomalyResult": {
        "type": "object",
        "properties": {
          "engine": { "type": "string" },
          "total_samples": { "type": "integer" },
          "anomalies_found": { "type": "integer" },
          "threshold": { "type": "number" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "anomaly_score": { "type": "number" },
                "is_anomaly": { "type": "boolean" },
                "label": { "type": "string" }
              }
            }
          }
        }
      },
      "PredictRequest": {
        "type": "object",
        "required": ["model_id", "samples"],
        "properties": {
          "model_id": { "type": "string" },
          "samples": {
            "type": "array",
            "items": { "type": "array", "items": { "type": "number" } }
          }
        }
      },
      "ClassifyResult": {
        "type": "object",
        "properties": {
          "engine": { "type": "string" },
          "total_samples": { "type": "integer" },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "prediction": { "type": "integer" },
                "class_name": { "type": "string" },
                "confidence": { "type": "number" },
                "is_certain": { "type": "boolean" }
              }
            }
          }
        }
      },
      "RootCauseRequest": {
        "type": "object",
        "required": ["model_id", "sample"],
        "properties": {
          "model_id": { "type": "string" },
          "sample": { "type": "array", "items": { "type": "number" } },
          "feature_names": { "type": "array", "items": { "type": "string" } }
        }
      },
      "RootCauseResult": {
        "type": "object",
        "properties": {
          "engine": { "type": "string" },
          "anomaly_score": { "type": "number" },
          "is_anomaly": { "type": "boolean" },
          "top_contributors": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "feature": { "type": "string" },
                "contribution": { "type": "number" }
              }
            }
          }
        }
      },
      "GenerateSyntheticRequest": {
        "type": "object",
        "required": ["failure_mode", "n_features"],
        "properties": {
          "failure_mode": { "type": "string", "example": "bearing_degradation" },
          "n_features": { "type": "integer", "example": 4 },
          "n_samples": { "type": "integer", "default": 100 },
          "severity": { "type": "number", "default": 1.0, "description": "0.5=mild, 1.0=medium, 2.0=severe" },
          "normal_data": {
            "type": "array",
            "items": { "type": "array", "items": { "type": "number" } },
            "description": "Optional normal reference data for realism"
          },
          "seed": { "type": "integer", "description": "Random seed for reproducibility" }
        }
      },
      "SyntheticResult": {
        "type": "object",
        "properties": {
          "failure_mode": { "type": "string" },
          "failure_name": { "type": "string" },
          "category": { "type": "string" },
          "severity": { "type": "number" },
          "n_samples": { "type": "integer" },
          "n_features": { "type": "integer" },
          "samples": {
            "type": "array",
            "items": { "type": "array", "items": { "type": "number" } }
          },
          "labels": { "type": "array", "items": { "type": "integer" } }
        }
      },
      "GenerateDatasetRequest": {
        "type": "object",
        "required": ["failure_modes", "n_features"],
        "properties": {
          "failure_modes": { "type": "array", "items": { "type": "string" } },
          "n_features": { "type": "integer" },
          "n_samples_per_class": { "type": "integer", "default": 50 },
          "severity": { "type": "number", "default": 1.0 },
          "include_normal": { "type": "boolean", "default": true },
          "seed": { "type": "integer" }
        }
      },
      "DatasetResult": {
        "type": "object",
        "properties": {
          "total_samples": { "type": "integer" },
          "n_classes": { "type": "integer" },
          "label_names": { "type": "object" },
          "samples": {
            "type": "array",
            "items": { "type": "array", "items": { "type": "number" } }
          },
          "labels": { "type": "array", "items": { "type": "integer" } }
        }
      },
      "UsageResult": {
        "type": "object",
        "properties": {
          "plan": { "type": "string" },
          "calls_used": { "type": "integer" },
          "calls_limit": { "type": "integer", "nullable": true },
          "resets_at": { "type": "string", "format": "date-time" },
          "features": { "type": "object" }
        }
      }
    }
  },
  "tags": [
    { "name": "Catalog", "description": "Browse available engines and failure modes" },
    { "name": "Training", "description": "Train anomaly detectors and classifiers" },
    { "name": "Inference", "description": "Score samples and classify data" },
    { "name": "Synthetic Data", "description": "Generate realistic industrial failure data" },
    { "name": "Models", "description": "Manage trained models" },
    { "name": "Account", "description": "Usage and billing" }
  ]
}