aia 0.9.15 → 0.9.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acca553714c1fe19ed2a152a5ca500691d0435817369e60a1d773b9996d02802
-  data.tar.gz: f97fd1bc43cf1d8d1a8d2364313ad59a89462c31b71648c28828faa3ddc36ab9
+  metadata.gz: ae5c7e9497837763b36226f8fc44aeb7dffe692c964e450938ff83aea043c10a
+  data.tar.gz: b839a219cb3f6e5b34d9aa02ff7f3ced77ff039816b6b2a3d9ef79076d32c302
 SHA512:
-  metadata.gz: 3b54ffdbcc2268e9a509f4c144182249c2d02cc520b0f1f37d7ebe8a4e79400cd2e23a96f77660019c5fb205a0bdf5df8eff14c3809f24c58886aee1fbde306f
-  data.tar.gz: 57a0a68ddedd0bdd69a5f25802cb9a09f8c300829d2e48c2f6025147eae3b29c861d47004614dc33108cf3a403605ee98ad9c0c239aae47e05afb8def40fb738
+  metadata.gz: 7df6fe4bbf0fd2ce33b9827390340d3cf1f8fd5ad5b4f52ceb343769dee6d699ab87c5dd2686472cd480bf5ac1e20b612f5c69e70b72eab68735560601423d7c
+  data.tar.gz: 9fa99822319f6e3ff213f62ba0c26121c045e4fa96035596df46b4d723df72cecb19c1abb98f760e6b435941a3cc9b869f6401da771452c3d226930b4f4ea104

data/.version

@@ -1 +1 @@
-0.9.15
+0.9.17

data/CHANGELOG.md

@@ -1,5 +1,67 @@
 # Changelog
 ## [Unreleased]
+
+### [0.9.17] 2025-10-04
+
+#### New Features
+- **NEW FEATURE**: Enhanced local model support with comprehensive validation and error handling
+- **NEW FEATURE**: Added `lms/` prefix support for LM Studio models with automatic validation against loaded models
+- **NEW FEATURE**: Enhanced `//models` directive to auto-detect and display local providers (Ollama and LM Studio)
+- **NEW FEATURE**: Added model name prefix display in error messages for LM Studio (`lms/` prefix)
+
+#### Improvements
+- **ENHANCEMENT**: Improved LM Studio integration with model validation against `/v1/models` endpoint
+- **ENHANCEMENT**: Enhanced error messages showing exact model names with correct prefixes when validation fails
+- **ENHANCEMENT**: Added environment variable support for custom LM Studio API base (`LMS_API_BASE`)
+- **ENHANCEMENT**: Improved `//models` directive output formatting for local models with size and modified date for Ollama
+- **ENHANCEMENT**: Enhanced multi-model support to seamlessly mix local and cloud models
+
+#### Documentation
+- **DOCUMENTATION**: Added comprehensive local model documentation to README.md
+- **DOCUMENTATION**: Created new docs/guides/local-models.md guide covering Ollama and LM Studio setup, usage, and troubleshooting
+- **DOCUMENTATION**: Updated docs/guides/models.md with local provider sections including comparison table and workflow examples
+- **DOCUMENTATION**: Enhanced docs/faq.md with 5 new FAQ entries covering local model usage, differences, and error handling
+
+#### Technical Changes
+- Enhanced RubyLLMAdapter with LM Studio model validation (lib/aia/ruby_llm_adapter.rb)
+- Updated models directive to query local provider endpoints (lib/aia/directives/models.rb)
+- Added provider_fix extension for RubyLLM compatibility (lib/extensions/ruby_llm/provider_fix.rb)
+- Added comprehensive test coverage with 22 new tests for local providers
+- Updated dependencies: ruby_llm, webmock, crack, rexml
+- Bumped Ruby bundler version to 2.7.2
+
+#### Bug Fixes
+- **BUG FIX**: Fixed missing `lms/` prefix in LM Studio model listings
+- **BUG FIX**: Fixed model validation error messages to show usable model names with correct prefixes
+- **BUG FIX**: Fixed Ollama endpoint to use native API (removed incorrect `/v1` suffix)
+
+#### Usage Examples
+```bash
+# Use LM Studio with validation
+aia --model lms/qwen/qwen3-coder-30b my_prompt
+
+# Use Ollama
+aia --model ollama/llama3.2 --chat
+
+# Mix local and cloud models
+aia --model ollama/llama3.2,gpt-4o-mini,claude-3-sonnet my_prompt
+
+# List available local models
+aia --model ollama/llama3.2 --chat
+> //models
+```
+
+### [0.9.16] 2025-09-26
+
+#### New Features
+- **NEW FEATURE**: Added support for Ollama AI provider
+- **NEW FEATURE**: Added support for Osaurus AI provider
+- **NEW FEATURE**: Added support for LM Studio AI provider
+
+#### Improvements
+- **ENHANCEMENT**: Expanded AI provider ecosystem with three new local/self-hosted model options
+- **ENHANCEMENT**: Improved flexibility for users preferring local LLM deployments
+
 ## Released
 ### [0.9.15] 2025-09-21
 

