ollama-client 0.2.4 → 0.2.6

data/lib/ollama/document_loader.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "csv"
+require "json"
+
+module Ollama
+  # Document loader for RAG (Retrieval-Augmented Generation)
+  #
+  # Loads files from a directory and provides them as context for LLM queries.
+  # Supports: .txt, .md, .csv, .json files
+  #
+  # Example:
+  #   loader = Ollama::DocumentLoader.new("docs/")
+  #   context = loader.load_all
+  #   result = client.generate(
+  #     prompt: "Context: #{context}\n\nQuestion: What is Ruby?",
+  #     schema: {...}
+  #   )
+  class DocumentLoader
+    SUPPORTED_EXTENSIONS = %w[.txt .md .markdown .csv .json].freeze
+
+    def initialize(directory, extensions: SUPPORTED_EXTENSIONS)
+      @directory = File.expand_path(directory)
+      @extensions = extensions
+      @documents = {}
+    end
+
+    # Load all supported files from the directory
+    #
+    # @param recursive [Boolean] Load files from subdirectories
+    # @return [Hash] Hash of filename => content
+    def load_all(recursive: false)
+      raise Error, "Directory not found: #{@directory}" unless Dir.exist?(@directory)
+
+      pattern = recursive ? "**/*" : "*"
+      files = Dir.glob(File.join(@directory, pattern)).select { |f| File.file?(f) }
+
+      loaded_count = 0
+      files.each do |file|
+        next unless supported_file?(file)
+
+        filename = File.basename(file)
+        content = load_file(file)
+        next if content.nil?
+
+        @documents[filename] = content
+        loaded_count += 1
+      end
+
+      @documents
+    end
+
+    # Load a specific file
+    #
+    # @param filename [String] Name of the file to load (can be relative or absolute)
+    # @return [String] File content as text, or nil if file not found
+    def load_file(filename)
+      # Handle both relative and absolute paths
+      full_path = if File.absolute_path?(filename)
+                    filename
+                  else
+                    File.join(@directory, filename)
+                  end
+
+      return nil unless File.exist?(full_path)
+
+      # Store with basename for consistency
+      basename = File.basename(filename)
+
+      ext = File.extname(filename).downcase
+      content = File.read(full_path)
+
+      parsed_content = case ext
+                       when ".csv"
+                         parse_csv(content)
+                       when ".json"
+                         parse_json(content)
+                       else
+                         # .txt, .md, .markdown, or any other text file
+                         content
+                       end
+
+      # Store in documents hash
+      @documents[basename] = parsed_content
+      parsed_content
+    end
+
+    # Get all loaded documents as a single context string
+    #
+    # @param separator [String] Separator between documents
+    # @return [String] Combined context from all documents
+    def to_context(separator: "\n\n---\n\n")
+      @documents.map do |filename, content|
+        "File: #{filename}\n#{content}"
+      end.join(separator)
+    end
+
+    # Get documents matching a pattern
+    #
+    # @param pattern [String, Regexp] Pattern to match filenames
+    # @return [Hash] Matching documents
+    def select(pattern)
+      if pattern.is_a?(Regexp)
+        @documents.select { |filename, _| filename.match?(pattern) }
+      else
+        @documents.select { |filename, _| filename.include?(pattern.to_s) }
+      end
+    end
+
+    # Get a specific document by filename
+    #
+    # @param filename [String] Name of the document
+    # @return [String, nil] Document content or nil if not found
+    def [](filename)
+      @documents[filename]
+    end
+
+    # List all loaded document names
+    #
+    # @return [Array<String>] Array of filenames
+    def files
+      @documents.keys
+    end
+
+    # Check if any documents are loaded
+    #
+    # @return [Boolean] True if documents are loaded
+    def empty?
+      @documents.empty?
+    end
+
+    private
+
+    def supported_file?(file)
+      ext = File.extname(file).downcase
+      @extensions.include?(ext)
+    end
+
+    def parse_csv(content)
+      rows = CSV.parse(content, headers: true)
+      return content if rows.empty?
+
+      # Convert CSV to readable text format
+      headers = rows.headers || []
+      text_rows = rows.map do |row|
+        if headers.any?
+          headers.map { |h| "#{h}: #{row[h]}" }.join(", ")
+        else
+          row.fields.join(", ")
+        end
+      end
+
+      "CSV Data:\n#{text_rows.join("\n")}"
+    end
+
+    def parse_json(content)
+      parsed = JSON.parse(content)
+      JSON.pretty_generate(parsed)
+    rescue JSON::ParserError
+      content
+    end
+  end
+end

