ollama-client 0.2.2 → 0.2.4

data/docs/GET_RUBYGEMS_SECRET.md

@@ -0,0 +1,151 @@
+# How to Get Your RubyGems OTP Secret
+
+## The Problem
+
+You need the **OTP secret key** from RubyGems, not the 6-digit codes from your authenticator app.
+
+## What It Looks Like
+
+```
+Example: JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP
+
+✅ Valid format:
+- All UPPERCASE letters A-Z
+- Numbers 2-7 only
+- Usually 16-32 characters
+- No spaces, dashes, underscores, or special characters
+
+❌ This is NOT it:
+- 123456 (that's the OTP code, not the secret)
+- abc123_secret (contains invalid characters)
+- YOUR_SECRET_HERE (that's a placeholder!)
+```
+
+## Step-by-Step: Get Your Secret
+
+### Method 1: Find Existing Secret (If Saved)
+
+When you first enabled MFA on RubyGems, it showed you a QR code and a secret key. If you saved that secret key, use it!
+
+Check these places:
+- Password manager (1Password, LastPass, Bitwarden, etc.)
+- Notes app
+- Screenshot of the QR code setup page
+
+### Method 2: Regenerate MFA on RubyGems
+
+If you can't find the original secret, regenerate it:
+
+#### Step 1: Log in to RubyGems
+Go to https://rubygems.org
+
+#### Step 2: Go to MFA Settings
+1. Click your profile picture/name (top right)
+2. Click **Edit Profile**
+3. Click **Multi-factor Authentication** (left sidebar)
+
+#### Step 3: Regenerate MFA
+1. Click **"Disable Multi-factor Authentication"**
+2. Confirm disabling
+3. Click **"Enable Multi-factor Authentication"** again
+4. You'll see a QR code and the **secret key** text
+
+#### Step 4: Save the Secret
+```
+IMPORTANT: Copy the secret key NOW!
+Example: JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP
+```
+
+#### Step 5: Update Your Authenticator App
+1. Remove the old RubyGems entry from your authenticator app
+2. Scan the new QR code
+3. Enter the 6-digit code to verify
+
+⚠️ **Warning:** After regenerating, your old authenticator codes won't work!
+
+## Test Your Secret
+
+Once you have the secret, test it:
+
+```bash
+# Replace JBSWY... with YOUR actual secret
+ruby -r rotp -e "puts ROTP::TOTP.new('JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP').now"
+```
+
+**Expected output:**
+```
+123456  ← A 6-digit number
+```
+
+**This number should match** your authenticator app at the same time!
+
+## Common Mistakes
+
+### ❌ Using the 6-digit OTP code
+```bash
+# WRONG - This is the code, not the secret
+ruby -r rotp -e "puts ROTP::TOTP.new('123456').now"
+# Error: Invalid Base32 Character
+```
+
+### ❌ Using the placeholder text
+```bash
+# WRONG - This is the example placeholder
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_SECRET_HERE').now"
+# Error: Invalid Base32 Character - '_'
+```
+
+### ✅ Using the actual secret
+```bash
+# CORRECT - Your actual Base32 secret from RubyGems
+ruby -r rotp -e "puts ROTP::TOTP.new('JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP').now"
+# Output: 123456
+```
+
+## Where to Use It
+
+Once you have your real secret:
+
+### 1. Test Locally
+```bash
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_ACTUAL_SECRET').now"
+```
+
+### 2. Add to GitHub Secrets
+1. Go to: https://github.com/YOUR_USERNAME/YOUR_REPO/settings/secrets/actions
+2. Click **New repository secret**
+3. Name: `RUBYGEMS_OTP_SECRET`
+4. Value: Your actual secret (e.g., `JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP`)
+5. Click **Add secret**
+
+## Still Having Issues?
+
+### Error: "Invalid Base32 Character"
+
+Your secret contains invalid characters. Check:
+- No underscores (`_`)
+- No lowercase letters
+- No numbers 0, 1, 8, 9
+- No spaces or special characters
+
+Valid characters: `A-Z` and `2-7` only
+
+### Error: "OTP code doesn't match"
+
+1. Make sure your computer's time is synchronized
+2. Try again (codes change every 30 seconds)
+3. Verify the secret is correct
+
+### Can't Find Secret Anywhere
+
+You'll need to regenerate MFA (see Method 2 above).
+
+## Security Note
+
+🔒 **Keep your OTP secret secure!**
+- Don't share it publicly
+- Don't commit it to git
+- Store it in a password manager
+- Only add it to GitHub Secrets (which are encrypted)
+
+The secret is like a password - anyone with it can generate your OTP codes!

