git-iris 1.1.0

AI-powered Git workflow assistant for smart commits, code reviews, changelogs, and release notes
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
# Git-Iris 2.0: Agent-Based Architecture

## Overview

Git-Iris 2.0 reimagines our application as an agent-centric system built on the Rig framework, moving away from the current approach of "throwing a bunch of context at the LLM and hoping for the best." This document outlines our architectural vision, implementation strategy, and migration path.

## Core Vision

Rather than gathering all possible context upfront, Git-Iris 2.0 will employ specialized agents that dynamically explore a codebase to gather precisely the context needed for a given task. These agents will:

1. Start with minimal context (the diff)
2. Iteratively explore the codebase through tool calls
3. Make decisions about what additional information is relevant
4. Stop when they have sufficient context to complete the task

This approach offers several advantages:
- **Precision over bulk**: Only gather what's necessary
- **Improved performance**: Reduce token usage and processing time
- **Better user experience**: Faster responses with more relevant outputs
- **Scalability**: Handle larger codebases without overwhelming token limits
- **Adaptability**: Easily adjust exploration strategy based on task requirements

## Architecture

### System Components

```
┌─────────────────────────────────────────────┐
│                                             │
│                Git-Iris Core                │
│                                             │
└───────────────────┬─────────────────────────┘
┌─────────────────────────────────────────────┐
│                                             │
│              Agent Orchestrator             │
│                                             │
└───────┬───────────────┬───────────┬─────────┘
        │               │           │
        ▼               ▼           ▼
┌───────────────┐ ┌───────────┐ ┌───────────┐
│ Commit Agent  │ │ Review    │ │ Changelog │
│               │ │ Agent     │ │ Agent     │
└───────┬───────┘ └─────┬─────┘ └─────┬─────┘
        │               │             │
        │               │             │
┌───────▼───────────────▼─────────────▼─────┐
│                                           │
│                 Tool Registry             │
│                                           │
└───────────────────────────────────────────┘
```

### Key Components

1. **Git-Iris Core**: The main application shell, handling user interactions, configuration, and coordinating the various agents. Provides a unified interface for CLI and API interactions.

2. **Agent Orchestrator**: Manages agent lifecycle, initializes appropriate agents based on the task, and provides common infrastructure. Responsible for:
   - Agent instantiation and configuration
   - Resource allocation and monitoring
   - Inter-agent communication
   - Task delegation and result aggregation
   - Error handling and recovery strategies

3. **Specialized Agents**:
   - **Commit Agent**: Generates commit messages based on staged changes
   - **Review Agent**: Performs code reviews of staged changes
   - **Changelog Agent**: Generates changelogs and release notes
   - **Context Explorer Agent**: Explores and maps codebase structure
   - **Code Analyzer Agent**: Analyzes specific code pieces for details
   - **Structure Analyzer Agent**: Maps relationships and dependencies
   - **Meta Analyzer Agent**: Examines metadata and configuration

4. **Tool Registry**: Centralized registry of tools that agents can utilize to explore and understand the codebase. Features:
   - Dynamic tool discovery and registration
   - Tool versioning and compatibility management
   - Access control and security boundaries
   - Performance monitoring and optimization

### Agent Workflow

Each specialized agent follows this general process:

1. **Initialize** with minimal context (usually the diff or basic repository info)
2. **Explore** the codebase using tools to gather relevant information
3. **Analyze** the gathered information to determine what else is needed
4. **Generate** the desired output once sufficient context is obtained
5. **Refine** the output based on additional context if necessary

## Implementation Using Rig

We'll leverage the [Rig framework](https://docs.rs/rig-core) to implement our agent architecture. Rig provides the foundations for building LLM-powered agents in Rust with strong typing and performance.

### Agent Implementation

```rust
use rig::{
    agent::AgentBuilder,
    completion::Prompt,
    providers::llm_provider
};

// Common agent setup pattern
pub fn create_commit_agent(
    config: &Config,
    diff: &str,
) -> Agent<impl CompletionModel> {
    let provider = get_provider_from_config(config);
    let model = provider.completion_model(config.model_name());
    
    AgentBuilder::new(model)
        .preamble(COMMIT_AGENT_PROMPT)
        .context(format!("DIFF:\n{}", diff))
        .tool(FileReaderTool::new())
        .tool(DirectoryListTool::new())
        .tool(CodeSearchTool::new())
        .tool(GitHistoryTool::new())
        .temperature(config.temperature())
        .build()
}
```

