ollama-client 0.2.4 → 0.2.6

data/docs/GETTING_STARTED.md

@@ -0,0 +1,361 @@
+# Getting Started: Creating an Ollama Client
+
+This guide shows you step-by-step how to create a client object to use all features of `ollama-client`.
+
+## Step 1: Install and Require the Gem
+
+### Option A: Using Bundler (Recommended)
+
+Add to your `Gemfile`:
+```ruby
+gem "ollama-client"
+```
+
+Then run:
+```bash
+bundle install
+```
+
+### Option B: Install Directly
+
+```bash
+gem install ollama-client
+```
+
+### Step 1b: Require in Your Code
+
+```ruby
+require "ollama_client"
+```
+
+The `.env` file is automatically loaded when you require the gem (if dotenv is available).
+
+---
+
+## Step 2: Create a Client Object
+
+You have several options depending on your needs:
+
+### Option A: Basic Client (Uses Defaults)
+
+```ruby
+require "ollama_client"
+
+# Simplest way - uses default configuration
+client = Ollama::Client.new
+
+# Defaults:
+# - base_url: "http://localhost:11434"
+# - model: "llama3.1:8b"
+# - timeout: 20 seconds
+# - retries: 2
+# - temperature: 0.2
+# - allow_chat: false
+# - streaming_enabled: false
+```
+
+### Option B: Client with Custom Configuration
+
+```ruby
+require "ollama_client"
+
+# Create config object
+config = Ollama::Config.new
+
+# Customize settings
+config.base_url = "http://localhost:11434"  # or your Ollama server URL
+config.model = "qwen2.5:14b"                # or your preferred model
+config.temperature = 0.1                    # Lower = more deterministic
+config.timeout = 60                         # Increase for complex schemas
+config.retries = 3                          # Number of retry attempts
+config.allow_chat = true                    # Enable chat API (if needed)
+config.streaming_enabled = true             # Enable streaming (if needed)
+
+# Create client with custom config
+client = Ollama::Client.new(config: config)
+```
+
+### Option C: Client from Environment Variables
+
+The gem automatically loads `.env` file. You can set these environment variables:
+
+```bash
+# In your .env file or shell environment
+OLLAMA_BASE_URL=http://localhost:11434
+OLLAMA_MODEL=qwen2.5:14b
+OLLAMA_TEMPERATURE=0.1
+```
+
+Then in your code:
+
+```ruby
+require "ollama_client"
+
+# Create config and read from environment
+config = Ollama::Config.new
+config.base_url = ENV["OLLAMA_BASE_URL"] if ENV["OLLAMA_BASE_URL"]
+config.model = ENV["OLLAMA_MODEL"] if ENV["OLLAMA_MODEL"]
+config.temperature = ENV["OLLAMA_TEMPERATURE"].to_f if ENV["OLLAMA_TEMPERATURE"]
+
+client = Ollama::Client.new(config: config)
+```
+
+### Option D: Client from JSON Config File
+
+Create a `config.json` file:
+
+```json
+{
+  "base_url": "http://localhost:11434",
+  "model": "llama3.1:8b",
+  "timeout": 30,
+  "retries": 3,
+  "temperature": 0.2,
+  "top_p": 0.9,
+  "num_ctx": 8192
+}
+```
+
+Then load it:
+
+```ruby
+require "ollama_client"
+
+config = Ollama::Config.load_from_json("config.json")
+client = Ollama::Client.new(config: config)
+```
+
+---
+
+## Step 3: Verify Your Client Works
+
+Test that your client can connect:
+
+```ruby
+require "ollama_client"
+
+client = Ollama::Client.new
+
+# List available models (verifies connection)
+begin
+  models = client.list_models
+  puts "✅ Connected! Available models: #{models.map { |m| m['name'] }.join(', ')}"
+rescue Ollama::Error => e
+  puts "❌ Connection failed: #{e.message}"
+  puts "   Make sure Ollama server is running at #{client.instance_variable_get(:@config).base_url}"
+end
+```
+
+---
+
+## Step 4: Use Client Features
+
+Once you have a client object, you can use all features:
+
+### 4.1: Generate (Structured Outputs) - Recommended for Agents
+
+```ruby
+client = Ollama::Client.new
+
+schema = {
+  "type" => "object",
+  "required" => ["action", "reasoning"],
+  "properties" => {
+    "action" => { "type" => "string", "enum" => ["search", "calculate", "finish"] },
+    "reasoning" => { "type" => "string" }
+  }
+}
+
+result = client.generate(
+  prompt: "Analyze the situation and decide next action.",
+  schema: schema
+)
+
+puts result["action"]      # => "search"
+puts result["reasoning"]    # => "User needs data..."
+```
+
+### 4.2: Generate (Plain Text)
+
+```ruby
+client = Ollama::Client.new
+
+# Use allow_plain_text: true to skip schema requirement
+response = client.generate(
+  prompt: "Explain Ruby blocks in one sentence.",
+  allow_plain_text: true
+)
+
+puts response  # => Plain text/markdown response (String)
+```
+
+### 4.3: Chat (Human-Facing Interfaces)
+
+```ruby
+# Enable chat in config
+config = Ollama::Config.new
+config.allow_chat = true
+client = Ollama::Client.new(config: config)
+
+response = client.chat(
+  messages: [
+    { role: "user", content: "Hello!" }
+  ],
+  allow_chat: true
+)
+
+puts response["message"]["content"]
+```
+
+### 4.4: ChatSession (Stateful Conversations)
+
+```ruby
+config = Ollama::Config.new
+config.allow_chat = true
+config.streaming_enabled = true
+client = Ollama::Client.new(config: config)
+
+observer = Ollama::StreamingObserver.new do |event|
+  print event.text if event.type == :token
+end
+
+chat = Ollama::ChatSession.new(
+  client,
+  system: "You are a helpful assistant.",
+  stream: observer
+)
+
+chat.say("Hello!")
+chat.say("Explain Ruby blocks")
+```
+
+### 4.5: Planner Agent (Schema-Based Planning)
+
+```ruby
+client = Ollama::Client.new
+
+planner = Ollama::Agent::Planner.new(
+  client,
+  system_prompt: Ollama::Personas.get(:architect, variant: :agent)
+)
+
+# Define the decision schema
+DECISION_SCHEMA = {
+  "type" => "object",
+  "required" => ["action", "reasoning"],
+  "properties" => {
+    "action" => {
+      "type" => "string",
+      "enum" => ["refactor", "test", "document", "defer"]
+    },
+    "reasoning" => {
+      "type" => "string"
+    }
+  }
+}
+
+plan = planner.run(
+  prompt: "Design a caching layer for a high-traffic API.",
+  schema: DECISION_SCHEMA
+)
+
+puts plan["action"]      # => "refactor" (or one of the enum values)
+puts plan["reasoning"]    # => Explanation string
+```
+
+### 4.6: Executor Agent (Tool-Calling)
+
+```ruby
+client = Ollama::Client.new
+
+# Define tools (copy-paste ready)
+tools = {
+  "get_price" => ->(symbol:) { { symbol: symbol, price: 24500.50, volume: 1_000_000 } },
+  "get_indicators" => ->(symbol:) { { symbol: symbol, rsi: 65.5, macd: 1.2 } }
+}
+
+executor = Ollama::Agent::Executor.new(client, tools: tools)
+
+answer = executor.run(
+  system: Ollama::Personas.get(:trading, variant: :agent),
+  user: "Analyze NIFTY. Get current price and technical indicators."
+)
+
+puts answer
+```
+
+### 4.7: Embeddings
+
+```ruby
+client = Ollama::Client.new
+
+embedding = client.embeddings.embed(
+  model: "all-minilm",
+  input: "What is Ruby?"
+)
+
+puts embedding.length  # => Array of floats
+```
+
+---
+
+## Complete Example: From Zero to Working Client
+
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Step 1: Require the gem
+require "ollama_client"
+
+# Step 2: Create client (using environment variables from .env)
+config = Ollama::Config.new
+config.base_url = ENV["OLLAMA_BASE_URL"] || "http://localhost:11434"
+config.model = ENV["OLLAMA_MODEL"] || "llama3.1:8b"
+config.temperature = ENV["OLLAMA_TEMPERATURE"].to_f if ENV["OLLAMA_TEMPERATURE"]
+
+client = Ollama::Client.new(config: config)
+
+# Step 3: Use the client
+begin
+  result = client.generate(
+    prompt: "Return a JSON object with a 'greeting' field saying hello.",
+    schema: {
+      "type" => "object",
+      "required" => ["greeting"],
+      "properties" => {
+        "greeting" => { "type" => "string" }
+      }
+    }
+  )
+  
+  puts "✅ Success!"
+  puts "Response: #{result['greeting']}"
+rescue Ollama::Error => e
+  puts "❌ Error: #{e.message}"
+end
+```
+
+---
+
+## Configuration Options Reference
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `base_url` | `"http://localhost:11434"` | Ollama server URL |
+| `model` | `"llama3.1:8b"` | Default model to use |
+| `timeout` | `20` | Request timeout in seconds |
+| `retries` | `2` | Number of retry attempts on failure |
+| `temperature` | `0.2` | Model temperature (0.0-2.0) |
+| `top_p` | `0.9` | Top-p sampling parameter |
+| `num_ctx` | `8192` | Context window size |
+| `allow_chat` | `false` | Enable chat API (must be explicitly enabled) |
+| `streaming_enabled` | `false` | Enable streaming support |
+
+---
+
+## Next Steps
+
+- See [README.md](../README.md) for detailed API documentation
+- See [PERSONAS.md](PERSONAS.md) for using personas
+- See [examples/](../examples/) for complete working examples

data/docs/INTEGRATION_TESTING.md

@@ -0,0 +1,170 @@
+# Integration Testing Guide
+
+Integration tests make **actual calls** to a running Ollama server to verify the client works end-to-end with real models.
+
+## Quick Start
+
+```bash
+# Run all integration tests (requires Ollama server running)
+bundle exec rspec --tag integration
+
+# Run with custom configuration
+OLLAMA_URL=http://localhost:11434 \
+OLLAMA_MODEL=llama3.1:8b \
+bundle exec rspec --tag integration
+```
+
+## Prerequisites
+
+1. **Ollama server running** (default: `http://localhost:11434`)
+   ```bash
+   # Start Ollama server
+   ollama serve
+   ```
+
+2. **At least one model installed**
+   ```bash
+   # Install a model
+   ollama pull llama3.1:8b
+   ```
+
+3. **Optional: Embedding model** (for embedding tests)
+   ```bash
+   ollama pull nomic-embed-text
+   ```
+
+## Test Coverage
+
+Integration tests verify:
+
+### ✅ Core Client Methods
+- `#list_models` - Lists available models
+- `#generate` - Structured JSON output with schema
+- `#generate` - Plain text output without schema
+- `#generate` - Complex schemas with enums
+- `#chat_raw` - Chat messages and responses
+- `#chat_raw` - Conversation history
+- `#chat_raw` - Tool calling (if model supports it)
+
+### ✅ Embeddings
+- Single text embeddings
+- Multiple text embeddings
+- Error handling for missing/unsupported models
+
+### ✅ Agent Components
+- `Ollama::Agent::Planner` - Planning decisions
+- `Ollama::Agent::Executor` - Tool execution loops (if model supports tools)
+
+### ✅ Chat Session
+- Session management
+- Conversation state
+- Message history
+
+### ✅ Error Handling
+- `NotFoundError` for non-existent models
+- Proper error propagation
+
+## Running Tests
+
+### Run All Integration Tests
+```bash
+bundle exec rspec --tag integration
+```
+
+### Run Specific Test File
+```bash
+bundle exec rspec spec/integration/ollama_client_integration_spec.rb --tag integration
+```
+
+### Run Specific Test
+```bash
+bundle exec rspec spec/integration/ollama_client_integration_spec.rb:32 --tag integration
+```
+
+### With Environment Variables
+```bash
+# Custom Ollama URL
+OLLAMA_URL=http://remote-server:11434 bundle exec rspec --tag integration
+
+# Custom model
+OLLAMA_MODEL=llama3.2:3b bundle exec rspec --tag integration
+
+# Custom embedding model
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text bundle exec rspec --tag integration
+
+# All together
+OLLAMA_URL=http://localhost:11434 \
+OLLAMA_MODEL=llama3.1:8b \
+OLLAMA_EMBEDDING_MODEL=nomic-embed-text \
+bundle exec rspec --tag integration
+```
+
+## Test Behavior
+
+### Automatic Skipping
+- Tests automatically skip if Ollama server is not available
+- Tests skip if required models are not installed
+- Tests skip if models don't support certain features (e.g., tool calling)
+
+### Expected Results
+- **Passing**: Client correctly communicates with Ollama
+- **Pending/Skipped**: Expected when models/features unavailable
+- **Failing**: Indicates actual client issues (rare)
+
+## Differences from Unit Tests
+
+| Aspect | Unit Tests | Integration Tests |
+|--------|-----------|-------------------|
+| **HTTP Calls** | Mocked (WebMock) | Real HTTP calls |
+| **Ollama Server** | Not required | Required |
+| **Speed** | Fast (~0.1s) | Slower (~15s) |
+| **Reliability** | 100% deterministic | Depends on server/model |
+| **Coverage** | Transport layer | End-to-end |
+| **Run Command** | `bundle exec rspec` | `bundle exec rspec --tag integration` |
+
+## Best Practices
+
+1. **Run unit tests first** - Ensure client code is correct
+2. **Run integration tests** - Verify real server communication
+3. **Use appropriate models** - Some models support tools, others don't
+4. **Handle skips gracefully** - Missing models/features are expected
+5. **Check server availability** - Tests skip if Ollama is down
+
+## Troubleshooting
+
+### "Ollama server not available"
+- Start Ollama: `ollama serve`
+- Check URL: `OLLAMA_URL=http://localhost:11434`
+- Verify connection: `curl http://localhost:11434/api/tags`
+
+### "Model not found"
+- Install model: `ollama pull llama3.1:8b`
+- Set model: `OLLAMA_MODEL=your-model`
+
+### "Empty embedding returned"
+- Install embedding model: `ollama pull nomic-embed-text`
+- Verify model supports embeddings
+- Set model: `OLLAMA_EMBEDDING_MODEL=nomic-embed-text`
+
+### "HTTP 400: Bad Request" (tool calling)
+- Some models don't support tool calling
+- Test will skip automatically
+- Try a different model that supports tools
+
+## CI/CD Integration
+
+Integration tests are **optional** and can be run separately:
+
+```yaml
+# Example GitHub Actions
+- name: Run Unit Tests
+  run: bundle exec rspec
+
+- name: Run Integration Tests (if Ollama available)
+  run: bundle exec rspec --tag integration
+  if: env.OLLAMA_URL != ''
+```
+
+## Summary
+
+Integration tests verify the client works with **real Ollama servers** and **real models**. They complement unit tests by ensuring end-to-end functionality while gracefully handling missing models or unsupported features.