data/lib/ollama/embeddings.rb

@@ -44,19 +44,9 @@ module Ollama
       response_body = JSON.parse(res.body)
       embedding = response_body["embedding"]
 
-      # Return single array for single input, or array of arrays for multiple inputs
-      if input.is_a?(Array)
-        # Ollama returns single embedding array even for multiple inputs
-        # We need to check the response structure
-        if embedding.is_a?(Array) && embedding.first.is_a?(Array)
-          embedding
-        else
-          # Single embedding returned, wrap it
-          [embedding]
-        end
-      else
-        embedding
-      end
+      validate_embedding_response!(embedding, response_body, model)
+
+      format_embedding_result(embedding, input)
     rescue JSON::ParserError => e
       raise InvalidJSONError, "Failed to parse embeddings response: #{e.message}"
     rescue Net::ReadTimeout, Net::OpenTimeout
@@ -67,6 +57,45 @@ module Ollama
 
     private
 
+    def validate_embedding_response!(embedding, response_body, model)
+      if embedding.nil?
+        keys = response_body.keys.join(", ")
+        response_preview = response_body.inspect[0..200]
+        raise Error, "Embedding not found in response. Response keys: #{keys}. " \
+                     "Full response: #{response_preview}"
+      end
+
+      return unless embedding.is_a?(Array) && embedding.empty?
+
+      error_msg = build_empty_embedding_error_message(model, response_body)
+      raise Error, error_msg
+    end
+
+    def build_empty_embedding_error_message(model, response_body)
+      curl_command = "curl http://localhost:11434/api/embeddings " \
+                     "-d '{\"model\":\"#{model}\",\"input\":\"test\"}'"
+      response_preview = response_body.inspect[0..300]
+
+      "Empty embedding returned. This usually means:\n  " \
+        "1. The model may not be properly loaded - try: ollama pull #{model}\n  " \
+        "2. The model may not support embeddings - verify it's an embedding model\n  " \
+        "3. Check if the model is working: #{curl_command}\n" \
+        "Response: #{response_preview}"
+    end
+
+    def format_embedding_result(embedding, input)
+      return embedding unless input.is_a?(Array)
+
+      # Ollama returns single embedding array even for multiple inputs
+      # We need to check the response structure
+      if embedding.is_a?(Array) && embedding.first.is_a?(Array)
+        embedding
+      else
+        # Single embedding returned, wrap it
+        [embedding]
+      end
+    end
+
     def handle_http_error(res, requested_model: nil)
       status_code = res.code.to_i
       raise NotFoundError.new(res.message, requested_model: requested_model) if status_code == 404

data/lib/ollama/errors.rb

@@ -6,6 +6,7 @@ module Ollama
   class InvalidJSONError < Error; end
   class SchemaViolationError < Error; end
   class RetryExhaustedError < Error; end
+  class ChatNotAllowedError < Error; end
 
   # HTTP error with retry logic
   class HTTPError < Error

data/lib/ollama/personas.rb

