🔧 AI-Powered System Diagnostic & Log Analysis Toolkit

A Bash + Python toolkit that automatically collects Linux system logs, analyzes them, and generates intelligent troubleshooting suggestions using an LLM.

---

📌 Overview

This project is an AI-assisted diagnostic tool for Linux-based systems.
It collects key system information — such as:

• System overview (CPU, RAM, Swap)
• Syslog / journal logs
• Kernel logs (dmesg)
• Disk usage & SMART data
• Network configuration & socket statistics

After collecting data, it builds a structured prompt and sends it to an LLM (via the UF LiteLLM OpenAI-compatible proxy).
The LLM then returns:

• Root cause analysis
• Potential system issues
• Safe troubleshooting steps
• Follow-up commands

This makes the toolkit useful for:

• DevOps Engineers: Quick triage of server issues.
• Students: Learning Linux system internals and diagnostics.
• SysAdmins: Automating the initial investigation phase.
• Developers: Debugging application environment issues.

---

📂 Project Structure

/
├── diagnose.sh            # Entry point script (Bash wrapper)
├── requirements.txt       # Python dependencies
├── readme.md              # Project documentation
└── diag_toolkit/          # Python package
    ├── __init__.py
    ├── collectors.py      # System data collection logic
    ├── llm_client.py      # LLM API client (OpenAI/LiteLLM)
    └── cli.py             # Main CLI logic & orchestration

---

✨ Features

• ✔ Real-time Diagnostics: Collects live system stats and logs.
• ✔ Hybrid Architecture: Combines Bash for environment setup and Python for robust logic.
• ✔ AI-Powered Analysis: Uses OpenAI v1.x SDK with UF LiteLLM proxy for intelligent insights.
• ✔ Safe Execution: Read-only collection; suggests fix commands but never auto-executes them.
• ✔ Flexible Deployment: Runs on WSL, Ubuntu, Debian, CentOS, or any standard Linux environment.

---

🚀 Getting Started

Prerequisites

• OS: Linux or Windows Subsystem for Linux (WSL).
• Python: Version 3.8 or higher.
• API Access: Access to a UF LiteLLM or OpenAI-compatible endpoint.

🛠 Installation

1. Clone or Download the Repository Ensure you are in the project directory.

2. Set Up Virtual Environment It's recommended to run in a virtual environment to avoid dependency conflicts.

   python3 -m venv venv
   source venv/bin/activate

3. Install Dependencies

   pip install -r requirements.txt

⚙️ Configuration

You need to configure the LLM client with your API key and endpoint.

Method 1: Environment Variables (Recommended)

export UF_LLM_API_KEY="your-api-key-here"
# Optional: Default is https://api.ai.it.ufl.edu
export UF_LLM_BASE_URL="https://api.ai.it.ufl.edu"

Method 2: Edit llm_client.py You can hardcode values in diag_toolkit/llm_client.py if you prefer (not recommended for shared code).

---

🖥 Usage

Basic Run

Run the helper script which handles the python execution for you:

./diagnose.sh

Advanced Options

You can pass arguments directly to the python CLI via the script:

# Skip LLM analysis (only collect and print logs)
./diagnose.sh --no-llm

# (Future) Specify number of log lines to capture
./diagnose.sh --lines 500

---

🧩 How It Works

1. Collection (collectors.py):

   • Runs shell commands (journalctl, dmesg, psutil) to gather raw data.
   • Handles permission errors gracefully (e.g., if not running as root).

2. Orchestration (cli.py):

   • Aggregates the data into a dictionary.
   • Prints a summary to the console for immediate human review.

3. Analysis (llm_client.py):

   • Constructs a prompt with the collected data.
   • Sends it to the configured LLM model (e.g., gpt-oss-120b).
   • Returns a markdown-formatted advice report.

---

⚠️ Disclaimer

This tool executes read-only commands to gather information. However, the remediation steps provided by the AI are suggestions. Always review commands before executing them, especially those involving sudo or file deletion.