parrot Public

Watch 0 Fork 0 Star 0
markdown · 11745 bytes Raw Blame History

Intelligent Insult System - ML-Inspired Architecture

Overview

The Parrot CLI now features a sophisticated, ML-inspired intelligent insult selection system that goes beyond random selection to deliver contextually relevant, personalized feedback based on:

  • Error pattern classification
  • Command intent analysis
  • Multi-factor relevance scoring
  • Adaptive learning from history
  • Semantic tagging

This creates a truly smart system that learns and adapts to deliver the most appropriate insult for each failure scenario.

Architecture

Five-Tier Intelligence System

TIER 5: ML-Inspired Semantic Matching (NEW!)
  ↓ (if score < threshold)
TIER 4: Historical Learning & Dynamic Generation
  ↓ (if no match)
TIER 3: LLM-like Context Awareness
  ↓ (if no match)
TIER 2: Environment Detection
  ↓ (if no match)
TIER 1: Basic Context Matching
  ↓ (if no match)
FALLBACK: Static Database

Key Components

1. Error Classifier (error_classifier.go)

Analyzes commands and exit codes to determine specific error types:

  • 20+ Error Categories: Permission errors, syntax errors, network failures, merge conflicts, test failures, segfaults, race conditions, and more
  • Multi-source Analysis: Combines exit codes, command patterns, and error output
  • Priority Ranking: Returns the most specific error type first

Example:

classifier.ClassifyError("git push origin main", 1, "permission denied")
// Returns: [ErrorPermission, ErrorAuthentication]

2. Semantic Tagging System (semantic_tags.go)

Each insult is tagged with rich metadata:

Tag Categories:

  • Error Types: permission, syntax, network, merge_conflict, test_failure, etc.
  • Command Types: git, docker, kubernetes, node, rust, python, etc.
  • User Intent: push, build, test, deploy, install, etc.
  • Context: late_night, ci, main_branch, streak, repeated, etc.
  • Severity: mild, sarcastic, savage (1-10 scale)

Example Tagged Insult:

{
    Text: "Tests failed. Shocking absolutely no one who read your code",
    Tags: [TagTestFailure, TagTest, TagSavage],
    Severity: 7,
    Weight: 0.9,
}

3. Intent Parser (intent_parser.go)

Extracts semantic meaning from commands:

  • Primary Intent Detection: What was the user trying to do? (push, build, test, deploy, etc.)
  • Target Extraction: Files, branches, containers being acted upon
  • Complexity Assessment: Simple, moderate, or complex command
  • Risk Analysis: Low, medium, or high risk operation

Example:

parser.ParseIntent("git push --force origin main")
// Returns: {
//     PrimaryIntent: "push",
//     Targets: ["origin", "main"],
//     Complexity: "simple",
//     RiskLevel: "high"
// }

4. Multi-Factor Scoring Algorithm (insult_scorer.go)

Ranks insults using weighted factors:

Scoring Factors:

  • Tag Matching (35%): How well do insult tags match the context?
  • Error Matching (30%): How specific is the insult to the error type?
  • Context Relevance (20%): Time of day, CI environment, branch type, etc.
  • Novelty (10%): Avoid recently shown insults
  • Personality Fit (5%): Match user's personality preference (mild/sarcastic/savage)

Example Scoring:

Permission error + late night + git push + repeated failure:
  → "chmod 777 isn't the answer this time, though I admire your optimism"
  → Score: 0.87 (high relevance)

5. Insult History Tracker (insult_history.go)

Prevents repetition and tracks usage:

  • Persistent Storage: Saves to ~/.parrot/insult_history.json
  • Recency Tracking: Penalizes recently shown insults
  • Frequency Analysis: Less used insults score higher
  • Automatic Cleanup: Old entries removed after 7 days
  • Statistics: Track most frequent insults, total shown, etc.

How It Works

Selection Flow

  1. Parse Context: Extract rich context from command, exit code, environment
  2. Classify Error: Determine specific error types (permission, syntax, network, etc.)
  3. Parse Intent: Understand what the user was trying to accomplish
  4. Generate Tags: Combine error tags, context tags, and intent tags
  5. Score All Insults: Rank every insult in the database using multi-factor scoring
  6. Apply Novelty: Penalize recently shown insults
  7. Filter by Personality: Ensure severity matches user preference
  8. Select Best: Return highest-scoring insult above quality threshold
  9. Record History: Save for future novelty calculations