### Tool Implementation

Each tool will implement the `Tool` trait from Rig:

```rust
use rig::tool::{Tool, ToolError};

pub struct FileReaderTool {
    // Implementation details
}

impl Tool for FileReaderTool {
    fn name(&self) -> &str {
        "read_file"
    }
    
    fn description(&self) -> &str {
        "Reads the contents of a specified file"
    }
    
    fn schema(&self) -> serde_json::Value {
        json!({
            "type": "object",
            "properties": {
                "path": {
                    "type": "string",
                    "description": "Path to the file, relative to the repository root"
                }
            },
            "required": ["path"]
        })
    }
    
    async fn run(&self, params: serde_json::Value) -> Result<serde_json::Value, ToolError> {
        // Implementation
    }
}
```

### Core Tools

We'll implement these foundational tools:

1. **FileReader**: Read specific files from the repository
   - Path validation and security boundaries
   - Smart chunking for large files
   - Syntax highlighting and metadata enrichment

2. **DirectoryLister**: List contents of directories
   - Filtering by file type, name patterns
   - Recursive exploration with depth control
   - Directory structure visualization

3. **CodeSearcher**: Search for patterns or symbols in the codebase
   - Regex and semantic search capabilities
   - Language-aware context extraction
   - Token-aware result pagination

4. **DiffAnalyzer**: Analyze changes in a specific file
   - Line-by-line diff visualization
   - Semantic change categorization
   - Impact analysis on dependencies

5. **GitHistoryReader**: Examine commit history for relevant information
   - Author and time-range filtering
   - Commit message analysis
   - Code evolution tracking

6. **RepositoryMetaReader**: Access metadata about the repository
   - Configuration file analysis
   - Dependency management
   - Project structure insights

### Task-Specific Tools

These specialized tools will be made available based on the task:

1. **CommitAnalyzer**: Analyze commit messages for patterns (for commit agent)
   - Conventional commit parsing
   - Historical style matching
   - Quality assessment

2. **CodeQualityAnalyzer**: Identify code quality issues (for review agent)
   - Pattern-based anti-pattern detection
   - Complexity analysis
   - Style consistency checking

3. **BreakingChangeDetector**: Detect API changes (for changelog agent)
   - Interface signature comparison
   - Public API tracking
   - Backward compatibility assessment

4. **DependencyAnalyzer**: Analyze project dependencies (for changelog/review agents)
   - Dependency graph visualization
   - Version compatibility checking
   - Security vulnerability scanning

## MCP Integration

The Model Context Protocol (MCP) integration will be re-architected to align with our agent-based approach. Each MCP tool will be mapped to a specialized agent:

```
MCP Tool                  Git-Iris Agent
-----------------------------------------
git_iris_commit       →   Commit Agent
git_iris_code_review  →   Review Agent
git_iris_changelog    →   Changelog Agent
git_iris_release_notes→   Changelog Agent
```

The MCP server will:
1. Receive tool calls from clients
2. Initialize the appropriate agent
3. Provide the agent with necessary context
4. Return the agent's output to the client
5. Support streaming responses for long-running tasks

## Performance Optimizations

To ensure responsiveness:

1. **Parallel Tool Execution**: When possible, execute multiple tool calls in parallel
   - Independent tool call batching
   - Priority-based execution queuing
   - Resource-aware scheduling

2. **Context Caching**: Cache results of expensive tool calls for reuse
   - Time-based cache invalidation
   - Dependency-aware cache refreshing
   - Shared cache across agent instances

3. **Progressive Generation**: Stream results as they become available
   - Incremental context assembly
   - Early output generation
   - Continuous refinement

4. **Adaptive Exploration**: Use heuristics to limit unnecessary exploration
   - Relevance scoring for exploration paths
   - Diminishing returns detection
   - Exploration depth budgeting

5. **Token Budget Management**: Track token usage and optimize queries
   - Dynamic context prioritization
   - Compression techniques for context
   - Important information highlighting

