reconcile-ai 1.0.3

AI-powered headless merge conflict resolver

Reconcile AI 🤖⚔️

AI-powered headless merge conflict resolver for Git repositories

Automatically resolve merge conflicts using large language models, with enterprise-grade hook management and comprehensive logging.

---

🌟 Features

🤖 AI-Powered Conflict Resolution

• Smart Merging: Uses OpenAI GPT models to intelligently resolve conflicts
• Batch Processing: Resolves multiple conflicts in single API calls (up to 80% cost reduction)
• Fallback Safety: Graceful degradation to individual resolution if batch processing fails
• Model Selection: Support for GPT-4, GPT-3.5-turbo, and other OpenAI models

🔧 Enterprise-Grade Hook Management

• Multiple Hook Types: Support for pre-commit, post-merge, pre-push, pre-merge
• Automatic Backup: Safely backs up existing hooks before installation
• Interactive Restoration: Restore previous hooks during uninstallation
• Smart Detection: Prevents duplicate installations and overwrites

📊 Advanced Logging & Monitoring

• Structured JSON Logs: Machine-readable logs for monitoring and analytics
• Performance Metrics: Track AI resolution latency, token usage, and success rates
• Verbose Debugging: Detailed step-by-step execution logging
• Conflict Hashing: Unique identifiers for tracking individual conflicts

⚙️ Flexible Configuration

• YAML Configuration: Project-specific settings and preferences
• CLI Overrides: Command-line arguments override config files
• File-Type Specific: Different models and prompts for different languages
• Branch Preferences: Customize resolution strategies per branch

---

🚀 Quick Start

Installation

# Install from PyPI
pip install reconcile-ai

# Or install from source
git clone https://github.com/yourusername/reconcile-ai.git
cd reconcile-ai
pip install -e .

Set up OpenAI API Key

export OPENAI_API_KEY="your-openai-api-key-here"

Basic Usage

# Resolve conflicts in current repository
reconcile run

# Preview conflicts without AI resolution
reconcile run --dry-run

# Install as a Git hook (runs automatically after merges)
reconcile install --hook post-merge

---

📚 User Guide

🎯 Basic Workflow Integration

1. Manual Conflict Resolution

Use reconcile when you encounter merge conflicts:

# Create a merge conflict
git merge feature-branch

# Resolve conflicts with AI
reconcile run --verbose

# Review the resolved files
git diff --cached

# Commit the resolution
git commit -m "Resolved conflicts with AI assistance"

2. Automated Hook Integration

Set up reconcile to run automatically:

# Install post-merge hook (runs after successful merges)
reconcile install --hook post-merge

# Install pre-commit hook (runs before commits)
reconcile install --hook pre-commit

# Install pre-push hook (runs before pushes)
reconcile install --hook pre-push

3. Team Workflow Integration

For Project Maintainers:

# Add reconcile config to your repository
cat > reconcile.yaml << EOF
model: "gpt-4"
max_batch_size: 5
temperature: 0
file_types:
  python:
    model: "gpt-4"
    custom_prompt: "Follow PEP 8 and Python best practices"
  javascript:
    model: "gpt-3.5-turbo"
    custom_prompt: "Follow ESLint rules and modern JS conventions"
EOF

# Commit the config
git add reconcile.yaml
git commit -m "Add reconcile AI configuration"

For Team Members:

# Install reconcile and set up hooks
pip install reconcile-ai
export OPENAI_API_KEY="your-key-here"
reconcile install --hook post-merge

# The hook will now run automatically on merges
git merge feature-branch  # Conflicts resolved automatically!

---

🛠️ Configuration

Configuration File (reconcile.yaml)

Create a reconcile.yaml file in your repository root:

# Model Configuration
model: "gpt-4"                    # Default AI model
max_batch_size: 5                 # Conflicts per batch (1-10)
temperature: 0                    # AI creativity (0-1)
timeout: 30                       # API timeout in seconds

# Branch Strategy
branch_preference: "feature"      # Prefer changes from specific branches
preserve_whitespace: true         # Maintain original formatting

