device-doctor 1.0.0

Read-only system diagnostics dashboard with AI-powered explanations

Device Doctor - Phase-1 Read-Only Diagnostic Agent

A local, read-only diagnostic agent that analyzes system health and provides clear explanations and safe recommendations.

Features

• Read-Only Operations: Never modifies system state
• Safe Diagnostics: Only executes allowlisted commands
• Clear Explanations: AI-powered explanations in plain English
• Safe Recommendations: Manual actions only, no automated fixes
• Comprehensive Reporting: Health scores, issues, and telemetry

Installation

1. Install dependencies:

pip install -r requirements.txt

Usage

Command Line Interface

Run the diagnostic agent:

python doctor/main.py

Web Dashboard

Start the API server:

python api_server.py

Then open your browser to:

http://localhost:8000

The dashboard provides a visual interface with:

• Real-time health score visualization
• CPU, Memory, and Disk usage charts
• Symptom detection display
• AI-powered issue explanations and recommendations

Architecture

device-doctor/
├── doctor/
│   ├── main.py                 # Entry point
│   ├── core/                   # Core functionality
│   │   ├── os_detect.py        # OS detection
│   │   ├── command_runner.py   # Safe command execution
│   │   └── telemetry.py        # System metrics collection
│   ├── diagnostics/            # Diagnostic engine
│   │   ├── symptoms.py         # Symptom abstraction
│   │   ├── rules.py            # Diagnostic rules
│   │   └── analyzer.py         # Analysis orchestration
│   ├── ai/                     # AI explanation layer
│   │   ├── prompt.py           # Prompt builder
│   │   ├── schema.py           # Response schema
│   │   └── explainer.py        # AI explainer
│   ├── report/                 # Report generation
│   │   ├── formatter.py        # Report formatting
│   │   └── health_score.py     # Health score calculation
│   └── security/               # Security controls
│       └── allowlist.py        # Command allowlist

Security Model

• All commands must be in the allowlist
• No user input modifies commands
• All executions are logged
• Output is sanitized
• Read-only operations only

Constraints

• No destructive commands
• No write operations to OS
• No sudo, rm, kill, registry edits, or driver changes
• No background services
• No auto-fixes
• AI explains only, never acts

Phase-1 Status

This is Phase-1 of Device Doctor. It provides:

• System telemetry collection
• Symptom detection
• Rule-based diagnostics
• AI-powered explanations
• Human-readable reports

Phase-2 will add auto-fix capabilities (not implemented in Phase-1).