# gptel Configuration Guide

## 🎉 What Was Configured

Your Doom Emacs now has a comprehensive gptel setup with:

### ✅ Installed Packages
1. **gptel** - Main LLM client
2. **gptel-quick** - Quick lookups in popup
3. **gptel-extensions** - Extra utility functions
4. **gptel-autocomplete** - Inline code completion

### ✅ Configured Features
- ✨ OpenRouter backend with multiple models (Gemini, Claude)
- 📝 Org-mode as default (better for saving conversations)
- ⌨️ Comprehensive keybindings under `SPC a` prefix
- 🎨 5 task-specific presets (coder, explain, refactor, quick, docs)
- 🤖 Auto-completion in programming modes
- 🛠️ Custom helper functions for quick explanations and proofreading

---

## 🔐 IMPORTANT: Secure Your API Key

**⚠️ WARNING**: Your OpenRouter API key is currently hardcoded in `ai.el`. This is a security risk!

### Recommended Setup: Use auth-source

1. **Create encrypted credentials file:**
   ```bash
   touch ~/.authinfo.gpg
   chmod 600 ~/.authinfo.gpg
   ```

2. **Add your API key to `~/.authinfo.gpg`:**
   ```
   machine openrouter.ai login apikey password sk-or-v1-YOUR_KEY_HERE
   ```

   Emacs will prompt for a password to encrypt this file.

3. **Update `~/.config/doom/ai.el`:**

   Replace the `:key` line in the `gptel-make-openai` section:
   ```elisp
   ;; BEFORE (insecure):
   :key "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"

   ;; AFTER (secure):
   :key (auth-source-pick-first-password :host "openrouter.ai")
   ```

4. **Reload Doom:**
   ```bash
   doom sync
   ```

---

## ⌨️ Keybindings Reference

All gptel commands are under `SPC a` (AI prefix):

| Keybinding | Command | Description |
|------------|---------|-------------|
| `SPC a g` | `gptel` | Open gptel chat buffer |
| `SPC a s` | `gptel-send` | Send prompt to LLM |
| `SPC a m` | `gptel-menu` | Open transient menu (change model, backend, etc) |
| `SPC a r` | `gptel-rewrite` | Rewrite selected region with AI |
| `SPC a c` | `gptel-add` | Add region/buffer to context |
| `SPC a f` | `gptel-add-file` | Add file to context |
| `SPC a q` | `gptel-quick` | Quick lookup in popup (word/region) |
| `SPC a l` | Load buffer into session | Send whole buffer as context |
| `SPC a b` | Send whole buffer | Send entire buffer to AI |
| `SPC a R` | Refactor region | Refactor selected code |
| `SPC a e` | Quick explain | Explain selected code quickly |
| `SPC a p` | Proofread text | Fix grammar/spelling in selection |

### In gptel buffer:
- `C-c RET` - Send message
- `C-c C-c` - Open menu
- `C-c C-k` - Abort request

### Auto-completion (in programming modes):
- `M-TAB` or `C-c TAB` - Trigger completion

---

## 🎨 Using Presets

Presets let you switch AI behavior for specific tasks:

1. Open gptel menu: `SPC a m` or `C-c C-c`
2. Select "Preset" option
3. Choose from:
   - **coder** - Expert coding assistant (uses Claude Sonnet 4.5)
   - **explain** - Explain code to beginners
   - **refactor** - Code refactoring expert
   - **quick** - Quick, concise answers (uses fast Gemini Flash)
   - **docs** - Documentation writer

Or use `C-u SPC a s` to adjust settings on-the-fly!

---

## 🚀 Quick Start Workflows

### 1. Chat with AI
```
SPC a g          → Opens gptel buffer
Type question    → Write your prompt
C-c RET         → Send (or SPC a s)
```

### 2. Rewrite Code
```
1. Select code region (visual mode)
2. SPC a r
3. Type instruction: "Add error handling"
4. Review changes and accept
```

### 3. Add Context (Multi-file awareness)
```
1. Open reference file
2. SPC a c (adds buffer to context)
3. Open gptel: SPC a g
4. Now AI knows about the reference file!
```

### 4. Quick Explanations
```
1. Hover over word or select code
2. SPC a q
3. See explanation in popup!
```

### 5. Code Completion
```
Start typing code...
M-TAB           → Shows AI completion as ghost text
TAB             → Accept completion
```

---

## 🏠 Local Models with Ollama (Optional)

Want to run AI locally for privacy?

1. **Install Ollama:**
   ```bash
   # Linux
   curl -fsSL https://ollama.com/install.sh | sh

   # Start Ollama
   ollama serve
   ```

2. **Pull models:**
   ```bash
   ollama pull qwen2.5-coder:latest
   ollama pull mistral:latest
   ```

3. **Uncomment Ollama config in `ai.el`:**

   Look for the "Optional: Add Ollama" section around line 126 and uncomment:
   ```elisp
   (after! gptel
     (gptel-make-ollama "Ollama"
       :host "localhost:11434"
       :stream t
       :models '(qwen2.5-coder:latest
                 mistral:latest
                 llama3.2:latest)))
   ```

4. **To make Ollama default**, uncomment lines 136-141 as well

5. **Reload:** `doom sync`

6. **Switch backends:** `SPC a m` → Select "Backend" → Choose "Ollama"

---

## 🎯 Pro Tips

1. **Save conversations**: gptel uses org-mode by default, so just save the buffer!

2. **Switch models on-the-fly**: `C-u SPC a s` before sending

3. **Context management**:
   - Add files in Dired: Mark files → `SPC a c`
   - Remove context: `SPC a m` → Manage context

4. **Org-mode features**:
   - Each heading can be a separate conversation branch
   - Set properties: `M-x gptel-org-set-properties`
   - Set topic: `M-x gptel-org-set-topic`

5. **Custom instructions**: Use `SPC a r` on selected code and give specific instructions

6. **Programmatic use**: See helper functions at bottom of `ai.el` for examples

---

## 📚 Next Steps

1. **Secure your API key** (see section above)
2. **Run:** `doom sync` to install packages
3. **Restart Emacs**
4. **Try:** `SPC a g` to start chatting!
5. **Watch:** "Every LLM in Emacs, with gptel" video (17 min)

---

## 🐛 Troubleshooting

### Packages not loading?
```bash
doom sync
doom build
```

### Transient version error?
```elisp
;; Add to ai.el before gptel config:
(setq package-install-upgrade-built-in t)
```
Then: `M-x package-install RET transient RET`

### API key not working?
- Check `~/.authinfo.gpg` format
- Ensure proper encryption password
- Test: `(auth-source-pick-first-password :host "openrouter.ai")`

### Autocomplete not showing?
- Enable manually: `M-x gptel-autocomplete-mode`
- Check if in prog-mode buffer
- May need specific model configuration

---

## 📖 Resources

- [gptel GitHub](https://github.com/karthink/gptel)
- [gptel Manual](https://gptel.org/manual.html)
- [OpenRouter Docs](https://openrouter.ai/docs)
- [Ollama Models](https://ollama.com/library)

---

**Enjoy your AI-powered Emacs! 🎉**