# WiseTLP

**AI-powered TLP configuration automation tool for Linux power management optimization**

WiseTLP is a professional-grade command-line application that leverages artificial intelligence to automatically generate optimized TLP (Linux Advanced Power Management) configurations tailored to your specific system hardware and usage patterns.

## Features

### Core Functionality

- **Comprehensive System Detection**: Automatically detects Linux distribution, hardware specifications, power management capabilities, and existing configurations
- **AI-Powered Configuration Generation**: Uses advanced AI models to generate optimized TLP configurations based on your system and preferences
- **Multi-Provider AI Support**: Compatible with multiple AI services including Groq, OpenRouter, Gemini, and custom OpenAI-compatible endpoints
- **Interactive User Interface**: Guided configuration process with clear explanations and user-friendly prompts
- **Secure API Key Management**: Encrypted storage of API keys with master password protection
- **Automated TLP Installation**: Handles TLP installation across major Linux distributions with proper privilege escalation

### System Compatibility

WiseTLP supports major Linux distributions including:

- **Debian-based**: Ubuntu, Debian, Linux Mint, Elementary OS, Pop!_OS
- **Red Hat-based**: Fedora, RHEL, CentOS, Rocky Linux, AlmaLinux
- **Arch-based**: Arch Linux, Manjaro, EndeavourOS, Garuda Linux
- **SUSE-based**: openSUSE Leap, openSUSE Tumbleweed
- **Other**: Alpine Linux, Gentoo

### Security Features

- **Encrypted API Key Storage**: API keys are encrypted using AES-GCM with master password protection
- **Secure Privilege Escalation**: Minimal privilege escalation with user confirmation and secure sudo handling
- **Input Validation**: Comprehensive input sanitization and validation to prevent security vulnerabilities
- **Configuration Backup**: Automatic backup of existing TLP configurations before applying changes

## Installation

### Prerequisites

- Linux operating system (kernel 2.6.32 or later)
- Go 1.22 or later (for building from source)
- sudo privileges (for TLP installation and configuration)

### Building from Source

```bash
# Clone the repository
git clone https://git.gostacks.org/iwasforcedtobehere/WiseTLP/autotlp.git
cd autotlp

# Build the application
go build -o autotlp ./cmd/autotlp

# Install to system path (optional)
sudo mv autotlp /usr/local/bin/
```

### Quick Start

```bash
# Run WiseTLP with interactive setup
./autotlp

# Or if installed system-wide
autotlp
```

## Usage

### Basic Usage

WiseTLP provides an interactive command-line interface that guides you through the configuration process:

1. **System Detection**: WiseTLP automatically detects your system specifications
2. **TLP Installation**: If TLP is not installed, WiseTLP can install it for you
3. **AI Service Configuration**: Choose and configure your preferred AI service
4. **User Preferences**: Specify your power management preferences and use case
5. **Configuration Generation**: AI generates an optimized TLP configuration
6. **Review and Apply**: Review the generated configuration and apply it to your system

### AI Service Configuration

WiseTLP supports multiple AI providers:

#### Groq (Recommended for speed)
```
Provider: Groq
Endpoint: https://api.groq.com/openai/v1/chat/completions
Model: openai/gpt-oss-20b
```

#### OpenRouter (Multiple model options)
```
Provider: OpenRouter
Endpoint: https://openrouter.ai/api/v1/chat/completions
Model: meta-llama/llama-3.1-8b-instruct:free (or others)
```

#### Google Gemini
```
Provider: Gemini
Endpoint: https://generativelanguage.googleapis.com/v1beta/models/gemini-pro:generateContent
Model: gemini-pro
```

#### Custom OpenAI-compatible
```
Provider: Custom
Endpoint: [Your custom endpoint]
Model: [Your model name]
```

### Configuration Options

#### Power Profiles

- **Balanced**: Optimal balance between performance and power efficiency
- **Performance**: Maximum performance with higher power consumption
- **Power Saving**: Maximum battery life with reduced performance
- **Custom**: Specify custom requirements and settings

#### Use Cases

- **General**: Web browsing, office work, media consumption
- **Development**: Programming, compiling, development tools
- **Gaming**: Gaming and graphics-intensive applications
- **Server**: Server workloads, always-on services
- **Multimedia**: Video editing, rendering, content creation
- **Office**: Primarily office applications and productivity

#### Special Requirements

- Minimize fan noise
- Prevent thermal throttling
- Optimize for external displays
- Gaming performance priority
- Maximum WiFi performance
- Minimize disk wear
- Fast system wake/sleep

## Configuration Examples

### Example 1: Gaming Laptop

```bash
Power Profile: Performance
Use Case: Gaming
Battery Priority: Balanced
Performance Mode: Maximum
Special Requirements: Gaming performance priority, Prevent thermal throttling
```

