Mai/.planning/phases/01-model-interface/01-03-PLAN.md

---
phase: 01-model-interface
plan: 03
type: execute
wave: 2
depends_on: ["01-01", "01-02"]
files_modified: ["src/models/model_manager.py", "src/mai.py", "src/__main__.py"]
autonomous: true

must_haves:
  truths:
    - "Model can be selected and loaded based on available resources"
    - "System automatically switches models when resources constrained"
    - "Conversation context is preserved during model switching"
    - "Basic Mai class can generate responses using the model system"
  artifacts:
    - path: "src/models/model_manager.py"
      provides: "Intelligent model selection and switching logic"
      min_lines: 80
    - path: "src/mai.py"
      provides: "Core Mai orchestration class"
      min_lines: 40
    - path: "src/__main__.py"
      provides: "CLI entry point for testing"
      min_lines: 20
  key_links:
    - from: "src/models/model_manager.py"
      to: "src/models/lmstudio_adapter.py"
      via: "model loading operations"
      pattern: "from.*lmstudio_adapter import"
    - from: "src/models/model_manager.py"
      to: "src/models/resource_monitor.py"
      via: "resource checks"
      pattern: "from.*resource_monitor import"
    - from: "src/models/model_manager.py"
      to: "src/models/context_manager.py"
      via: "context retrieval"
      pattern: "from.*context_manager import"
    - from: "src/mai.py"
      to: "src/models/model_manager.py"
      via: "model management"
      pattern: "from.*model_manager import"
---

<objective>
Integrate all components into intelligent model switching system.

Purpose: Combine LM Studio client, resource monitoring, and context management into a cohesive system that can intelligently select and switch models based on resources and conversation needs.
Output: Working ModelManager with intelligent switching and basic Mai orchestration.
</objective>

<execution_context>
@~/.opencode/get-shit-done/workflows/execute-plan.md
@~/.opencode/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/phases/01-model-interface/01-RESEARCH.md
@.planning/phases/01-model-interface/01-CONTEXT.md
@.planning/codebase/ARCHITECTURE.md
@.planning/codebase/STRUCTURE.md
@.planning/phases/01-model-interface/01-01-SUMMARY.md
@.planning/phases/01-model-interface/01-02-SUMMARY.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Implement ModelManager with intelligent switching</name>
  <files>src/models/model_manager.py</files>
  <action>
Create ModelManager class that orchestrates all model operations:
1. Load model configuration from config/models.yaml
2. Implement intelligent model selection based on:
   - Available system resources (from ResourceMonitor)
   - Task complexity and conversation context
   - Model capability tiers
3. Add dynamic model switching during conversation (from CONTEXT.md)
4. Implement fallback chains when primary model fails
5. Handle model loading/unloading with proper resource cleanup
6. Support silent switching without user notification

Key methods:
- __init__: Load config, initialize adapters and monitors
- select_best_model(conversation_context): Choose optimal model
- switch_model(target_model_key): Handle model transition
- generate_response(message, conversation): Generate response with auto-switching
- get_current_model_status(): Return current model and resource usage
- preload_model(model_key): Background model loading

Follow CONTEXT.md decisions:
- Silent switching with no user notifications
- Dynamic switching mid-task if model struggles
- Smart context transfer during switches
- Auto-retry on model failures

Use research patterns for resource-aware selection and implement graceful degradation when no model fits constraints.
  </action>
  <verify>python -c "from src.models.model_manager import ModelManager; mm = ModelManager(); print(hasattr(mm, 'select_best_model') and hasattr(mm, 'generate_response'))"</verify>
  <done>ModelManager can intelligently select and switch models based on resources</done>
</task>

<task type="auto">
  <name>Task 2: Create core Mai orchestration class</name>
  <files>src/mai.py</files>
  <action>
Create core Mai class following architecture patterns:
1. Initialize ModelManager, ContextManager, and other systems
2. Provide main conversation interface:
   - process_message(user_input): Process message and return response
   - get_conversation_history(): Retrieve conversation context
   - get_system_status(): Return current model and resource status
3. Implement basic conversation flow using ModelManager
4. Add error handling and graceful degradation
5. Support both synchronous and async operation (asyncio)
6. Include basic logging of model switches and resource events

Key methods:
- __init__: Initialize all subsystems
- process_message(message): Main conversation entry point
- get_status(): Return system state for monitoring
- shutdown(): Clean up resources

Follow architecture: Mai class is main coordinator, delegates to specialized subsystems. Keep logic simple - most complexity should be in ModelManager and ContextManager.
  </action>
  <verify>python -c "from src.mai import Mai; mai = Mai(); print(hasattr(mai, 'process_message') and hasattr(mai, 'get_status'))"</verify>
  <done>Core Mai class orchestrates conversation processing with model switching</done>
</task>

<task type="auto">
  <name>Task 3: Create CLI entry point for testing</name>
  <files>src/__main__.py</files>
  <action>
Create CLI entry point following project structure:
1. Implement __main__.py with command-line interface
2. Add simple interactive chat loop for testing model switching
3. Include status commands to show current model and resources
4. Support basic configuration and model management commands
5. Add proper signal handling for graceful shutdown
6. Include help text and usage examples

Commands:
- chat: Interactive conversation mode
- status: Show current model and system resources
- models: List available models
- switch <model>: Manual model override for testing

Use argparse for command-line parsing. Follow standard Python package entry point patterns.
  </action>
  <verify>python -m mai --help shows usage information and commands</verify>
  <done>CLI interface provides working chat and system monitoring commands</done>
</task>

</tasks>

<verification>
Verify integrated system:
1. ModelManager can select appropriate models based on resources
2. Conversation processing works with automatic model switching
3. CLI interface allows testing chat and monitoring
4. Context is preserved during model switches
5. System gracefully handles model loading failures
6. Resource monitoring triggers appropriate model changes
</verification>

<success_criteria>
Complete model interface system:
- Intelligent model selection based on system resources
- Seamless conversation processing with automatic switching
- Working CLI interface for testing and monitoring
- Foundation ready for integration with memory and personality systems
</success_criteria>

<output>
After completion, create `.planning/phases/01-model-interface/01-03-SUMMARY.md`
</output>