---
phase: 03-resource-management
plan: 02
type: execute
wave: 1
depends_on: []
files_modified: [src/resource/__init__.py, src/resource/tiers.py, src/config/resource_tiers.yaml]
autonomous: true
user_setup: []
must_haves:
truths:
- "Hardware tier system detects and classifies system capabilities"
- "Tier definitions are configurable and maintainable"
- "Model mapping uses tiers for intelligent selection"
artifacts:
- path: "src/resource/tiers.py"
provides: "Hardware tier detection and management system"
min_lines: 80
- path: "src/config/resource_tiers.yaml"
provides: "Configurable hardware tier definitions"
min_lines: 30
- path: "src/resource/__init__.py"
provides: "Resource management module initialization"
key_links:
- from: "src/resource/tiers.py"
to: "src/config/resource_tiers.yaml"
via: "YAML configuration loading"
pattern: "yaml.safe_load|yaml.load"
- from: "src/resource/tiers.py"
to: "src/models/resource_monitor.py"
via: "Resource monitoring integration"
pattern: "ResourceMonitor"
---
Create a hardware tier detection and management system that classifies systems into performance tiers (low_end, mid_range, high_end) with configurable thresholds and intelligent model mapping.
Purpose: Enable Mai to adapt gracefully from low-end hardware to high-end systems by understanding hardware capabilities and selecting appropriate models.
Output: Tier detection system with configurable definitions and model mapping capabilities.
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
# Research-based architecture
@.planning/phases/03-resource-management/03-RESEARCH.md
Create resource module structure
src/resource/__init__.py
Create the resource module directory and __init__.py file. The __init__.py should expose the main resource management classes that will be created in this phase:
- HardwareTierDetector (from tiers.py)
- ProactiveScaler (from scaling.py)
- ResourcePersonality (from personality.py)
Include proper module docstring explaining the resource management system's purpose.
ls -la src/resource/ shows the directory exists with __init__.py file
Resource module structure is established for Phase 3 components
Create configurable hardware tier definitions
src/config/resource_tiers.yaml
Create a YAML configuration file defining hardware tiers based on the research patterns. Include:
1. Three tiers: low_end, mid_range, high_end
2. Resource thresholds for each tier:
- RAM amounts (min/max in GB)
- CPU core counts (min/max)
- GPU requirements (required/optional)
- GPU VRAM thresholds
3. Preferred model categories for each tier
4. Performance characteristics and expectations
5. Scaling thresholds specific to each tier
Example structure:
```yaml
tiers:
low_end:
ram_gb: {min: 2, max: 4}
cpu_cores: {min: 2, max: 4}
gpu_required: false
preferred_models: ["small"]
scaling_thresholds:
memory_percent: 75
cpu_percent: 80
mid_range:
ram_gb: {min: 4, max: 8}
cpu_cores: {min: 4, max: 8}
gpu_required: false
preferred_models: ["small", "medium"]
scaling_thresholds:
memory_percent: 80
cpu_percent: 85
high_end:
ram_gb: {min: 8, max: null}
cpu_cores: {min: 6, max: null}
gpu_required: true
gpu_vram_gb: {min: 6}
preferred_models: ["medium", "large"]
scaling_thresholds:
memory_percent: 85
cpu_percent: 90
```
Include comments explaining each threshold's purpose.
python -c "import yaml; print('YAML valid:', yaml.safe_load(open('src/config/resource_tiers.yaml')))" loads the file without errors
Hardware tier definitions are configurable and well-documented
Implement HardwareTierDetector class
src/resource/tiers.py
Create the HardwareTierDetector class that:
1. Loads tier definitions from resource_tiers.yaml
2. Detects current system resources using ResourceMonitor
3. Determines hardware tier based on resource thresholds
4. Provides model recommendations for detected tier
5. Supports tier-specific scaling thresholds
Key methods:
- load_tier_config(): Load YAML configuration
- detect_current_tier(): Determine system tier from resources
- get_preferred_models(): Return model preferences for tier
- get_scaling_thresholds(): Return tier-specific thresholds
- is_gpu_required(): Check if tier requires GPU
- can_upgrade_model(): Check if system can handle larger models
Include proper error handling for configuration loading and resource detection. The detector should integrate with the enhanced ResourceMonitor from Plan 01.
python -c "from src.resource.tiers import HardwareTierDetector; htd = HardwareTierDetector(); tier = htd.detect_current_tier(); print('Detected tier:', tier)" returns a valid tier name
HardwareTierDetector accurately classifies system capabilities and provides tier-based recommendations
Test hardware tier detection across simulated system configurations:
- Low-end systems (2-4GB RAM, 2-4 CPU cores, no GPU)
- Mid-range systems (4-8GB RAM, 4-8 CPU cores, optional GPU)
- High-end systems (8GB+ RAM, 6+ CPU cores, GPU required)
Verify tier recommendations align with research patterns and model mapping is logical.
HardwareTierDetector successfully classifies systems into appropriate tiers, loads configuration correctly, integrates with ResourceMonitor, and provides accurate model recommendations based on detected capabilities.