From 285fbe0f976a28d93d1b9b1d3ecf6eda3a71679f Mon Sep 17 00:00:00 2001 From: rob Date: Tue, 30 Dec 2025 06:46:23 +0000 Subject: [PATCH] Add Home --- Home.md | 353 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 353 insertions(+) create mode 100644 Home.md diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..1f9b74b --- /dev/null +++ b/Home.md @@ -0,0 +1,353 @@ +# SmartTools Wiki + +Welcome to SmartTools - a lightweight personal tool builder for AI-powered CLI commands. + +SmartTools lets you turn any AI model into a Unix-style pipe command. Build your own AI tools once, use them forever - no coding required. + +## What is SmartTools? + +Think of SmartTools as a universal adapter between you and AI. Instead of opening a chat window and copy-pasting text, you create reusable command-line tools: + +```bash +# Before: Copy text, open browser, paste into ChatGPT, wait, copy result +# After: +cat article.txt | summarize + +# Before: Manually ask AI to fix grammar +# After: +echo "teh cat sat on teh mat" | fix-grammar +# Output: The cat sat on the mat. + +# Chain tools together like any Unix command +cat report.txt | summarize | translate --lang Spanish +``` + +### Core Philosophy + +SmartTools follows the **Unix philosophy**: + +1. **Each tool does one thing well** - `summarize` summarizes, `translate` translates +2. **Tools are composable** - Chain them with pipes: `cat file | tool1 | tool2` +3. **Text is the interface** - Works with `grep`, `awk`, `sed`, and every other Unix tool +4. **You own everything** - Tools are simple YAML files, no vendor lock-in + +--- + +## Quick Start Options + +### Option 1: Try It Now (60 seconds, no install) + +```bash +# Pull the pre-built container +docker pull gitea.brrd.tech/rob/smarttools:latest + +# Run it +docker run -it --rm gitea.brrd.tech/rob/smarttools bash + +# Inside container - install OpenCode (includes FREE AI models) +smarttools providers install # Select option 4, then 'y' +source ~/.bashrc + +# Try a tool! Uses free Big Pickle model +cat README.md | eli5 +``` + +### Option 2: Native Install + +```bash +git clone https://gitea.brrd.tech/rob/SmartTools.git +cd SmartTools +pip install -e . +export PATH="$HOME/.local/bin:$PATH" +smarttools providers install +``` + +--- + +## Understanding Providers + +SmartTools doesn't include any AI - it connects to AI **providers**. A provider is any CLI tool that reads text from stdin and outputs a response. + +### Available Providers + +| Provider | Models | Cost | Best For | +|----------|--------|------|----------| +| **OpenCode** | 75+ models | 4 FREE, others paid | Best starting point | +| **Claude** | Haiku, Sonnet, Opus | Pay-per-use | High quality | +| **Codex** | GPT models | Pay-per-use | Reliable | +| **Gemini** | Flash, Pro | Free tier | Large documents (1M tokens) | +| **Ollama** | Llama, Mistral, etc. | FREE (local) | Privacy, offline use | + +### Free Models in OpenCode + +When you install OpenCode, these models are available immediately with no sign-up: + +- **Big Pickle** - High quality, used by `eli5` and other tools by default +- **GLM-4.7** - Chinese AI lab model +- **Grok Code Fast 1** - Fast but less accurate +- **MiniMax M2.1** - Alternative free option + +### Installing a Provider + +```bash +smarttools providers install +``` + +This interactive guide shows all options and runs the installation for you. After installing, run the provider once to authenticate (opens browser). + +--- + +## The 27 Built-in Tools + +SmartTools comes with ready-to-use tools organized by category: + +### Text Processing + +| Tool | What it does | Example | +|------|--------------|---------| +| `summarize` | Condense documents | `cat article.txt \| summarize` | +| `translate` | Translate to any language | `echo "Hello" \| translate --lang Spanish` | +| `fix-grammar` | Fix spelling and grammar | `cat draft.txt \| fix-grammar` | +| `simplify` | Rewrite for clarity | `cat legal.txt \| simplify --level "5th grade"` | +| `tone-shift` | Change writing 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 | What it does | 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 | `git 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 messages | `git diff --staged \| commit-msg` | + +### Data Tools + +| Tool | What it does | 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` | +| `csv-insights` | Analyze CSV data | `cat sales.csv \| csv-insights --question "trends?"` | + +### Multi-Step Tools + +These tools combine AI prompts with code for validation: + +| Tool | Pattern | What it does | +|------|---------|--------------| +| `log-errors` | Code→AI | Extract and explain errors from huge logs | +| `diff-focus` | Code→AI | Extract only added lines, then review | +| `changelog` | Code→AI→Code | Parse git log, generate changelog, format it | +| `code-validate` | AI→Code | Generate code, validate syntax | + +--- + +## Creating Your Own Tools + +### Using the TUI + +The easiest way to create tools: + +```bash +smarttools ui +``` + +Navigate with arrow keys, create tools visually, edit prompts, test with mock provider. + +### Tool Anatomy (YAML) + +Every tool is a YAML file in `~/.smarttools//config.yaml`: + +```yaml +name: my-tool +description: What this tool does +arguments: + - flag: --style + variable: style + default: "casual" +steps: + - type: prompt + prompt: | + Rewrite this in a {style} style: + + {input} + provider: opencode-pickle + output_var: response +output: "{response}" +``` + +### Variables + +| Variable | Description | +|----------|-------------| +| `{input}` | The piped/file input | +| `{argname}` | Value of `--argname` flag | +| `{previous_output}` | Output from previous step | + +### Multi-Step Example + +Chain AI with code for validated output: + +```yaml +name: safe-json +description: Extract data as validated JSON +steps: + # Step 1: AI extracts data + - type: prompt + prompt: "Extract {fields} as JSON: {input}" + provider: opencode-pickle + output_var: raw_json + + # Step 2: Python validates + - type: code + code: | + import json + try: + parsed = json.loads(raw_json) + result = json.dumps(parsed, indent=2) + except: + result = '{"error": "Invalid JSON"}' + output_var: result + +output: "{result}" +``` + +--- + +## Provider Selection Strategy + +### Choosing the Right Provider + +| Use Case | Recommended Provider | +|----------|---------------------| +| Quick tasks, free | `opencode-pickle` | +| Daily use, cheap | `opencode-deepseek` | +| High quality | `claude-haiku` or `claude-opus` | +| Large documents | `gemini` (1M token context) | +| Complex reasoning | `opencode-reasoner` | +| Offline/private | `ollama` | + +### Override at Runtime + +Any tool can use a different provider for a single run: + +```bash +# Tool defaults to opencode-pickle, but use claude this time +cat important.txt | summarize --provider claude-opus +``` + +### Change Tool Default + +Edit the tool's config or use the TUI: + +```bash +smarttools ui +# Select tool → Edit → Change provider in step +``` + +--- + +## Troubleshooting + +### "Command 'X' not found" + +The AI CLI isn't installed: + +```bash +smarttools providers install +# Select the provider and follow instructions +``` + +### "Model 'X' is not available" + +The model isn't connected in your provider: + +```bash +# For OpenCode models: +opencode +# Connect the required provider in the menu + +# Or use a different model: +cat file.txt | tool --provider opencode-pickle +``` + +### Tool returns empty output + +1. Check the provider is configured: `smarttools providers check` +2. Test the provider directly: `smarttools providers test opencode-pickle` +3. Try a different provider: `--provider opencode-pickle` + +### Provider is slow + +- Use `gemini-flash` instead of `gemini` +- Use `claude-haiku` instead of `claude-opus` +- Use `opencode-deepseek` for best speed/quality ratio + +--- + +## Advanced Usage + +### Shell Integration + +Add to `~/.bashrc`: + +```bash +export PATH="$HOME/.local/bin:$PATH" + +# Aliases +alias wtf='explain-error' +alias fixme='fix-grammar' +alias gc='git diff --staged | commit-msg' +``` + +### Git Hooks + +Auto-generate commit messages: + +```bash +# .git/hooks/prepare-commit-msg +#!/bin/bash +git diff --cached | commit-msg > "$1" +``` + +### Vim Integration + +```vim +" Fix grammar in selection +vnoremap fg :!fix-grammar + +" Explain selected code +vnoremap ec :!explain-code +``` + +### Pipeline Examples + +```bash +# Review pipeline: focus on changes, review, summarize +git diff | diff-focus | review-code | tldr + +# Translation pipeline: summarize then translate +cat article.txt | summarize | translate --lang Japanese + +# Code review: only check large changes +git diff --stat | awk '$3 > 100 {print $1}' | xargs cat | review-code +``` + +--- + +## Links + +- **Repository**: https://gitea.brrd.tech/rob/SmartTools +- **Docker Image**: `gitea.brrd.tech/rob/smarttools:latest` +- **Issues**: https://gitea.brrd.tech/rob/SmartTools/issues + +--- + +*SmartTools is MIT licensed. Use it, modify it, share it.*