data/docs/QUICK_OTP_SETUP.md

@@ -0,0 +1,80 @@
+# Quick OTP Setup for Automated Releases
+
+## What You Need
+
+Your GitHub repository needs **two secrets** for automated gem releases with MFA:
+
+1. **RUBYGEMS_API_KEY** - Your RubyGems API key
+2. **RUBYGEMS_OTP_SECRET** - Your RubyGems OTP secret
+
+## Step 1: Get Your OTP Secret
+
+1. Log in to https://rubygems.org
+2. Go to **Edit Profile** → **Multi-factor Authentication**
+3. Copy the **secret key** (long alphanumeric string like `JBSWY3DPEHPK3PXP`)
+
+**⚠️ Save this securely!** If you don't see it, you may need to regenerate your MFA.
+
+## Step 2: Add Secrets to GitHub
+
+1. Go to your GitHub repo: https://github.com/shubhamtaywade82/ollama-client
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Add two secrets:
+
+| Secret Name           | Value           | Where to Get It                       |
+| --------------------- | --------------- | ------------------------------------- |
+| `RUBYGEMS_API_KEY`    | Your API key    | https://rubygems.org/profile/api_keys |
+| `RUBYGEMS_OTP_SECRET` | Your OTP secret | RubyGems MFA settings (Step 1)        |
+
+## Step 3: Test It
+
+```bash
+# Bump version in lib/ollama/version.rb
+# Then create and push tag:
+git tag v0.2.4
+git push origin v0.2.4
+```
+
+The GitHub Action will automatically:
+- Generate OTP code
+- Build gem
+- Push to RubyGems with OTP authentication
+
+## Test OTP Locally (Optional)
+
+```bash
+gem install rotp
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_SECRET_HERE').now"
+```
+
+This should match the code in your authenticator app.
+
+## Troubleshooting
+
+### "Invalid OTP code"
+- Verify `RUBYGEMS_OTP_SECRET` is correct
+- Check it matches your authenticator app
+
+### "unauthorized"
+- Verify `RUBYGEMS_API_KEY` is correct
+- Create new API key with push permissions
+
+### Need more help?
+See full guide: `docs/RUBYGEMS_OTP_SETUP.md`
+
+## How It Works
+
+```yaml
+- name: Install OTP generator
+  run: gem install rotp
+
+- name: Publish gem with OTP
+  env:
+    GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+    RUBYGEMS_OTP_SECRET: ${{ secrets.RUBYGEMS_OTP_SECRET }}
+  run: |
+    otp_code=$(ruby -r rotp -e "puts ROTP::TOTP.new(ENV['RUBYGEMS_OTP_SECRET']).now")
+    gem push "ollama-client-${version}.gem" --otp "$otp_code"
+```
+
+That's it! Your automated releases are now secured with MFA. 🔒

data/docs/QUICK_RELEASE.md