Scoring Example

Command: git push origin main (Exit Code: 1, Time: 2 AM, Repeated failure)

Context Tags Generated:

  • TagGit
  • TagPush
  • TagMainBranch
  • TagLateNight
  • TagRepeated

Top Insult Candidates:

Insult Tag Match Error Match Context Novelty Personality Total
"Push rejected: The remote has standards" 0.80 0.90 0.75 1.0 0.85 0.83 ✓
"Failed to push. The remote branch has standards" 0.75 0.85 0.70 0.90 0.80 0.78
"Working at 2 AM? Even your rubber duck has clocked out" 0.60 0.50 0.95 1.0 0.75 0.69

Winner: "Push rejected: The remote has standards" (Score: 0.83)

Database

Insult Statistics

  • 200+ Semantically Tagged Insults in the new system
  • ~3000 Static Insults in the fallback database
  • Comprehensive Coverage: All major error types, languages, and tools
  • Context-Specific: Insults for specific scenarios (CI failures, late night coding, merge conflicts, etc.)

Example Categories

Permission Errors:

  • "chmod 777 isn't the answer this time, though I admire your optimism"
  • "Permission denied. The computer has decided you're not ready for this level of responsibility"

Test Failures:

  • "Tests failed. Shocking absolutely no one who read your code"
  • "Expected: working code. Received: whatever this is"

Build Failures:

  • "The compiler is personally offended by what you've written"
  • "Your build broke so hard it took down the CI server's will to live"

Late Night Context:

  • "It's 2 AM. The bugs aren't the only thing that needs fixing"
  • "Caffeine and bad decisions: a programmer's autobiography"

CI/Production:

  • "Failed in CI. Congratulations, everyone on the team just got your shame notification"
  • "Red pipeline. That's the color of your team's disappointment"

Benefits

🎯 Context Awareness

No more generic insults! Each failure gets a response tailored to:

  • The specific error type
  • What you were trying to do
  • Your current environment
  • Time of day
  • Failure patterns

🧠 Learning & Adaptation

  • Tracks which insults you've seen recently
  • Avoids repetition
  • Learns your common failure patterns
  • Adjusts based on your personality preference

📊 Intelligent Ranking

  • Multi-factor scoring ensures relevance
  • Quality threshold prevents low-relevance matches
  • Falls back gracefully to other tiers if needed

🎭 Personality Matching

Respects your configured personality:

  • Mild: Gentle, constructive feedback (severity ≤ 4)
  • Sarcastic: Witty, clever mocking (severity 4-7)
  • Savage: Brutal, devastating roasts (severity ≥ 6)

Configuration

Personality Setting

The intelligent system respects your personality preference:

# ~/.config/parrot/config.toml
[general]
personality = "sarcastic"  # Options: mild, sarcastic, savage

Fallback Behavior

If the ML-inspired system doesn't find a high-confidence match (score < 0.3), it falls through to Tier 4, 3, 2, 1, and finally the static database. This ensures you always get a response.

Technical Details

Performance

  • Fast: Scoring algorithm is O(n) where n = number of insults (~200)
  • Lightweight: Minimal memory footprint
  • Cached: Database loaded once at startup
  • Persistent: History stored in JSON for cross-session learning

Files Created

  • ~/.parrot/insult_history.json: Tracks shown insults and usage statistics
  • ~/.parrot/failures.json: User failure history (existing Tier 4 system)

Quality Threshold

Insults must score ≥ 0.3 (30%) to be used. This ensures only relevant, contextual insults are shown. Lower-scoring matches fall through to other intelligence tiers.

Examples

Example 1: Permission Error at 2 AM

Command: sudo rm -rf /important/file (Exit: 126)

Analysis:

  • Error Type: Permission denied
  • Time: 2 AM (late night)
  • Risk: High (destructive command)
  • Intent: Delete

Selected Insult:

"Permission denied. The computer has decided you're not ready for this level of responsibility"

