Documentation

Configuration Files

Configuration is stored in:

• Config Directory: ~/.config/chat-linux-client/
• Data Directory: ~/.local/share/chat-linux-client/
• History File: SQLite database in data directory

Provider Configuration

{
  "providers": {
    "ollama": {
      "enabled": true,
      "base_url": "http://localhost:11434",
      "timeout": 30,
      "max_retries": 3
    },
    "openai": {
      "enabled": false,
      "api_key": "your-api-key-here",
      "base_url": "https://api.openai.com/v1"
    },
    "groq": {
      "enabled": false,
      "api_key": "your-groq-api-key"
    }
  },
  "ui": {
    "theme": "dark",
    "font_size": 12,
    "font_family": "Inter"
  },
  "chat": {
    "default_provider": "ollama",
    "default_model": "llama3.2:1b",
    "stream_responses": true,
    "save_history": true,
    "context_window": 4096
  }
}

Settings Dialog

Access the settings dialog through:

• Menu: Edit → Settings
• Keyboard: Ctrl+P, Ctrl+K, or Ctrl+U
• Button: Settings button in the toolbar

Configuration Sections

• Providers: Configure API keys and endpoints
• Models: Select default models and parameters
• Chat: Set chat behavior and preferences
• UI: Customize appearance and themes
• Privacy: Configure encryption and data handling
• Advanced: System-level settings and debugging

Basic Usage

1. Launch Application: Start Chat Linux Client
2. Select Model: Choose from the model dropdown
3. Type Message: Enter your message in the input box
4. Send Message: Press Enter or click Send button
5. View Response: Response appears in real-time with streaming

Advanced Features

• Model Information: Click model name for detailed info
• Search: Use Ctrl+F to search through chat history
• Health Monitoring: View provider status in real-time
• Performance Tracking: Monitor response times and token usage
• System Remediation: One-click fixes for common issues

Chat Management

• New Chat: Ctrl+N or File → New Chat
• Clear Chat: Ctrl+L or Edit → Clear Chat
• Save Chat: Automatically saved to history
• Export Chat: File → Export Chat (JSON/TXT)
• Chat History: View previous conversations

Model Selection

Supported Providers

Ollama (Local)

• Type: Local inference
• Privacy: 100% private, no data leaves your system
• Cost: Free (uses your hardware)
• Models: 4+ local models available
• Setup: Automatic with application

OpenAI

• Type: Cloud API
• Models: GPT-3.5-turbo, GPT-4, GPT-4-turbo
• API Key: Required from OpenAI platform
• Cost: Pay-per-use
• Quality: High-quality responses

Groq

• Type: Cloud API
• Models: Llama2-70b-4096, Mixtral-8x7b
• API Key: Required from Groq platform
• Speed: Fastest inference
• Cost: Pay-per-use

OpenRouter

• Type: API aggregator
• Models: Access to multiple providers
• API Key: Required from OpenRouter
• Flexibility: Choose from many models
• Cost: Pay-per-use

HuggingFace

• Type: Cloud API
• Models: Open-source models
• API Key: Required from HuggingFace
• Variety: Large model selection
• Cost: Pay-per-use

Provider Configuration

# Access provider settings
1. Open Settings dialog (Ctrl+P)
2. Navigate to "Providers" tab
3. Enable/disable providers
4. Enter API keys for cloud providers
5. Configure endpoints and timeouts
6. Test provider connectivity
7. Save settings

Provider Health Monitoring

The application continuously monitors provider health:

• Real-time status indicators
• Automatic failover for unavailable providers
• Performance metrics tracking
• Error logging and recovery
• Health dashboard with detailed status

Local Models (Ollama)

Model Management

# List available models
ollama list

# Pull new models
ollama pull llama3.2:1b
ollama pull qwen2.5:3b

# Show model information
ollama show llama3.2:1b

# Remove models
ollama rm mistral:7b

# Update models
ollama pull llama3.2:1b --update

Model Configuration

{
  "models": {
    "llama3.2:1b": {
      "provider": "ollama",
      "context_window": 2048,
      "max_tokens": 1024,
      "temperature": 0.7,
      "top_p": 0.9,
      "frequency_penalty": 0.0,
      "presence_penalty": 0.0
    }
  }
}

Model Performance

Performance tracking includes:

• Response time measurement
• Tokens per second calculation
• Memory usage tracking
• Quality scoring
• Cost calculation for cloud models

Model Information Display

Real-time model metadata including:

• Context window size
• Model type and architecture
• Provider information
• Performance metrics
• Cost information (for cloud models)
• Model capabilities and limitations

Search Functionality

Advanced search capabilities:

