begriffs open source - ai-unix/blob - README.md

   1 # ai-unix
   2
   3 Unix tools with a sprinkling of spicy non-determinism.
   4
   5 ## Examples
   6
   7 ### Log Analysis & Monitoring
   8
   9 ```bash
  10 # Find critical errors in recent logs
  11 tail -n 1000 app.log | ai-grep "errors" | ai-class "critical,warning,info" | grep "^critical" | head -10
  12
  13 # Extract error data and count by component
  14 ai-cut -f "timestamp,component,error_code" error.log | sort -k2 | uniq -c | sort -nr
  15
  16 # Monitor specific error patterns
  17 ai-grep "database issues" app.log | wc -l > error-count.txt
  18 ```
  19
  20 ### Data Cleaning & Processing
  21
  22 ```bash
  23 # Clean contact list with traditional unix validation
  24 ai-cut -f "name,email,phone" raw-contacts.txt | sort | uniq | ai-test -p "valid email format" | grep "@"
  25
  26 # Process feedback and count by sentiment
  27 ai-class "positive,negative,neutral" reviews.txt | sort | uniq -c | sort -nr
  28
  29 # Extract structured data and validate
  30 ai-cut -f "date,amount,vendor" receipts.txt | ai-test -p "complete data" | awk '{sum+=$2} END {print "Total:", sum}'
  31 ```
  32
  33 ### Content & Code Management
  34
  35 ```bash
  36 # Find high-priority TODOs across codebase
  37 find src/ -name "*.py" -exec ai-grep "TODO items" {} \; | ai-cut -f "file,priority,task" | grep "high" | sort
  38
  39 # Validate documentation before commit
  40 find docs/ -name "*.md" | xargs ai-test -q "ready for publication" && git add docs/ || echo "Docs need review"
  41
  42 # Convert and organize documentation
  43 ls *.txt | xargs -I {} ai-tr "markdown format" {} > {}.md && rm *.txt
  44
  45 # Extract and categorize code issues
  46 ai-grep "code problems" src/*.py | ai-class "bug,performance,style" | tee issues.log | grep "^bug" | wc -l
  47 ```
  48
  49 ## Tool Specifications
  50
  51 ### `ai-grep` - Semantic Search
  52
  53 Searches for content based on meaning rather than exact string matching.
  54
  55 **Synopsis:**
  56
  57 ```bash
  58 ai-grep [OPTIONS] PATTERN [FILE...]
  59 ```
  60
  61 **Options:**
  62 - `-v` - Select non-matching lines (semantic inverse)
  63 - `-n` - Show line numbers
  64 - `-c` - Show only count of matching lines
  65
  66 **Input:** Text from stdin or files
  67 **Output:** Matching lines or statistics
  68 **Exit Codes:**
  69 - 0: Matches found
  70 - 1: No matches found
  71 - 2: System error (invalid options, file not found)
  72 - 3: LLM behavioral error (ambiguous pattern, context too complex)
  73 - 4: API/infrastructure error
  74
  75 ### `ai-cut` - Structured Data Extraction
  76
  77 Extracts structured fields from unstructured text using natural language field descriptions.
  78
  79 **Synopsis:**
  80
  81 ```bash
  82 ai-cut -f FIELDS [FILE...]
  83 ```
  84
  85 **Options:**
  86 - `-f FIELDS` - Comma-separated field descriptions (required)
  87 - `-j` - Output as JSON objects (default: TSV)
  88
  89 **Input:** Unstructured text from stdin or files
  90 **Output:** Structured data in specified format
  91 **Exit Codes:**
  92 - 0: Extraction successful
  93 - 1: No extractable data found
  94 - 2: System error (invalid field specification, file not found)
  95 - 3: LLM behavioral error (ambiguous fields, unstructured input)
  96 - 4: API/infrastructure error
  97
  98 ### `ai-class` - Semantic Categorization
  99
 100 Categorizes input text into predefined buckets based on semantic content.
 101
 102 **Synopsis:**
 103
 104 ```bash
 105 ai-class CATEGORIES [FILE...]
 106 ```
 107
 108 **Options:**
 109 (None - use standard Unix tools like `head -n1` to limit output)
 110
 111 **Input:** Text lines from stdin or files
 112 **Output:** Each line prefixed with category label
 113 **Exit Codes:**
 114 - 0: Classification successful
 115 - 1: No classifiable input
 116 - 2: System error (invalid categories, file not found)
 117 - 3: LLM behavioral error (ambiguous categories, unclear input)
 118 - 4: API/infrastructure error
 119
 120 ### `ai-tr` - Semantic Transformation
 121
 122 Transforms text format or style while preserving semantic meaning.
 123
 124 **Synopsis:**
 125
 126 ```bash
 127 ai-tr TRANSFORMATION [FILE...]
 128 ```
 129
 130 **Input:** Text from stdin or files
 131 **Output:** Transformed text
 132 **Exit Codes:**
 133 - 0: Transformation successful
 134 - 1: Transformation failed (unable to perform transformation)
 135 - 2: System error (file not found, invalid syntax)
 136 - 3: LLM behavioral error (ambiguous transformation request)
 137 - 4: API/infrastructure error
 138
 139 ### `ai-test` - Semantic Validation
 140
 141 Validates text content against semantic criteria, returning appropriate exit codes for use in conditionals.
 142
 143 **Synopsis:**
 144
 145 ```bash
 146 ai-test CONDITION [FILE...]
 147 ```
 148
 149 **Options:**
 150 - `-q` - Suppress all output (exit code only)
 151 - `-v` - Invert match (exit 0 when condition is false)
 152 - `-p` - Pass-through mode (output input unchanged when condition is true)
 153
 154 **Input:** Text from stdin or files
 155 **Output:** Validation results, or input text in pass-through mode
 156 **Exit Codes:**
 157 - 0: Condition is true/valid (or false when -v used)
 158 - 1: Condition is false/invalid (or true when -v used)
 159 - 2: System error (invalid condition syntax, file not found)
 160 - 3: LLM behavioral error (ambiguous condition, unclear input)
 161 - 4: API/infrastructure error