Commit 081db4f
2025-06-10 21:16:23
Changed files (1)
README.md
@@ -0,0 +1,1448 @@
+# Open Source AI Code Assistant - Design Document
+
+## Table of Contents
+1. [Project Overview](#project-overview)
+2. [System Architecture](#system-architecture)
+3. [Hardware Requirements](#hardware-requirements)
+4. [Technology Stack](#technology-stack)
+5. [Component Specifications](#component-specifications)
+6. [API Specification](#api-specification)
+7. [CLI Interface Specification](#cli-interface-specification)
+8. [Shell Integration](#shell-integration)
+9. [MCP Integration](#mcp-integration)
+10. [REPL Requirements](#repl-requirements)
+11. [Model Training Pipeline](#model-training-pipeline)
+12. [Data Processing Requirements](#data-processing-requirements)
+13. [Implementation Phases](#implementation-phases)
+14. [Testing Requirements](#testing-requirements)
+
+## Project Overview
+
+### Mission Statement
+Build "Del the Funky Robosapien" (or "Del" for short) - a completely free, open-source AI code assistant that runs entirely on consumer hardware, providing privacy-first AI assistance for developers without any cloud dependencies.
+
+### Core Requirements
+- **Privacy First**: All data processing must happen locally
+- **Open Source**: MIT license, fully auditable code
+- **Consumer Hardware**: Must run on typical developer machines
+- **Self-Contained**: No external API dependencies
+- **Extensible**: Plugin architecture for custom workflows
+- **Multi-Platform**: Support Linux, macOS, and Windows
+
+### Target Users
+- Individual developers seeking privacy-first AI assistance
+- Teams wanting to keep code confidential
+- Organizations with strict data governance requirements
+- Students learning to code without subscription costs
+- Open source projects needing AI assistance
+
+### Success Criteria
+- Generate useful code suggestions within 3 seconds
+- Handle codebases up to 100,000 files
+- Support 10+ programming languages
+- Process Git histories with 50,000+ commits
+- Train custom models on user data in under 4 hours
+
+## System Architecture
+
+### High-Level Architecture
+```
+┌─────────────────────────────────────────────────────────┐
+│ User Interfaces │
+│ ┌─────────────┬─────────────┬─────────────────────────┐ │
+│ │ CLI Client │ Web Client │ IDE Extensions │ │
+│ │ Commands │ Dashboard │ VS Code, Vim, Emacs │ │
+│ │ REPL │ Chat UI │ IntelliJ, Sublime │ │
+│ │ Scripts │ File Upload │ Custom integrations │ │
+│ └─────────────┴─────────────┴─────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+ │ HTTP/WebSocket API
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ API Gateway │
+│ • HTTP/HTTPS Server • Request/Response Logging │
+│ • WebSocket Support • Rate Limiting │
+│ • Authentication • Input Validation │
+│ • CORS Handling • Error Management │
+└─────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ Business Logic │
+│ ┌─────────────────┬─────────────────┬─────────────────┐ │
+│ │ Context Manager │ Code Analyzer │ Response Gen │ │
+│ │ • File tracking │ • AST parsing │ • Prompt eng │ │
+│ │ • Embeddings │ • Syntax check │ • Templates │ │
+│ │ • Similarity │ • Dependencies │ • Streaming │ │
+│ │ • Ranking │ • Call graphs │ • Formatting │ │
+│ └─────────────────┴─────────────────┴─────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ Infrastructure │
+│ ┌─────────────────┬─────────────────┬─────────────────┐ │
+│ │ Model Server │ Data Pipeline │ Storage Layer │ │
+│ │ • LLM Inference │ • Git Parser │ • Vector DB │ │
+│ │ • GPU Support │ • Email Parser │ • Context Store │ │
+│ │ • Model Cache │ • Doc Parser │ • Config Store │ │
+│ │ • Memory Mgmt │ • Training Prep │ • Session Mgmt │ │
+│ └─────────────────┴─────────────────┴─────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Data Flow Architecture
+```
+Input Sources → Data Pipeline → Context Store → Model Server → Response
+ │ │ │ │ │
+ ▼ ▼ ▼ ▼ ▼
+• Git repos • Parse files • Vector DB • LLM Inference • Text
+• Email boxes • Extract code • Embeddings • GPU Accel • Code
+• Documents • Analyze AST • Similarity • Memory Mgmt • Explanations
+• Live files • Generate • Ranking • Streaming • Suggestions
+• User input training data • Search • Error Handle • Context
+```
+
+## Hardware Requirements
+
+### Minimum Configuration (Basic Usage)
+| Component | Specification | Purpose |
+|-----------|---------------|---------|
+| **CPU** | 4-core x86_64/ARM64, 2.5GHz+ | Model inference, embeddings |
+| **RAM** | 8GB total (4GB model + 4GB system) | Model loading, context storage |
+| **Storage** | 20GB free space, preferably SSD | Models, embeddings, context data |
+| **GPU** | Optional, any OpenCL/CUDA compatible | Accelerated inference |
+| **Network** | None (fully offline after setup) | Initial model downloads only |
+| **OS** | Linux/macOS/Windows 10+ | Cross-platform support |
+
+**Expected Performance**: 3B parameter model, 5-10 tokens/second, 4K context, single user
+
+### Recommended Configuration (Optimal Experience)
+| Component | Specification | Purpose |
+|-----------|---------------|---------|
+| **CPU** | 8-core with AVX2, 3.0GHz+ | Faster CPU inference |
+| **RAM** | 16GB total (8GB model + 8GB system) | Larger models, more context |
+| **Storage** | 100GB SSD, NVMe preferred | Multiple models, large context store |
+| **GPU** | NVIDIA RTX 3060+ (8GB VRAM) or Apple M2 | GPU acceleration |
+| **Network** | Gigabit for initial setup | Faster model downloads |
+
+**Expected Performance**: 7B parameter model, 15-25 tokens/second, 8K context, 2-3 concurrent users
+
+### Enterprise Configuration (Heavy Usage)
+| Component | Specification | Purpose |
+|-----------|---------------|---------|
+| **CPU** | 16+ cores, server grade | Multiple concurrent requests |
+| **RAM** | 32GB+ | Large models (13B+), extensive context |
+| **Storage** | 500GB+ NVMe SSD | Multiple models, large datasets |
+| **GPU** | RTX 4090 (24GB) or multiple GPUs | Maximum inference speed |
+| **Network** | Multiple network interfaces | Team sharing, distributed setup |
+
+**Expected Performance**: 13B+ parameter model, 30-100+ tokens/second, 16K+ context, 10+ users
+
+## Technology Stack
+
+### Core Technologies
+- **Primary Language**: Go 1.21+ (performance, concurrency, simple deployment)
+- **ML Backend**: llama.cpp with Go bindings (GGML/GGUF model support)
+- **Vector Database**: ChromaDB with SQLite backend (embeddings storage)
+- **Web Framework**: Gin framework (HTTP API) + Gorilla WebSocket
+- **CLI Framework**: Cobra (commands) + Viper (configuration)
+- **Database**: SQLite with GORM (metadata, sessions, configuration)
+- **Containerization**: Docker + Docker Compose (easy deployment)
+
+### Key Rationale
+- **Go**: Single binary deployment, excellent concurrency, fast compilation
+- **llama.cpp**: Best performance for local LLM inference, active community
+- **SQLite**: Zero-configuration, reliable, perfect for local storage
+- **ChromaDB**: Purpose-built for embeddings, good Go integration
+
+### Alternative Technologies Considered
+| Technology | Pros | Cons | Decision |
+|------------|------|------|----------|
+| Python | Rich ML ecosystem | Slower, complex deployment | Rejected |
+| Rust | Maximum performance | Steeper learning curve | Future consideration |
+| PostgreSQL | More features | Requires setup/maintenance | Unnecessary complexity |
+| Weaviate | Advanced vector features | Heavy resource usage | Overkill for local use |
+
+## Component Specifications
+
+### 1. Model Server Component
+**Purpose**: Handle LLM inference with optimized performance
+
+**Requirements**:
+- Load GGUF format models (4-bit, 8-bit, 16-bit quantization)
+- Support models from 1B to 70B parameters (based on hardware)
+- Implement both CPU and GPU inference paths
+- Provide streaming and batch inference APIs
+- Manage model memory efficiently (load/unload based on usage)
+- Support multiple concurrent requests with queueing
+- Implement request timeout and cancellation
+- Cache frequently used prompts and responses
+
+**Interfaces**:
+- `LoadModel(path string, config ModelConfig) error`
+- `GenerateResponse(request InferenceRequest) InferenceResponse`
+- `GenerateStream(request InferenceRequest) <-chan StreamToken`
+- `UnloadModel() error`
+- `GetModelInfo() ModelInfo`
+- `GetPerformanceStats() PerformanceStats`
+
+### 2. Context Manager Component
+**Purpose**: Manage and search through codebase context
+
+**Requirements**:
+- Index files, Git commits, emails, and documents
+- Generate embeddings for all content types
+- Provide fast similarity search (sub-100ms for 10K documents)
+- Rank results by relevance and recency
+- Handle real-time file updates
+- Support context windows up to 32K tokens
+- Implement context compression for large codebases
+- Provide context explanations (why something was included)
+
+**Interfaces**:
+- `AddContext(item ContextItem) error`
+- `SearchContext(query string, limit int) []ContextResult`
+- `UpdateContext(path string) error`
+- `RemoveContext(path string) error`
+- `GetContextStats() ContextStats`
+- `OptimizeContextStore() error`
+
+### 3. Data Pipeline Component
+**Purpose**: Process various data sources into searchable context
+
+**Requirements**:
+- **Git Integration**: Parse repositories, extract commits, diffs, messages
+- **Email Processing**: Support mbox/maildir, extract code snippets
+- **File Processing**: Handle 20+ programming languages, extract functions/classes
+- **Document Processing**: Parse markdown, PDFs, text files
+- **Real-time Monitoring**: Watch for file changes, auto-update context
+- **Batch Processing**: Handle large datasets efficiently
+- **Data Validation**: Ensure data quality, detect duplicates
+- **Format Conversion**: Normalize different input formats
+
+**Supported File Types**:
+```
+Programming: .go .py .js .ts .java .cpp .c .rs .rb .php .swift .kt
+Markup: .md .html .xml .json .yaml .toml
+Documents: .txt .pdf .rtf
+Archives: .zip .tar.gz .git
+Email: mbox, maildir formats
+```
+
+### 4. API Gateway Component
+**Purpose**: Provide stable external interfaces
+
+**Requirements**:
+- REST API with OpenAPI 3.0 specification
+- WebSocket API for real-time communication
+- Request/response logging and metrics
+- Rate limiting and abuse prevention
+- Input validation and sanitization
+- Error handling with meaningful messages
+- CORS support for web clients
+- Optional authentication/authorization
+- API versioning support
+- Health check endpoints
+
+### 5. Storage Layer Component
+**Purpose**: Persist context, configuration, and session data
+
+**Requirements**:
+- **Vector Storage**: Efficient embedding storage and retrieval
+- **Metadata Storage**: File metadata, timestamps, relationships
+- **Configuration Storage**: User preferences, model settings
+- **Session Storage**: Conversation history, context state
+- **Cache Storage**: Frequently accessed data
+- **Backup/Restore**: Data export/import capabilities
+- **Migration Support**: Schema updates without data loss
+- **Performance**: Sub-10ms queries for common operations
+
+## API Specification
+
+### Base URL and Versioning
+```
+Base URL: http://localhost:8080/api/v1/
+WebSocket: ws://localhost:8080/ws/
+```
+
+### Authentication
+```
+Optional API key authentication:
+Header: Authorization: Bearer <api_key>
+```
+
+### Core Endpoints
+
+#### 1. Health and Status
+```http
+GET /health
+Response: {
+ "status": "healthy",
+ "version": "1.0.0",
+ "model_loaded": true,
+ "uptime_seconds": 3600,
+ "memory_usage_mb": 4096
+}
+```
+
+#### 2. Text Generation
+```http
+POST /generate
+Content-Type: application/json
+
+Request Body:
+{
+ "prompt": "How do I implement a binary search in Go?",
+ "max_tokens": 500,
+ "temperature": 0.7,
+ "top_p": 0.9,
+ "top_k": 40,
+ "repeat_penalty": 1.1,
+ "stop": ["```", "\n\n"],
+ "include_context": true,
+ "system_prompt": "You are a helpful coding assistant.",
+ "stream": false
+}
+
+Response:
+{
+ "id": "gen_123456",
+ "text": "Here's how to implement binary search in Go:\n\n```go\nfunc binarySearch(arr []int, target int) int {\n left, right := 0, len(arr)-1\n \n for left <= right {\n mid := left + (right-left)/2\n if arr[mid] == target {\n return mid\n } else if arr[mid] < target {\n left = mid + 1\n } else {\n right = mid - 1\n }\n }\n return -1\n}\n```",
+ "token_count": 87,
+ "time_taken_ms": 1250,
+ "tokens_per_second": 69.6,
+ "context_used": [
+ {
+ "type": "file",
+ "path": "algorithms/search.go",
+ "relevance_score": 0.92,
+ "content_preview": "Binary search implementation..."
+ }
+ ],
+ "finished": true
+}
+```
+
+#### 3. Streaming Generation
+```http
+POST /generate/stream
+Content-Type: application/json
+
+Same request body as /generate with "stream": true
+
+Response (Server-Sent Events):
+data: {"type": "token", "content": "Here's"}
+data: {"type": "token", "content": " how"}
+data: {"type": "token", "content": " to"}
+data: {"type": "context", "items": [...]}
+data: {"type": "token", "content": " implement"}
+data: {"type": "done", "stats": {"tokens": 87, "time_ms": 1250}}
+```
+
+#### 4. Context Management
+```http
+POST /context
+Content-Type: application/json
+
+Request Body:
+{
+ "type": "file|git|email|document",
+ "path": "/path/to/source",
+ "content": "optional content override",
+ "metadata": {
+ "language": "go",
+ "size_bytes": 1024,
+ "last_modified": "2024-01-15T10:30:00Z"
+ }
+}
+
+Response:
+{
+ "id": "ctx_789",
+ "status": "indexed",
+ "embedding_id": "emb_456",
+ "processing_time_ms": 150
+}
+```
+
+#### 5. Context Search
+```http
+GET /context/search?q=error%20handling&limit=10&type=file
+
+Response:
+{
+ "query": "error handling",
+ "results": [
+ {
+ "id": "ctx_123",
+ "type": "file",
+ "path": "utils/errors.go",
+ "content_preview": "Error handling utilities for...",
+ "relevance_score": 0.94,
+ "metadata": {
+ "language": "go",
+ "functions": ["HandleError", "WrapError"],
+ "last_modified": "2024-01-15T10:30:00Z"
+ }
+ }
+ ],
+ "total_results": 25,
+ "search_time_ms": 45
+}
+```
+
+#### 6. Model Management
+```http
+GET /models
+Response:
+{
+ "current_model": {
+ "name": "codellama-7b-instruct",
+ "path": "/models/codellama-7b.gguf",
+ "size_gb": 3.8,
+ "parameters": "7B",
+ "quantization": "q4_0",
+ "context_length": 16384,
+ "loaded_at": "2024-01-15T09:00:00Z"
+ },
+ "available_models": [...]
+}
+
+POST /models/load
+Request Body: {"model_path": "/path/to/model.gguf"}
+Response: {"status": "loading", "estimated_time_seconds": 30}
+```
+
+#### 7. Training Data Management
+```http
+POST /training/prepare
+Request Body:
+{
+ "sources": [
+ {"type": "git", "path": "/path/to/repo"},
+ {"type": "email", "path": "/path/to/mailbox"},
+ {"type": "files", "path": "/path/to/docs", "pattern": "*.md"}
+ ],
+ "output_path": "/tmp/training_data.jsonl",
+ "format": "instruction_following"
+}
+
+Response:
+{
+ "job_id": "train_prep_001",
+ "status": "processing",
+ "estimated_examples": 50000,
+ "progress_url": "/training/prepare/train_prep_001/status"
+}
+```
+
+### WebSocket API
+```javascript
+// Connection
+ws://localhost:8080/ws/chat
+
+// Message format
+{
+ "type": "chat_message|context_update|model_status",
+ "id": "msg_123",
+ "content": {...},
+ "timestamp": "2024-01-15T10:30:00Z"
+}
+
+// Chat message
+{
+ "type": "chat_message",
+ "content": {
+ "message": "Explain this function",
+ "context": ["file:///path/to/file.go:42-60"],
+ "stream": true
+ }
+}
+
+// Response
+{
+ "type": "chat_response",
+ "id": "msg_123",
+ "content": {
+ "text": "This function implements...",
+ "partial": false,
+ "context_used": [...]
+ }
+}
+```
+
+### Error Responses
+```http
+Status Codes:
+200: Success
+400: Bad Request (invalid input)
+401: Unauthorized (if auth enabled)
+429: Rate Limited
+500: Internal Server Error
+503: Service Unavailable (model loading)
+
+Error Format:
+{
+ "error": {
+ "code": "INVALID_REQUEST",
+ "message": "Temperature must be between 0 and 2",
+ "details": {
+ "field": "temperature",
+ "provided": 2.5,
+ "allowed_range": [0, 2]
+ }
+ }
+}
+```
+
+## CLI Interface Specification
+
+### Command Structure
+```bash
+del [global-flags] <command> [subcommand] [flags] [arguments]
+```
+
+### Global Flags
+```bash
+--config, -c Config file path (default: ~/.del/config.yaml)
+--verbose, -v Enable verbose logging
+--debug Enable debug mode
+--server, -s Server URL (default: http://localhost:8080)
+--timeout Request timeout (default: 30s)
+--no-color Disable colored output
+--quiet, -q Suppress non-essential output
+--format, -f Output format: text|json|yaml (default: text)
+```
+
+### Server Management Commands
+```bash
+# Start server with various options
+del server start [flags]
+ --port, -p Port number (default: 8080)
+ --host Bind address (default: localhost)
+ --model-path Model file path
+ --gpu Enable GPU acceleration
+ --max-memory Memory limit in GB (default: 8)
+ --workers Number of worker threads (default: auto)
+ --cors Enable CORS (default: true)
+ --auth Enable authentication
+ --cert TLS certificate file
+ --key TLS private key file
+ --log-level Logging level: debug|info|warn|error
+ --daemon, -d Run as daemon
+ --pid-file PID file path (daemon mode)
+
+# Server control
+del server stop [--force]
+del server restart [start-flags]
+del server status [--json]
+del server logs [--tail N] [--follow]
+```
+
+### Chat and Query Commands
+```bash
+# Single question
+del ask "How do I handle errors in Go?" [flags]
+ --context Include context from files/git
+ --temperature Sampling temperature (0.0-2.0)
+ --max-tokens Maximum response tokens
+ --system-prompt Custom system prompt
+ --no-stream Disable streaming output
+ --save Save conversation to file
+
+# Interactive chat mode
+del chat [flags]
+ --model Model to use
+ --temperature Sampling temperature
+ --system-prompt System prompt file or text
+ --context-dir Directory to use for context
+ --load Load previous conversation
+ --save-on-exit Auto-save on exit
+
+# Code-specific queries
+del code [command] [flags]
+ explain FILE[:LINES] Explain code in file/lines
+ review FILE Review code for issues
+ optimize FILE Suggest optimizations
+ document FUNCTION Generate documentation
+ test FILE Generate unit tests
+ refactor FILE Suggest refactoring
+
+ Flags:
+ --language, -l Force language detection
+ --context Include related files
+ --output, -o Output file for generated code
+ --diff Show changes as diff
+```
+
+### Context Management Commands
+```bash
+# Add context sources
+del context add [type] [path] [flags]
+ file PATH Add file(s) to context
+ git REPO_PATH Add git repository
+ email MAILBOX_PATH Add email archive
+ url URL Add web page/documentation
+
+ Flags:
+ --recursive, -r Process directories recursively
+ --pattern File pattern filter (e.g., "*.go")
+ --exclude Exclusion patterns
+ --max-size Maximum file size (default: 1MB)
+ --follow-links Follow symbolic links
+ --encoding Text encoding (default: auto-detect)
+
+# Search and manage context
+del context search QUERY [flags]
+ --type Filter by type: file|git|email|url
+ --limit, -n Number of results (default: 10)
+ --min-score Minimum relevance score
+ --since Show items since date/time
+ --sort Sort by: relevance|date|size
+
+del context list [--type TYPE] [--stats]
+del context remove PATH [--type TYPE]
+del context clear [--type TYPE] [--confirm]
+del context rebuild [--force]
+del context export FILE [--format json|yaml]
+del context import FILE
+```
+
+### Model Management Commands
+```bash
+# List and download models
+del model list [flags]
+ --local Show only locally available models
+ --remote Show downloadable models
+ --size Include model sizes
+ --details Show detailed information
+
+del model download NAME [flags]
+ --url Custom download URL
+ --quantization Quantization level: q4_0|q4_1|q5_0|q5_1|q8_0
+ --verify Verify checksum after download
+ --resume Resume interrupted download
+
+# Model operations
+del model load PATH [--force]
+del model unload
+del model info [NAME]
+del model test [--prompt "test prompt"]
+del model benchmark [--duration 60s]
+del model convert INPUT OUTPUT [--quantization q4_0]
+```
+
+### Training Commands
+```bash
+# Prepare training data
+del train prepare [flags]
+ --sources Source specification file
+ --output Output training file
+ --format Format: alpaca|chatml|instruction
+ --max-examples Maximum training examples
+ --validation-split Validation set percentage
+ --shuffle Shuffle examples
+ --deduplicate Remove duplicate examples
+
+# Run training
+del train start CONFIG_FILE [flags]
+ --base-model Base model path
+ --output-dir Training output directory
+ --resume Resume from checkpoint
+ --gpu Enable GPU training
+ --wandb Enable Weights & Biases logging
+ --dry-run Validate config without training
+
+del train status [JOB_ID]
+del train stop JOB_ID [--save-checkpoint]
+del train logs JOB_ID [--follow]
+```
+
+### Configuration Commands
+```bash
+# Configuration management
+del config init [--force]
+del config show [KEY]
+del config set KEY VALUE
+del config get KEY
+del config validate
+del config reset [--confirm]
+del config backup FILE
+del config restore FILE
+
+# Common settings
+del config set model.default_path ./models/codellama-7b.gguf
+del config set server.port 8080
+del config set context.max_files 10000
+del config set generation.temperature 0.7
+```
+
+### Utility Commands
+```bash
+# System information
+del info
+ --system Show system capabilities
+ --gpu GPU information
+ --models Installed models
+ --context Context statistics
+ --performance Performance benchmarks
+
+# Maintenance
+del doctor Check system health
+del cleanup [--force] Clean temporary files
+del upgrade [--check-only] Upgrade to latest version
+del export DATA_DIR Export all data
+del import DATA_DIR [--merge] Import data
+
+# Help and documentation
+del help [COMMAND]
+del version [--full]
+del examples [TOPIC]
+```
+
+## Shell Integration
+
+Del should provide seamless integration with Unix/Linux shell tools, allowing developers to combine AI assistance with traditional command-line workflows.
+
+### Command Execution Modes
+
+#### 1. Direct Shell Commands
+```bash
+# Execute shell commands directly within Del
+del exec "ls -la src/"
+del exec "grep -r 'TODO' . --include='*.go'"
+del exec "find . -name '*.py' | head -10"
+
+# With AI interpretation
+del exec "ps aux | grep python" --explain
+del exec "netstat -tulpn" --summarize
+del exec "docker ps" --analyze
+```
+
+#### 2. AI-Assisted Command Generation
+```bash
+# Generate and optionally execute commands
+del suggest "show me all Go files modified in the last week"
+# Outputs: find . -name "*.go" -mtime -7
+# Prompt: Execute this command? [y/N/e(dit)]
+
+del suggest "find large files over 100MB"
+# Outputs: find . -type f -size +100M -exec ls -lh {} \;
+
+del suggest "show git commits from last month with file changes"
+# Outputs: git log --since="1 month ago" --stat --oneline
+```
+
+#### 3. Shell Pipeline Integration
+```bash
+# Del as part of Unix pipelines
+ls -la | del analyze "what files should I focus on?"
+git log --oneline | del summarize
+ps aux | del explain "what processes are using most memory?"
+
+# Complex pipelines
+find . -name "*.go" | xargs wc -l | del rank "by lines of code"
+grep -r "func.*Error" . | del explain "error handling patterns"
+```
+
+#### 4. REPL Shell Integration
+```bash
+# Within Del's interactive mode
+> !ls -la src/
+drwxr-xr-x 5 user user 4096 Jan 15 10:30 handlers/
+-rw-r--r-- 1 user user 2048 Jan 15 09:45 main.go
+...
+
+> !grep -r "panic" . --include="*.go" | head -5
+./handlers/auth.go:45: panic("invalid session")
+./utils/db.go:23: // TODO: remove panic for production
+...
+
+> explain the last command output
+The grep command found 2 instances of "panic" in your Go code:
+1. Line 45 in auth.go has an actual panic call - this should be replaced with proper error handling
+2. Line 23 in db.go has a TODO comment about removing a panic
+
+Let me suggest safer alternatives for these...
+```
+
+### Shell Integration Specifications
+
+#### Command Execution Component
+**Purpose**: Execute shell commands safely and capture output for AI processing
+
+**Requirements**:
+- **Safe Execution**: Sandboxed command execution with timeout protection
+- **Output Capture**: Capture stdout, stderr, and exit codes
+- **Real-time Streaming**: Show command output as it executes
+- **Working Directory**: Respect current working directory context
+- **Environment Variables**: Pass through relevant environment variables
+- **Interactive Commands**: Handle commands requiring user input
+- **Privilege Control**: Never execute commands requiring elevated privileges
+- **Command History**: Track executed commands for context
+
+**Security Constraints**:
+```yaml
+Blocked Commands:
+ - sudo, su, doas (privilege escalation)
+ - rm -rf /, mkfs (destructive operations)
+ - dd, shred (disk operations)
+ - chmod 777, chown (permission changes)
+ - curl/wget to unknown domains (network security)
+ - eval, exec with untrusted input
+
+Restricted Commands:
+ - git push (require confirmation)
+ - rm (require confirmation for multiple files)
+ - mv, cp (confirm overwrite operations)
+ - docker run (limit resource usage)
+
+Time Limits:
+ - Default timeout: 30 seconds
+ - Long-running commands: 5 minutes with confirmation
+ - Interactive commands: 2 minutes timeout
+```
+
+#### Command Suggestion Engine
+**Purpose**: Generate shell commands from natural language descriptions
+
+**Requirements**:
+- **Context Awareness**: Understand current directory, file types, project structure
+- **Platform Detection**: Generate appropriate commands for Linux/macOS/Windows
+- **Safety Validation**: Never suggest dangerous or destructive commands
+- **Command Explanation**: Explain what generated commands do
+- **Alternative Options**: Provide multiple command options when possible
+- **Learning**: Learn from user corrections and preferences
+
+**Training Data Sources**:
+```yaml
+Command Examples:
+ - Common shell command patterns
+ - Stack Overflow command snippets
+ - GitHub repository scripts
+ - Unix manual pages and examples
+ - User's command history (with permission)
+
+Pattern Recognition:
+ - "find files" → find, ls, locate commands
+ - "search content" → grep, ag, ripgrep commands
+ - "git operations" → git command variations
+ - "process management" → ps, kill, jobs commands
+ - "file operations" → cp, mv, chmod, tar commands
+```
+
+### Command Categories and Examples
+
+#### File and Directory Operations
+```bash
+# Natural language → Generated commands
+"show me all Python files in this project"
+→ find . -name "*.py" -type f
+
+"find large files taking up space"
+→ find . -type f -size +10M -exec ls -lh {} \; | sort -k5 -hr
+
+"list files modified today"
+→ find . -type f -newermt "today" -ls
+
+"count lines of code in each directory"
+→ find . -name "*.go" -exec wc -l {} \; | awk '{sum+=$1} END {print sum}'
+```
+
+#### Text Processing and Search
+```bash
+"find all TODO comments in Go files"
+→ grep -rn "TODO\|FIXME\|XXX" --include="*.go" .
+
+"show functions that return errors"
+→ grep -rn "func.*error" --include="*.go" .
+
+"find duplicate function names"
+→ grep -rh "^func " --include="*.go" . | sort | uniq -d
+
+"extract email addresses from logs"
+→ grep -oE '\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b' *.log
+```
+
+#### Git Operations
+```bash
+"show commits from last week"
+→ git log --since="1 week ago" --oneline
+
+"find who changed this line"
+→ git blame -L 45,45 src/main.go
+
+"show files changed in last commit"
+→ git diff --name-only HEAD~1
+
+"find commits that mention 'bug'"
+→ git log --grep="bug" --oneline
+```
+
+#### System Monitoring
+```bash
+"show processes using most CPU"
+→ ps aux --sort=-%cpu | head -10
+
+"check disk usage by directory"
+→ du -sh */ | sort -hr
+
+"show network connections"
+→ netstat -tuln
+
+"monitor log file for errors"
+→ tail -f /var/log/app.log | grep -i error
+```
+
+#### Development Tools
+```bash
+"run tests and show coverage"
+→ go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out
+
+"format all Go code"
+→ find . -name "*.go" -exec gofmt -w {} \;
+
+"check for security vulnerabilities"
+→ gosec ./...
+
+"build for multiple platforms"
+→ GOOS=linux GOARCH=amd64 go build -o myapp-linux ./cmd/
+```
+
+### REPL Shell Integration
+
+#### Shell Command Syntax in REPL
+```bash
+# Prefix commands with ! for execution
+> !ls -la
+> !grep -r "func main" .
+> !git status
+
+# Multi-line shell commands
+> !for file in *.go; do
+... echo "Processing $file"
+... go fmt "$file"
+... done
+
+# Combine with AI analysis
+> !docker ps
+> explain what these containers do
+
+# Store command output for analysis
+> $output = !ps aux
+> analyze $output for memory usage patterns
+```
+
+#### Interactive Command Building
+```bash
+# Step-by-step command construction
+> build command to find large files
+Del: I'll help you build a command to find large files. Let me ask a few questions:
+
+1. What size threshold? (e.g., >100MB)
+> 50MB
+
+2. Which directory to search?
+> current directory and subdirectories
+
+3. Should I show file sizes?
+> yes
+
+Generated command: find . -type f -size +50M -exec ls -lh {} \;
+Execute this command? [y/N/e(dit)/s(ave)]
+> y
+
+[Command executes and shows results]
+
+Would you like me to explain what each part does?
+```
+
+#### Command History and Favorites
+```bash
+# Show recent shell commands
+> :history shell
+1. ls -la src/
+2. grep -r "TODO" . --include="*.go"
+3. git log --oneline | head -10
+4. docker ps
+
+# Save frequently used commands
+> :save-command "show-todos" "grep -r 'TODO\|FIXME' --include='*.go' ."
+> :run show-todos
+
+# Command aliases for complex operations
+> :alias disk-usage "du -sh */ | sort -hr"
+> !disk-usage
+```
+
+### API Endpoints for Shell Integration
+
+#### Execute Shell Command
+```http
+POST /api/v1/shell/execute
+Content-Type: application/json
+
+Request:
+{
+ "command": "ls -la src/",
+ "working_directory": "/path/to/project",
+ "timeout_seconds": 30,
+ "capture_output": true,
+ "environment": {
+ "GOPATH": "/go",
+ "PATH": "/usr/local/bin:/usr/bin:/bin"
+ }
+}
+
+Response:
+{
+ "command": "ls -la src/",
+ "exit_code": 0,
+ "stdout": "drwxr-xr-x 5 user user 4096 Jan 15 10:30 handlers/\n-rw-r--r-- 1 user user 2048 Jan 15 09:45 main.go\n",
+ "stderr": "",
+ "execution_time_ms": 45,
+ "working_directory": "/path/to/project"
+}
+```
+
+#### Generate Shell Command
+```http
+POST /api/v1/shell/suggest
+Content-Type: application/json
+
+Request:
+{
+ "description": "find all Go files modified in the last 24 hours",
+ "context": {
+ "operating_system": "linux",
+ "current_directory": "/path/to/project",
+ "available_tools": ["find", "grep", "git"],
+ "project_type": "go"
+ }
+}
+
+Response:
+{
+ "suggestions": [
+ {
+ "command": "find . -name '*.go' -mtime -1",
+ "explanation": "Find all .go files modified in the last 24 hours",
+ "confidence": 0.95,
+ "safety_level": "safe"
+ },
+ {
+ "command": "git log --since='24 hours ago' --name-only --pretty=format: | grep '\\.go
+
+### Command Examples
+```bash
+# Quick start
+del model download codellama-7b-instruct
+del server start --port 8080 --gpu
+del context add git .
+del ask "How does the authentication work in this codebase?"
+
+# Development workflow
+del chat --context-dir ./src --save-on-exit
+> How can I optimize the database queries in user.go?
+> Generate unit tests for the UserService class
+> Explain the dependency injection pattern used here
+
+# Code review workflow
+del context add git . --since "24 hours ago"
+del code review src/handlers/auth.go
+del code explain src/models/user.go:45-67
+del code test src/services/email.go --output tests/
+
+# Training custom model
+del train prepare --sources training_sources.yaml --output training.jsonl
+del train start training_config.yaml --gpu --wandb
+del model load ./fine_tuned_model/model.gguf
+```
+
+## REPL Requirements
+
+### Interactive Mode Features
+The REPL (Read-Eval-Print Loop) should provide an interactive chat interface with the following capabilities:
+
+#### Core REPL Commands
+```bash
+# Enter interactive mode
+del chat
+
+# REPL-specific commands (prefixed with : or /)
+:help, :h Show available commands
+:quit, :q, :exit Exit REPL
+:clear, :cls Clear screen
+:history Show command history
+:save [filename] Save conversation
+:load filename Load conversation
+:context Show current context
+:model Show current model info
+:stats Show session statistics
+:reset Reset conversation
+:set key=value Change settings
+:get key Show setting value
+:debug Toggle debug mode
+```
+
+#### Multi-line Input Support
+```bash
+# Automatic multi-line detection
+> def fibonacci(n):
+... if n <= 1:
+... return n
+... return fibonacci(n-1) + fibonacci(n-2)
+...
+[Generated response]
+
+# Explicit multi-line mode
+> ```
+... This is a multi-line
+... input that continues
+... until I type ```
+```
+
+#### Context Integration
+```bash
+# File reference
+> @file:src/main.go explain this function
+
+# Line range reference
+> @src/auth.go:42-58 how can I improve this?
+
+# Git commit reference
+> @commit:abc123 what changed in this commit?
+
+# Auto-complete suggestions
+> @src/[TAB]
+src/main.go src/auth.go src/utils.go
+
+# Context shortcuts
+> /explain # Explain current file/selection
+> /review # Review current file
+> /optimize # Suggest optimizations
+> /document # Generate documentation
+> /test # Generate tests
+```
+
+#### Advanced Features
+```bash
+# Code mode - specialized for code questions
+> /code
+Code mode enabled. Ask about code, get code responses.
+code> implement binary search in rust
+
+# Conversation modes
+> /mode explain # Explanation-focused responses
+> /mode debug # Debugging assistance
+> /mode review # Code review mode
+> /mode teach # Educational responses
+
+# Session management
+> /save important_discussion
+Saved conversation to important_discussion.chat
+
+> /load important_discussion
+Loaded conversation from important_discussion.chat
+```
+
+#### Visual Enhancements
+- **Syntax Highlighting**: Color-coded code in responses
+- **Progress Indicators**: Show when model is thinking
+- **Token Streaming**: Display responses as they generate
+- **Context Previews**: Show what context is being used
+- **Error Formatting**: Clear error messages with suggestions
+
+#### Example REPL Session
+```bash
+$ del chat --context-dir ./myproject
+Del the Funky Robosapien v1.0.0 (codellama-7b-instruct)
+Context: 1,247 files indexed from ./myproject
+Type :help for commands or start chatting!
+
+> I'm getting a panic in my Go code, can you help debug it?
+
+I'd be happy to help debug your Go panic! Could you share the panic
+message and the relevant code? You can reference files directly like
+@file:path/to/file.go or paste the error message.
+
+> @file:src/handlers/user.go the panic happens around line 45
+
+[Loading src/handlers/user.go...]
+
+Looking at your user.go file around line 45, I can see the issue. You have:
+
+```go
+user := users[id] // Line 45
+return user.Name // This panics if user is nil
+```
+
+The panic occurs because you're not checking if the user exists in the map
+before accessing its fields. Here's the fix:
+
+```go
+user, exists := users[id]
+if !exists {
+ return "", fmt.Errorf("user with id %s not found", id)
+}
+return user.Name, nil
+```
+
+This uses the two-value assignment to check if the key exists in the map.
+
+> That makes sense! Are there other similar patterns in my codebase?
+
+Let me search for similar patterns in your codebase...
+
+[Context: Searching 1,247 files for map access patterns]
+
+I found 3 other locations with similar unsafe map access:
+
+1. **src/handlers/auth.go:23** - `sessions[sessionID].UserID`
+2. **src/models/cache.go:67** - `cache[key].Data`
+3. **src/utils/config.go:12** - `settings[param].Value`
+
+Would you like me to show you how to fix each of these?
+
+> :save debugging_session
+Saved conversation to debugging_session.chat
+
+> :quit
+Goodbye! Your conversation was saved.
+``` | sort | uniq",
+ "explanation": "Use git to find Go files changed in last 24 hours (only if files are tracked)",
+ "confidence": 0.87,
+ "safety_level": "safe"
+ }
+ ]
+}
+```
+
+### Configuration Options
+
+#### Shell Integration Settings
+```yaml
+# ~/.del/config.yaml
+shell:
+ # Enable/disable shell integration
+ enabled: true
+
+ # Default shell to use
+ default_shell: "/bin/bash"
+
+ # Command timeout settings
+ timeouts:
+ default: 30s
+ interactive: 120s
+ long_running: 300s
+
+ # Safety settings
+ safety:
+ require_confirmation:
+ - "rm *"
+ - "git push"
+ - "docker run"
+
+ blocked_commands:
+ - "sudo"
+ - "rm -rf /"
+ - "mkfs"
+ - "dd if="
+
+ blocked_patterns:
+ - "curl.*|.*sh" # Prevent pipe to shell
+ - "wget.*|.*bash"
+
+ # Command suggestion settings
+ suggestions:
+ enabled: true
+ max_suggestions: 3
+ learn_from_usage: true
+
+ # History settings
+ history:
+ enabled: true
+ max_entries: 1000
+ file: "~/.del/shell_history"
+```
+
+This shell integration makes Del incredibly powerful by combining AI assistance with the full Unix toolchain that developers already know and love!
+
+### Command Examples
+```bash
+# Quick start
+del model download codellama-7b-instruct
+del server start --port 8080 --gpu
+del context add git .
+del ask "How does the authentication work in this codebase?"
+
+# Development workflow
+del chat --context-dir ./src --save-on-exit
+> How can I optimize the database queries in user.go?
+> Generate unit tests for the UserService class
+> Explain the dependency injection pattern used here
+
+# Code review workflow
+del context add git . --since "24 hours ago"
+del code review src/handlers/auth.go
+del code explain src/models/user.go:45-67
+del code test src/services/email.go --output tests/
+
+# Training custom model
+del train prepare --sources training_sources.yaml --output training.jsonl
+del train start training_config.yaml --gpu --wandb
+del model load ./fine_tuned_model/model.gguf
+```
+
+## REPL Requirements
+
+### Interactive Mode Features
+The REPL (Read-Eval-Print Loop) should provide an interactive chat interface with the following capabilities:
+
+#### Core REPL Commands
+```bash
+# Enter interactive mode
+del chat
+
+# REPL-specific commands (prefixed with : or /)
+:help, :h Show available commands
+:quit, :q, :exit Exit REPL
+:clear, :cls Clear screen
+:history Show command history
+:save [filename] Save conversation
+:load filename Load conversation
+:context Show current context
+:model Show current model info
+:stats Show session statistics
+:reset Reset conversation
+:set key=value Change settings
+:get key Show setting value
+:debug Toggle debug mode
+```
+
+#### Multi-line Input Support
+```bash
+# Automatic multi-line detection
+> def fibonacci(n):
+... if n <= 1:
+... return n
+... return fibonacci(n-1) + fibonacci(n-2)
+...
+[Generated response]
+
+# Explicit multi-line mode
+> ```
+... This is a multi-line
+... input that continues
+... until I type ```
+```
+
+#### Context Integration
+```bash
+# File reference
+> @file:src/main.go explain this function
+
+# Line range reference
+> @src/auth.go:42-58 how can I improve this?
+
+# Git commit reference
+> @commit:abc123 what changed in this commit?
+
+# Auto-complete suggestions
+> @src/[TAB]
+src/main.go src/auth.go src/utils.go
+
+# Context shortcuts
+> /explain # Explain current file/selection
+> /review # Review current file
+> /optimize # Suggest optimizations
+> /document # Generate documentation
+> /test # Generate tests
+```
+
+#### Advanced Features
+```bash
+# Code mode - specialized for code questions
+> /code
+Code mode enabled. Ask about code, get code responses.
+code> implement binary search in rust
+
+# Conversation modes
+> /mode explain # Explanation-focused responses
+> /mode debug # Debugging assistance
+> /mode review # Code review mode
+> /mode teach # Educational responses
+
+# Session management
+> /save important_discussion
+Saved conversation to important_discussion.chat
+
+> /load important_discussion
+Loaded conversation from important_discussion.chat
+```
+
+#### Visual Enhancements
+- **Syntax Highlighting**: Color-coded code in responses
+- **Progress Indicators**: Show when model is thinking
+- **Token Streaming**: Display responses as they generate
+- **Context Previews**: Show what context is being used
+- **Error Formatting**: Clear error messages with suggestions
+
+#### Example REPL Session
+```bash
+$ del chat --context-dir ./myproject
+Del the Funky Robosapien v1.0.0 (codellama-7b-instruct)
+Context: 1,247 files indexed from ./myproject
+Type :help for commands or start chatting!
+
+> I'm getting a panic in my Go code, can you help debug it?
+
+I'd be happy to help debug your Go panic! Could you share the panic
+message and the relevant code? You can reference files directly like
+@file:path/to/file.go or paste the error message.
+
+> @file:src/handlers/user.go the panic happens around line 45
+
+[Loading src/handlers/user.go...]
+
+Looking at your user.go file around line 45, I can see the issue. You have:
+
+```go
+user := users[id] // Line 45
+return user.Name // This panics if user is nil
+```
+
+The panic occurs because you're not checking if the user exists in the map
+before accessing its fields. Here's the fix:
+
+```go
+user, exists := users[id]
+if !exists {
+ return "", fmt.Errorf("user with id %s not found", id)
+}
+return user.Name, nil
+```
+
+This uses the two-value assignment to check if the key exists in the map.
+
+> That makes sense! Are there other similar patterns in my codebase?
+
+Let me search for similar patterns in your codebase...
+
+[Context: Searching 1,247 files for map access patterns]
+
+I found 3 other locations with similar unsafe map access:
+
+1. **src/handlers/auth.go:23** - `sessions[sessionID].UserID`
+2. **src/models/cache.go:67** - `cache[key].Data`
+3. **src/utils/config.go:12** - `settings[param].Value`
+
+Would you like me to show you how to fix each of these?
+
+> :save debugging_session
+Saved conversation to debugging_session.chat
+
+> :quit
+Goodbye! Your conversation was saved.
+```