WiseTLP/README.md

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

# 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

# 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

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

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

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:

# 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:

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.