@@ -0,0 +1,106 @@
+# Quick Release Reference
+
+Quick reference for releasing gems via GitHub Actions. See [GEM_RELEASE_GUIDE.md](GEM_RELEASE_GUIDE.md) for full details.
+
+## One-Time Setup
+
+### 1. RubyGems API Key
+1. Visit: https://rubygems.org/profile/edit
+2. Create API key with "Push rubygems" scope
+3. Copy the key
+
+### 2. GitHub Secret
+1. Go to: `https://github.com/USERNAME/REPO/settings/secrets/actions`
+2. Add secret: `RUBYGEMS_API_KEY`
+3. Paste your RubyGems API key
+
+### 3. Workflow File
+Create `.github/workflows/release.yml`:
+
+```yaml
+name: Release
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3.4"
+          bundler-cache: true
+      - name: Validate version
+        run: |
+          tag_version="${GITHUB_REF#refs/tags/v}"
+          gem_version=$(ruby -e "require_relative 'lib/your_gem/version'; puts YourGem::VERSION")
+          [ "$tag_version" = "$gem_version" ] || exit 1
+      - name: Build and publish
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+        run: |
+          gem build your-gem.gemspec
+          gem push your-gem-*.gem
+```
+
+## Release Process
+
+### Every Release
+
+```bash
+# 1. Update version
+# Edit: lib/your_gem/version.rb
+VERSION = "1.2.3"
+
+# 2. Update changelog
+# Edit: CHANGELOG.md
+
+# 3. Commit
+git add lib/your_gem/version.rb CHANGELOG.md
+git commit -m "Bump version to 1.2.3"
+git push
+
+# 4. Tag and push
+git tag -a v1.2.3 -m "Release v1.2.3"
+git push origin v1.2.3
+
+# 5. Monitor
+# https://github.com/USERNAME/REPO/actions
+```
+
+## Quick Commands
+
+```bash
+# Create release script: bin/release.sh
+#!/bin/bash
+VERSION=$1
+git tag -a v${VERSION} -m "Release v${VERSION}"
+git push origin v${VERSION}
+echo "✅ Releasing v${VERSION} - check GitHub Actions"
+
+# Use it:
+chmod +x bin/release.sh
+./bin/release.sh 1.2.3
+```
+
+## Common Issues
+
+**Access Denied?**
+- Check `RUBYGEMS_API_KEY` secret exists
+- Verify API key has "Push rubygems" scope
+
+**Version Mismatch?**
+- Update `lib/your_gem/version.rb`
+- Delete tag: `git tag -d v1.2.3 && git push origin :refs/tags/v1.2.3`
+
+**Workflow Not Running?**
+- Verify `.github/workflows/release.yml` exists
+- Check tag format: `v1.2.3` (with v prefix)
+
+## Links
+
+- **Full Guide:** [GEM_RELEASE_GUIDE.md](GEM_RELEASE_GUIDE.md)
+- **Your Actions:** https://github.com/USERNAME/REPO/actions
+- **RubyGems:** https://rubygems.org/profile/edit
+- **GitHub Secrets:** https://github.com/USERNAME/REPO/settings/secrets/actions

data/docs/README.md

@@ -0,0 +1,43 @@
+# Internal Documentation
+
+This directory contains internal development documentation for the ollama-client gem.
+
+## Quick Links
+
+- 🚀 **[Quick Release Reference](QUICK_RELEASE.md)** - Fast release checklist
+- 📘 **[Complete Release Guide](GEM_RELEASE_GUIDE.md)** - Full automation setup (794 lines)
+
+## Contents
+
+### Design Documentation
+- **[HANDLERS_ANALYSIS.md](HANDLERS_ANALYSIS.md)** - Analysis of handler architecture decisions (why we didn't adopt ollama-ruby's handler pattern)
+- **[FEATURES_ADDED.md](FEATURES_ADDED.md)** - Features integrated from ollama-ruby that align with our agent-first philosophy
+- **[PRODUCTION_FIXES.md](PRODUCTION_FIXES.md)** - Production-ready fixes for hybrid agents (JSON parsing, retry policy, etc.)
+- **[SCHEMA_FIXES.md](SCHEMA_FIXES.md)** - Schema validation fixes and best practices for numeric constraints
+- **[CONSOLE_IMPROVEMENTS.md](CONSOLE_IMPROVEMENTS.md)** - Interactive console UX improvements (thinking indicators, formatted tool results)
+
+### Testing Documentation
+- **[TESTING.md](TESTING.md)** - Testing guide and examples
+- **[TEST_UPDATES.md](TEST_UPDATES.md)** - Recent test updates for DhanHQ tool calling enhancements
+
+### CI/Automation
+- **[CLOUD.md](CLOUD.md)** - Cloud agent guide for automated testing and fixes
+- **[GEM_RELEASE_GUIDE.md](GEM_RELEASE_GUIDE.md)** - Complete guide for automated gem releases via GitHub Actions and git tags
+
+## For Users
+
+If you're looking for user-facing documentation, see:
+- [Main README](../README.md) - Getting started, API reference, examples
+- [CHANGELOG](../CHANGELOG.md) - Version history and changes
+- [CONTRIBUTING](../CONTRIBUTING.md) - How to contribute
+- [Examples](../examples/) - Working code examples
+
+## For Contributors
+
+These internal docs help maintainers understand:
+- **Why** certain design decisions were made
+- **What** features have been added and why
+- **How** to test and maintain the codebase
+- **Where** production fixes were applied
+
+They are not intended for end users and can be safely ignored when using the gem.