# File-Type Specific Settings
file_types:
  python:
    model: "gpt-4"
    custom_prompt: "Follow PEP 8, use type hints, prefer comprehensions"
    max_batch_size: 3
  
  javascript:
    model: "gpt-3.5-turbo"
    custom_prompt: "Use modern ES6+, follow ESLint rules"
    max_batch_size: 5
  
  go:
    model: "gpt-4"
    custom_prompt: "Follow Go conventions, use gofmt style"

# Logging Configuration
logging:
  level: "INFO"                   # DEBUG, INFO, WARNING, ERROR
  json_format: true               # Enable structured logging
  file_path: ".reconcile/logs"    # Custom log directory

# Hook Configuration
hooks:
  post_merge:
    enabled: true
    auto_stage: true              # Automatically stage resolved files
    
  pre_commit:
    enabled: false
    check_conflicts: true         # Prevent commits with unresolved conflicts

Environment Variables

# Required
export OPENAI_API_KEY="sk-..."

# Optional
export RECONCILE_MODEL="gpt-4"
export RECONCILE_BATCH_SIZE="3"
export RECONCILE_LOG_LEVEL="DEBUG"

---

💻 Command Line Interface

Core Commands

reconcile run - Resolve Conflicts

# Basic conflict resolution
reconcile run

# With verbose logging
reconcile run --verbose

# Dry-run (show conflicts without resolving)
reconcile run --dry-run

# Override configuration
reconcile run --model gpt-3.5-turbo --max-batch-size 3

# Enable JSON logging
reconcile run --json-logs --verbose

# Specify repository path
reconcile run --repo /path/to/repo

reconcile install - Install Git Hooks

# Install post-merge hook (default)
reconcile install

# Install specific hook type
reconcile install --hook pre-commit
reconcile install --hook pre-push
reconcile install --hook pre-merge

# List available hooks
reconcile install --help

reconcile uninstall - Remove Git Hooks

# Uninstall post-merge hook (with interactive backup restoration)
reconcile uninstall

# Uninstall specific hook
reconcile uninstall --hook pre-commit

# View available backups and restore previous hooks
reconcile uninstall --hook post-merge

Advanced Usage Examples

Batch Processing for Large Conflicts

# Process conflicts in larger batches (faster, more cost-effective)
reconcile run --max-batch-size 8 --verbose

# Use smaller batches for complex conflicts
reconcile run --max-batch-size 2 --model gpt-4

Development and Debugging

# Debug mode with detailed logging
reconcile run --verbose --json-logs

# Check logs
tail -f .reconcile/reconcile.jsonl | jq '.'

# Dry-run with configuration preview
reconcile run --dry-run --verbose

---

🔍 Advanced Features

📊 Batch Processing

Reconcile AI can process multiple conflicts in a single API call:

# Automatically batches conflicts for efficiency
reconcile run  # Uses config max_batch_size

# Override batch size
reconcile run --max-batch-size 8

Benefits:

• ⚡ 80% faster processing for multiple conflicts
• 💰 Reduced API costs through batch requests
• 🧠 Better context awareness across related conflicts
• 🔄 Automatic fallback to individual resolution if batch fails

📈 Performance Monitoring

Track AI resolution performance with structured logging:

# Enable JSON logging
reconcile run --json-logs

# Analyze performance
cat .reconcile/reconcile.jsonl | jq '.latency_seconds' | awk '{sum+=$1; count++} END {print "Avg:", sum/count "s"}'

# Token usage analysis
cat .reconcile/reconcile.jsonl | jq '.tokens_used' | awk '{sum+=$1; count++} END {print "Total tokens:", sum}'

🔒 Enterprise Security

Safe Hook Management:

• Automatic backup of existing hooks
• Interactive restoration during uninstallation
• Verification of hook ownership before removal

API Key Security:

• Environment variable-based configuration
• No API keys stored in configuration files
• Clear error messages for missing credentials

---

🏢 Enterprise Workflows

CI/CD Integration

GitHub Actions

name: AI Conflict Resolution
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  resolve-conflicts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install Reconcile AI
        run: pip install reconcile-ai
      
      - name: Check for conflicts
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          git config user.name "AI Bot"
          git config user.email "[e-mail]"
          reconcile run --dry-run --json-logs