## Metrics and Monitoring

To ensure our agent-based system delivers on its promises, we'll implement comprehensive metrics and monitoring:

### Key Metrics to Track

1. **Performance Metrics**:
   - Average response time per agent type
   - Token usage per agent interaction
   - Tool call frequency and latency
   - Cache hit/miss ratio for context requests
   - Memory usage and garbage collection patterns

2. **Quality Metrics**:
   - Output quality scoring (via separate evaluation)
   - User satisfaction ratings
   - Error rates and recovery success
   - Context relevance assessment
   - Hallucination frequency detection

3. **Exploration Metrics**:
   - Depth of exploration per task
   - Files accessed vs. files available ratio
   - Tool call patterns and efficiency
   - Path redundancy in exploration
   - Time spent in exploration vs. generation

### Monitoring Infrastructure

We'll implement:
1. **Telemetry Pipeline**: Collect detailed usage statistics
2. **Performance Dashboard**: Real-time visualization of system performance
3. **A/B Testing Framework**: Compare different agent configurations
4. **Anomaly Detection**: Identify and alert on unusual behavior patterns
5. **User Feedback Loop**: Capture and incorporate user satisfaction data

## Technical Debt Considerations

As we transition to an agent-based architecture, we need to be mindful of potential technical debt:

1. **Legacy System Compatibility**: Ensure backward compatibility during migration
2. **Prompt Engineering Maintenance**: Develop systems to maintain and version agent prompts
3. **Tool Proliferation**: Avoid creating redundant or overlapping tools
4. **Provider Lock-in**: Maintain abstraction layers for LLM provider flexibility
5. **Testing Complexity**: Develop strategies for testing non-deterministic agent behavior
6. **Error Handling Consistency**: Establish patterns for error recovery across components
7. **Documentation Overhead**: Keep documentation in sync with rapidly evolving components

We'll address these concerns through:
- Regular architecture reviews
- Comprehensive test coverage
- Careful documentation of design decisions
- Planned refactoring cycles
- Clear component boundaries and interfaces
- Automated testing and validation pipelines

## Implementation Roadmap

The detailed implementation plan for Git-Iris 2.0 is maintained in a separate document: [Implementation Checklist](implementation-checklist.md).

The implementation is divided into four main phases:

1. **Foundation**: Building the core architecture and fundamental tools
   - Tool registry implementation
   - Agent orchestrator framework
   - Basic tool set development
   - Initial agent prototypes

2. **Agent Development**: Implementing specialized agents with advanced capabilities
   - Agent communication protocols
   - Specialized agent implementation
   - Advanced tool development
   - Agent collaboration mechanisms

3. **MCP & User Experience**: Reimplementing the MCP integration and enhancing UX
   - MCP server redesign
   - CLI improvements
   - Performance optimizations
   - User feedback integration

4. **Testing & Refinement**: Comprehensive testing and final refinements
   - Test suite development
   - Documentation updates
   - Performance tuning
   - Final release preparation

For detailed tasks, status tracking, and implementation notes, refer to the implementation checklist document.

## Transitioning from llms to Rig

Git-Iris currently utilizes the `llms` crate as a flexible abstraction layer for interfacing with various LLM providers. Moving to Rig represents a significant architecture change that offers several advantages while requiring careful migration.

### Rig vs. llms Comparison

| Feature | llms | Rig |
|---------|------|-----|
| Provider Support | OpenAI, Anthropic, Google, etc. | OpenAI, Anthropic, Cohere, Perplexity |
| Type Safety | Basic | Enhanced with stronger type guarantees |
| Agent Support | Limited, requires custom implementation | First-class, built-in agent framework |
| RAG Capabilities | Not included, requires separate implementation | Integrated vector stores and embedding support |
| Streaming | Basic support | Native, first-class streaming support |
| Tool Integration | Not included | Built-in tool framework |
| Error Handling | Basic | Comprehensive with recovery strategies |
| Caching | Not included | Built-in context caching |

### Migration Strategy

#### 1. Provider Adapter Layer

We'll begin by creating a compatibility layer that adapts our existing provider configurations to Rig's provider system:

