smarttools/README.md

# SmartTools

**A lightweight personal tool builder for AI-powered CLI commands.**

Turn any AI model into a Unix-style pipe command. Build once, use forever.

```bash
# Fix grammar in any file
echo "teh cat sat on teh mat" | fix-grammar
# Output: The cat sat on the mat

# Explain errors instantly
cat error.log | explain-error

# Generate commit messages
git diff --staged | commit-msg

# Extract data as validated JSON
echo "Price $49.99, SKU ABC-123" | json-extract --fields "price, sku"
# Output: {"price": 49.99, "sku": "ABC-123"}
```

## Why SmartTools?

- **Unix Philosophy** - Tools that do one thing well, composable with pipes
- **Provider Agnostic** - Works with Claude, GPT, Gemini, DeepSeek, local models
- **No Lock-in** - Your tools are YAML files, your prompts are yours
- **Multi-step Pipelines** - Chain AI prompts with Python code for validation
- **12+ Providers Profiled** - We tested them so you don't have to

## Quick Start

```bash
# Install
pip install smarttools

# Ensure ~/.local/bin is in PATH
export PATH="$HOME/.local/bin:$PATH"

# Launch the UI
smarttools ui

# Or create your first tool
smarttools create summarize
```

## Installation

### From PyPI (Recommended)

```bash
pip install smarttools
```

### From Source

```bash
git clone https://gitea.brrd.tech/rob/smarttools.git
cd smarttools
pip install -e .
```

### Requirements

- Python 3.10+
- At least one AI CLI tool installed (see [Provider Setup](docs/PROVIDERS.md))
- Optional: `urwid` for the TUI (`pip install urwid`)

### Post-Install

Add to your `~/.bashrc` or `~/.zshrc`:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

Then refresh wrapper scripts:

```bash
smarttools refresh
```

## Usage

### UI Mode (Recommended for Beginners)

```bash
smarttools ui
```

Navigate with arrow keys, Tab, Enter, and mouse. Create tools visually with the built-in prompt editor.

### CLI Mode

```bash
smarttools list              # List all tools
smarttools create mytool     # Create new tool
smarttools edit mytool       # Edit in $EDITOR
smarttools delete mytool     # Delete tool
smarttools run mytool        # Run a tool
smarttools test mytool       # Test with mock provider
smarttools refresh           # Update executable wrappers
```

### Running Tools

Once created, tools work like any Unix command:

```bash
# Direct invocation
mytool -i input.txt -o output.txt

# Pipe input (most common)
cat file.txt | mytool

# With arguments
echo "hello" | translate --lang French

# Preview without calling AI
cat file.txt | mytool --dry-run

# Test with mock provider
cat file.txt | mytool --provider mock
```

## Example Tools

SmartTools comes with 28 pre-built examples you can install:

### Text Processing

| Tool | Description | Example |
|------|-------------|---------|
| `summarize` | Condense documents | `cat article.txt \| summarize` |
| `translate` | Translate text | `echo "Hello" \| translate --lang Spanish` |
| `fix-grammar` | Fix spelling/grammar | `cat draft.txt \| fix-grammar` |
| `simplify` | Rewrite for clarity | `cat legal.txt \| simplify --level "5th grade"` |
| `tone-shift` | Change tone | `cat email.txt \| tone-shift --tone professional` |
| `eli5` | Explain like I'm 5 | `cat quantum.txt \| eli5` |
| `tldr` | One-line summary | `cat readme.txt \| tldr` |
| `expand` | Expand bullet points | `cat notes.txt \| expand` |

### Developer Tools

| Tool | Description | Example |
|------|-------------|---------|
| `explain-error` | Explain stack traces | `cat error.log \| explain-error` |
| `explain-code` | Explain what code does | `cat script.py \| explain-code` |
| `review-code` | Quick code review | `cat pr.diff \| review-code --focus security` |
| `gen-tests` | Generate unit tests | `cat module.py \| gen-tests --framework pytest` |
| `docstring` | Add docstrings | `cat functions.py \| docstring` |
| `commit-msg` | Generate commit message | `git diff --staged \| commit-msg` |

### Data Tools

| Tool | Description | Example |
|------|-------------|---------|
| `json-extract` | Extract as validated JSON | `cat text.txt \| json-extract --fields "name, email"` |
| `json2csv` | Convert JSON to CSV | `cat data.json \| json2csv` |
| `extract-emails` | Extract email addresses | `cat page.html \| extract-emails` |
| `extract-contacts` | Extract contacts as CSV | `cat notes.txt \| extract-contacts` |
| `sql-from-text` | Natural language to SQL | `echo "get active users" \| sql-from-text` |
| `safe-sql` | SQL with safety checks | `echo "delete old records" \| safe-sql` |
| `parse-log` | Analyze log files | `cat app.log \| parse-log --focus errors` |
| `csv-insights` | Analyze CSV data | `cat sales.csv \| csv-insights --question "trends?"` |

