Architecture Overview
Upsilon follows a modular, extensible architecture designed for composability and maintainability. This document provides a high-level overview of the system architecture and design principles.
Design Principles
1. Composability
Upsilon is built as a collection of loosely coupled components that can be mixed and matched:
- Pluggable tools: Built-in and external tools through common interfaces
- Configurable workflows: Customizable review processes
- Multiple interfaces: CLI, API, and pre-commit integration
2. External Tool Integration
Rather than reimplementing existing functionality, Upsilon leverages proven tools:
- Real compilers: Python's
compile(), rustc, go build - Established linters: mypy, ruff, eslint
- Language servers: Future integration potential
3. Type Safety
Built with modern Python practices:
- mypy strict mode: Full type checking coverage
- Pydantic models: Runtime validation and serialization
- Generic interfaces: Type-safe plugin system
4. Testability
Comprehensive testing strategy:
- 59 test cases: High coverage across all components
- Mock implementations: Testable without external dependencies
- Integration tests: Real tool execution validation
System Architecture
Core Components
1. Configuration System (config.py)
Manages all application configuration using Pydantic models:
class UpsilonConfig(BaseModel):
model: str = "claude-3-haiku-20240307"
max_tokens: int = 2000
temperature: float = 0.1
builtin_tools: Dict[str, BuiltinToolConfig] = Field(default_factory=dict)
rules: RulesConfig = Field(default_factory=RulesConfig)
prompts: PromptConfig = Field(default_factory=PromptConfig)
Key Features:
- TOML file parsing with validation
- Default value management
- Type-safe configuration access
- Hierarchical configuration structure
2. Code Reviewer (reviewer.py)
The main orchestrator that coordinates the review process:
class CodeReviewer:
def __init__(self, config: UpsilonConfig, use_mock: bool = True):
self.config = config
self.llm_client = create_llm_client(config, use_mock=use_mock)
self._initialize_tools()
def review_file(self, file_path: Path) -> Dict[str, Any]:
# File validation and language detection
# Tool execution coordination
# LLM analysis integration
# Result aggregation
Responsibilities:
- File type detection and validation
- Tool initialization and registration
- Review workflow orchestration
- Result aggregation and formatting
3. Tool System (tools/)
Pluggable architecture for code analysis tools:
Base Interface (tools/base.py)
class Tool(ABC):
def __init__(self, name: str, config: Dict[str, Any]):
self.name = name
self.config = config
@abstractmethod
def analyze(self, content: str, file_path: str, language: str) -> ToolResult:
pass
@abstractmethod
def get_function_schema(self) -> Dict[str, Any]:
pass
Built-in Tools (tools/builtin.py)
- SpellChecker: Detects typos in comments and strings
- SyntaxChecker: Uses language compilers for syntax validation
- ImportAnalyzer: Checks import patterns and usage
External Tools (tools/external.py)
- Generic ExternalTool: Subprocess execution framework
- Language-specific tools: mypy, ruff, rustc, go build, etc.
- Auto-detection: Checks tool availability on system
4. LLM Integration (llm_client.py)
Handles communication with language models:
class LLMClient(ABC):
def __init__(self, config: UpsilonConfig):
self.config = config
self.tools: Dict[str, Tool] = {}
def register_tool(self, tool: Tool) -> None:
self.tools[tool.name] = tool
@abstractmethod
def review_code(self, content: str, file_path: str,
language: str, available_tools: List[str]) -> Dict[str, Any]:
pass
Implementations:
- MockLLMClient: Deterministic responses for testing
- AnthropicLLMClient: Real Claude API integration with function calling
5. CLI Interface (main.py)
Rich command-line interface using Typer and Rich:
app = typer.Typer(name="upsilon", help="AI-powered code review")
@app.command()
def review(
files: List[Path] = typer.Argument(...),
config_path: Optional[Path] = typer.Option(None),
format: OutputFormat = typer.Option(OutputFormat.text),
mock: bool = typer.Option(True),
verbose: bool = typer.Option(False),
stdin: bool = typer.Option(False)
):
# Implementation
Data Flow
1. Initialization Flow
CLI Command → Load Config → Initialize Reviewer → Register Tools → Ready
2. Review Flow
File Input → Language Detection → Tool Selection → Tool Execution →
LLM Analysis → Function Calling → Result Aggregation → Output Formatting
3. Tool Execution Flow
Tool Registration → Availability Check → Configuration → Execution →
Result Parsing → Normalization → Return ToolResult
Extension Points
1. Custom Tools
Implement the Tool interface:
class CustomTool(Tool):
def analyze(self, content: str, file_path: str, language: str) -> ToolResult:
# Custom analysis logic
pass
def get_function_schema(self) -> Dict[str, Any]:
# LLM function calling schema
pass
2. Custom LLM Clients
Implement the LLMClient interface for other providers:
class CustomLLMClient(LLMClient):
def review_code(self, content: str, file_path: str,
language: str, available_tools: List[str]) -> Dict[str, Any]:
# Custom LLM integration
pass
3. Output Formatters
Extend output formatting for different use cases:
class CustomFormatter:
def format_results(self, results: List[Dict[str, Any]]) -> str:
# Custom formatting logic
pass
Performance Considerations
1. Tool Execution
- Parallel execution: Tools run independently
- Caching: Results cached per file content hash
- Timeout handling: Prevents hanging on problematic files
2. LLM Optimization
- Token management: Configurable limits per request
- Batch processing: Multiple files in single request when possible
- Model selection: Fast models for pre-commit, powerful for CI/CD
3. Memory Management
- Streaming: Large files processed in chunks
- Cleanup: Temporary files automatically removed
- Resource limits: Configurable memory and time constraints
Security Considerations
1. External Tool Execution
- Sandboxing: External tools run in isolated environments
- Input validation: All file content is validated before processing
- Timeout enforcement: Prevents denial-of-service attacks
2. API Key Management
- Environment variables: API keys stored securely
- No logging: API keys never logged or exposed
- Validation: API key format validation
3. File Access
- Path validation: Prevents directory traversal attacks
- Permission checks: Respects file system permissions
- Temporary files: Secure temporary file creation and cleanup
Next: External Tools →