Jenkins Pipeline

pipeline {
    agent any
    environment {
        OPENAI_API_KEY = credentials('openai-api-key')
    }
    stages {
        stage('Resolve Conflicts') {
            steps {
                sh 'pip install reconcile-ai'
                sh 'reconcile run --verbose --json-logs'
                archiveArtifacts artifacts: '.reconcile/*.jsonl', allowEmptyArchive: true
            }
        }
    }
}

Team Standards

Code Review Integration

# Pre-commit hook for conflict prevention
reconcile install --hook pre-commit

# Pre-push hook for final validation
reconcile install --hook pre-push

Monitoring and Analytics

# Aggregate team metrics
find . -name "reconcile.jsonl" -exec cat {} \; | \
  jq -s 'group_by(.level) | map({level: .[0].level, count: length})'

# Resolution success rate
cat .reconcile/reconcile.jsonl | \
  jq 'select(.message | contains("Successfully resolved")) | .tokens_used' | \
  awk '{sum+=$1; count++} END {print "Success rate:", count " resolutions"}'

---

🤝 Development & Contributing

Local Development Setup

# Clone and setup
git clone https://github.com/yourusername/reconcile-ai.git
cd reconcile-ai

# Install in development mode
pip install -e ".[dev,yaml]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/ -v

# Run linting
black src/ tests/
flake8 src/ tests/
mypy src/

Running Tests

# Unit tests
pytest tests/test_reconcile.py -v

# Integration tests (requires Git)
pytest tests/test_integration.py -v

# Hook installation tests
pytest tests/test_hooks.py -v

# All tests with coverage
pytest --cov=reconcile --cov-report=html

Project Structure

reconcile-ai/
├── src/reconcile/
│   └── __init__.py          # Main application
├── tests/
│   ├── test_reconcile.py    # Unit tests
│   ├── test_integration.py  # Integration tests
│   └── conftest.py          # Test configuration
├── .github/workflows/
│   └── ci.yml               # GitHub Actions CI
├── pyproject.toml           # Package configuration
├── reconcile.yaml           # Example configuration
└── README.md               # This file

---

📊 Performance & Costs

Batch Processing Benefits

Conflicts	Individual Calls	Batch Calls	Time Saved	Cost Saved
5	5 calls	1 call	~80%	~60%
10	10 calls	2 calls	~80%	~60%
20	20 calls	4 calls	~80%	~60%

Token Usage Optimization

• Smart Prompting: Minimal context with maximum clarity
• Conflict Grouping: Related conflicts processed together
• Model Selection: Automatic model selection based on complexity
• Caching: Avoid re-processing identical conflicts

---

❓ FAQ

Q: Is my code sent to OpenAI?

A: Yes, conflict sections are sent to OpenAI's API for resolution. Review their data usage policy. Use --dry-run to see conflicts without sending data.

Q: What happens if the AI resolution is wrong?

A: Always review resolved conflicts before committing. Reconcile stages files but doesn't commit automatically. Use git diff --cached to review changes.

Q: Can I use other AI models besides OpenAI?

A: Currently, only OpenAI models are supported. Support for other providers (Anthropic, local models) is planned for future releases.

Q: Does this work with large files?

A: Yes, but very large conflicts may hit API token limits. Use smaller max_batch_size for complex conflicts.

Q: How do I uninstall hooks safely?

A: Use reconcile uninstall --hook <type>. It will show available backups and offer to restore your previous hooks.

Q: Can I customize the AI prompts?

A: Yes! Use the custom_prompt field in reconcile.yaml for file-type specific prompts.

---

📄 License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

---

🙏 Acknowledgments

• OpenAI for providing the GPT models that power conflict resolution
• GitPython for Git repository interaction
• PyYAML for configuration file support
• The open-source community for inspiration and contributions

---

🔗 Links

• Documentation: Full Documentation
• Issues: Bug Reports & Feature Requests
• Discussions: Community Discussion
• PyPI Package: reconcile-ai

---

Made with ❤️ for developers who hate merge conflicts

⭐ Star this project | 🐛 Report Issues | 💬 Join Discussion