Generated settings include:
- CPU governor: performance on AC, balanced on battery
- Platform profile: performance
- Aggressive GPU power management
- Optimized disk settings for game loading

### Example 2: Development Workstation

```bash
Power Profile: Balanced
Use Case: Development
Battery Priority: Runtime
Performance Mode: Adaptive
Special Requirements: Fast system wake/sleep, Minimize fan noise
```

Generated settings include:
- CPU governor: ondemand on AC, powersave on battery
- Balanced disk APM levels
- Conservative thermal management
- Optimized compilation performance

### Example 3: Ultrabook for Office Work

```bash
Power Profile: Power Saving
Use Case: Office
Battery Priority: Longevity
Performance Mode: Efficient
Special Requirements: Minimize fan noise, Maximum WiFi performance
```

Generated settings include:
- CPU governor: powersave
- Aggressive power management
- Conservative disk settings
- Optimized for battery longevity

## Architecture

WiseTLP follows a modular architecture with clear separation of concerns:

```
autotlp/
├── cmd/autotlp/           # Main application entry point
├── internal/              # Internal application modules
│   ├── ai/               # AI client implementation
│   ├── config/           # Configuration management
│   ├── security/         # Security and privilege management
│   ├── system/           # System detection and information gathering
│   └── tlp/              # TLP installation and configuration
├── pkg/                  # Public packages
│   ├── types/            # Type definitions
│   └── utils/            # Utility functions
├── test/                 # Integration tests
├── docs/                 # Documentation
└── examples/             # Example configurations
```

### Key Components

- **System Detector**: Identifies Linux distribution, hardware, and power management capabilities
- **AI Client**: Handles communication with various AI service providers
- **TLP Manager**: Manages TLP installation, configuration, and validation
- **Security Manager**: Handles privilege escalation and secure key storage
- **Configuration Engine**: Processes user preferences and generates TLP settings

## Security Considerations

WiseTLP implements several security measures:

### API Key Protection
- API keys are encrypted using AES-GCM with a user-provided master password
- Keys are stored in `~/.config/autotlp/` with restrictive permissions (0600)
- Master password is hashed using SHA-256 for verification

### Privilege Escalation
- Minimal privilege escalation using sudo only when necessary
- Clear user prompts explaining why elevated privileges are required
- Secure handling of elevated processes with proper exit code propagation

### Input Validation
- Comprehensive input sanitization to prevent injection attacks
- Path validation to prevent directory traversal vulnerabilities
- Configuration validation to ensure system stability

## Testing

WiseTLP includes comprehensive test coverage:

```bash
# Run all tests
go test ./...

# Run tests with coverage
go test -cover ./...

# Run specific package tests
go test ./pkg/utils
go test ./internal/system
go test ./internal/config
```

### Test Categories

- **Unit Tests**: Test individual functions and components
- **Integration Tests**: Test component interactions
- **System Tests**: Test on various Linux distributions (manual)

## Contributing

We welcome contributions to WiseTLP! Please follow these guidelines:

### Development Setup

1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes with proper tests
4. Ensure all tests pass: `go test ./...`
5. Follow Go coding standards and run `gofmt`
6. Submit a pull request with a clear description

### Code Standards

- Follow Go best practices and idiomatic patterns
- Include comprehensive error handling
- Add tests for new functionality
- Update documentation for API changes
- Use structured logging with appropriate log levels

### Reporting Issues

Please report bugs and feature requests through GitHub Issues:

1. Check existing issues first
2. Provide detailed system information
3. Include steps to reproduce bugs
4. Attach relevant log output or configuration files

## Troubleshooting

### Common Issues

#### TLP Installation Fails
```
Error: failed to install TLP: permission denied
```
**Solution**: Ensure you have sudo privileges and run with appropriate permissions.

#### AI API Connection Issues
```
Error: failed to validate AI connection: connection timeout
```
**Solution**: Check your internet connection, API key validity, and endpoint URL.

#### System Detection Problems
```
Error: failed to detect system: unsupported distribution
```
**Solution**: WiseTLP supports major distributions. For unsupported distributions, please file an issue.

### Debug Mode

Enable debug logging for troubleshooting:

```bash
export TLP_DEBUG=1
./autotlp
```

### Log Files

Application logs are written to:
- stdout/stderr for interactive sessions
- System journal when run as a service

## Performance

WiseTLP is designed for efficiency:

- **Startup Time**: < 1 second for system detection
- **AI Response Time**: 5-30 seconds depending on provider and model
- **Configuration Application**: < 5 seconds
- **Memory Usage**: < 50MB during operation
- **Binary Size**: < 10MB compiled



### Version History

- **v1.0.0**: Initial release with core functionality
  - AI-powered configuration generation
  - Multi-provider AI support
  - Comprehensive system detection
  - Secure API key management
  - Automated TLP installation


**WiseTLP** - Intelligent power management for the modern Linux desktop and server.