data/docs/NEXT_STEPS_SUMMARY.md

@@ -0,0 +1,114 @@
+# Next Steps Summary
+
+## ✅ Completed
+
+### 1. Testing Documentation
+- ✅ **Rewrote `docs/TESTING.md`** - Focuses on client-only testing (transport/protocol, not agent behavior)
+- ✅ **Created `docs/TEST_CHECKLIST.md`** - Comprehensive checklist with test categories (G1-G3, C1-C3, A1-A2, F1-F3)
+
+### 2. Example Reorganization
+- ✅ **Created `docs/EXAMPLE_REORGANIZATION.md`** - Complete proposal for separating examples
+- ✅ **Created `docs/MIGRATION_CHECKLIST.md`** - Detailed migration tracking
+
+### 3. Minimal Examples Created
+- ✅ **`examples/basic_generate.rb`** - Basic `/generate` usage with schema
+- ✅ **`examples/basic_chat.rb`** - Basic `/chat` usage
+- ✅ **`examples/tool_calling_parsing.rb`** - Tool-call parsing (no execution)
+
+### 4. Documentation Updates
+- ✅ **Updated `examples/README.md`** - Reflects minimal examples only
+- ✅ **Updated main `README.md`** - Enhanced "What This Gem IS NOT" section, updated examples section
+- ✅ **Updated all repository links** - Point to `shubhamtaywade82/ollama-agent-examples`
+
+## 📋 Remaining Tasks
+
+### Phase 2: Create Separate Repository
+
+**Action Required:** Set up the `ollama-agent-examples` repository structure
+
+1. Repository: https://github.com/shubhamtaywade82/ollama-agent-examples
+2. Initialize with README that links back to `ollama-client`
+4. Set up repository structure:
+   ```
+   ollama-agent-examples/
+   ├── README.md
+   ├── basic/
+   ├── trading/
+   │   └── dhanhq/
+   ├── coding/
+   ├── rag/
+   ├── advanced/
+   └── tools/
+   ```
+
+### Phase 3: Migrate Examples
+
+**Files to Move:** (See `docs/MIGRATION_CHECKLIST.md` for complete list)
+
+- All files in `examples/dhanhq/` directory
+- `dhan_console.rb`, `dhanhq_agent.rb`, `dhanhq_tools.rb`
+- `multi_step_agent_*.rb` files
+- `advanced_*.rb` files
+- `test_tool_calling.rb`, `tool_calling_direct.rb`, `tool_calling_pattern.rb`
+- `chat_console.rb`, `chat_session_example.rb`, `ollama_chat.rb`
+- `complete_workflow.rb`, `structured_outputs_chat.rb`, `personas_example.rb`
+- `structured_tools.rb`
+- `ollama-api.md` (if example-related)
+
+**Files to Keep:**
+- ✅ `basic_generate.rb`
+- ✅ `basic_chat.rb`
+- ✅ `tool_calling_parsing.rb`
+- ✅ `tool_dto_example.rb`
+
+### Phase 4: Clean Up
+
+1. Remove moved examples from `ollama-client/examples/`
+2. Verify minimal examples work
+3. Update any CI/CD that references examples
+4. Test migrated examples in new location
+
+## 📚 Documentation Created
+
+1. **`docs/TESTING.md`** - Client-only testing guide
+2. **`docs/TEST_CHECKLIST.md`** - Test checklist with categories
+3. **`docs/EXAMPLE_REORGANIZATION.md`** - Example reorganization proposal
+4. **`docs/MIGRATION_CHECKLIST.md`** - Migration tracking checklist
+5. **`docs/NEXT_STEPS_SUMMARY.md`** - This file
+
+## 🎯 Key Principles Established
+
+### Testing Boundaries
+- ✅ Test transport layer only
+- ✅ Test protocol correctness
+- ✅ Test schema enforcement
+- ✅ Test tool-call parsing
+- ❌ Do NOT test agent loops, tool execution, convergence logic
+
+### Example Boundaries
+- ✅ Keep minimal client usage examples
+- ✅ Focus on transport/protocol demonstration
+- ❌ Move all agent behavior examples
+- ❌ Move all tool execution examples
+- ❌ Move all domain-specific examples
+
+## 🔗 Repository Links
+
+- **Main Repository:** https://github.com/shubhamtaywade82/ollama-client
+- **Examples Repository:** https://github.com/shubhamtaywade82/ollama-agent-examples
+
+## 📝 Next Actions
+
+1. **Set up `ollama-agent-examples` repository** structure
+2. **Copy agent examples** to new repository
+3. **Organize examples** by category (trading, coding, rag, advanced, tools)
+4. **Remove migrated examples** from `ollama-client`
+5. **Test everything** works in both repositories
+
+## ✨ Benefits Achieved
+
+- ✅ Clear separation of concerns
+- ✅ Client stays focused on transport layer
+- ✅ Examples can evolve independently
+- ✅ Users won't confuse client vs agent
+- ✅ Easier maintenance and contribution