Add comprehensive documentation and 28 example tools

- Updated README with full feature overview and examples - Added docs/INSTALL.md with detailed setup instructions - Added docs/PROVIDERS.md with 12 profiled providers - Added docs/EXAMPLES.md with all 28 tool configurations - Added examples/install.py for one-command tool installation - Updated pyproject.toml with better metadata - Added urwid TUI with provider descriptions in dropdown - Profiled all providers for speed/accuracy/cost 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
2025-12-04 12:42:04 -04:00
parent 28dac465e6
commit 4c71dbded2
14 changed files with 6072 additions and 565 deletions
@@ -1,79 +1,334 @@
 # SmartTools

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

-## What is this?
-
-SmartTools lets you create custom AI-powered terminal commands. You define a tool once (name, prompt, provider), then use it like any Linux command.
+Turn any AI model into a Unix-style pipe command. Build once, use forever.

 ```bash
-# Create a summarizer, then use it like any command:
-sum -i document.txt -o summary.txt --max 512
+# 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"}
 ```

-## Quick Example
+## Why SmartTools?

-A tool is just a YAML config:
+- **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

-```yaml
-# ~/.smarttools/sum/config.yaml
-name: sum
-description: "Summarize documents"
-prompt: |
-  Summarize the following text in {max} words or less:
-  {input}
-provider: codex
-provider_args: "-p"
-inputs:
-  - name: max
-    flag: --max
-    default: 500
-```
-
-Then run it:
+## Quick Start

 ```bash
-sum -i myfile.txt -o summary.txt
-sum -i myfile.txt --dry-run          # preview prompt
-sum -i myfile.txt --provider mock    # test without API
+# 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
 ```

-## Features
-
- **Simple UI** - Create/edit/delete tools with `dialog`-based interface
- **CLI-first** - Tools work like regular Linux commands
- **Provider-agnostic** - Use Codex, Claude, Gemini, or any CLI AI tool
- **Testing built-in** - `--dry-run`, `--show-prompt`, `--provider mock`
- **Minimal** - ~430 lines of Python, minimal dependencies
-
 ## Installation

+### From PyPI (Recommended)
+
 ```bash
 pip install smarttools
 ```

-## Usage
+### From Source

 ```bash
-# Launch UI to manage tools
-smarttools
-
-# Or use CLI:
-smarttools list
-smarttools create mytool
-smarttools edit mytool
-smarttools delete mytool
-smarttools test mytool
+git clone https://github.com/yourusername/smarttools.git
+cd smarttools
+pip install -e .
 ```

-## Documentation
+### Requirements

-See [docs/DESIGN.md](docs/DESIGN.md) for the full design document.
+- 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://raw.githubusercontent.com/yourusername/smarttools/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

-This is a **personal power tool**. You write the tools, you run the tools, you accept the responsibility. No trust tiers, no sandboxing, no signing - just like any bash script you write.
+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://github.com/yourusername/smarttools.git
+cd smarttools
+pip install -e ".[dev]"
+pytest
+```
+
+## Support
+
+If SmartTools saves you time, consider:
+
+- [GitHub Sponsors](https://github.com/sponsors/yourusername)
+- [Buy Me a Coffee](https://buymeacoffee.com/yourusername)

 ## License

-MIT
+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)