# ai-unix

Unix tools with a sprinkling of spicy non-determinism.

## Examples

### Log Analysis & Monitoring

```bash
# Find critical errors in recent logs
tail -n 1000 app.log | ai-grep "errors" | ai-class "critical,warning,info" | grep "^critical" | head -10

# Extract error data and count by component
ai-cut -f "timestamp,component,error_code" error.log | sort -k2 | uniq -c | sort -nr

# Monitor specific error patterns
ai-grep "database issues" app.log | wc -l > error-count.txt
```

### Data Cleaning & Processing

```bash
# Clean contact list with traditional unix validation
ai-cut -f "name,email,phone" raw-contacts.txt | sort | uniq | ai-test -p "valid email format" | grep "@"

# Process feedback and count by sentiment
ai-class "positive,negative,neutral" reviews.txt | sort | uniq -c | sort -nr

# Extract structured data and validate
ai-cut -f "date,amount,vendor" receipts.txt | ai-test -p "complete data" | awk '{sum+=$2} END {print "Total:", sum}'
```

### Content & Code Management

```bash
# Find high-priority TODOs across codebase
find src/ -name "*.py" -exec ai-grep "TODO items" {} \; | ai-cut -f "file,priority,task" | grep "high" | sort

# Validate documentation before commit
find docs/ -name "*.md" | xargs ai-test -q "ready for publication" && git add docs/ || echo "Docs need review"

# Convert and organize documentation
ls *.txt | xargs -I {} ai-tr "markdown format" {} > {}.md && rm *.txt

# Extract and categorize code issues
ai-grep "code problems" src/*.py | ai-class "bug,performance,style" | tee issues.log | grep "^bug" | wc -l
```

## Tool Specifications

### `ai-grep` - Semantic Search

Searches for content based on meaning rather than exact string matching.

**Synopsis:**

```bash
ai-grep [OPTIONS] PATTERN [FILE...]
```

**Options:**
- `-v` - Select non-matching lines (semantic inverse)
- `-n` - Show line numbers
- `-c` - Show only count of matching lines

**Input:** Text from stdin or files
**Output:** Matching lines or statistics
**Exit Codes:**
- 0: Matches found
- 1: No matches found
- 2: System error (invalid options, file not found)
- 3: LLM behavioral error (ambiguous pattern, context too complex)
- 4: API/infrastructure error

### `ai-cut` - Structured Data Extraction

Extracts structured fields from unstructured text using natural language field descriptions.

**Synopsis:**

```bash
ai-cut -f FIELDS [FILE...]
```

**Options:**
- `-f FIELDS` - Comma-separated field descriptions (required)
- `-j` - Output as JSON objects (default: TSV)

**Input:** Unstructured text from stdin or files
**Output:** Structured data in specified format
**Exit Codes:**
- 0: Extraction successful
- 1: No extractable data found
- 2: System error (invalid field specification, file not found)
- 3: LLM behavioral error (ambiguous fields, unstructured input)
- 4: API/infrastructure error

### `ai-class` - Semantic Categorization

Categorizes input text into predefined buckets based on semantic content.

**Synopsis:**

```bash
ai-class CATEGORIES [FILE...]
```

**Options:**
(None - use standard Unix tools like `head -n1` to limit output)

**Input:** Text lines from stdin or files
**Output:** Each line prefixed with category label
**Exit Codes:**
- 0: Classification successful
- 1: No classifiable input
- 2: System error (invalid categories, file not found)
- 3: LLM behavioral error (ambiguous categories, unclear input)
- 4: API/infrastructure error

### `ai-tr` - Semantic Transformation

Transforms text format or style while preserving semantic meaning.

**Synopsis:**

```bash
ai-tr TRANSFORMATION [FILE...]
```

**Input:** Text from stdin or files
**Output:** Transformed text
**Exit Codes:**
- 0: Transformation successful
- 1: Transformation failed (unable to perform transformation)
- 2: System error (file not found, invalid syntax)
- 3: LLM behavioral error (ambiguous transformation request)
- 4: API/infrastructure error

### `ai-test` - Semantic Validation

Validates text content against semantic criteria, returning appropriate exit codes for use in conditionals.

**Synopsis:**

```bash
ai-test CONDITION [FILE...]
```

**Options:**
- `-q` - Suppress all output (exit code only)
- `-v` - Invert match (exit 0 when condition is false)
- `-p` - Pass-through mode (output input unchanged when condition is true)

**Input:** Text from stdin or files
**Output:** Validation results, or input text in pass-through mode
**Exit Codes:**
- 0: Condition is true/valid (or false when -v used)
- 1: Condition is false/invalid (or true when -v used)
- 2: System error (invalid condition syntax, file not found)
- 3: LLM behavioral error (ambiguous condition, unclear input)
- 4: API/infrastructure error