data/README.md

@@ -563,6 +563,83 @@ Model Details:
 - **Error Handling**: Invalid models are reported but don't prevent valid models from working
 - **Batch Mode Support**: Multi-model responses are properly formatted in output files
 
+### Local Model Support
+
+AIA supports running local AI models through Ollama and LM Studio, providing privacy, offline capability, and cost savings.
+
+#### Ollama Integration
+
+[Ollama](https://ollama.ai) runs AI models locally on your machine.
+
+```bash
+# Install Ollama (macOS)
+brew install ollama
+
+# Pull a model
+ollama pull llama3.2
+
+# Use with AIA - prefix model name with 'ollama/'
+aia --model ollama/llama3.2 my_prompt
+
+# In chat mode
+aia --chat --model ollama/llama3.2
+
+# Combine with cloud models
+aia --model ollama/llama3.2,gpt-4o-mini --consensus my_prompt
+```
+
+**Environment Variables:**
+```bash
+# Optional: Set custom Ollama API endpoint
+export OLLAMA_API_BASE=http://localhost:11434
+```
+
+#### LM Studio Integration
+
+[LM Studio](https://lmstudio.ai) provides a desktop application for running local models with an OpenAI-compatible API.
+
+```bash
+# 1. Install LM Studio from lmstudio.ai
+# 2. Download and load a model in LM Studio
+# 3. Start the local server in LM Studio
+
+# Use with AIA - prefix model name with 'lms/'
+aia --model lms/qwen/qwen3-coder-30b my_prompt
+
+# In chat mode
+aia --chat --model lms/your-model-name
+
+# Mix local and cloud models
+aia --model lms/local-model,gpt-4o-mini my_prompt
+```
+
+**Environment Variables:**
+```bash
+# Optional: Set custom LM Studio API endpoint (default: http://localhost:1234/v1)
+export LMS_API_BASE=http://localhost:1234/v1
+```
+
+#### Listing Local Models
+
+The `//models` directive automatically detects local providers and queries their endpoints:
+
+```bash
+# In a prompt file or chat session
+//models
+
+# Output will show:
+# - Ollama models from http://localhost:11434/api/tags
+# - LM Studio models from http://localhost:1234/v1/models
+# - Cloud models from RubyLLM database
+```
+
+**Benefits of Local Models:**
+- 🔒 **Privacy**: No data sent to external servers
+- 💰 **Cost**: Zero API costs after initial setup
+- 🚀 **Speed**: No network latency
+- 📡 **Offline**: Works without internet connection
+- 🔧 **Control**: Full control over model and parameters
+
 ### Shell Integration
 
 AIA automatically processes shell patterns in prompts:

data/docs/faq.md

@@ -23,7 +23,89 @@ export ANTHROPIC_API_KEY="your_key_here"
 ```
 
 ### Q: Can I use AIA without internet access?
-**A:** Yes, if you use local models through Ollama. Most AI models require internet access, but you can run models locally for offline use.
+**A:** Yes! AIA supports two local model providers for complete offline operation:
+
+1. **Ollama**: Run open-source models locally
+   ```bash
+   # Install and use Ollama
+   brew install ollama
+   ollama pull llama3.2
+   aia --model ollama/llama3.2 --chat
+   ```
+
+2. **LM Studio**: GUI-based local model runner
+   ```bash
+   # Download from https://lmstudio.ai
+   # Load a model and start local server
+   aia --model lms/your-model-name --chat
+   ```
+
+Both options provide full AI functionality without internet connection, perfect for:
+- 🔒 Private/sensitive data processing
+- ✈️ Offline/travel use
+- 💰 Zero API costs
+- 🏠 Air-gapped environments
+
+### Q: How do I list available local models?
+**A:** Use the `//models` directive in a chat session or prompt:
+
+```bash
+# Start chat with any local model
+aia --model ollama/llama3.2 --chat
+
+# In the chat session
+> //models
+
+# Output shows:
+# - Ollama models from local installation
+# - LM Studio models currently loaded
+# - Cloud models from RubyLLM database
+```
+
+For Ollama specifically: `ollama list`
+For LM Studio: Check the Models tab in the LM Studio GUI
+
+### Q: What's the difference between Ollama and LM Studio?
+**A:**
+- **Ollama**: Command-line focused, quick model switching, multiple models available
+- **LM Studio**: GUI application, visual model management, one model at a time
+
+Choose **Ollama** if you prefer CLI tools and automation.
+Choose **LM Studio** if you want a visual interface and easier model discovery.
+
+Both work great with AIA!
+
+### Q: Can I mix local and cloud models?
+**A:** Absolutely! This is a powerful feature:
+
+```bash
+# Compare local vs cloud responses
+aia --model ollama/llama3.2,gpt-4o-mini my_prompt
+
+# Get consensus across local and cloud models
+aia --model ollama/mistral,lms/qwen-coder,claude-3-sonnet --consensus decision
+
+# Use local for drafts, cloud for refinement
+aia --model ollama/llama3.2 --out_file draft.md initial_analysis
+aia --model gpt-4 --include draft.md final_report
+```
+
+### Q: Why does my lms/ model show an error?
+**A:** Common causes:
+
+1. **Model not loaded in LM Studio**: Load a model first
+2. **Wrong model name**: AIA validates against available models and shows the exact names to use
+3. **Server not running**: Start the local server in LM Studio
+4. **Wrong prefix**: Always use `lms/` prefix with full model name
+
+If you get an error, AIA will show you the exact model names to use:
+```
+❌ 'wrong-name' is not a valid LM Studio model.
+
+Available LM Studio models:
+  - lms/qwen/qwen3-coder-30b
+  - lms/llama-3.2-3b-instruct
+```
 
 ## Basic Usage
 

data/docs/guides/local-models.md

@@ -0,0 +1,304 @@
+# Local Models Guide
+
+Complete guide to using Ollama and LM Studio with AIA for local AI processing.
+
+## Why Use Local Models?
+
+### Benefits
+
+- 🔒 **Privacy**: All processing happens on your machine
+- 💰 **Cost**: No API fees
+- 🚀 **Speed**: No network latency
+- 📡 **Offline**: Works without internet
+- 🔧 **Control**: Choose exact model and parameters
+- 📦 **Unlimited**: No rate limits or quotas
+
+### Use Cases
+
+- Processing confidential business data
+- Working with personal information
+- Development and testing
+- High-volume batch processing
+- Air-gapped environments
+- Learning and experimentation
+
+## Ollama Setup
+
+### Installation
+
+```bash
+# macOS
+brew install ollama
+
+# Linux
+curl -fsSL https://ollama.ai/install.sh | sh
+
+# Windows
+# Download installer from https://ollama.ai
+```
+
+### Model Management
+
+```bash
+# List available models
+ollama list
+
+# Pull new models
+ollama pull llama3.2
+ollama pull mistral
+ollama pull codellama
+
+# Remove models
+ollama rm model-name
+
+# Show model info
+ollama show llama3.2
+```
+
+### Using with AIA
+
+```bash
+# Basic usage - prefix with 'ollama/'
+aia --model ollama/llama3.2 my_prompt
+
+# Chat mode
+aia --chat --model ollama/mistral
+
+# Batch processing
+for file in *.md; do
+  aia --model ollama/llama3.2 summarize "$file"
+done
+```
+
+### Recommended Ollama Models
+
+#### General Purpose
+- `llama3.2` - Versatile, good quality
+- `llama3.2:70b` - Higher quality, slower
+- `mistral` - Fast, efficient
+
+#### Code
+- `qwen2.5-coder` - Excellent for code
+- `codellama` - Code-focused
+- `deepseek-coder` - Programming tasks
+
+#### Specialized
+- `mixtral` - High performance
+- `phi3` - Small, efficient
+- `gemma2` - Google's open model
+
+## LM Studio Setup
+
+### Installation
+
+1. Download from https://lmstudio.ai
+2. Install the application
+3. Launch LM Studio
+
+### Model Management
+
+1. Click "🔍 Search" tab
+2. Browse or search for models
+3. Click download button
+4. Wait for download to complete
+
+### Starting Local Server
+
+1. Click "💻 Local Server" tab
+2. Select loaded model from dropdown
+3. Click "Start Server"
+4. Note the endpoint (default: http://localhost:1234/v1)
+
+### Using with AIA
+
+```bash
+# Prefix model name with 'lms/'
+aia --model lms/qwen/qwen3-coder-30b my_prompt
+
+# Chat mode
+aia --chat --model lms/llama-3.2-3b-instruct
+
+# AIA validates model names
+# Error shows available models if name is wrong
+```
+
+### Popular LM Studio Models
+
+- `lmsys/vicuna-7b` - Conversation
+- `TheBloke/Llama-2-7B-Chat-GGUF` - Chat
+- `TheBloke/CodeLlama-7B-GGUF` - Code
+- `qwen/qwen3-coder-30b` - Advanced coding
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Ollama custom endpoint
+export OLLAMA_API_BASE=http://localhost:11434
+
+# LM Studio custom endpoint
+export LMS_API_BASE=http://localhost:1234/v1
+```
+
+### Config File
+
+```yaml
+# ~/.aia/config.yml
+model: ollama/llama3.2
+
+# Or for LM Studio
+model: lms/qwen/qwen3-coder-30b
+```
+
+### In Prompts
+
+```
+//config model = ollama/mistral
+//config temperature = 0.7
+
+Your prompt here...
+```
+
+## Listing Models
+
+### In Chat Session
+
+```bash
+aia --model ollama/llama3.2 --chat
+> //models
+```
+
+**Ollama Output:**
+```
+Local LLM Models:
+
+Ollama Models (http://localhost:11434):
+------------------------------------------------------------
+- ollama/llama3.2:latest (size: 2.0 GB, modified: 2024-10-01)
+- ollama/mistral:latest (size: 4.1 GB, modified: 2024-09-28)
+
+2 Ollama model(s) available
+```
+
+**LM Studio Output:**
+```
+Local LLM Models:
+
+LM Studio Models (http://localhost:1234/v1):
+------------------------------------------------------------
+- lms/qwen/qwen3-coder-30b
+- lms/llama-3.2-3b-instruct
+
+2 LM Studio model(s) available
+```
+
+## Advanced Usage
+
+### Mixed Local/Cloud Models
+
+```bash
+# Compare local and cloud responses
+aia --model ollama/llama3.2,gpt-4o-mini,claude-3-sonnet analysis_prompt
+
+# Get consensus
+aia --model ollama/llama3.2,ollama/mistral,gpt-4 --consensus decision_prompt
+```
+
+### Local-First Workflow
+
+```bash
+# 1. Process with local model (private)
+aia --model ollama/llama3.2 --out_file draft.md sensitive_data.txt
+
+# 2. Review and sanitize draft.md manually
+
+# 3. Polish with cloud model
+aia --model gpt-4 --include draft.md final_output
+```
+
+### Cost Optimization
+
+```bash
+# Bulk tasks with local model
+for i in {1..1000}; do
+  aia --model ollama/mistral --out_file "result_$i.md" process "input_$i.txt"
+done
+
+# No API costs!
+```
+
+## Troubleshooting
+
+### Ollama Issues
+
+**Problem:** "Cannot connect to Ollama"
+```bash
+# Check if Ollama is running
+ollama list
+
+# Start Ollama service (if needed)
+ollama serve
+```
+
+**Problem:** "Model not found"
+```bash
+# List installed models
+ollama list
+
+# Pull missing model
+ollama pull llama3.2
+```
+
+### LM Studio Issues
+
+**Problem:** "Cannot connect to LM Studio"
+1. Ensure LM Studio is running
+2. Check local server is started
+3. Verify endpoint in settings
+
+**Problem:** "Model validation failed"
+- Check exact model name in LM Studio
+- Ensure model is loaded (not just downloaded)
+- Use full model path with `lms/` prefix
+
+**Problem:** "Model not listed"
+1. Load model in LM Studio
+2. Start local server
+3. Run `//models` directive
+
+### Performance Issues
+
+**Slow responses:**
+- Use smaller models (7B instead of 70B)
+- Reduce max_tokens
+- Check system resources (CPU/RAM/GPU)
+
+**High memory usage:**
+- Close other applications
+- Use quantized models (Q4, Q5)
+- Try smaller model variants
+
+## Best Practices
+
+### Security
+✅ Keep local models for sensitive data
+✅ Use cloud models for general tasks
+✅ Review outputs before sharing externally
+
+### Performance
+✅ Use appropriate model size for task
+✅ Leverage GPU if available
+✅ Cache common responses
+
+### Cost Management
+✅ Use local models for development/testing
+✅ Use local models for high-volume processing
+✅ Reserve cloud models for critical tasks
+
+## Related Documentation
+
+- [Models Guide](models.md)
+- [Configuration](../configuration.md)
+- [Chat Mode](chat.md)
+- [CLI Reference](../cli-reference.md)