Alarm Investigation and Procedure Guidance Copilot

This repository implements an evidence-backed alarm investigation workflow using:

• a FastAPI-based Alarm Management API simulator
• a candidate-developed MCP server exposing alarm operations as typed tools
• a Streamlit GUI that discovers and invokes MCP tools
• a document RAG workflow over alarm procedures and troubleshooting guides

Main capabilities

• Natural-language alarm investigation requests
• MCP tool discovery and invocation for asset search, metadata lookup, alarm retrieval, summaries, priority scoring, and recommendations
• RAG-backed evidence using operating procedures and maintenance documents
• Tool trace and raw response inspection in the UI

Technology stack

• Python 3.11+
• FastAPI
• Streamlit
• scikit-learn for TF-IDF retrieval
• pytest

MCP server

The MCP server is implemented under apps/mcp_server and exposes the following tools:

• asset_search
• asset_metadata
• alarm_retrieval
• alarm_summary
• priority_score
• operator_recommendations

Start the MCP server independently:

uvicorn apps.mcp_server.main:app --host 0.0.0.0 --port 9000

Alarm API backend

Start the backend simulator:

uvicorn apps.backend.main:app --host 0.0.0.0 --port 8000

Streamlit UI

Start the GUI:

streamlit run apps/frontend/app.py

RAG workflow

Documents are stored under rag/documents and ingested through the existing TF-IDF index in apps/backend/rag.py.

Tests

python -m pytest -q

Configuration

Copy .env.example and adjust values as needed.

Architecture summary

See docs/architecture.md and docs/architecture-diagram.svg.