INTEGRATION_PLAN.md
1 # Kamaji Go Tool + go-tui Integration Plan 2 3 ## Overview 4 5 Integrate the Kamaji Go CLI tool with the existing go-tui to create a unified, high-performance interface that leverages both Go's speed for system operations and Python's rich LLM ecosystem. 6 7 ## Architecture 8 9 ``` 10 ┌─────────────────────────────────────┐ 11 │ go-tui (Frontend) │ 12 │ - Bubble Tea interface │ 13 │ - User input/output │ 14 │ - Command routing │ 15 └─────────────┬───────────────────────┘ 16 │ 17 ▼ 18 ┌─────────────────────────────────────┐ 19 │ Integration Layer │ 20 │ - Command routing logic │ 21 │ - Backend selection │ 22 │ - Unified configuration │ 23 └─────┬───────────────────────┬───────┘ 24 │ │ 25 ▼ ▼ 26 ┌─────────────┐ ┌─────────────┐ 27 │ Go Tool │ │ Python │ 28 │ Backend │ │ Backend │ 29 │ │ │ │ 30 │ - Config │ │ - LLM ops │ 31 │ - Tools │ │ - Agents │ 32 │ - Status │ │ - RAG │ 33 │ - Files │ │ - Memory │ 34 └─────────────┘ └─────────────┘ 35 ``` 36 37 ## Implementation Steps 38 39 ### Phase 1: Foundation (2 hours) 40 41 1. **Unified Configuration System** 42 - Create shared config format (JSON) 43 - Support both Go and Python settings 44 - Hot-reload configuration changes 45 46 2. **Integration Layer** 47 - Command routing logic 48 - Backend selection algorithm 49 - Error handling and fallbacks 50 51 3. **Enhanced TUI Model** 52 - Extend existing go-tui model 53 - Add backend switching capabilities 54 - Integrate configuration management 55 56 ### Phase 2: Command Routing (3 hours) 57 58 1. **Smart Command Routing** 59 ```go 60 // Route based on command capabilities 61 commandRouting := map[string]string{ 62 "agent": "python", // LLM operations 63 "ask": "python", // LLM operations 64 "rag": "python", // RAG operations 65 "config": "go", // System config 66 "provider": "go", // Provider management 67 "status": "go", // System status 68 "tools": "go", // Tool management 69 "files": "go", // File operations 70 } 71 ``` 72 73 2. **Fallback Mechanisms** 74 - Try Go tool first for unknown commands 75 - Fallback to Python if Go tool fails 76 - User override for backend selection 77 78 3. **Performance Optimization** 79 - Cache backend capabilities 80 - Parallel execution where possible 81 - Minimize subprocess overhead 82 83 ### Phase 3: Enhanced Features (2 hours) 84 85 1. **Backend Status Display** 86 - Show current backend in status bar 87 - Display backend health/availability 88 - Performance metrics 89 90 2. **Advanced Commands** 91 ``` 92 /backend go|python|hybrid - Switch backend mode 93 /status - Show system status 94 /config edit - Edit configuration 95 /benchmark - Performance comparison 96 ``` 97 98 3. **Configuration UI** 99 - In-TUI configuration editor 100 - Backend preference settings 101 - Command routing customization 102 103 ### Phase 4: Integration Testing (2 hours) 104 105 1. **Comprehensive Testing** 106 - Test all command routes 107 - Verify fallback mechanisms 108 - Performance benchmarking 109 110 2. **Error Handling** 111 - Backend unavailability 112 - Configuration errors 113 - Command failures 114 115 3. **User Experience** 116 - Smooth backend transitions 117 - Clear status indicators 118 - Helpful error messages 119 120 ## Key Benefits 121 122 ### 1. **Performance Optimization** 123 - **Go Tool**: Fast system operations (config, status, files) 124 - **Python Backend**: Rich LLM capabilities (agents, RAG) 125 - **Smart Routing**: Use the right tool for each job 126 127 ### 2. **Unified Experience** 128 - Single TUI interface for all operations 129 - Seamless backend switching 130 - Consistent command syntax 131 132 ### 3. **Flexibility** 133 - User can choose preferred backend 134 - Fallback mechanisms ensure reliability 135 - Easy to extend with new backends 136 137 ### 4. **Maintainability** 138 - Clear separation of concerns 139 - Modular architecture 140 - Shared configuration system 141 142 ## Configuration Example 143 144 ```json 145 { 146 "provider": "ollama", 147 "model": "gpt-oss:120b", 148 "base_url": "http://192.222.50.154:11434", 149 "go_tool_enabled": true, 150 "python_backend_path": "kamaji", 151 "go_tool_path": "./go/bin/kamaji", 152 "theme": "fire", 153 "default_mode": "hybrid", 154 "enable_streaming": true, 155 "command_routing": { 156 "agent": "python", 157 "ask": "python", 158 "config": "go", 159 "provider": "go", 160 "status": "go", 161 "tools": "go" 162 } 163 } 164 ``` 165 166 ## Usage Examples 167 168 ### 1. **Hybrid Mode (Default)** 169 ```bash 170 # Automatically routes to appropriate backend 171 kamaji-tui 172 > /config show # → Go tool (fast) 173 > agent "analyze code" # → Python backend (LLM) 174 > /status # → Go tool (fast) 175 ``` 176 177 ### 2. **Backend Switching** 178 ```bash 179 > /backend go # Switch to Go-only mode 180 > /backend python # Switch to Python-only mode 181 > /backend hybrid # Smart routing (default) 182 ``` 183 184 ### 3. **Performance Comparison** 185 ```bash 186 > /benchmark config # Compare Go vs Python for config ops 187 > /benchmark status # Compare backend performance 188 ``` 189 190 ## File Structure 191 192 ``` 193 kamaji/ 194 ├── go-tui/ # Enhanced TUI 195 │ ├── integration.go # Integration layer 196 │ ├── config.go # Unified configuration 197 │ ├── enhanced_model.go # Enhanced TUI model 198 │ └── ...existing files... 199 ├── go/ # Go tool 200 │ ├── internal/cli/ # CLI commands 201 │ └── ...existing files... 202 ├── kamaji/ # Python backend 203 │ └── ...existing files... 204 └── integration_examples/ # Usage examples 205 ├── hybrid_usage.md 206 ├── config_examples.json 207 └── benchmark_results.md 208 ``` 209 210 ## Success Metrics 211 212 1. **Performance**: 10x faster system operations via Go tool 213 2. **Usability**: Seamless backend switching without user confusion 214 3. **Reliability**: 99%+ command success rate with fallbacks 215 4. **Maintainability**: Clean separation between Go and Python components 216 217 ## Timeline 218 219 - **Phase 1**: 2 hours - Foundation and configuration 220 - **Phase 2**: 3 hours - Command routing and integration 221 - **Phase 3**: 2 hours - Enhanced features and UI 222 - **Phase 4**: 2 hours - Testing and optimization 223 224 **Total**: ~9 hours for complete integration 225 226 ## Next Steps 227 228 1. Implement unified configuration system 229 2. Create integration layer with command routing 230 3. Enhance go-tui model with backend switching 231 4. Add comprehensive testing and error handling 232 5. Document usage patterns and best practices 233 234 This integration will provide the best of both worlds: Go's performance for system operations and Python's rich LLM ecosystem, all through a unified, fast TUI interface.