WiseTLP/docs/API.md

WiseTLP API Documentation

This document provides detailed information about WiseTLP's internal APIs and interfaces.

Table of Contents

• System Detection API
• AI Client API
• TLP Management API
• Security API
• Configuration API
• Types and Structures

System Detection API

The system detection module provides comprehensive Linux system information gathering.

system.DetectSystem(ctx context.Context) (*Info, error)

Detects basic system information including distribution, version, and package manager.

Parameters:

• ctx: Context for cancellation and timeout control

Returns:

• *Info: Basic system information structure
• error: Error if detection fails

Example:

ctx := context.Background()
info, err := system.DetectSystem(ctx)
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Distribution: %s %s\n", info.Distribution, info.Version)

system.GatherSystemInfo(ctx context.Context) (*types.SystemInfo, error)

Collects comprehensive system information including hardware, power management, and kernel details.

Parameters:

• ctx: Context for cancellation and timeout control

Returns:

• *types.SystemInfo: Complete system information structure
• error: Error if gathering fails

Gathered Information:

• CPU details (model, cores, frequency, governor)
• Memory information (total, available, swap)
• Battery information (if present)
• Power supply status
• Kernel information and parameters
• Hardware details (chassis, manufacturer, storage)
• Distribution information

AI Client API

The AI client module handles communication with various AI service providers.

ai.NewClient(config *types.AIConfig, logger *utils.Logger) *Client

Creates a new AI client with the specified configuration.

Parameters:

• config: AI service configuration
• logger: Logger instance for structured logging

Returns:

• *Client: Configured AI client instance

ai.ConfigureClient(logger *utils.Logger) (*Client, error)

Interactively configures an AI client by prompting the user for provider selection and credentials.

Parameters:

• logger: Logger instance

Returns:

• *Client: Configured AI client
• error: Configuration error

(*Client).GenerateConfig(ctx context.Context, sysInfo *types.SystemInfo, preferences *types.UserPreferences) (*types.TLPConfiguration, error)

Generates an optimized TLP configuration using AI based on system information and user preferences.

Parameters:

• ctx: Context for request timeout
• sysInfo: Complete system information
• preferences: User power management preferences

Returns:

• *types.TLPConfiguration: Generated TLP configuration
• error: Generation error

TLP Management API

The TLP management module handles TLP installation, configuration, and validation.

tlp.NewManager(logger *utils.Logger) *Manager

Creates a new TLP manager instance.

Parameters:

• logger: Logger instance

Returns:

• *Manager: TLP manager instance

(*Manager).GetStatus(ctx context.Context) (*types.TLPStatus, error)

Retrieves the current TLP installation and configuration status.

Returns:

• *types.TLPStatus: Current TLP status
• error: Status retrieval error

(*Manager).Install(ctx context.Context, sysInfo *system.Info) error

Installs TLP using the appropriate package manager for the detected distribution.

Parameters:

• ctx: Context for operation timeout
• sysInfo: System information for package manager selection

Returns:

• error: Installation error

Supported Package Managers:

• apt (Ubuntu, Debian)
• dnf (Fedora, RHEL, CentOS)
• pacman (Arch, Manjaro)
• zypper (openSUSE)
• yum (Legacy RHEL/CentOS)
• apk (Alpine)

(*Manager).ApplyConfig(ctx context.Context, config *types.TLPConfiguration) error

Applies a TLP configuration to the system.

Parameters:

• ctx: Context for operation timeout
• config: TLP configuration to apply

Returns:

• error: Application error

Operations:

1. Validates configuration
2. Backs up existing configuration
3. Writes new configuration
4. Reloads TLP service

(*Manager).ValidateConfig(config *types.TLPConfiguration) error

Validates a TLP configuration for correctness and safety.

Parameters:

• config: Configuration to validate

Returns:

• error: Validation error

Security API

The security module handles API key storage and privilege escalation.

security.NewKeyStore() (*KeyStore, error)

Creates a new encrypted key store for API keys.

Returns:

• *KeyStore: Key store instance
• error: Initialization error

(*KeyStore).StoreAPIKey(provider, apiKey string) error

Securely stores an API key for a provider.

Parameters:

• provider: AI service provider name
• apiKey: API key to store

Returns:

• error: Storage error

Security Features:

• AES-GCM encryption
• Master password protection
• Secure file permissions (0600)

