Skip to main content

​
Overview

Refactron v1.0.15+ integrates Large Language Models (LLMs) with Retrieval-Augmented Generation (RAG) to provide context-aware, intelligent code refactoring and documentation generation.

​
Core Components

LLM Orchestrator

Coordinates between analyzer, retriever, and LLM backends

RAG System

Vector database (ChromaDB) for code indexing and retrieval

LLM Backends

Support for Groq, local models, and custom providers

Safety Gate

Validates LLM-generated code for syntax and safety

​
Setup

​
Prerequisites

AI features require additional dependencies (already included with Refactron):
  • ChromaDB for vector storage
  • Sentence Transformers for embeddings
  • Groq API access (or alternative LLM provider)

​
Configuration

Set your LLM API key: 
export GROQ_API_KEY='your-api-key-here'
Configure LLM settings in .refactron.yaml:
.refactron.yaml
llm:
  provider: groq
  model: llama3-70b-8192
  temperature: 0.1
  max_tokens: 4096

rag:
  enabled: true
  storage_dir: .refactron/rag_index
  embedding_model: all-MiniLM-L6-v2

​
RAG Indexing

​
Index Your Codebase

Before using AI features, index your project: 
# Basic indexing
refactron rag index

# Index with AI-generated summaries
refactron rag index --summarize
This creates vector embeddings of your code for context retrieval.

​
Check Index Status

refactron rag status
Output: 
✓ RAG Index Status
  Indexed files: 142
  Total chunks: 856
  Last updated: 2024-02-15 10:30:42
  Storage: .refactron/rag_index

​
Search Codebase

Semantic search across your codebase: 
# Basic search
refactron rag search "authentication logic"

# With AI reranking
refactron rag search "database connection" --rerank

​
AI-Powered Refactoring

​
Enable AI Suggestions

Use the --ai flag to enable LLM-powered refactoring: 
# Preview AI refactoring suggestions
refactron refactor myfile.py --ai --preview

# Apply AI suggestions
refactron refactor myfile.py --ai --apply

​
How It Works

1

Analysis

Refactron analyzes your code for issues
2

Context Retrieval

RAG system retrieves relevant code chunks from your project
3

LLM Generation

LLM generates refactoring suggestions with project context
4

Safety Validation

Safety gate validates syntax and checks for issues
5

Presentation

Suggestions presented with explanations and risk scores

​
Example

# Original code with issues
def process_users(users):
    result = []
    for user in users:
        if user.age > 18:
            if user.status == 'active':
                if user.verified:
                    result.append(user)
    return result
AI-powered refactoring suggests: 
# AI-suggested refactoring
def process_users(users):
    """Process and filter users based on eligibility criteria.
    
    Args:
        users: List of user objects to process
        
    Returns:
        List of eligible users (adult, active, verified)
    """
    return [
        user for user in users
        if user.age > 18 and user.status == 'active' and user.verified
    ]

​
AI Documentation Generation

​
Generate Docstrings

Automatically create docstrings using AI: 
# Preview docstring generation
refactron document myfile.py

# Apply docstrings
refactron document myfile.py --apply

​
Line-Specific Suggestions

Get AI suggestions for specific lines: 
# Suggest improvements for line 42
refactron suggest myfile.py --line 42

# Apply suggestion instantly
refactron suggest myfile.py --line 42 --apply

​
Available LLM Providers

Bring your own LLM providerConfigure in .refactron.yaml:
llm:
  provider: custom
  endpoint: https://your-llm-api.com/v1
  api_key: your-key

​
RAG Workflow

​
How RAG Enhances Refactoring

  1. Parsing: Code files split into semantic chunks (classes, methods)
  2. Embedding: Chunks converted to vector representations
  3. Indexing: Vectors stored in ChromaDB with metadata
  4. Retrieval: Relevant chunks retrieved when analyzing issues
  5. Context: LLM receives project-specific context for better suggestions

​
Update Index

Re-index after significant code changes: 
# Update index incrementally
refactron rag index --update

# Full re-index
refactron rag index --force

​
Feedback and Learning

Provide feedback on AI suggestions to improve quality: 
# Record acceptance
refactron feedback <operation-id> --action accepted

# Record rejection with reason
refactron feedback <operation-id> --action rejected --reason "Breaks API contract"
AI suggestions integrate with Pattern Learning to improve over time

​
Configuration Options

​
llm.provider
string
default:"groq"
LLM provider (groq, custom)
​
llm.model
string
default:"llama3-70b-8192"
Model identifier for the provider
​
llm.temperature
number
default:"0.1"
Temperature for generation (0.0 - 1.0, lower = more deterministic)
​
llm.max_tokens
number
default:"4096"
Maximum tokens in LLM response
​
rag.enabled
boolean
default:"true"
Enable RAG system
​
rag.storage_dir
string
default:".refactron/rag_index"
Directory for RAG index storage
​
rag.embedding_model
string
default:"all-MiniLM-L6-v2"
Sentence transformer model for embeddings

​
Best Practices

Re-run refactron rag index after significant code changes for accurate context
Models like Llama 3 70B provide better refactoring logic than smaller models
Use --preview to review AI-generated code before applying
Record feedback to improve AI suggestions over time
Run your test suite after applying AI refactorings

​
Troubleshooting

Ensure GROQ_API_KEY is set:
echo $GROQ_API_KEY
Export it in your shell profile for persistence
Create index first:
refactron rag index
  • Use smaller models (llama3-8b-8192)
  • Reduce max_tokens
  • Limit context retrieval chunks

​
Next Steps

Pattern Learning

Learn how feedback improves suggestions

CLI Reference

Explore all AI-related commands