# ⚙️ Maintenance & Work-Order Intelligence Copilot

An enterprise-grade, AI-driven **Maintenance and Work-Order Intelligence Copilot** built for platform architecture. 

This copilot empowers reliability engineers and plant operators to investigate recurring alarm storms, query structured CMMS work orders, and extract grounded troubleshooting procedures from technical manuals through a unified natural-language interface.

---


* **Architecture Overview:**
```mermaid
flowchart TD
    subgraph PRESENTATION["Presentation Layer"]
        GUI["Streamlit Web GUI<br/>• Interactive Chat Panel<br/>• Alarm & Work Order Tables<br/>• Document Citations<br/>• MCP Execution Trace Timeline"]
    end

    subgraph COPILOT["Copilot Orchestration Layer"]
        ORCH["LangGraph Copilot Orchestrator<br/>(Query Decomposition & Agent Logic)"]
        CLIENT["MCP Client Manager<br/>• Tool Discovery & Validation<br/>• Trace Propagation (X-Trace-ID)<br/>• Error & Timeout Handling"]
        RAG_ENG["Document RAG Engine<br/>• Vector Search & Grounding<br/>• Prompt Injection Guardrails<br/>• Citation Metadata Formatter"]
    end

    subgraph MCP_LAYER["Standardized Protocol Layer"]
        SERVER["FastMCP Server<br/>(Alarm-CMMS-MCP)<br/>Port: 9000"]
    end

    subgraph DATA_SOURCES["Data Sources & Core Backend"]
        SIMULATOR["Alarm API Simulator<br/>(FastAPI - Postman Spec Compliant)<br/>Port: 8000"]
        CMMS["CMMS Work-Order DB<br/>(SQLite Database)"]
        VECTOR_DB[("ChromaDB Vector Store<br/>(Equipment Manuals & SOPs)")]
    end

    GUI -->|HTTP / REST| ORCH
    ORCH --> CLIENT
    ORCH --> RAG_ENG

    CLIENT -->|JSON-RPC| SERVER
    RAG_ENG -->|Semantic Vector Search| VECTOR_DB

    SERVER -->|HTTP REST APIs| SIMULATOR
    SERVER -->|SQL Queries| CMMS
```

## 🎯 Selected Use Case

**Maintenance and Work-Order Intelligence Copilot**
                           
## 🎯 Selected Use Case

**Maintenance and Work-Order Intelligence Copilot**
* **Business Scenario:** Industrial reliability teams need to combine telemetry alarm behavior, CMMS maintenance history, and equipment manuals to identify assets requiring immediate intervention.
* **Core Value:** Reconciles structured alarm and CMMS data with unstructured operating manuals using canonical asset identifiers (`BFP-101`), eliminating manual cross-referencing during alarm floods.

---

## ✨ Main Capabilities

1. **Natural-Language Query Understanding:** Decomposes complex plant queries into structured intent and multi-step tool execution plans.
2. **Standardized Model Context Protocol (MCP) Integration:** Exposes Alarm Management APIs and CMMS databases as standardized, typed tools using `FastMCP`.
3. **Document RAG with Security Guardrails:** Vector search over equipment manuals using `ChromaDB` and `SentenceTransformers`, equipped with prompt-injection defenses and strict similarity thresholds.
4. **End-to-End Traceability & Observability:** Live execution timeline showing tool invocations, inputs, trace headers (`X-Trace-ID`), and document confidence scores directly in the UI.
5. **Zero-Cost Offline Execution:** Includes an offline rule-based mock engine that allows running all automated tests and UI demos without requiring paid external LLM API keys.

---

## 🛠️ Technology Stack

| Component | Technology |
| :--- | :--- |
| **User Interface** | Streamlit |
| **Copilot Orchestration** | LangGraph / Python Async Engine |
| **MCP Server & Client** | FastMCP / Model Context Protocol SDK |
| **Backend & Simulator** | FastAPI, Uvicorn, SQLite |
| **Vector Store & Embeddings** | ChromaDB, `sentence-transformers/all-MiniLM-L6-v2` |
| **Testing & Quality** | PyTest, PyTest-Asyncio, Ruff |
| **Packaging & CI** | Docker, Docker Compose, GitHub Actions |

---

## 🔌 MCP Server Description & Tool Catalog

The candidate-developed MCP server exposes backend source-system capabilities over standard JSON-RPC interface contracts.

### Registered MCP Tools
| Tool Name | Description | Source System Operation |
| :--- | :--- | :--- |
| `search_assets` | Resolves asset names/keywords into canonical Asset IDs | `GET /assets/search` |
| `get_alarms` | Fetches active or historical alarm events for an asset | `GET /alarms` |
| `get_alarm_summary` | Calculates aggregated KPIs, recurring rates, and trends | `POST /alarms/summary` |
| `get_alarm_correlation` | Advanced Operation: Performs cross-asset event correlation | `POST /alarms/correlation` |
| `get_cmms_work_orders` | Queries structured maintenance work orders and costs | `GET /api/v1/cmms/work_orders` |

> For complete input/output JSON schemas, trace header propagation details, and error mapping, see [`docs/mcp-tool-catalog.md`](docs/mcp-tool-catalog.md).

### Independent MCP Server Launch Command
```bash
$env:PYTHONPATH="."
python -m mcp_servers.alarm_management.server