@@ -0,0 +1,287 @@
+# frozen_string_literal: true
+
+module Ollama
+  # Persona system for explicit, contextual personalization.
+  #
+  # Personas are NOT baked into models or server config. They are injected
+  # explicitly at the system/prompt layer, allowing you to:
+  #
+  # - Use compressed versions for schema-based agent work (deterministic)
+  # - Use minimal chat-safe versions for chat/streaming UI work (human-facing)
+  # - Switch personas per task without model changes
+  # - Maintain multiple personas for different contexts
+  #
+  # This is architecturally superior to ChatGPT's implicit global personalization.
+  #
+  # ## Persona Variants
+  #
+  # Each persona has two variants:
+  #
+  # ### Agent Variants (`:agent`)
+  # - Designed for `/api/generate` with JSON schemas
+  # - Minimal, directive, non-chatty
+  # - Preserves determinism in structured outputs
+  # - No markdown, no explanations, no extra fields
+  # - Use with Planner, structured extraction, decision engines
+  #
+  # ### Chat Variants (`:chat`)
+  # - Designed for `/api/chat` with ChatSession
+  # - Minimal, chat-safe, allows explanations
+  # - Explicitly disclaims authority and side effects
+  # - Allows streaming and markdown for presentation
+  # - Use ONLY for human-facing chat interfaces
+  # - Must NEVER be used for schema-based agent work
+  #
+  # ## Critical Separation
+  #
+  # - Agent personas: `/api/generate` + schemas = deterministic reasoning
+  # - Chat personas: `/api/chat` + humans = explanatory conversation
+  #
+  # Mixing them breaks determinism and safety boundaries.
+  # rubocop:disable Metrics/ModuleLength
+  module Personas
+    # Minimal agent-safe persona for schema-based planning and structured outputs.
+    #
+    # This version is:
+    # - Minimal and direct (no verbosity)
+    # - Focused on correctness and invariants
+    # - No chatty behavior or markdown drift
+    # - Preserves determinism in structured outputs
+    # - Designed for /api/generate, schema-validated, deterministic workflows
+    #
+    # This prompt turns the LLM into a deterministic reasoning subroutine,
+    # not a conversational partner. Use for planners, routers, decision engines.
+    ARCHITECT_AGENT = <<~PROMPT
+      You are acting as a senior software architect and system designer.
+
+      Operating rules:
+      - Optimize for correctness and robustness first.
+      - Make explicit decisions; do not hedge.
+      - Do not invent data, APIs, or system behavior.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume side effects; propose intent only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer simple, explicit solutions over clever ones.
+
+      Focus areas:
+      - System boundaries and invariants
+      - Failure modes and edge cases
+      - Production-grade architecture decisions
+    PROMPT
+
+    # Minimal chat-safe persona for human-facing chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    ARCHITECT_CHAT = <<~PROMPT
+      You are a senior software architect and systems engineer.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and technically precise.
+      - Explain reasoning when it helps understanding.
+      - Avoid unnecessary verbosity or motivational language.
+      - Do not invent APIs, data, or system behavior.
+      - If information is missing, say so explicitly.
+      - Prefer concrete examples over abstract theory.
+
+      Boundaries:
+      - You do not execute actions or side effects.
+      - You provide explanations, guidance, and reasoning only.
+      - Decisions that affect systems must be validated externally.
+
+      Tone:
+      - Professional, calm, and no-nonsense.
+      - Assume the user has strong technical background.
+    PROMPT
+
+    # Minimal agent-safe persona for trading/analysis work.
+    #
+    # Designed for /api/generate, schema-validated, deterministic workflows.
+    # This prompt turns the LLM into a deterministic reasoning subroutine
+    # for market analysis, risk assessment, and trading decisions.
+    TRADING_AGENT = <<~PROMPT
+      You are acting as a quantitative trading system analyst.
+
+      Operating rules:
+      - Optimize for data accuracy and risk assessment first.
+      - Make explicit decisions based on provided data only.
+      - Do not invent market data, prices, or indicators.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume market behavior; base analysis on data only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer explicit risk statements over predictions.
+
+      Focus areas:
+      - Risk management and edge cases
+      - Data-driven analysis without emotional bias
+      - Objective assessment of market conditions
+    PROMPT
+
+    # Minimal chat-safe persona for trading chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    TRADING_CHAT = <<~PROMPT
+      You are a quantitative trading system analyst.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and data-focused.
+      - Explain analysis when it helps understanding.
+      - Avoid predictions, guarantees, or emotional language.
+      - Do not invent market data, prices, or indicators.
+      - If information is missing, say so explicitly.
+      - Prefer concrete data examples over abstract theory.
+
+      Boundaries:
+      - You do not execute trades or market actions.
+      - You provide analysis, guidance, and reasoning only.
+      - Trading decisions must be validated externally.
+
+      Tone:
+      - Professional, objective, and risk-aware.
+      - Assume the user understands market fundamentals.
+    PROMPT
+
+    # Minimal agent-safe persona for code review work.
+    #
+    # Designed for /api/generate, schema-validated, deterministic workflows.
+    # This prompt turns the LLM into a deterministic reasoning subroutine
+    # for code quality assessment and refactoring decisions.
+    REVIEWER_AGENT = <<~PROMPT
+      You are acting as a code review assistant focused on maintainability and correctness.
+
+      Operating rules:
+      - Optimize for code clarity and maintainability first.
+      - Make explicit decisions about code quality issues.
+      - Do not invent code patterns or assume implementation details.
+      - If required information is missing, state it clearly.
+      - Treat the LLM as a reasoning component, not an authority.
+      - Never assume intent; identify issues from code structure only.
+
+      Output rules:
+      - Output MUST conform exactly to the provided JSON schema.
+      - Do not include markdown, explanations, or extra fields.
+      - Use deterministic reasoning; avoid creative variation.
+      - Prefer explicit refactoring suggestions over general advice.
+
+      Focus areas:
+      - Unclear names, long methods, hidden responsibilities
+      - Single responsibility and testability
+      - Unnecessary complexity and code smells
+    PROMPT
+
+    # Minimal chat-safe persona for code review chat interfaces.
+    #
+    # This version:
+    # - Allows explanations and examples (chat needs)
+    # - Allows streaming (presentation needs)
+    # - Still prevents hallucination (safety)
+    # - Explicitly disclaims authority (boundaries)
+    # - Never implies side effects (safety)
+    #
+    # Designed for ChatSession, /api/chat, streaming, human-facing interactions.
+    # Must NEVER be used for schema-based agent work.
+    REVIEWER_CHAT = <<~PROMPT
+      You are a code review assistant focused on maintainability and correctness.
+
+      You are interacting with a human in a conversational interface.
+
+      Guidelines:
+      - Be clear, direct, and technically precise.
+      - Explain code quality issues when it helps understanding.
+      - Avoid unnecessary verbosity or motivational language.
+      - Do not invent code patterns or assume implementation details.
+      - If information is missing, say so explicitly.
+      - Prefer concrete refactoring examples over abstract principles.
+
+      Boundaries:
+      - You do not modify code or execute refactorings.
+      - You provide review, guidance, and suggestions only.
+      - Code changes must be validated externally.
+
+      Tone:
+      - Professional, constructive, and no-nonsense.
+      - Assume the user values code quality and maintainability.
+    PROMPT
+
+    # Registry of all available personas.
+    #
+    # Each persona has two variants:
+    # - `:agent` - Minimal version for schema-based agent work (/api/generate)
+    # - `:chat` - Minimal chat-safe version for human-facing interfaces (/api/chat)
+    #
+    # IMPORTANT: Chat personas must NEVER be used for schema-based agent work.
+    # They are designed for ChatSession and streaming only.
+    REGISTRY = {
+      architect: {
+        agent: ARCHITECT_AGENT,
+        chat: ARCHITECT_CHAT
+      },
+      trading: {
+        agent: TRADING_AGENT,
+        chat: TRADING_CHAT
+      },
+      reviewer: {
+        agent: REVIEWER_AGENT,
+        chat: REVIEWER_CHAT
+      }
+    }.freeze
+
+    # Get a persona by name and variant.
+    #
+    # @param name [Symbol] Persona name (:architect, :trading, :reviewer)
+    # @param variant [Symbol] Variant (:agent or :chat)
+    # @return [String, nil] Persona prompt text, or nil if not found
+    #
+    # @example
+    #   Personas.get(:architect, :agent)  # => Compressed agent version
+    #   Personas.get(:architect, :chat)    # => Full chat version
+    def self.get(name, variant: :agent)
+      REGISTRY.dig(name.to_sym, variant.to_sym)
+    end
+
+    # List all available persona names.
+    #
+    # @return [Array<Symbol>] List of persona names
+    def self.available
+      REGISTRY.keys
+    end
+
+    # Check if a persona exists.
+    #
+    # @param name [Symbol, String] Persona name
+    # @return [Boolean] True if persona exists
+    def self.exists?(name)
+      REGISTRY.key?(name.to_sym)
+    end
+  end
+  # rubocop:enable Metrics/ModuleLength
+end