data/docs/RUBYGEMS_OTP_SETUP.md

@@ -0,0 +1,199 @@
+# RubyGems OTP Setup for Automated Releases
+
+This guide explains how to configure OTP (One-Time Password) authentication for automated gem releases with MFA enabled.
+
+## Why This Is Needed
+
+When `rubygems_mfa_required = "true"` is set in your gemspec, RubyGems requires MFA verification for all gem pushes, including automated CI/CD releases. This guide shows how to configure GitHub Actions to generate OTP codes automatically.
+
+## Prerequisites
+
+- RubyGems account with MFA enabled
+- Admin access to your GitHub repository (to add secrets)
+- Authenticator app (Google Authenticator, Authy, 1Password, etc.)
+
+## Step 1: Get Your RubyGems OTP Secret
+
+### Option A: From Existing MFA Setup
+
+If you already have MFA enabled on RubyGems:
+
+1. **Log in to RubyGems.org**
+2. **Go to Edit Profile** → **Multi-factor Authentication**
+3. **Click "Show QR Code"** or **"Regenerate Recovery Codes"**
+4. When you see the QR code, look for the **secret key** (usually shown below the QR code)
+5. Copy the secret key (it's a long alphanumeric string like `JBSWY3DPEHPK3PXP`)
+
+### Option B: Enable MFA Fresh
+
+If you're setting up MFA for the first time:
+
+1. **Log in to RubyGems.org**
+2. **Go to Edit Profile** → **Multi-factor Authentication**
+3. **Click "Enable MFA"**
+4. You'll see a QR code and a **secret key** below it
+5. **Copy the secret key** before scanning the QR code
+6. Scan the QR code with your authenticator app
+7. Enter the 6-digit code to verify
+
+**⚠️ IMPORTANT:** Save the secret key securely. You'll need it for GitHub Actions.
+
+### What the Secret Looks Like
+
+```
+Example: JBSWY3DPEHPK3PXPJBSWY3DPEHPK3PXP
+- All uppercase letters and numbers
+- Typically 32 characters long
+- Base32 encoded
+```
+
+## Step 2: Add Secrets to GitHub
+
+### 2.1: Add API Key Secret
+
+1. Go to your GitHub repository
+2. Click **Settings** → **Secrets and variables** → **Actions**
+3. Click **New repository secret**
+4. Name: `RUBYGEMS_API_KEY`
+5. Value: Your RubyGems API key (get from https://rubygems.org/profile/api_keys)
+6. Click **Add secret**
+
+### 2.2: Add OTP Secret
+
+1. Still in **Secrets and variables** → **Actions**
+2. Click **New repository secret**
+3. Name: `RUBYGEMS_OTP_SECRET`
+4. Value: Your OTP secret key (from Step 1)
+5. Click **Add secret**
+
+## Step 3: Verify GitHub Secrets
+
+Your repository should now have two secrets:
+
+```
+✅ RUBYGEMS_API_KEY
+✅ RUBYGEMS_OTP_SECRET
+```
+
+## Step 4: Test the Setup
+
+### Test Locally First
+
+You can test OTP generation locally before pushing:
+
+```bash
+# Install rotp gem
+gem install rotp
+
+# Generate an OTP code (replace with your actual secret)
+ruby -r rotp -e "puts ROTP::TOTP.new('YOUR_SECRET_HERE').now"
+```
+
+This should output a 6-digit code that matches your authenticator app.
+
+### Test in CI/CD
+
+1. Bump your gem version in `lib/ollama/version.rb`
+2. Commit and push
+3. Create and push a matching tag:
+
+```bash
+git tag v0.2.4
+git push origin v0.2.4
+```
+
+4. Check GitHub Actions to see the release workflow run
+
+## How It Works
+
+The GitHub Actions workflow:
+
+1. **Installs `rotp` gem** - Ruby library for generating TOTP codes
+2. **Generates OTP code** - Uses your secret to generate a 6-digit code
+3. **Pushes gem** - Runs `gem push --otp <code>` with the generated code
+
+```yaml
+- name: Install OTP generator
+  run: gem install rotp
+
+- name: Publish gem with OTP
+  env:
+    GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_API_KEY }}
+    RUBYGEMS_OTP_SECRET: ${{ secrets.RUBYGEMS_OTP_SECRET }}
+  run: |
+    otp_code=$(ruby -r rotp -e "puts ROTP::TOTP.new(ENV['RUBYGEMS_OTP_SECRET']).now")
+    gem push "ollama-client-${gem_version}.gem" --otp "$otp_code"
+```
+
+## Troubleshooting
+
+### "Invalid OTP code" Error
+
+**Cause:** Time synchronization issue or wrong secret
+
+**Solutions:**
+1. Verify your secret is correct
+2. Check server time is synchronized:
+   ```bash
+   date
+   ```
+3. Try regenerating the secret on RubyGems
+
+### "OTP code expired" Error
+
+**Cause:** Code expired before being used (they last 30 seconds)
+
+**Solution:** The workflow generates the code immediately before use, so this shouldn't happen. If it does, there may be a network delay. The workflow will need to retry.
+
+### "unauthorized" Error
+
+**Cause:** API key is invalid or doesn't have push permissions
+
+**Solutions:**
+1. Verify `RUBYGEMS_API_KEY` is correct
+2. Create a new API key with push permissions
+3. Update the secret in GitHub
+
+### Missing Secrets
+
+**Error:** `RUBYGEMS_OTP_SECRET not found`
+
+**Solution:** Ensure both secrets are added to GitHub (Settings → Secrets and variables → Actions)
+
+## Security Considerations
+
+### ✅ Pros
+- MFA protection on gem releases
+- OTP secret encrypted in GitHub Secrets
+- No manual intervention needed
+- Audit trail in GitHub Actions
+
+### ⚠️ Considerations
+- OTP secret stored in GitHub increases attack surface
+- If GitHub is compromised, attacker has both API key and OTP secret
+- Alternative: Remove `rubygems_mfa_required` and rely on account-level MFA
+
+### Best Practices
+
+1. **Rotate API keys** regularly
+2. **Use scoped API keys** (push-only if possible)
+3. **Enable GitHub branch protection** on main branch
+4. **Require PR reviews** for sensitive changes
+5. **Monitor release logs** for unauthorized pushes
+6. **Regenerate OTP secret** if you suspect compromise
+
+## Alternative: Account-Level MFA Only
+
+If you want simpler automation:
+
+1. Remove `rubygems_mfa_required` from gemspec
+2. Keep account-level MFA enabled on RubyGems
+3. Use API key only (no OTP needed)
+
+This is the recommended approach for most projects as it provides good security with less complexity.
+
+## Reference
+
+- [RubyGems MFA Documentation](https://guides.rubygems.org/setting-up-multifactor-authentication/)
+- [ROTP Gem Documentation](https://github.com/mdp/rotp)
+- [GitHub Encrypted Secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets)