# 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

## Try It Now (60 seconds)

See SmartTools in action without installing anything on your system:

```bash
# Pull the container
docker pull gitea.brrd.tech/rob/smarttools:latest

# Run it
docker run -it --rm gitea.brrd.tech/rob/smarttools bash

# Inside the container - install OpenCode (includes free AI models)
smarttools providers install   # Select option 4, then 'y'
source ~/.bashrc

# Try it! This explains the README using the free Big Pickle model
cat README.md | eli5
```

That's it - you just used AI to explain itself. The `eli5` tool uses a free model by default, no sign-up required.

## Quick Start (Native Install)

For regular use, install natively:

```bash
# Clone and install
git clone https://gitea.brrd.tech/rob/SmartTools.git
cd SmartTools
pip install -e .

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

# Install an AI provider (interactive guide)
smarttools providers install

# Launch the UI
smarttools ui

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

## Installation

### Native Install

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

### With Development Dependencies

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

### 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
```

### Composing Tools

SmartTools follows Unix philosophy: each tool does one thing well, and tools chain together for complex workflows.

```bash
# Chain SmartTools together
cat error.log | log-errors | summarize | translate --lang Spanish

# Code review pipeline: focus on changes, review, then summarize
git diff | diff-focus | review-code | tldr

# Extract data, convert format, analyze
cat report.pdf | json-extract --fields "revenue, costs, date" | json2csv | csv-insights

# Process text through multiple transformations
cat technical_doc.txt | simplify | fix-grammar | tone-shift --tone friendly

# Generate code, validate it, then explain what it does
echo "parse CSV and calculate averages" | code-validate | explain-code
```

**Mix with standard Unix tools:**

```bash
# Extract emails, deduplicate, count
cat inbox.txt | extract-emails | sort -u | wc -l

# Find errors in multiple logs, explain them
cat *.log | grep -i error | explain-error

# Generate changelog for specific author
git log --author="rob" --oneline | changelog > CHANGELOG.md

# Review only large files in a commit
git diff --stat | awk '$3 > 100 {print $1}' | xargs cat | review-code
```

**Build shell functions for common pipelines:**

```bash
# ~/.bashrc
quick-review() {
    git diff "$@" | diff-focus | review-code --focus "bugs and security" | tldr
}

translate-doc() {
    cat "$1" | summarize | translate --lang "$2"
}

# Usage: quick-review HEAD~3
# Usage: translate-doc manual.txt French
```

## 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
# Run the example installer (from the SmartTools directory)
python examples/install.py
smarttools refresh
```

## 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
category: Text  # Optional: Text, Developer, Data, or Other
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}"
```

### Categories

Tools can be organized into categories for easier navigation in the UI:

| Category | Description |
|----------|-------------|
| `Text` | Text processing (summarize, translate, grammar) |
| `Developer` | Dev tools (explain-error, gen-tests, commit-msg) |
| `Data` | Data extraction and conversion (json-extract, csv) |
| `Other` | Default for uncategorized tools |

### 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 |
| **Scroll content** | Mouse wheel |
| **Scroll up** | Click top of scrollbar |
| **Scroll down** | Click bottom of scrollbar |
| **Page up/down** | Click middle of scrollbar |
| **Select text** | `Shift` + mouse drag |
| **Copy** | Terminal native (with Shift) |
| **Paste** | `Ctrl+Shift+V` |
| **Undo** (code editor) | `Alt+U` |
| **Redo** (code editor) | `Alt+R` |

**Tips:**
- Hold `Shift` while using mouse for terminal-native text selection.
- Code/Prompt editors have DOS-style scrollbars with `▲` and `▼` arrow buttons.
- In step dialogs, use `Tab` to cycle between File, Editor, and Output fields.
- The code editor supports undo/redo (up to 50 states) with `Alt+U` and `Alt+R`.
- Use the `$EDITOR` button to open code or prompts in your external editor.

## AI-Assisted Code Generation

When adding or editing a **Code Step**, the dialog includes an AI assist panel:

```
┌─ Code ─────────────┐ ┌─ AI Assisted Auto-adjust ─────────────┐
│ result = input...  │ │ Provider: [opencode-deepseek] [▼]    │
│                    │ │ ┌─ Prompt ──────────────────────────┐ │
│                    │ │ │ Modify this code to...           │ │
│                    │ │ │ {code}                           │ │
│                    │ │ └──────────────────────────────────┘ │
│                    │ │ ┌─ Output & Feedback ───────────────┐ │
│                    │ │ │ ✓ Code updated successfully!     │ │
│                    │ │ └──────────────────────────────────┘ │
│                    │ │         < Auto-adjust >              │
└────────────────────┘ └───────────────────────────────────────┘
```

- **Provider**: Select any configured AI provider
- **Prompt**: Fully editable template - use `{code}` placeholder for current code
- **Output**: Shows status, success/error messages, and provider feedback
- **Auto-adjust**: Sends prompt to AI and replaces code with response

This lets you generate or modify Python code using AI directly within the tool builder.

## Philosophy

SmartTools is built on **Unix philosophy**:

1. **Do one thing well** - Each tool solves one problem. `summarize` summarizes. `translate` translates. No bloated mega-tools.

2. **Compose freely** - Tools read stdin, write stdout. Chain them: `cat doc.txt | summarize | translate --lang French`

3. **Text is the interface** - No proprietary formats. Pipe text in, get text out. Works with `grep`, `awk`, `sed`, and every other Unix tool.

4. **You own everything** - Tools are YAML files. Prompts are plain text. No vendor lock-in, no cloud dependency for your tool definitions.

5. **Swap parts freely** - Change AI providers per-tool or per-run. Today's best model might not be tomorrow's.

## 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.

## Docker

### Pre-built Container (Fastest)

Pull and run the pre-built image directly:

```bash
# Pull from registry
docker pull gitea.brrd.tech/rob/smarttools:latest

# Run SmartTools
docker run -it --rm gitea.brrd.tech/rob/smarttools smarttools --help

# List available tools
docker run -it --rm gitea.brrd.tech/rob/smarttools smarttools list

# Interactive shell
docker run -it --rm gitea.brrd.tech/rob/smarttools bash
```

### Build from Source

Alternatively, build the container yourself:

```bash
# Clone the repo
git clone https://gitea.brrd.tech/rob/SmartTools.git
cd SmartTools

# Build the container
docker-compose build

# Run tests
docker-compose run --rm test

# Use the CLI
docker-compose run --rm cli smarttools list

# Interactive shell
docker-compose run --rm shell
```

### Installing AI Providers in Docker

AI providers require browser-based authentication. You need display access for the browser to open.

**Using the pre-built container:**

```bash
# Allow Docker to access your display (Linux)
xhost +local:docker

# Run with display access and persistent storage
docker run -it --rm \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  -v smarttools-data:/root/.smarttools \
  --network host \
  gitea.brrd.tech/rob/smarttools bash

# Inside the container:
smarttools providers install
```

**Using docker-compose (build from source):**

```bash
xhost +local:docker
docker-compose run --rm setup

# Inside the container:
smarttools providers install
```

**After installing a provider:**

```bash
# Test the provider works
smarttools providers test claude
```

**Available Providers:**
| # | Provider | Cost | Notes |
|---|----------|------|-------|
| 1 | Claude | Pay-per-use | Anthropic account |
| 2 | Codex | Pay-per-use | OpenAI account |
| 3 | Gemini | Free tier | Google account |
| 4 | OpenCode | Free tier | Multiple models |
| 5 | Ollama | FREE | Local, no internet |

## Links

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