Score Breakdown:

  • Tag Match: 0.90 (permission + late_night tags match)
  • Error Match: 1.0 (perfect permission error match)
  • Context: 0.85 (late night + high risk)
  • Novelty: 1.0 (not shown recently)
  • Personality: 0.80 (sarcastic, severity 5)
  • Total: 0.88 ✓

Example 2: Test Failure in CI

Command: npm test (Exit: 1, CI environment)

Analysis:

  • Error Type: Test failure
  • Environment: GitHub Actions CI
  • Project: Node.js
  • Intent: Test

Selected Insult:

"Did you test this before committing? Oh wait, that's what the CI is for, right?"

Score Breakdown:

  • Tag Match: 0.85 (test + node + ci tags)
  • Error Match: 0.95 (test failure match)
  • Context: 0.90 (CI context bonus)
  • Novelty: 1.0
  • Personality: 0.85
  • Total: 0.89 ✓

Example 3: Merge Conflict on Main Branch

Command: git merge feature/new-ui (Exit: 1, on main branch)

Analysis:

  • Error Type: Merge conflict
  • Branch: main (high risk)
  • Command: git
  • Intent: Merge

Selected Insult:

"<<<<<<< HEAD is not a valid merge resolution strategy"

Score Breakdown:

  • Tag Match: 0.95 (merge_conflict + git + main_branch)
  • Error Match: 1.0 (perfect merge conflict match)
  • Context: 0.80 (main branch penalty)
  • Novelty: 1.0
  • Personality: 0.90
  • Total: 0.92 ✓

Future Enhancements

Possible improvements for future versions:

  1. True ML Model: Train a lightweight model on historical data
  2. User Preference Learning: Learn which insults the user appreciates most
  3. Team Patterns: Share anonymized patterns across team members
  4. Custom Insults: Allow users to add their own tagged insults
  5. Sentiment Analysis: Detect frustration level from command patterns
  6. Integration: Pull error messages from stderr for better classification

Code Structure

internal/llm/
├── error_classifier.go      # Classifies error types from exit codes & patterns
├── semantic_tags.go         # Tagged insult database with metadata
├── intent_parser.go         # Extracts command intent and complexity
├── insult_scorer.go         # Multi-factor scoring algorithm
├── insult_history.go        # Persistent history tracking
└── smart_fallback.go        # Integration layer (Tier 5 addition)

Summary

The new ML-inspired intelligent insult system transforms Parrot from a simple random insult generator into a context-aware, adaptive, learning system that delivers highly relevant feedback tailored to:

✅ What went wrong (error classification) ✅ What you were trying to do (intent parsing) ✅ Your environment (CI, time, branch, project type) ✅ Your history (avoiding repetition, learning patterns) ✅ Your preference (personality matching)

This represents a significant intelligence upgrade that makes every failure... well, at least entertainingly personalized! 🎯

