Initial commit: Solar PV Predictive Maintenance API

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,15 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Environments
+.env
+.venv/
+
+# IDE
+.vscode/
+
+# OS
+.DS_Store
+Thumbs.db

Dockerfile

@@ -0,0 +1,20 @@
+# Minimal production-ready Dockerfile for Solar PV PdM API
+FROM python:3.9-slim
+
+# Create non-root user for security
+RUN useradd -m -u 1000 user
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+# Install dependencies
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy app code
+COPY --chown=user . /app
+
+EXPOSE 7860
+
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -0,0 +1,50 @@
+---
+title: Solar PV Predictive Maintenance
+emoji: ☀️
+colorFrom: yellow
+colorTo: orange
+sdk: docker
+app_port: 7860
+pinned: false
+---
+
+# Solar PV Predictive Maintenance API
+
+AI-powered predictive maintenance for solar PV inverters using ML models and LLM-based diagnosis.
+
+## API Endpoints
+
+### POST /analyze
+Accepts voltage and current sensor data, returns ML predictions and agent diagnosis.
+
+**Request:**
+```json
+{
+  "vdc1": [600.0, 601.0, 602.0],
+  "idc1": [10.0, 10.1, 10.2]
+}
+```
+
+**Response:**
+```json
+{
+  "ml_output": {
+    "asset_id": "PV_INVERTER_001",
+    "failure_probability": 0.12,
+    "expected_ttf_days": 450.5,
+    "expected_rul_days": 9800.0,
+    "confidence": 0.85
+  },
+  "agent_output": {
+    "diagnosis": "...",
+    "urgency": "Low",
+    "recommended_action": "...",
+    "justification": ["..."]
+  }
+}
+```
+
+## ML Pipeline
+- **Anomaly Detection**: Isolation Forest + LSTM Autoencoder
+- **Failure Forecasting**: XGBoost (Time-to-Failure + Failure Probability)
+- **Agent Reasoning**: Gemini 2.5 Flash Lite via LangChain

agent/agent.py

@@ -0,0 +1,40 @@
+import json
+from langchain_google_genai import GoogleGenerativeAI
+
+class MaintenanceAgent:
+    def __init__(self, api_key, model_name="gemini-2.5-flash-lite", temperature=0.0):
+        self.llm = GoogleGenerativeAI(
+            model=model_name,
+            temperature=temperature,
+            google_api_key=api_key
+        )
+
+    def run(self, phase2_output: dict) -> dict:
+        prompt = f"""
+You are a maintenance decision AI.
+You must reason ONLY from the provided JSON.
+Do NOT invent data.
+
+INPUT:
+{json.dumps(phase2_output, indent=2)}
+
+MANDATORY: Return output strictly in JSON format only. Do not include any markdown, code blocks, or extra text.
+
+OUTPUT FORMAT:
+{{
+  "diagnosis": "...",
+  "urgency": "Low | Medium | High",
+  "recommended_action": "...",
+  "justification": ["...", "..."]
+}}
+"""
+
+        response = self.llm.invoke(prompt)
+        try:
+            return json.loads(response)
+        except json.JSONDecodeError:
+            import re
+            match = re.search(r'```json\s*(.*?)\s*```', response, re.DOTALL) or re.search(r'\{.*\}', response, re.DOTALL)
+            if match:
+                return json.loads(match.group(1) if '```' in response else match.group(0))
+            raise ValueError(f"Could not parse LLM response: {response[:200]}")

app.py

