htm 0.0.17 → 0.0.20

data/docs/getting-started/installation.md

@@ -8,7 +8,7 @@ Before installing HTM, ensure you have:
 
 - **Ruby 3.0 or higher** - HTM requires modern Ruby features
 - **PostgreSQL 17+** - For the database backend
-- **Ollama** - For generating vector embeddings (via RubyLLM)
+- **LLM Provider** - For generating embeddings and tags (Ollama is the default for local development, but OpenAI, Anthropic, Gemini, and others are also supported via RubyLLM)
 
 ### Check Your Ruby Version
 
@@ -103,24 +103,24 @@ CREATE EXTENSION IF NOT EXISTS pg_trgm;
 
 ```bash
 # Add to ~/.bashrc or your preferred config file
-export HTM_DBURL="postgres://username:password@localhost:5432/htm_db"
-export HTM_DBNAME="htm_db"
-export HTM_DBUSER="your_username"
-export HTM_DBPASS="your_password"
-export HTM_DBPORT="5432"
-export HTM_DBHOST="localhost"
+export HTM_DATABASE__URL="postgres://username:password@localhost:5432/htm_db"
+export HTM_DATABASE__NAME="htm_db"
+export HTM_DATABASE__USER="your_username"
+export HTM_DATABASE__PASSWORD="your_password"
+export HTM_DATABASE__PORT="5432"
+export HTM_DATABASE__HOST="localhost"
 
 # Load the configuration
 source ~/.bashrc
 ```
 
 !!! tip "Environment Configuration"
-    HTM automatically uses the `HTM_DBURL` environment variable if available. You can also pass database configuration directly to `HTM.new()`.
+    HTM automatically uses the `HTM_DATABASE__URL` environment variable if available. You can also pass database configuration directly to `HTM.new()`.
 
 Set environment variable:
 
 ```bash
-export HTM_DBURL="postgres://localhost/htm_db"
+export HTM_DATABASE__URL="postgres://localhost/htm_db"
 ```
 
 ## Step 3: Enable PostgreSQL Extensions
@@ -139,7 +139,7 @@ Test your database connection and verify extensions:
 cd /path/to/your/project
 ruby -e "
 require 'pg'