• Keyboard Shortcut: Ctrl+F
• Search Toolbar: Toggle search interface
• Text Search: Search through entire chat history
• Highlighting: Visual highlighting of search results
• Navigation: Jump between search results
• Case Sensitivity: Optional case-sensitive search

Health Monitoring

Comprehensive system health monitoring:

• Provider Status: Real-time provider availability
• Model Health: Model performance and availability
• System Resources: CPU, memory, and disk usage
• Network Status: Connection quality and latency
• Health Dashboard: Detailed health information panel
• Alerts: Automatic notifications for issues

Performance Tracking

Detailed performance metrics:

• Response Time: Time to first token and completion
• Token Generation: Tokens per second calculation
• Performance History: Historical performance data
• Model Comparison: Performance comparison across models
• Resource Usage: Memory and CPU utilization

System Remediation

One-click fixes for common issues:

• Ollama Service: Start/stop Ollama service
• Permission Fixes: Fix file permission issues
• Dependency Installation: Install missing dependencies
• Configuration Repair: Fix corrupted configuration
• Cache Cleanup: Clear temporary files and cache

Keyboard Shortcuts

Chat Shortcuts

Search Shortcuts

UI Shortcuts

Settings Shortcuts

System Shortcuts

Navigation Shortcuts

Search Features

• Full-Text Search: Search through entire chat history
• Real-Time Results: Instant search result highlighting
• Case Sensitivity: Optional case-sensitive search
• Regular Expressions: Advanced pattern matching
• Search History: Recent searches remembered
• Result Navigation: Jump between search results

Search Controls

# Search shortcuts
Ctrl+F                    - Open search
Ctrl+G                    - Find next result
Ctrl+Shift+G              - Find previous result
Escape                    - Close search
Enter                     - Find next
Shift+Enter               - Find previous

Search Options

• Match Case: Case-sensitive search
• Whole Words: Match whole words only
• Regular Expression: Use regex patterns
• Search Scope: Current chat or all history

Search Results

Search results display:

• Highlighted matching text
• Context around matches
• Result count and navigation
• Jump to specific results
• Export search results

Monitoring Dashboard

Comprehensive health monitoring includes:

• Provider Status: Real-time provider availability
• Model Health: Model performance metrics
• System Resources: CPU, memory, disk usage
• Network Status: Connection quality and latency
• Error Tracking: Error rates and patterns

Health Indicators

Performance Metrics

• Response Time: Average response time per provider
• Success Rate: Percentage of successful requests
• Error Rate: Percentage of failed requests
• Token Rate: Tokens generated per second
• Memory Usage: Memory consumption per model

Health Actions

• Refresh Status: Manually refresh provider status
• Test Connection: Test provider connectivity
• View Details: Detailed health information
• Export Health: Export health data to file
• Health History: View historical health data

Performance Optimization

• Model Selection: Choose optimal models for tasks
• Context Management: Optimize context window size
• Streaming: Enable response streaming
• Caching: Cache model responses
• Batch Processing: Process multiple requests efficiently

System Remediation

One-click fixes for common issues:

• Ollama Service: Start/stop Ollama service
• Permission Fixes: Fix file permission issues
• Dependencies: Install missing dependencies
• Configuration: Repair corrupted configuration
• Cache Cleanup: Clear temporary files

Performance Monitoring

# Monitor performance
# Response time tracking
# Token generation rate
# Memory usage
# CPU utilization
# Network latency
# Error rates

Troubleshooting Tools

• System Check: Comprehensive system diagnostics
• Log Analysis: Analyze application logs
• Network Test: Test network connectivity
• Model Test: Test model availability
• Configuration Check: Validate configuration

Development Environment

# Clone repository
git clone https://github.com/AutoBotSolutions/AI-Chat-Linux-Client.git
cd AI-Chat-Linux-Client

# Create development environment
python3 -m venv venv
source venv/bin/activate

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

Project Structure

chat-linux-client/
├── core/                   # Core business logic
│   ├── settings.py        # Configuration management
│   ├── provider_router.py # Provider routing
│   └── model_manager.py   # Model management
├── ui/                     # User interface
│   ├── main_window.py      # Main application window
│   └── settings_dialog.py  # Settings dialog
├── utils/                  # Utilities
│   ├── key_handler.py      # API key management
│   └── system_checks.py    # System diagnostics
├── storage/                # Data storage
│   ├── config_manager.py   # Configuration storage
│   └── history_manager.py  # Chat history
├── styles/                 # UI themes
├── scripts/                # Utility scripts
├── tests/                  # Test suite
└── docs/                   # Documentation

Running Tests

# Run all tests
python -m pytest tests/

# Run specific test
python -m pytest tests/test_settings.py

# Run with coverage
python -m pytest --cov=core --cov=ui tests/