### Advanced Multi-Step Tools

| Tool | Description | Pattern |
|------|-------------|---------|
| `log-errors` | Extract & explain errors from huge logs | Code→AI |
| `diff-focus` | Review only added lines | Code→AI |
| `changelog` | Git log to formatted changelog | Code→AI→Code |
| `code-validate` | Generate syntax-checked Python | AI→Code |

### Install Example Tools

```bash
# Download and run the example installer
curl -sSL https://gitea.brrd.tech/rob/smarttools/raw/branch/main/examples/install.py | python3

# Or manually copy from examples/
```

## Providers

SmartTools works with any AI CLI tool. We've profiled 12 providers:

| Provider | Speed | Accuracy | Cost | Best For |
|----------|-------|----------|------|----------|
| `opencode-deepseek` | 13s | 4/4 | Cheap | **Best value** - daily use |
| `opencode-pickle` | 13s | 4/4 | FREE | **Best free** - accurate |
| `claude-haiku` | 14s | 4/4 | Paid | Fast + accurate |
| `codex` | 14s | 4/4 | Paid | Reliable |
| `claude-opus` | 18s | 4/4 | $$$ | Highest quality |
| `gemini` | 91s | 3/4 | Paid | Large docs (1M tokens) |

See [docs/PROVIDERS.md](docs/PROVIDERS.md) for setup instructions.

## Tool Anatomy

A tool is a YAML config file in `~/.smarttools/<name>/config.yaml`:

```yaml
name: summarize
description: Condense documents to key points
arguments:
  - flag: --length
    variable: length
    default: "3-5 bullet points"
steps:
  - type: prompt
    prompt: |
      Summarize this text into {length}:

      {input}      
    provider: opencode-pickle
    output_var: response
output: "{response}"
```

### Multi-Step Tools

Chain AI prompts with Python code for powerful workflows:

```yaml
name: json-extract
description: Extract data as validated JSON
steps:
  # Step 1: AI extracts data
  - type: prompt
    prompt: "Extract {fields} as JSON from: {input}"
    provider: opencode-deepseek
    output_var: raw_json

  # Step 2: Code validates JSON
  - type: code
    code: |
      import json
      try:
          parsed = json.loads(raw_json)
          validated = json.dumps(parsed, indent=2)
      except:
          validated = "ERROR: Invalid JSON"      
    output_var: validated
output: "{validated}"
```

### Variables

| Variable | Description |
|----------|-------------|
| `{input}` | The piped/file input |
| `{argname}` | Custom argument value |
| `{step_output}` | Output from previous step |

## Shell Integration

### Git Hooks

```bash
# .git/hooks/prepare-commit-msg
#!/bin/bash
git diff --cached | commit-msg > "$1"
```

### Aliases

```bash
# ~/.bashrc
alias gc='git diff --staged | commit-msg'
alias wtf='explain-error'
alias fixme='fix-grammar'
```

### Vim Integration

```vim
" Fix grammar in selection
vnoremap <leader>fg :!fix-grammar<CR>

" Explain selected code
vnoremap <leader>ec :!explain-code<CR>
```

## UI Navigation

| Action | Keys |
|--------|------|
| Cycle sections | `Tab` |
| Go back | `Escape` |
| Select | `Enter` or click |
| Navigate | Arrow keys |
| **Select text** | `Shift` + mouse drag |
| **Copy** | Terminal native (with Shift) |
| **Paste** | `Ctrl+Shift+V` |

**Tip:** Hold `Shift` while using mouse for terminal-native text selection.

## Philosophy

SmartTools is a **personal power tool**:

- **You own your tools** - YAML files you can read, edit, share
- **You choose the AI** - Any provider, swap anytime
- **You accept responsibility** - No sandboxing, like any script you write
- **Unix philosophy** - Small tools that compose

## Contributing

```bash
git clone https://gitea.brrd.tech/rob/smarttools.git
cd smarttools
pip install -e ".[dev]"
pytest
```

## Support

If SmartTools saves you time, consider supporting the project:

**Bitcoin:** `3KeLqGv2Xo8jGYkqA1i68a6nXwgQnuJoza`

**Questions?** robdickson444@hotmail.com

## License

MIT - Use it, modify it, share it.

## Links

- [Installation Guide](docs/INSTALL.md)
- [Provider Setup](docs/PROVIDERS.md)
- [Example Tools](docs/EXAMPLES.md)
- [Design Document](docs/DESIGN.md)