# 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:
```bash
pip install -r requirements.txt
```

## Usage

### Command Line Interface

Run the diagnostic agent:
```bash
python doctor/main.py
```

### Web Dashboard

Start the API server:
```bash
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).