@@ -0,0 +1,68 @@
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+import pandas as pd
+import os
+import logging
+from dotenv import load_dotenv
+from ml.inference import MLEngine
+from agent.agent import MaintenanceAgent
+
+load_dotenv()
+logging.basicConfig(level=logging.INFO)
+
+app = FastAPI(title="Solar PV Predictive Maintenance API", version="1.0.0")
+
+# Load models once on startup for production performance
+ml_engine = MLEngine()
+agent = MaintenanceAgent(
+    api_key=os.getenv("GOOGLE_API_KEY"),
+    model_name="gemini-2.5-flash-lite",
+    temperature=0.0
+)
+
+class SensorData(BaseModel):
+    vdc1: list[float]
+    idc1: list[float]
+
+class AnalysisResponse(BaseModel):
+    ml_output: dict
+    agent_output: dict
+
+@app.post("/analyze", response_model=AnalysisResponse)
+async def analyze_sensor_data(data: SensorData):
+    try:
+        logging.info(f"Processing request with {len(data.vdc1)} voltage and {len(data.idc1)} current data points")
+        
+        if len(data.vdc1) != len(data.idc1):
+            raise HTTPException(status_code=400, detail="Voltage and current lists must have the same length")
+        
+        if len(data.vdc1) < 3:
+            raise HTTPException(status_code=400, detail="Need at least 3 data points")
+        
+        # Repeat to make at least 100 points if needed
+        raw_df = pd.DataFrame({
+            "vdc1": (data.vdc1 * (100 // len(data.vdc1) + 1))[:100],
+            "idc1": (data.idc1 * (100 // len(data.idc1) + 1))[:100]
+        })
+        
+        # ML Inference
+        phase2_output = ml_engine.predict_from_raw(raw_df)
+        
+        # Agent Reasoning
+        agent_output = agent.run(phase2_output)
+        
+        return AnalysisResponse(ml_output=phase2_output, agent_output=agent_output)
+    
+    except HTTPException:
+        raise
+    except Exception as e:
+        logging.error(f"Error processing request: {e}")
+        raise HTTPException(status_code=500, detail=str(e))
+
+@app.get("/")
+async def root():
+    return {"message": "Solar PV Predictive Maintenance API", "endpoint": "/analyze (POST)"}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=7860)

data/phase2_output.json

@@ -0,0 +1,7 @@
+{
+  "asset_id": "PV_INVERTER_001",
+  "failure_probability": 0.0,
+  "expected_ttf_days": 10338.5,
+  "expected_rul_days": 10942.0,
+  "confidence": 1.0
+}

docker-compose.yml

@@ -0,0 +1,12 @@
+version: '3.8'
+
+services:
+  pdm-api:
+    build: .
+    ports:
+      - "7860:7860"
+    environment:
+      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
+    volumes:
+      - .:/app
+    command: uvicorn app:app --host 0.0.0.0 --port 7860 --reload

main.py

@@ -0,0 +1,32 @@
+import pandas as pd
+import os
+from dotenv import load_dotenv
+from ml.inference import MLEngine
+from agent.agent import MaintenanceAgent
+import numpy as np
+
+load_dotenv()
+
+raw_df = pd.DataFrame({
+    "vdc1": np.random.normal(600, 3, 200),
+    "idc1": np.random.normal(10.0, 0.2, 200)
+})
+
+
+engine = MLEngine()
+phase2_output = engine.predict_from_raw(raw_df)
+
+print("\n=== ML OUTPUT ===")
+print(phase2_output)
+
+# ---- LLM AGENT ----
+agent = MaintenanceAgent(
+    api_key=os.getenv("GOOGLE_API_KEY"),
+    model_name="gemini-2.5-flash-lite",
+    temperature=0.0
+)
+
+agent_output = agent.run(phase2_output)
+
+print("\n=== AGENT OUTPUT ===")
+print(agent_output)

ml/artifacts/lstm_autoencoder.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:82d18871f0809d8d26332184f269943ea757df9529a535fa031314877c7eefb0
+size 26232

ml/artifacts/ml_config.json

@@ -0,0 +1,16 @@
+{
+  "feature_cols": [
+    "vdc_mean",
+    "vdc_std",
+    "pdc_mean",
+    "pdc_std",
+    "pdc_delta",
+    "pdc_slope",
+    "efficiency_norm"
+  ],
+  "window": 50,
+  "seq_len": 30,
+  "downsample": 10,
+  "failure_horizon_days": 30,
+  "design_life_days": 10958
+}

ml/artifacts/scaler.json

@@ -0,0 +1,20 @@
+{
+  "mean": [
+    142.25967157616776,
+    3.5676508560940654,
+    635.9378633904394,
+    16.520853955427857,
+    1.1263708972285581e-07,
+    1.271437542337093e-07,
+    1.0000000011260433
+  ],
+  "scale": [
+    135.83560758590238,
+    9.960201153946878,
+    867.4447952608547,
+    72.25659454825748,
+    22.465312616553394,
+    3.96862260102056,
+    8.867862393270387e-07
+  ]
+}

ml/features.py

@@ -0,0 +1,27 @@
+import numpy as np
+import pandas as pd
+
+def build_features(df, window):
+    df = df.copy()
+
+    df["pdc1"] = df["vdc1"] * df["idc1"]
+
+    df["vdc_mean"] = df["vdc1"].rolling(window).mean()
+    df["vdc_std"]  = df["vdc1"].rolling(window).std()
+
+    df["pdc_mean"] = df["pdc1"].rolling(window).mean()
+    df["pdc_std"]  = df["pdc1"].rolling(window).std()
+
+    df["pdc_delta"] = df["pdc1"].diff()
+
+    df["pdc_slope"] = df["pdc1"].rolling(window).apply(
+        lambda x: np.polyfit(range(len(x)), x, 1)[0],
+        raw=False
+    )
+
+    df["efficiency"] = df["pdc1"] / (df["vdc1"] * df["idc1"] + 1e-6)
+    df["efficiency_norm"] = (
+        df["efficiency"] / df["efficiency"].rolling(window).mean()
+    )
+
+    return df

ml/inference.py

@@ -0,0 +1,123 @@
+import json
+import os
+import joblib
+import torch
+import numpy as np
+import pandas as pd
+from sklearn.preprocessing import StandardScaler
+from sklearn.ensemble import IsolationForest
+from safetensors.torch import load_file
+
+from ml.features import build_features
+from ml.lstm_model import LSTMAutoencoder
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+ARTIFACTS_DIR = os.path.join(BASE_DIR, "artifacts")
+
+class MLEngine:
+    def __init__(self):
+        with open(os.path.join(ARTIFACTS_DIR, "ml_config.json")) as f:
+            self.config = json.load(f)
+
+        self.feature_cols = self.config["feature_cols"]
+        self.window = self.config["window"]
+        self.seq_len = self.config["seq_len"]
+        self.design_life_days = self.config["design_life_days"]
+
+        # Load scaler from JSON
+        with open(os.path.join(ARTIFACTS_DIR, "scaler.json"), "r") as f:
+            params = json.load(f)
+        self.scaler = StandardScaler()
+        self.scaler.mean_ = np.array(params["mean"])
+        self.scaler.scale_ = np.array(params["scale"])
+        self.scaler.var_ = self.scaler.scale_ ** 2
+        self.scaler.n_features_in_ = len(self.scaler.mean_)
+
+        # Retrain IsolationForest at startup using saved training data
+        self.iso = IsolationForest(
+            n_estimators=200,
+            contamination=0.05,
+            random_state=42
+        )
+        # Load training data (scaled features from Colab) and fit
+        train_data = pd.read_json(os.path.join(ARTIFACTS_DIR, "training_data.json"))
+        self.iso.fit(train_data[self.feature_cols])
+
+        # Load XGBoost from JSON
+        import xgboost as xgb
+        self.ttf_model = xgb.XGBRegressor()
+        self.ttf_model.load_model(os.path.join(ARTIFACTS_DIR, "xgb_ttf.json"))
+        self.fail_model = xgb.XGBClassifier()
+        self.fail_model.load_model(os.path.join(ARTIFACTS_DIR, "xgb_fail.json"))
+
+        # Load LSTM from safetensors
+        self.lstm = LSTMAutoencoder(
+            input_dim=len(self.feature_cols),
+            hidden_dim=32
+        )
+        state_dict = load_file(os.path.join(ARTIFACTS_DIR, "lstm_autoencoder.safetensors"))
+        self.lstm.load_state_dict(state_dict)
+        self.lstm.eval()
+
+    def predict_from_raw(self, raw_df: pd.DataFrame):
+        # --- Feature engineering ---
+        df = build_features(raw_df, self.window)
+        df = df[self.feature_cols].dropna()
+
+        if len(df) < self.seq_len:
+            raise ValueError("Not enough data for LSTM sequence")
+
+        # --- Scaling ---
+        df_scaled = pd.DataFrame(
+            self.scaler.transform(df),
+            columns=self.feature_cols,
+            index=df.index
+        )
+
+        # --- Isolation Forest anomaly ---
+        df_scaled["anomaly_iforest"] = -self.iso.decision_function(df_scaled)
+
+        # --- LSTM anomaly ---
+        X = df_scaled[self.feature_cols].values
+        X_seq = np.array([X[-self.seq_len:]])
+
+        with torch.no_grad():
+            recon = self.lstm(torch.tensor(X_seq, dtype=torch.float32))
+
+        anomaly_lstm = float(((recon - torch.tensor(X_seq)) ** 2).mean())
+
+        # --- Health (0–1) ---
+        # Normalize anomaly_lstm (assuming max error ~1e6 from training)
+        anomaly_norm = min(anomaly_lstm / 1e6, 1.0)
+        health = max(0.0, 1.0 - anomaly_norm)
+
+        # --- ML predictions ---
+        latest_features = df_scaled[self.feature_cols].iloc[[-1]].copy()
+        latest_features["anomaly_lstm"] = anomaly_lstm
+        latest_features["health_index"] = health
+
+        expected_ttf_days = float(
+            self.ttf_model.predict(latest_features, validate_features=False)[0]
+        )
+
+        failure_probability = float(
+            self.fail_model.predict_proba(latest_features, validate_features=False)[0][1]
+        )
+
+        # --- RUL ---
+        expected_rul_days = float(health * self.design_life_days)
+
+        # --- Confidence ---
+        confidence = round(
+            0.5 * abs(failure_probability - 0.5) * 2
+            + 0.5 * health,
+            2
+        )
+
+        return {
+            "asset_id": "PV_INVERTER_001",
+            "failure_probability": round(failure_probability, 2),
+            "expected_ttf_days": round(expected_ttf_days, 1),
+            "expected_rul_days": round(expected_rul_days, 1),
+            "confidence": confidence
+        }

ml/lstm_model.py

@@ -0,0 +1,12 @@
+import torch.nn as nn
+
+class LSTMAutoencoder(nn.Module):
+    def __init__(self, input_dim, hidden_dim):
+        super().__init__()
+        self.encoder = nn.LSTM(input_dim, hidden_dim, batch_first=True)
+        self.decoder = nn.LSTM(hidden_dim, input_dim, batch_first=True)
+
+    def forward(self, x):
+        encoded, _ = self.encoder(x)
+        decoded, _ = self.decoder(encoded)
+        return decoded

requirements.txt

@@ -0,0 +1,11 @@
+langchain-google-genai
+python-dotenv
+joblib
+torch
+numpy
+pandas
+scikit-learn
+xgboost
+fastapi
+uvicorn
+safetensors