# Run integration tests
python -m pytest tests/integration/

Code Quality

# Run linting
flake8 core/ ui/ utils/ storage/

# Run type checking
mypy core/ ui/ utils/ storage/

# Run security checks
bandit -r core/ ui/ utils/ storage/

# Run formatting check
black --check core/ ui/ utils/ storage/

System Architecture

The Chat Linux Client follows a layered architecture:

• Presentation Layer: PyQt6 GUI components
• Business Logic Layer: Core modules for routing and management
• Data Layer: Storage and configuration management
• Utility Layer: Helper functions and system checks

Core Components

• SettingsManager: Centralized configuration management
• ProviderRouter: Intelligent provider routing and selection
• ModelManager: AI model information and capabilities
• HistoryManager: Chat history persistence and retrieval
• KeyHandler: Secure API key management

Data Flow

1. User input → UI layer
2. UI layer → Provider router
3. Provider router → AI provider
4. AI provider → Response processing
5. Response → UI display
6. Chat → History storage

Design Patterns

• Model-View-Controller (MVC): Separation of concerns
• Observer Pattern: Event-driven updates
• Strategy Pattern: Provider selection strategies
• Factory Pattern: Provider instantiation
• Singleton Pattern: Configuration management

Test Suite

Comprehensive testing includes:

• Unit Tests: Individual component testing
• Integration Tests: Component interaction testing
• UI Tests: User interface testing
• System Tests: End-to-end testing
• Performance Tests: Performance and load testing

Test Categories

• Core Tests: Settings, provider routing, model management
• UI Tests: Main window, settings dialog, components
• Storage Tests: Configuration, history management
• Utils Tests: Key handling, system checks
• Integration Tests: Cross-component functionality

Test Validation Results

Running Tests

# Run all tests
python -m pytest tests/ -v

# Run with coverage
python -m pytest --cov=core --cov=ui --cov-report=html tests/

# Run specific test categories
python -m pytest tests/test_core.py -v
python -m pytest tests/test_ui.py -v
python -m pytest tests/test_integration.py -v

# Run performance tests
python -m pytest tests/test_performance.py -v

Validation Approaches

• Top-Down Validation: From entry point to components
• Bottom-Up Validation: From foundation to application
• Core-Outward Validation: From core to periphery

Validation Results

System Status

Getting Started

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request

Development Guidelines

• Follow PEP 8 style guidelines
• Write comprehensive tests
• Update documentation
• Use meaningful commit messages
• Keep changes focused and minimal

Code Review Process

• All changes require code review
• Tests must pass
• Documentation must be updated
• Performance impact must be considered
• Security implications must be reviewed

Reporting Issues

• Use GitHub Issues for bug reports
• Provide detailed reproduction steps
• Include system information
• Add relevant logs and screenshots
• Suggest possible solutions

Data Protection

• Local-First: All data stored locally by default
• Encryption: API keys encrypted with Fernet
• No Telemetry: No data sent to external servers
• Privacy Controls: User-controlled data sharing

API Key Security

• Encrypted Storage: Keys stored encrypted at rest
• Memory Protection: Keys cleared from memory when not in use
• Access Control: Restricted file permissions
• Key Validation: API key format validation

Network Security

• HTTPS Only: All external communications use HTTPS
• Certificate Validation: SSL certificate validation
• Timeout Protection: Request timeouts to prevent hangs
• Rate Limiting: Built-in rate limiting for API calls

Security Best Practices

• Regular security audits
• Dependency vulnerability scanning
• Secure coding practices
• Input validation and sanitization
• Error handling without information leakage

Common Issues

Application Won't Start

• Check Python version (3.8+ required)
• Verify virtual environment is activated
• Install missing dependencies
• Check system requirements

Ollama Connection Failed

• Verify Ollama is installed and running
• Check if port 11434 is accessible
• Restart Ollama service
• Check firewall settings

Provider Authentication Issues

• Verify API keys are correct
• Check API key format
• Verify account status
• Check rate limits

Performance Issues

• Use lightweight models
• Clear chat history
• Check system resources
• Optimize context window size

Diagnostic Tools

# System diagnostics
python3 main.py --check-system

# Provider diagnostics
python3 main.py --test-providers

# Configuration diagnostics
python3 main.py --check-config

# Performance diagnostics
python3 main.py --benchmark

Log Analysis

• Check application logs for errors
• Review provider connection logs
• Analyze performance metrics
• Monitor system resource usage

Getting Help

• Check the FAQ section
• Search existing GitHub issues
• Create new issue with detailed information
• Join community discussions

General Questions

Technical Questions

Privacy Questions

Troubleshooting Questions

Feature Questions