```rust
pub fn adapt_provider(provider_config: &ProviderConfig) -> Box<dyn RigCompatibleProvider> {
    match provider_config.provider_type() {
        ProviderType::OpenAI => {
            let client = openai::Client::new(provider_config.api_key());
            Box::new(OpenAIAdapter { client })
        },
        ProviderType::Anthropic => {
            let client = anthropic::Client::new(provider_config.api_key());
            Box::new(AnthropicAdapter { client })
        },
        // Other providers...
    }
}
```

#### 2. Gradual Feature Migration

We'll migrate features from the current architecture to Rig in this order:

1. **Basic Completion API**: Ensure we can get equivalent results with Rig
2. **Provider Authentication**: Migrate all provider auth patterns
3. **Tool Implementation**: Recreate our current tools using Rig's tool framework
4. **Agent Implementation**: Build specialized agents using Rig's agent system

#### 3. Dual-Mode Operation

During transition, we'll support both systems simultaneously:

```rust
pub enum CompletionBackend {
    Legacy(llms::CompletionProvider),
    Rig(rig::Agent<impl CompletionModel>)
}

impl CompletionBackend {
    pub async fn complete(&self, prompt: &str) -> Result<String> {
        match self {
            Self::Legacy(provider) => provider.complete(prompt).await,
            Self::Rig(agent) => {
                let response = agent.prompt(prompt).await?;
                Ok(response.to_string())
            }
        }
    }
}
```

#### 4. Testing & Validation

For each migrated component:
- Create parity tests to ensure consistency
- Benchmark performance differences
- Validate output quality between implementations
- Implement canary deployments to detect issues early

#### 5. Dependency Updates

We'll need to carefully manage our dependencies during transition:
- Add Rig as a dependency
- Maintain llms until migration is complete
- Eventually remove llms dependency
- Update other dependent crates
- Ensure compatibility with the broader ecosystem

### Key Rig Features to Leverage

In our transition, we'll focus on these key Rig advantages:

1. **Native Agent Framework**: Rig's agent system eliminates our need to build custom agent infrastructure, providing a solid foundation that handles:
   - Tool discovery and execution
   - Context management
   - Agent state tracking
   - Reasoning step tracking

2. **Built-in RAG Support**: Rig provides integrated vector database and embedding functionality that we can leverage for:
   - Semantic code search
   - Relevant file discovery
   - Similar code pattern identification
   - Intelligent context prioritization

3. **Provider Simplification**: Rig offers a cleaner API for working with LLM providers:
   - Consistent error handling
   - Simplified authentication
   - Standardized parameter passing
   - Automatic model detection
   - Capability-based provider selection

4. **Dynamic Context Management**: Rig's ability to handle dynamic contexts will allow us to:
   - Progressively load relevant files
   - Automatically manage token limits
   - Intelligently prioritize context elements
   - Track context utilization

## Migration Strategy

We'll implement a phased migration approach:

1. **Dual-Mode Operation**: Support both current and agent-based approaches with a configuration toggle
2. **Feature Parity**: Ensure all existing functionality works with the new approach
3. **Gradual Transition**: Move features one at a time to the agent-based approach
4. **Performance Benchmarking**: Compare results and performance between approaches
5. **User Feedback Collection**: Gather input on quality and performance differences

## Expected Outcomes

The agent-based architecture is expected to deliver:

1. **More Relevant Outputs**: By focusing on what matters for the task
2. **Faster Performance**: By reducing unnecessary context gathering
3. **Higher Quality**: Better understanding of codebase relationships
4. **Improved Scalability**: Better handling of large repositories
5. **More Maintainable Codebase**: Clearer separation of concerns
6. **Enhanced Extensibility**: Easier to add new capabilities
7. **Finer Control**: More precise configuration options for advanced users

## Conclusion

Git-Iris 2.0's agent-based architecture represents a significant advancement in how AI interacts with codebases. By moving from bulk context loading to intelligent exploration, we'll deliver a more responsive, accurate, and powerful developer tool.

This approach aligns with the cutting edge of AI agent research while maintaining Git-Iris's commitment to performance, privacy, and user experience. The implementation checklist provides a clear path forward, with measurable milestones to track our progress toward this vision.