View source
1 # Intelligent Insult System - ML-Inspired Architecture
2
3 ## Overview
4
5 The Parrot CLI now features a sophisticated, **ML-inspired intelligent insult selection system** that goes beyond random selection to deliver contextually relevant, personalized feedback based on:
6
7 - **Error pattern classification**
8 - **Command intent analysis**
9 - **Multi-factor relevance scoring**
10 - **Adaptive learning from history**
11 - **Semantic tagging**
12
13 This creates a truly smart system that learns and adapts to deliver the most appropriate insult for each failure scenario.
14
15 ---
16
17 ## Architecture
18
19 ### Five-Tier Intelligence System
20
21 ```
22 TIER 5: ML-Inspired Semantic Matching (NEW!)
23 ↓ (if score < threshold)
24 TIER 4: Historical Learning & Dynamic Generation
25 ↓ (if no match)
26 TIER 3: LLM-like Context Awareness
27 ↓ (if no match)
28 TIER 2: Environment Detection
29 ↓ (if no match)
30 TIER 1: Basic Context Matching
31 ↓ (if no match)
32 FALLBACK: Static Database
33 ```
34
35 ---
36
37 ## Key Components
38
39 ### 1. Error Classifier (`error_classifier.go`)
40
41 Analyzes commands and exit codes to determine specific error types:
42
43 - **20+ Error Categories**: Permission errors, syntax errors, network failures, merge conflicts, test failures, segfaults, race conditions, and more
44 - **Multi-source Analysis**: Combines exit codes, command patterns, and error output
45 - **Priority Ranking**: Returns the most specific error type first
46
47 **Example:**
48 ```go
49 classifier.ClassifyError("git push origin main", 1, "permission denied")
50 // Returns: [ErrorPermission, ErrorAuthentication]
51 ```
52
53 ### 2. Semantic Tagging System (`semantic_tags.go`)
54
55 Each insult is tagged with rich metadata:
56
57 **Tag Categories:**
58 - **Error Types**: `permission`, `syntax`, `network`, `merge_conflict`, `test_failure`, etc.
59 - **Command Types**: `git`, `docker`, `kubernetes`, `node`, `rust`, `python`, etc.
60 - **User Intent**: `push`, `build`, `test`, `deploy`, `install`, etc.
61 - **Context**: `late_night`, `ci`, `main_branch`, `streak`, `repeated`, etc.
62 - **Severity**: `mild`, `sarcastic`, `savage` (1-10 scale)
63
64 **Example Tagged Insult:**
65 ```go
66 {
67 Text: "Tests failed. Shocking absolutely no one who read your code",
68 Tags: [TagTestFailure, TagTest, TagSavage],
69 Severity: 7,
70 Weight: 0.9,
71 }
72 ```
73
74 ### 3. Intent Parser (`intent_parser.go`)
75
76 Extracts semantic meaning from commands:
77
78 - **Primary Intent Detection**: What was the user trying to do? (push, build, test, deploy, etc.)
79 - **Target Extraction**: Files, branches, containers being acted upon
80 - **Complexity Assessment**: Simple, moderate, or complex command
81 - **Risk Analysis**: Low, medium, or high risk operation
82
83 **Example:**
84 ```go
85 parser.ParseIntent("git push --force origin main")
86 // Returns: {
87 // PrimaryIntent: "push",
88 // Targets: ["origin", "main"],
89 // Complexity: "simple",
90 // RiskLevel: "high"
91 // }
92 ```
93
94 ### 4. Multi-Factor Scoring Algorithm (`insult_scorer.go`)
95
96 Ranks insults using weighted factors:
97
98 **Scoring Factors:**
99 - **Tag Matching (35%)**: How well do insult tags match the context?
100 - **Error Matching (30%)**: How specific is the insult to the error type?
101 - **Context Relevance (20%)**: Time of day, CI environment, branch type, etc.
102 - **Novelty (10%)**: Avoid recently shown insults
103 - **Personality Fit (5%)**: Match user's personality preference (mild/sarcastic/savage)
104
105 **Example Scoring:**
106 ```
107 Permission error + late night + git push + repeated failure:
108 → "chmod 777 isn't the answer this time, though I admire your optimism"
109 → Score: 0.87 (high relevance)
110 ```
111
112 ### 5. Insult History Tracker (`insult_history.go`)
113
114 Prevents repetition and tracks usage:
115
116 - **Persistent Storage**: Saves to `~/.parrot/insult_history.json`
117 - **Recency Tracking**: Penalizes recently shown insults
118 - **Frequency Analysis**: Less used insults score higher
119 - **Automatic Cleanup**: Old entries removed after 7 days
120 - **Statistics**: Track most frequent insults, total shown, etc.
121
122 ---
123
124 ## How It Works
125
126 ### Selection Flow
127
128 1. **Parse Context**: Extract rich context from command, exit code, environment
129 2. **Classify Error**: Determine specific error types (permission, syntax, network, etc.)
130 3. **Parse Intent**: Understand what the user was trying to accomplish
131 4. **Generate Tags**: Combine error tags, context tags, and intent tags
132 5. **Score All Insults**: Rank every insult in the database using multi-factor scoring
133 6. **Apply Novelty**: Penalize recently shown insults
134 7. **Filter by Personality**: Ensure severity matches user preference
135 8. **Select Best**: Return highest-scoring insult above quality threshold
136 9. **Record History**: Save for future novelty calculations
137
138 ### Scoring Example
139
140 **Command:** `git push origin main` (Exit Code: 1, Time: 2 AM, Repeated failure)
141
142 **Context Tags Generated:**
143 - `TagGit`
144 - `TagPush`
145 - `TagMainBranch`
146 - `TagLateNight`
147 - `TagRepeated`
148
149 **Top Insult Candidates:**
150
151 | Insult | Tag Match | Error Match | Context | Novelty | Personality | **Total** |
152 |--------|-----------|-------------|---------|---------|-------------|-----------|
153 | "Push rejected: The remote has standards" | 0.80 | 0.90 | 0.75 | 1.0 | 0.85 | **0.83** ✓ |
154 | "Failed to push. The remote branch has standards" | 0.75 | 0.85 | 0.70 | 0.90 | 0.80 | **0.78** |
155 | "Working at 2 AM? Even your rubber duck has clocked out" | 0.60 | 0.50 | 0.95 | 1.0 | 0.75 | **0.69** |
156
157 **Winner:** "Push rejected: The remote has standards" (Score: 0.83)
158
159 ---
160
161 ## Database
162
163 ### Insult Statistics
164
165 - **200+ Semantically Tagged Insults** in the new system
166 - **~3000 Static Insults** in the fallback database
167 - **Comprehensive Coverage**: All major error types, languages, and tools
168 - **Context-Specific**: Insults for specific scenarios (CI failures, late night coding, merge conflicts, etc.)
169
170 ### Example Categories
171
172 **Permission Errors:**
173 - "chmod 777 isn't the answer this time, though I admire your optimism"
174 - "Permission denied. The computer has decided you're not ready for this level of responsibility"
175
176 **Test Failures:**
177 - "Tests failed. Shocking absolutely no one who read your code"
178 - "Expected: working code. Received: whatever this is"
179
180 **Build Failures:**
181 - "The compiler is personally offended by what you've written"
182 - "Your build broke so hard it took down the CI server's will to live"
183
184 **Late Night Context:**
185 - "It's 2 AM. The bugs aren't the only thing that needs fixing"
186 - "Caffeine and bad decisions: a programmer's autobiography"
187
188 **CI/Production:**
189 - "Failed in CI. Congratulations, everyone on the team just got your shame notification"
190 - "Red pipeline. That's the color of your team's disappointment"
191
192 ---
193
194 ## Benefits
195
196 ### 🎯 **Context Awareness**
197 No more generic insults! Each failure gets a response tailored to:
198 - The specific error type
199 - What you were trying to do
200 - Your current environment
201 - Time of day
202 - Failure patterns
203
204 ### 🧠 **Learning & Adaptation**
205 - Tracks which insults you've seen recently
206 - Avoids repetition
207 - Learns your common failure patterns
208 - Adjusts based on your personality preference
209
210 ### 📊 **Intelligent Ranking**
211 - Multi-factor scoring ensures relevance
212 - Quality threshold prevents low-relevance matches
213 - Falls back gracefully to other tiers if needed
214
215 ### 🎭 **Personality Matching**
216 Respects your configured personality:
217 - **Mild**: Gentle, constructive feedback (severity ≤ 4)
218 - **Sarcastic**: Witty, clever mocking (severity 4-7)
219 - **Savage**: Brutal, devastating roasts (severity ≥ 6)
220
221 ---
222
223 ## Configuration
224
225 ### Personality Setting
226
227 The intelligent system respects your personality preference:
228
229 ```toml
230 # ~/.config/parrot/config.toml
231 [general]
232 personality = "sarcastic" # Options: mild, sarcastic, savage
233 ```
234
235 ### Fallback Behavior
236
237 If the ML-inspired system doesn't find a high-confidence match (score < 0.3), it falls through to Tier 4, 3, 2, 1, and finally the static database. This ensures you **always** get a response.
238
239 ---
240
241 ## Technical Details
242
243 ### Performance
244
245 - **Fast**: Scoring algorithm is O(n) where n = number of insults (~200)
246 - **Lightweight**: Minimal memory footprint
247 - **Cached**: Database loaded once at startup
248 - **Persistent**: History stored in JSON for cross-session learning
249
250 ### Files Created
251
252 - `~/.parrot/insult_history.json`: Tracks shown insults and usage statistics
253 - `~/.parrot/failures.json`: User failure history (existing Tier 4 system)
254
255 ### Quality Threshold
256
257 Insults must score **≥ 0.3** (30%) to be used. This ensures only relevant, contextual insults are shown. Lower-scoring matches fall through to other intelligence tiers.
258
259 ---
260
261 ## Examples
262
263 ### Example 1: Permission Error at 2 AM
264
265 **Command:** `sudo rm -rf /important/file` (Exit: 126)
266
267 **Analysis:**
268 - Error Type: Permission denied
269 - Time: 2 AM (late night)
270 - Risk: High (destructive command)
271 - Intent: Delete
272
273 **Selected Insult:**
274 > "Permission denied. The computer has decided you're not ready for this level of responsibility"
275
276 **Score Breakdown:**
277 - Tag Match: 0.90 (permission + late_night tags match)
278 - Error Match: 1.0 (perfect permission error match)
279 - Context: 0.85 (late night + high risk)
280 - Novelty: 1.0 (not shown recently)
281 - Personality: 0.80 (sarcastic, severity 5)
282 - **Total: 0.88** ✓
283
284 ---
285
286 ### Example 2: Test Failure in CI
287
288 **Command:** `npm test` (Exit: 1, CI environment)
289
290 **Analysis:**
291 - Error Type: Test failure
292 - Environment: GitHub Actions CI
293 - Project: Node.js
294 - Intent: Test
295
296 **Selected Insult:**
297 > "Did you test this before committing? Oh wait, that's what the CI is for, right?"
298
299 **Score Breakdown:**
300 - Tag Match: 0.85 (test + node + ci tags)
301 - Error Match: 0.95 (test failure match)
302 - Context: 0.90 (CI context bonus)
303 - Novelty: 1.0
304 - Personality: 0.85
305 - **Total: 0.89** ✓
306
307 ---
308
309 ### Example 3: Merge Conflict on Main Branch
310
311 **Command:** `git merge feature/new-ui` (Exit: 1, on main branch)
312
313 **Analysis:**
314 - Error Type: Merge conflict
315 - Branch: main (high risk)
316 - Command: git
317 - Intent: Merge
318
319 **Selected Insult:**
320 > "<<<<<<< HEAD is not a valid merge resolution strategy"
321
322 **Score Breakdown:**
323 - Tag Match: 0.95 (merge_conflict + git + main_branch)
324 - Error Match: 1.0 (perfect merge conflict match)
325 - Context: 0.80 (main branch penalty)
326 - Novelty: 1.0
327 - Personality: 0.90
328 - **Total: 0.92** ✓
329
330 ---
331
332 ## Future Enhancements
333
334 Possible improvements for future versions:
335
336 1. **True ML Model**: Train a lightweight model on historical data
337 2. **User Preference Learning**: Learn which insults the user appreciates most
338 3. **Team Patterns**: Share anonymized patterns across team members
339 4. **Custom Insults**: Allow users to add their own tagged insults
340 5. **Sentiment Analysis**: Detect frustration level from command patterns
341 6. **Integration**: Pull error messages from stderr for better classification
342
343 ---
344
345 ## Code Structure
346
347 ```
348 internal/llm/
349 ├── error_classifier.go # Classifies error types from exit codes & patterns
350 ├── semantic_tags.go # Tagged insult database with metadata
351 ├── intent_parser.go # Extracts command intent and complexity
352 ├── insult_scorer.go # Multi-factor scoring algorithm
353 ├── insult_history.go # Persistent history tracking
354 └── smart_fallback.go # Integration layer (Tier 5 addition)
355 ```
356
357 ---
358
359 ## Summary
360
361 The new ML-inspired intelligent insult system transforms Parrot from a simple random insult generator into a **context-aware, adaptive, learning system** that delivers highly relevant feedback tailored to:
362
363 ✅ **What went wrong** (error classification)
364 ✅ **What you were trying to do** (intent parsing)
365 ✅ **Your environment** (CI, time, branch, project type)
366 ✅ **Your history** (avoiding repetition, learning patterns)
367 ✅ **Your preference** (personality matching)
368
369 This represents a **significant intelligence upgrade** that makes every failure... well, at least entertainingly personalized! 🎯