Be Student Project

🚀 Insight Stack

A unified and lightweight stack designed for integrating MCP gateway, Insight backend, MySQL, and an optional OPC UA simulator.

This stack provides a comprehensive solution for:

• MCP gateway (FastAPI): Exposes database - backed tools and a local LLM (llama.cpp via llama - cpp - python) within the process.
• Insight backend (FastAPI): Offers anomaly scoring (LSTM - AE) and operator - facing explanations through MCP tools.
• MySQL: Stores the sensor schema (with read - only LLM user provisioning).
• OPC UA simulator (optional): Generates streaming values.

🚀 Quick Start

1. Prerequisite Checks

Ensure that Docker and Docker Compose are installed.

⚠️ Important Note

For Windows Users: If you are unable to run .ps1 scripts, you may need to set the execution policy. Run the following command in PowerShell:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Configuration: Copy the example environment file:

cp .env.example .env

To enable GPU support, please refer to the GPU Prerequisites guide.

2. Bootstrap Data & Model

Option A: Smart Scripts (Recommended) Automatically generates data, trains the model (detecting GPU if available), and avoids orphan container warnings.

Linux/Mac/Git Bash:

./bootstrap.sh

Windows PowerShell:

./bootstrap.ps1

Option B: Manual Docker Compose Run manually if you prefer explicitly defining flags.

docker compose -f compose.bootstrap.yml up --build

For GPU training:

docker compose -f compose.bootstrap.yml -f compose.bootstrap.gpu.yml up --build

3. Start the Stack

Option A: Smart Scripts (Recommended) Automatically detects GPU and includes the simulator.

Linux/Mac:

./start.sh

Windows:

./start.ps1

Option B: Manual Docker Compose

docker compose -f compose.yml -f compose.sim.yml up -d --build

For GPU Inference support:

docker compose -f compose.yml -f compose.gpu.yml -f compose.sim.yml up -d --build

✨ Features

• Unified architecture integrating multiple components for seamless operation.
• Anomaly scoring and explanations provided by the Insight backend.
• Local LLM integration for enhanced data processing.
• Optional OPC UA simulator for data generation.

📦 Installation

Prerequisites

• Docker and Docker Compose installed.

Configuration

Copy the example environment file:

cp .env.example .env

Bootstrap and Start

Follow the steps in the "Quick Start" section to bootstrap data, train the model, and start the stack.

💻 Usage Examples

Verifying LLM Tool Use

You can verify the MCP server tools using curl:

Basic Usage

curl -s -X POST http://localhost:8090/mcp \
  -H 'Content-Type: application/json' -H 'MCP-Protocol-Version: 2025-06-18' \
  -d '{"jsonrpc":"2.0","id":"list-1","method":"tools/list"}'

📚 Documentation

System Architecture

graph TD
    Sim["Simulator<br/>(OPC UA)"] -->|Stream Data| Backend[Insight Backend]
    Backend -->|Store Metrics| DB[(MySQL)]
    Backend -->|Request Context| MCP[MCP Server]
    MCP -->|Query| DB
    MCP -->|Inference| LLM["LLM<br/>(llama.cpp)"]
    HMI[WebIQ HMI] -->|Visualize| Backend
    HMI -->|Ask Questions| MCP

Modules

This repository is organized into the following modules, each with its own documentation:

• Insight Backend: Main backend service for anomaly detection and explanations.
• MCP Server: Model Context Protocol server bridging the LLM with system data.
• Simulator: OPC UA production machine simulator for data generation.
• WebIQ LLM MCP: Integration components for the WebIQ HMI.
• Shared: Shared configuration and resources.

Reference & Guides

• Configuration: Environment variables and settings.
• Troubleshooting: Solutions for common issues.
• API Reference: API documentation for the Insight Backend.
• GPU Prerequisites: Requirements for GPU acceleration.
• ML Training & Dataset Generation: Instructions for generating historical data and training.

🔧 Technical Details

The MCP server uses a unified performance profile system (cpu_only or gpu_accel) for llama.cpp inference. The system automatically detects available hardware.

See MCP Server Documentation for detailed configuration options.

Local Development

To run components locally (without Docker) for development:

1. Python Environment

It is recommended to use a virtual environment.

python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/Mac:
source .venv/bin/activate

2. Install Dependencies

pip install -r requirements.txt
# Or specific requirements for sub - modules
pip install -r mcp-server/requirements.txt
pip install -r insight-backend/requirements.txt