diff options
| -rw-r--r-- | README.md | 1448 |
1 files changed, 1448 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..01adea3 --- /dev/null +++ b/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. +``` |