-conn = PG.connect(ENV['HTM_DBURL'])
+conn = PG.connect(ENV['HTM_DATABASE__URL'])
 result = conn.exec('SELECT extname, extversion FROM pg_extension ORDER BY extname')
 result.each { |row| puts \"✓ #{row['extname']}: Version #{row['extversion']}\" }
 conn.close
@@ -156,14 +156,29 @@ Expected output:
 !!! warning "Missing Extensions"
     If extensions are missing, you may need to install them. On Debian/Ubuntu: `sudo apt-get install postgresql-17-pgvector`. On macOS: `brew install pgvector`.
 
-## Step 4: Install Ollama
+## Step 4: Configure LLM Provider
 
-HTM uses [Ollama](https://ollama.ai/) via RubyLLM for generating vector embeddings.
+HTM uses RubyLLM to generate vector embeddings and extract tags. RubyLLM supports multiple providers, allowing you to choose what works best for your use case.
 
-### Install Ollama
+### Supported Providers
 
-#### macOS
+| Provider | Best For | API Key Required |
+|----------|----------|------------------|
+| **Ollama** (default) | Local development, privacy, no API costs | No |
+| **OpenAI** | Production, high-quality embeddings | Yes (`OPENAI_API_KEY`) |
+| **Anthropic** | Tag extraction with Claude models | Yes (`ANTHROPIC_API_KEY`) |
+| **Gemini** | Google Cloud integration | Yes (`GEMINI_API_KEY`) |
+| **Azure** | Enterprise Azure deployments | Yes (Azure credentials) |
+| **Bedrock** | AWS integration | Yes (AWS credentials) |
+| **DeepSeek** | Cost-effective alternative | Yes (`DEEPSEEK_API_KEY`) |
 
+### Option A: Ollama (Recommended for Local Development)
+
+Ollama runs locally with no API costs and keeps your data private.
+
+#### Install Ollama
+
+**macOS:**
 ```bash
 # Option 1: Direct download
 curl https://ollama.ai/install.sh | sh
@@ -172,17 +187,15 @@ curl https://ollama.ai/install.sh | sh
 brew install ollama
 ```
 
-#### Linux
-
+**Linux:**
 ```bash
 curl https://ollama.ai/install.sh | sh
 ```
 
-#### Windows
-
+**Windows:**
 Download the installer from [https://ollama.ai/download](https://ollama.ai/download)
 
-### Start Ollama Service
+#### Start Ollama Service
 
 ```bash
 # Ollama typically starts automatically
@@ -190,43 +203,68 @@ Download the installer from [https://ollama.ai/download](https://ollama.ai/downl
 curl http://localhost:11434/api/version
 ```
 
-Expected output:
+#### Pull Required Models
+
+```bash
+# Download embedding model
+ollama pull nomic-embed-text
+
+# Download tag extraction model
+ollama pull gemma3:latest
 
-```json
-{"version":"0.1.x"}
+# Verify models are available
+ollama list
 ```
 
-### Pull the gpt-oss Model
+#### Configure Environment (Optional)
 
-HTM uses the `gpt-oss` model by default:
+If Ollama is running on a different host or port:
 
 ```bash
-# Download the model
-ollama pull gpt-oss
-
-# Verify the model is available
-ollama list
+export OLLAMA_URL="http://custom-host:11434"
 ```
 
-You should see `gpt-oss` in the list.
+### Option B: OpenAI (Recommended for Production)
 
-### Test Embedding Generation
+OpenAI provides high-quality embeddings with simple API access.
 
 ```bash
-# Test that embeddings work
-ollama run gpt-oss "Hello, world!"
+# Set your API key
+export OPENAI_API_KEY="sk-..."
 ```
 
-### Custom Ollama URL (Optional)
+Configure HTM to use OpenAI:
 
-If Ollama is running on a different host or port:
+```ruby
+HTM.configure do |config|
+  config.embedding.provider = :openai
+  config.embedding.model = 'text-embedding-3-small'
+  config.tag.provider = :openai
+  config.tag.model = 'gpt-4o-mini'
+end
+```
+
+### Option C: Other Providers
+
+For Anthropic, Gemini, Azure, Bedrock, or DeepSeek, set the appropriate API key and configure HTM:
 
 ```bash
-export OLLAMA_URL="http://custom-host:11434"
+# Example: Anthropic
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Example: Gemini
+export GEMINI_API_KEY="..."
+```
+
+```ruby
+HTM.configure do |config|
+  config.tag.provider = :anthropic
+  config.tag.model = 'claude-3-haiku-20240307'
+end
 ```
 
-!!! tip "Ollama Model Selection"
-    HTM defaults to `gpt-oss`, but you can use any embedding model supported by Ollama. Just pass `embedding_model: 'your-model'` to `HTM.new()`.
+!!! tip "Mix and Match Providers"
+    You can use different providers for embeddings and tags. For example, use Ollama for local embedding generation and OpenAI for tag extraction.
 
 ## Step 5: Initialize HTM Database Schema
 
@@ -297,10 +335,9 @@ puts "Testing HTM Installation..."
 # Initialize HTM
 htm = HTM.new(
   robot_name: "Test Robot",
-  working_memory_size: 128_000,
-  embedding_service: :ollama,
-  embedding_model: 'gpt-oss'
+  working_memory_size: 128_000
 )
+# Uses configured provider, or defaults to Ollama
 
 puts "✓ HTM initialized successfully"
 puts "  Robot ID: #{htm.robot_id}"
@@ -352,12 +389,15 @@ HTM uses the following environment variables:
 
 | Variable | Description | Default | Required |
 |----------|-------------|---------|----------|
-| `HTM_DBURL` | PostgreSQL connection URL | - | Yes |
-| `HTM_DBNAME` | Database name | `htm_db` | No |
-| `HTM_DBUSER` | Database user | `postgres` | No |
-| `HTM_DBPASS` | Database password | - | No |
-| `HTM_DBPORT` | Database port | `5432` | No |
-| `OLLAMA_URL` | Ollama API URL | `http://localhost:11434` | No |
+| `HTM_DATABASE__URL` | PostgreSQL connection URL | - | Yes |
+| `HTM_DATABASE__NAME` | Database name | `htm_db` | No |
+| `HTM_DATABASE__USER` | Database user | `postgres` | No |
+| `HTM_DATABASE__PASSWORD` | Database password | - | No |
+| `HTM_DATABASE__PORT` | Database port | `5432` | No |
+| `OLLAMA_URL` | Ollama API URL (if using Ollama) | `http://localhost:11434` | No |
+| `OPENAI_API_KEY` | OpenAI API key (if using OpenAI) | - | No |
+| `ANTHROPIC_API_KEY` | Anthropic API key (if using Anthropic) | - | No |
+| `GEMINI_API_KEY` | Gemini API key (if using Gemini) | - | No |
 
 ### Example Configuration File
 
@@ -365,8 +405,13 @@ Create a configuration file for easy loading:
 
 ```bash
 # ~/.bashrc__htm
-export HTM_DBURL="postgres://user:pass@host:port/db?sslmode=require"
+export HTM_DATABASE__URL="postgres://user:pass@host:port/db?sslmode=require"
+# Ollama (for local development)
 export OLLAMA_URL="http://localhost:11434"
+
+# Or use cloud providers:
+# export OPENAI_API_KEY="sk-..."
+# export ANTHROPIC_API_KEY="sk-ant-..."
 ```
 
 Load it in your shell:
@@ -385,11 +430,11 @@ source ~/.bashrc__htm
 **Solutions**:
 
 ```bash
-# 1. Verify HTM_DBURL is set
-echo $HTM_DBURL
+# 1. Verify HTM_DATABASE__URL is set
+echo $HTM_DATABASE__URL
 
 # 2. Test connection manually
-psql $HTM_DBURL
+psql $HTM_DATABASE__URL
 
 # 3. Check if PostgreSQL is running (local installs)
 pg_ctl status
@@ -398,11 +443,11 @@ pg_ctl status
 # Ensure URL includes: ?sslmode=require
 ```
 
-### Ollama Connection Issues
+### LLM Provider Connection Issues
 
-**Error**: `Connection refused - connect(2) for localhost:11434`
+**Error**: `Connection refused` (Ollama) or `API key invalid` (cloud providers)
 
-**Solutions**:
+**Solutions for Ollama**:
 
 ```bash
 # 1. Check if Ollama is running
@@ -415,8 +460,19 @@ curl http://localhost:11434/api/version
 killall ollama
 ollama serve
 
-# 4. Verify gpt-oss model is installed
-ollama list | grep gpt-oss
+# 4. Verify embedding model is installed
+ollama list | grep nomic-embed-text
+```
+
+**Solutions for Cloud Providers**:
+
+```bash
+# Verify API key is set
+echo $OPENAI_API_KEY
+echo $ANTHROPIC_API_KEY
+
+# Test API connectivity
+curl https://api.openai.com/v1/models -H "Authorization: Bearer $OPENAI_API_KEY"
 ```
 
 ### Missing Extensions
@@ -433,7 +489,7 @@ make
 sudo make install
 
 # Enable in database
-psql $HTM_DBURL -c "CREATE EXTENSION IF NOT EXISTS pgvector;"
+psql $HTM_DATABASE__URL -c "CREATE EXTENSION IF NOT EXISTS pgvector;"
 ```
 
 ### Ruby Version Issues
@@ -462,7 +518,7 @@ ruby --version
 
 ```bash
 # Ensure your database user has necessary permissions
-psql $HTM_DBURL -c "
+psql $HTM_DATABASE__URL -c "
   GRANT ALL PRIVILEGES ON DATABASE your_db TO your_user;
   GRANT ALL ON ALL TABLES IN SCHEMA public TO your_user;
 "
@@ -491,7 +547,8 @@ If you encounter issues:
 
 ## Additional Resources
 
-- **Ollama Documentation**: [https://ollama.ai/](https://ollama.ai/)
+- **RubyLLM Documentation**: [https://rubyllm.com/](https://rubyllm.com/) - Multi-provider LLM interface
+- **Ollama Documentation**: [https://ollama.ai/](https://ollama.ai/) - Local LLM provider
+- **OpenAI API**: [https://platform.openai.com/docs/](https://platform.openai.com/docs/) - Cloud embeddings
 - **pgvector Documentation**: [https://github.com/pgvector/pgvector](https://github.com/pgvector/pgvector)
 - **PostgreSQL Documentation**: [https://www.postgresql.org/docs/](https://www.postgresql.org/docs/)
-- **RubyLLM Documentation**: [https://github.com/madbomber/ruby_llm](https://github.com/madbomber/ruby_llm)

data/docs/getting-started/quick-start.md

@@ -123,12 +123,13 @@ puts "=" * 60
 Create an HTM instance for your robot:
 
 ```ruby
-# Configure HTM globally (optional - uses Ollama by default)
+# Configure HTM globally (optional - defaults to Ollama for local development)
+# HTM uses RubyLLM which supports: :ollama, :openai, :anthropic, :gemini, :azure, :bedrock, :deepseek
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.embedding.provider = :ollama           # or :openai, etc.
+  config.embedding.model = 'nomic-embed-text'   # provider-specific model
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 # Initialize HTM with a robot name
@@ -336,12 +337,13 @@ require 'htm'
 puts "My First HTM Application"
 puts "=" * 60
 
-# Step 1: Configure and initialize HTM
+# Step 1: Configure and initialize HTM (optional - uses Ollama by default)
+# Supports: :ollama, :openai, :anthropic, :gemini, :azure, :bedrock, :deepseek
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'nomic-embed-text:latest'
-  config.tag_provider = :ollama
-  config.tag_model = 'gemma3:latest'
+  config.embedding.provider = :ollama
+  config.embedding.model = 'nomic-embed-text'
+  config.tag.provider = :ollama
+  config.tag.model = 'gemma3:latest'
 end
 
 htm = HTM.new(
@@ -520,10 +522,15 @@ htm = HTM.new(
   working_memory_size: 256_000  # 256k tokens
 )
 
-# Try different embedding models via configure
+# Try different providers or models
 HTM.configure do |config|
-  config.embedding_provider = :ollama
-  config.embedding_model = 'llama3:latest'  # Use Llama3
+  # Use OpenAI for production
+  config.embedding.provider = :openai
+  config.embedding.model = 'text-embedding-3-small'
+
+  # Or use Ollama locally with different model
+  # config.embedding.provider = :ollama
+  # config.embedding.model = 'mxbai-embed-large'
 end
 
 # Try different recall strategies
@@ -595,33 +602,43 @@ htm.remember(
 
 ## Troubleshooting Quick Start
 
-### Issue: "Connection refused" error
+### Issue: "Connection refused" error (Ollama)
 
 **Solution**: Make sure Ollama is running:
 
 ```bash
 curl http://localhost:11434/api/version
-# If this fails, start Ollama
+# If this fails, start Ollama with: ollama serve
+```
+
+### Issue: "API key invalid" error (cloud providers)
+
+**Solution**: Verify your API key is set:
+
+```bash
+echo $OPENAI_API_KEY  # or ANTHROPIC_API_KEY, GEMINI_API_KEY, etc.
 ```
 
 ### Issue: "Database connection failed"
 
-**Solution**: Verify your `HTM_DBURL` is set:
+**Solution**: Verify your `HTM_DATABASE__URL` is set:
 
 ```bash
-echo $HTM_DBURL
+echo $HTM_DATABASE__URL
 # Should show your connection string
 ```
 
 ### Issue: Embeddings taking too long
 
-**Solution**: Check Ollama's status and ensure the model is downloaded:
+**Solution for Ollama**: Check the model is downloaded:
 
 ```bash
 ollama list | grep nomic-embed-text
 # Should show nomic-embed-text model
 ```
 
+**Solution for cloud providers**: Check your internet connection and API status.
+
 ### Issue: Memory not found during recall
 
 **Solution**: Check your timeframe. If you just added a memory, use a recent timeframe: