ollama-client 0.2.0

data/lib/ollama/config.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Configuration class with safe defaults for agent-grade usage
+  #
+  # ⚠️ THREAD SAFETY WARNING:
+  # Global configuration via OllamaClient.configure is NOT thread-safe.
+  # For concurrent agents or multi-threaded applications, use per-client
+  # configuration instead:
+  #
+  #   config = Ollama::Config.new
+  #   config.model = "llama3.1"
+  #   client = Ollama::Client.new(config: config)
+  #
+  class Config
+    attr_accessor :base_url, :model, :timeout, :retries, :temperature, :top_p, :num_ctx, :on_response
+
+    def initialize
+      @base_url = "http://localhost:11434"
+      @model = "llama3.1:8b"
+      @timeout = 20
+      @retries = 2
+      @temperature = 0.2
+      @top_p = 0.9
+      @num_ctx = 8192
+      @on_response = nil
+    end
+  end
+end

data/lib/ollama/errors.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Ollama
+  class Error < StandardError; end
+  class TimeoutError < Error; end
+  class InvalidJSONError < Error; end
+  class SchemaViolationError < Error; end
+  class RetryExhaustedError < Error; end
+
+  # HTTP error with retry logic
+  class HTTPError < Error
+    attr_reader :status_code
+
+    def initialize(message, status_code = nil)
+      super(message)
+      @status_code = status_code
+    end
+
+    def retryable?
+      # Explicit retry policy:
+      # - Retry: 408 (Request Timeout), 429 (Too Many Requests),
+      #   500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable)
+      # - Never retry: 400-407, 409-428, 430-499 (client errors)
+      # - Never retry: 501, 504-599 (other server errors - may indicate permanent issues)
+      return true if @status_code.nil? # Unknown status - retry for safety
+      return true if [408, 429, 500, 502, 503].include?(@status_code)
+
+      false
+    end
+  end
+
+  # Specific error for 404 Not Found responses
+  class NotFoundError < HTTPError
+    attr_reader :requested_model, :suggestions
+
+    def initialize(message = "Resource not found", requested_model: nil, suggestions: [])
+      super("HTTP 404: #{message}", 404)
+      @requested_model = requested_model
+      @suggestions = suggestions
+    end
+
+    def retryable?
+      false
+    end
+
+    def to_s
+      msg = super
+      return msg unless @requested_model && !@suggestions.empty?
+
+      suggestion_text = @suggestions.map { |m| "  - #{m}" }.join("\n")
+      "#{msg}\n\nModel '#{@requested_model}' not found. Did you mean one of these?\n#{suggestion_text}"
+    end
+  end
+end

data/lib/ollama/schema_validator.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "json-schema"
+require_relative "errors"
+
+module Ollama
+  # Validates JSON data against JSON Schema
+  #
+  # For agent-grade usage, enforces strict schemas by default:
+  # - additionalProperties: false (unless explicitly set)
+  # - Prevents LLMs from adding unexpected fields
+  class SchemaValidator
+    def self.validate!(data, schema)
+      JSON::Validator.validate!(prepare_schema(schema), data)
+    rescue JSON::Schema::ValidationError => e
+      raise SchemaViolationError, e.message
+    end
+
+    # JSON Schema defaults to allowing additional properties unless
+    # `additionalProperties: false` is specified. For agent-grade contracts,
+    # we want the stricter default, while still allowing callers to override
+    # it explicitly on any object schema.
+    def self.prepare_schema(schema)
+      enforce_no_additional_properties(schema)
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def self.enforce_no_additional_properties(node)
+      case node
+      when Array
+        node.map { |v| enforce_no_additional_properties(v) }
+      when Hash
+        h = node.dup
+
+        # Recurse into common schema composition keywords
+        %w[anyOf oneOf allOf].each do |k|
+          h[k] = h[k].map { |v| enforce_no_additional_properties(v) } if h[k].is_a?(Array)
+        end
+
+        # Recurse into nested schemas
+        h["not"] = enforce_no_additional_properties(h["not"]) if h["not"].is_a?(Hash)
+
+        if h["properties"].is_a?(Hash)
+          h["properties"] = h["properties"].transform_values { |v| enforce_no_additional_properties(v) }
+        end
+
+        if h["patternProperties"].is_a?(Hash)
+          h["patternProperties"] = h["patternProperties"].transform_values { |v| enforce_no_additional_properties(v) }
+        end
+
+        h["items"] = enforce_no_additional_properties(h["items"]) if h["items"]
+
+        h["additionalItems"] = enforce_no_additional_properties(h["additionalItems"]) if h["additionalItems"]
+
+        # JSON Schema draft variants
+        if h["definitions"].is_a?(Hash)
+          h["definitions"] = h["definitions"].transform_values { |v| enforce_no_additional_properties(v) }
+        end
+
+        h["$defs"] = h["$defs"].transform_values { |v| enforce_no_additional_properties(v) } if h["$defs"].is_a?(Hash)
+
+        # Enforce strict object shape by default.
+        is_objectish =
+          h["type"] == "object" ||
+          h.key?("properties") ||
+          h.key?("patternProperties")
+
+        h["additionalProperties"] = false if is_objectish && !h.key?("additionalProperties")
+
+        h
+      else
+        node
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    private_class_method :prepare_schema, :enforce_no_additional_properties
+  end
+end

data/lib/ollama/schemas/base.json

@@ -0,0 +1,5 @@
+{
+  "type": "object",
+  "additionalProperties": true
+}
+

data/lib/ollama/streaming_observer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Presentation-only streaming observer for agent loops.
+  # This object must never control tool execution or loop termination.
+  class StreamingObserver
+    Event = Struct.new(:type, :text, :name, :state, :data, keyword_init: true)
+
+    def initialize(&block)
+      @block = block
+    end
+
+    def emit(type, text: nil, name: nil, state: nil, data: nil)
+      return unless @block
+
+      @block.call(Event.new(type: type, text: text, name: name, state: state, data: data))
+    rescue StandardError
+      # Observers must never break control flow.
+      nil
+    end
+  end
+end

data/lib/ollama/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Ollama
+  VERSION = "0.2.0"
+end

data/lib/ollama_client.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative "ollama/config"
+require_relative "ollama/errors"
+require_relative "ollama/schema_validator"
+require_relative "ollama/client"
+require_relative "ollama/streaming_observer"
+require_relative "ollama/agent/messages"
+require_relative "ollama/agent/planner"
+require_relative "ollama/agent/executor"
+
+# Main entry point for OllamaClient gem
+#
+# ⚠️ THREAD SAFETY WARNING:
+# Global configuration via OllamaClient.configure is NOT thread-safe.
+# For concurrent agents or multi-threaded applications, use per-client
+# configuration instead:
+#
+#   config = Ollama::Config.new
+#   config.model = "llama3.1"
+#   client = Ollama::Client.new(config: config)
+#
+module OllamaClient
+  @config_mutex = Mutex.new
+  @warned_thread_config = false
+
+  def self.config
+    @config_mutex.synchronize do
+      @config ||= Ollama::Config.new
+    end
+  end
+
+  def self.configure
+    if Thread.current != Thread.main && !@warned_thread_config
+      @warned_thread_config = true
+      msg = "[ollama-client] Global OllamaClient.configure is not thread-safe. " \
+            "Prefer per-client config (Ollama::Client.new(config: ...))."
+      warn(msg)
+    end
+
+    @config_mutex.synchronize do
+      @config ||= Ollama::Config.new
+      yield(@config)
+    end
+  end
+end

data/sig/ollama/client.rbs

@@ -0,0 +1,6 @@
+module Ollama
+  module Client
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: ollama-client
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Shubham Taywade
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: json-schema
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+description: A production-ready, agent-first Ruby client for the Ollama API with schema
+  validation, bounded retries, and explicit safety defaults. Includes a minimal agent
+  layer (Ollama::Agent::Planner for deterministic /api/generate, and Ollama::Agent::Executor
+  for stateful /api/chat tool loops with disciplined, observer-only streaming). Not
+  a chatbot UI and not a promise of full Ollama endpoint coverage.
+email:
+- shubhamtaywade82@gmail.com
+executables:
+- ollama-client
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- PRODUCTION_FIXES.md
+- README.md
+- Rakefile
+- TESTING.md
+- examples/advanced_complex_schemas.rb
+- examples/advanced_edge_cases.rb
+- examples/advanced_error_handling.rb
+- examples/advanced_multi_step_agent.rb
+- examples/advanced_performance_testing.rb
+- examples/complete_workflow.rb
+- examples/dhanhq_agent.rb
+- examples/dhanhq_tools.rb
+- examples/structured_outputs_chat.rb
+- examples/tool_calling_pattern.rb
+- exe/ollama-client
+- lib/ollama/agent/executor.rb
+- lib/ollama/agent/messages.rb
+- lib/ollama/agent/planner.rb
+- lib/ollama/client.rb
+- lib/ollama/config.rb
+- lib/ollama/errors.rb
+- lib/ollama/schema_validator.rb
+- lib/ollama/schemas/base.json
+- lib/ollama/streaming_observer.rb
+- lib/ollama/version.rb
+- lib/ollama_client.rb
+- sig/ollama/client.rbs
+homepage: https://github.com/shubhamtaywade82/ollama-client
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/shubhamtaywade82/ollama-client
+  source_code_uri: https://github.com/shubhamtaywade82/ollama-client
+  changelog_uri: https://github.com/shubhamtaywade82/ollama-client/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: An agent-first Ruby client for Ollama (planner/executor + safe tool loops)
+test_files: []