(*KeyStore).RetrieveAPIKey(provider string) (string, error)

Retrieves and decrypts an API key for a provider.

Parameters:

• provider: AI service provider name

Returns:

• string: Decrypted API key
• error: Retrieval error

security.NewPrivilegeManager(logger *utils.Logger) *PrivilegeManager

Creates a new privilege manager for secure elevation.

(*PrivilegeManager).EscalateIfNeeded(args []string, operation string) error

Escalates privileges using sudo if not already running as root.

Parameters:

• args: Command arguments for elevated execution
• operation: Description of operation requiring elevation

Returns:

• error: Escalation error

Configuration API

The configuration module handles user preference gathering and processing.

config.GatherUserPreferences() (*types.UserPreferences, error)

Interactively gathers user preferences for power management.

Returns:

• *types.UserPreferences: User preferences
• error: Gathering error

Collected Preferences:

• Power profile (balanced, performance, power saving, custom)
• Use case (general, development, gaming, server, multimedia, office)
• Battery priority (balanced, runtime, longevity)
• Performance mode (adaptive, maximum, efficient)
• Special requirements
• Custom settings

config.ValidatePreferences(preferences *types.UserPreferences) error

Validates user preferences for consistency and conflicts.

Parameters:

• preferences: Preferences to validate

Returns:

• error: Validation error

config.GetRecommendedSettings(preferences *types.UserPreferences) map[string]string

Generates recommended TLP settings based on user preferences.

Parameters:

• preferences: User preferences

Returns:

• map[string]string: Recommended TLP settings

Types and Structures

SystemInfo

Complete system information structure containing:

type SystemInfo struct {
    CPU           CPUInfo           `json:"cpu"`
    Memory        MemoryInfo        `json:"memory"`
    Battery       *BatteryInfo      `json:"battery,omitempty"`
    PowerSupply   PowerSupplyInfo   `json:"power_supply"`
    Kernel        KernelInfo        `json:"kernel"`
    Distribution  DistributionInfo  `json:"distribution"`
    Hardware      HardwareInfo      `json:"hardware"`
    TLPStatus     TLPStatus         `json:"tlp_status"`
}

UserPreferences

User power management preferences:

type UserPreferences struct {
    PowerProfile        PowerProfile               `json:"power_profile"`
    UseCase            UseCase                    `json:"use_case"`
    BatteryPriority    BatteryPriority            `json:"battery_priority"`
    PerformanceMode    PerformanceMode            `json:"performance_mode"`
    CustomSettings     map[string]interface{}     `json:"custom_settings"`
    SpecialRequirements []string                  `json:"special_requirements"`
}

TLPConfiguration

Generated TLP configuration:

type TLPConfiguration struct {
    Settings    map[string]string `json:"settings"`
    Description string           `json:"description"`
    Rationale   map[string]string `json:"rationale"`
    Warnings    []string         `json:"warnings"`
    Generated   time.Time        `json:"generated"`
    SystemInfo  *SystemInfo      `json:"system_info"`
    Preferences *UserPreferences `json:"preferences"`
}

AIConfig

AI service configuration:

type AIConfig struct {
    Provider    AIProvider `json:"provider"`
    APIKey      string     `json:"-"` // Never serialized
    Endpoint    string     `json:"endpoint"`
    Model       string     `json:"model"`
    MaxTokens   int        `json:"max_tokens"`
    Temperature float64    `json:"temperature"`
}

Error Handling

All APIs follow Go's standard error handling patterns:

• Functions return error as the last return value
• Errors are wrapped with context using fmt.Errorf
• Custom error types are used for specific error conditions
• Logging is performed at appropriate levels

Context Usage

All long-running operations accept a context.Context parameter for:

• Cancellation support
• Timeout handling
• Request tracing
• Graceful shutdown

Logging

WiseTLP uses structured logging throughout:

logger := utils.NewLogger()
logger.Info("Operation completed", "duration", elapsed, "items", count)
logger.Error("Operation failed", "error", err, "context", ctx)

Log levels:

• Debug: Detailed debugging information
• Info: General operational information
• Warn: Warning conditions
• Error: Error conditions

Testing

All APIs include comprehensive unit tests:

# Run API tests
go test ./internal/...
go test ./pkg/...

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

Test patterns:

• Table-driven tests for multiple scenarios
• Mock interfaces for external dependencies
• Integration tests for component interactions
• Error condition testing