data/lib/ollama/version.rb

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

data/lib/ollama_client.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+# Load .env file if available (.env takes precedence over shell environment variables)
+require "dotenv"
+Dotenv.overload
+
+require_relative "ollama/version"
 require_relative "ollama/config"
 require_relative "ollama/errors"
 require_relative "ollama/schema_validator"
@@ -7,10 +12,13 @@ require_relative "ollama/options"
 require_relative "ollama/response"
 require_relative "ollama/tool"
 require_relative "ollama/client"
+require_relative "ollama/document_loader"
 require_relative "ollama/streaming_observer"
+require_relative "ollama/chat_session"
 require_relative "ollama/agent/messages"
 require_relative "ollama/agent/planner"
 require_relative "ollama/agent/executor"
+require_relative "ollama/personas"
 
 # Main entry point for OllamaClient gem
 #

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ollama-client
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - Shubham Taywade
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-01-18 00:00:00.000000000 Z
+date: 2026-01-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: csv
+  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
@@ -46,7 +60,6 @@ description: A production-ready, agent-first Ruby client for the Ollama API with
 email:
 - shubhamtaywade82@gmail.com
 executables:
-- dhan_console
 - ollama-client
 extensions: []
 extra_rdoc_files: []
@@ -59,75 +72,40 @@ files:
 - Rakefile
 - docs/CLOUD.md
 - docs/CONSOLE_IMPROVEMENTS.md
+- docs/EXAMPLE_REORGANIZATION.md
 - docs/FEATURES_ADDED.md
-- docs/GEM_RELEASE_GUIDE.md
-- docs/GET_RUBYGEMS_SECRET.md
+- docs/GETTING_STARTED.md
 - docs/HANDLERS_ANALYSIS.md
+- docs/INTEGRATION_TESTING.md
+- docs/NEXT_STEPS_SUMMARY.md
+- docs/PERSONAS.md
 - docs/PRODUCTION_FIXES.md
-- docs/QUICK_OTP_SETUP.md
-- docs/QUICK_RELEASE.md
+- docs/QUICK_START.md
 - docs/README.md
-- docs/RUBYGEMS_OTP_SETUP.md
+- docs/RELEASE_GUIDE.md
 - docs/SCHEMA_FIXES.md
 - docs/TESTING.md
+- docs/TEST_CHECKLIST.md
 - docs/TEST_UPDATES.md
+- docs/ruby_guide.md
 - examples/README.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/chat_console.rb
-- examples/complete_workflow.rb
-- examples/dhan_console.rb
-- examples/dhanhq/README.md
-- examples/dhanhq/agents/base_agent.rb
-- examples/dhanhq/agents/data_agent.rb
-- examples/dhanhq/agents/orchestrator_agent.rb
-- examples/dhanhq/agents/technical_analysis_agent.rb
-- examples/dhanhq/agents/trading_agent.rb
-- examples/dhanhq/analysis/market_structure.rb
-- examples/dhanhq/analysis/pattern_recognizer.rb
-- examples/dhanhq/analysis/trend_analyzer.rb
-- examples/dhanhq/builders/market_context_builder.rb
-- examples/dhanhq/dhanhq_agent.rb
-- examples/dhanhq/indicators/technical_indicators.rb
-- examples/dhanhq/scanners/intraday_options_scanner.rb
-- examples/dhanhq/scanners/swing_scanner.rb
-- examples/dhanhq/schemas/agent_schemas.rb
-- examples/dhanhq/services/base_service.rb
-- examples/dhanhq/services/data_service.rb
-- examples/dhanhq/services/trading_service.rb
-- examples/dhanhq/technical_analysis_agentic_runner.rb
-- examples/dhanhq/technical_analysis_runner.rb
-- examples/dhanhq/test_tool_calling.rb
-- examples/dhanhq/test_tool_calling_verbose.rb
-- examples/dhanhq/utils/instrument_helper.rb
-- examples/dhanhq/utils/parameter_cleaner.rb
-- examples/dhanhq/utils/parameter_normalizer.rb
-- examples/dhanhq/utils/rate_limiter.rb
-- examples/dhanhq/utils/trading_parameter_normalizer.rb
-- examples/dhanhq_agent.rb
-- examples/dhanhq_tools.rb
-- examples/multi_step_agent_with_external_data.rb
-- examples/structured_outputs_chat.rb
-- examples/structured_tools.rb
-- examples/test_dhanhq_tool_calling.rb
-- examples/test_tool_calling.rb
-- examples/tool_calling_direct.rb
-- examples/tool_calling_pattern.rb
+- examples/basic_chat.rb
+- examples/basic_generate.rb
+- examples/tool_calling_parsing.rb
 - examples/tool_dto_example.rb
-- exe/dhan_console
 - exe/ollama-client
 - lib/ollama/agent/executor.rb
 - lib/ollama/agent/messages.rb
 - lib/ollama/agent/planner.rb
+- lib/ollama/chat_session.rb
 - lib/ollama/client.rb
 - lib/ollama/config.rb
+- lib/ollama/document_loader.rb
 - lib/ollama/dto.rb
 - lib/ollama/embeddings.rb
 - lib/ollama/errors.rb
 - lib/ollama/options.rb
+- lib/ollama/personas.rb
 - lib/ollama/response.rb
 - lib/ollama/schema_validator.rb
 - lib/ollama/schemas/base.json