soka 0.0.1.beta2

data/lib/soka/llms/anthropic.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Soka
+  module LLMs
+    # Anthropic (Claude) LLM provider implementation
+    class Anthropic < Base
+      include Concerns::ResponseParser
+
+      ENV_KEY = 'ANTHROPIC_API_KEY'
+
+      private
+
+      def default_model
+        'claude-4-sonnet'
+      end
+
+      def base_url
+        'https://api.anthropic.com'
+      end
+
+      def default_options
+        {
+          temperature: 0.7,
+          top_p: 1.0,
+          top_k: 1,
+          max_tokens: 2048,
+          anthropic_version: '2023-06-01'
+        }
+      end
+
+      public
+
+      def chat(messages, **params)
+        request_params = build_request_params(messages, params)
+
+        response = connection.post do |req|
+          req.url '/v1/messages'
+          req.headers['x-api-key'] = api_key
+          req.headers['anthropic-version'] = options[:anthropic_version]
+          req.body = request_params
+        end
+
+        parse_response(response)
+      rescue Faraday::Error => e
+        handle_error(e)
+      end
+
+      def supports_streaming?
+        true
+      end
+
+      def streaming_chat(messages, **params, &)
+        request_params = build_streaming_params(messages, params)
+        execute_streaming_request(request_params, &)
+      rescue Faraday::Error => e
+        handle_error(e)
+      end
+
+      def build_streaming_params(messages, params)
+        request_params = build_request_params(messages, params)
+        request_params[:stream] = true
+        request_params
+      end
+
+      def execute_streaming_request(request_params, &)
+        connection.post('/v1/messages') do |req|
+          req.headers['x-api-key'] = api_key
+          req.headers['anthropic-version'] = options[:anthropic_version]
+          req.body = request_params
+          req.options.on_data = proc do |chunk, _overall_received_bytes|
+            process_stream_chunk(chunk, &)
+          end
+        end
+      end
+
+      private
+
+      def build_request_params(messages, params)
+        formatted_messages, system_prompt = extract_system_prompt(messages)
+        request = build_base_request(formatted_messages, params)
+        request[:system] = system_prompt if system_prompt
+        request
+      end
+
+      def build_base_request(formatted_messages, params)
+        {
+          model: model,
+          messages: formatted_messages,
+          temperature: params[:temperature] || options[:temperature],
+          top_p: params[:top_p] || options[:top_p],
+          top_k: params[:top_k] || options[:top_k],
+          max_tokens: params[:max_tokens] || options[:max_tokens]
+        }
+      end
+
+      def extract_system_prompt(messages)
+        system_message = messages.find { |m| m[:role] == 'system' }
+        other_messages = messages.reject { |m| m[:role] == 'system' }
+
+        formatted_messages = other_messages.map do |message|
+          {
+            role: map_role(message[:role]),
+            content: message[:content]
+          }
+        end
+
+        [formatted_messages, system_message&.dig(:content)]
+      end
+
+      def map_role(role)
+        case role.to_s
+        when 'user'
+          'user'
+        when 'assistant'
+          'assistant'
+        else
+          role.to_s
+        end
+      end
+
+      # Response parsing methods are in ResponseParser module
+    end
+  end
+end

data/lib/soka/llms/base.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Soka
+  module LLMs
+    # Result structure for LLM responses
+    Result = Struct.new(:model, :content, :input_tokens, :output_tokens, :finish_reason, :raw_response,
+                        keyword_init: true) do
+      def successful?
+        !content.nil? && !content.empty?
+      end
+    end
+
+    # Base class for LLM providers
+    class Base
+      attr_reader :model, :api_key, :options
+
+      def initialize(model: nil, api_key: nil, **options)
+        @model = model || default_model
+        @api_key = api_key || api_key_from_env
+        @options = default_options.merge(options)
+        validate_configuration!
+      end
+
+      def chat(messages, **params)
+        raise NotImplementedError, "#{self.class} must implement #chat method"
+      end
+
+      def streaming_chat(messages, **params, &)
+        raise NotImplementedError, "#{self.class} does not support streaming"
+      end
+
+      def supports_streaming?
+        false
+      end
+
+      private
+
+      def default_model
+        raise NotImplementedError, "#{self.class} must implement #default_model method"
+      end
+
+      def default_options
+        {}
+      end
+
+      def validate_configuration!
+        raise LLMError, 'API key is required' if api_key.nil? || api_key.empty?
+        raise LLMError, 'Model is required' if model.nil? || model.empty?
+      end
+
+      def api_key_from_env
+        ENV.fetch(self.class::ENV_KEY, nil)
+      end
+
+      def connection
+        @connection ||= Faraday.new(url: base_url) do |faraday|
+          faraday.request :json
+          faraday.response :json
+          faraday.adapter Faraday.default_adapter
+          faraday.options.timeout = options[:timeout] || 30
+          faraday.options.open_timeout = options[:open_timeout] || 10
+        end
+      end
+
+      def base_url
+        raise NotImplementedError, "#{self.class} must implement #base_url method"
+      end
+
+      def handle_error(error)
+        case error
+        when Faraday::TimeoutError
+          raise LLMError, 'Request timed out'
+        when Faraday::ConnectionFailed
+          raise LLMError, "Connection failed: #{error.message}"
+        when Faraday::ClientError
+          handle_client_error(error)
+        else
+          raise LLMError, "Unexpected error: #{error.message}"
+        end
+      end
+
+      def handle_client_error(error)
+        status = error.response[:status]
+        body = error.response[:body]
+        raise_error_for_status(status, body)
+      end
+
+      def raise_error_for_status(status, body)
+        error_message = build_error_message(status, body)
+        raise LLMError, error_message
+      end
+
+      def build_error_message(status, body)
+        case status
+        when 401 then 'Unauthorized: Invalid API key'
+        when 429 then 'Rate limit exceeded'
+        when 400..499 then extract_error_message(body) || "Client error: #{status}"
+        when 500..599 then "Server error: #{status}"
+        else "HTTP error: #{status}"
+        end
+      end
+
+      def extract_error_message(body)
+        return body if body.is_a?(String)
+
+        # Try common error message paths
+        body.dig('error', 'message') ||
+          body.dig('error', 'text') ||
+          body['message'] ||
+          body.to_s
+      end
+    end
+  end
+end

data/lib/soka/llms/concerns/response_parser.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Soka
+  module LLMs
+    module Concerns
+      # Module for parsing Anthropic API responses
+      module ResponseParser
+        private
+
+        # Parse API response
+        # @param response [Faraday::Response] The HTTP response
+        # @return [String] The parsed content
+        # @raise [LLMError] If response indicates an error
+        def parse_response(response)
+          handle_error(response) unless response.success?
+
+          data = JSON.parse(response.body)
+          extract_content(data)
+        end
+
+        # Extract content from response data
+        # @param data [Hash] The parsed response data
+        # @return [String] The extracted content
+        # @raise [LLMError] If content is missing
+        def extract_content(data)
+          content = data.dig('content', 0, 'text')
+          raise LLMError, 'No content in response' unless content
+
+          content
+        end
+
+        # Handle API errors
+        # @param response [Faraday::Response] The HTTP response
+        # @raise [LLMError] Always raises with error details
+        def handle_error(response)
+          error_data = begin
+            JSON.parse(response.body)
+          rescue StandardError
+            {}
+          end
+          error_message = error_data.dig('error', 'message') || "HTTP #{response.status}"
+          raise LLMError, "Anthropic API error: #{error_message}"
+        end
+      end
+    end
+  end
+end

data/lib/soka/llms/concerns/streaming_handler.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Soka
+  module LLMs
+    module Concerns
+      # Module for handling streaming responses from OpenAI
+      module StreamingHandler
+        private
+
+        # Stream chat completion
+        # @param messages [Array<Hash>] The messages to send
+        # @param params [Hash] Additional parameters
+        # @yield [String] Yields each chunk of the response
+        # @return [String] The complete response
+        def stream_chat(messages, **params, &)
+          return regular_chat(messages, **params) unless block_given?
+
+          complete_response = +''
+          request_params = build_request_params(messages, **params, stream: true)
+
+          response = connection.post('/v1/chat/completions') do |req|
+            req.body = request_params.to_json
+          end
+
+          handle_streaming_response(response, complete_response, &)
+        end
+
+        # Handle streaming response
+        # @param response [Faraday::Response] The HTTP response
+        # @param complete_response [String] Buffer for complete response
+        # @yield [String] Yields each chunk
+        # @return [String] The complete response
+        def handle_streaming_response(response, complete_response)
+          response.body.each_line do |line|
+            chunk = process_streaming_line(line)
+            next unless chunk
+
+            complete_response << chunk
+            yield chunk
+          end
+          complete_response
+        end
+
+        # Process a single streaming line
+        # @param line [String] The line to process
+        # @return [String, nil] The parsed chunk or nil
+        def process_streaming_line(line)
+          return nil if line.strip.empty? || !line.start_with?('data: ')
+
+          data = line[6..].strip
+          return nil if data == '[DONE]'
+
+          parse_streaming_chunk(data)
+        end
+
+        # Parse a streaming chunk
+        # @param data [String] The chunk data
+        # @return [String, nil] The parsed content
+        def parse_streaming_chunk(data)
+          parsed = JSON.parse(data)
+          parsed.dig('choices', 0, 'delta', 'content')
+        rescue JSON::ParserError
+          nil
+        end
+
+        # Perform regular (non-streaming) chat
+        # @param messages [Array<Hash>] The messages
+        # @param params [Hash] Additional parameters
+        # @return [String] The response content
+        def regular_chat(messages, **params)
+          request_params = build_request_params(messages, **params)
+          response = connection.post('/v1/chat/completions', request_params.to_json)
+          parse_response(response)
+        end
+      end
+    end
+  end
+end

data/lib/soka/llms/gemini.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Soka
+  module LLMs
+    # Google Gemini LLM provider implementation
+    class Gemini < Base
+      ENV_KEY = 'GEMINI_API_KEY'
+
+      private
+
+      def default_model
+        'gemini-2.5-flash-lite'
+      end
+
+      def base_url
+        'https://generativelanguage.googleapis.com'
+      end
+
+      def default_options
+        {
+          temperature: 0.7,
+          top_p: 1.0,
+          top_k: 1,
+          max_output_tokens: 2048
+        }
+      end
+
+      public
+
+      def chat(messages, **params)
+        request_params = build_request_params(messages, params)
+
+        response = connection.post do |req|
+          req.url "/v1beta/models/#{model}:generateContent"
+          req.params['key'] = api_key
+          req.body = request_params
+        end
+
+        parse_response(response)
+      rescue Faraday::Error => e
+        handle_error(e)
+      end
+
+      private
+
+      def build_request_params(messages, params)
+        {
+          contents: format_messages(messages),
+          generationConfig: {
+            temperature: params[:temperature] || options[:temperature],
+            topP: params[:top_p] || options[:top_p],
+            topK: params[:top_k] || options[:top_k],
+            maxOutputTokens: params[:max_output_tokens] || options[:max_output_tokens]
+          }
+        }
+      end
+
+      def format_messages(messages)
+        messages.map do |message|
+          {
+            role: map_role(message[:role]),
+            parts: [{ text: message[:content] }]
+          }
+        end
+      end
+
+      def map_role(role)
+        case role.to_s
+        when 'system', 'assistant'
+          'model'
+        when 'user'
+          'user'
+        else
+          role.to_s
+        end
+      end
+
+      def parse_response(response)
+        body = response.body
+        validate_response_status(response.status, body)
+        build_result_from_response(body)
+      end
+
+      def validate_response_status(status, body)
+        return if status == 200
+
+        error_message = body.dig('error', 'message') || 'Unknown error'
+        raise LLMError, "Gemini API error: #{error_message}"
+      end
+
+      def build_result_from_response(body)
+        candidate = body.dig('candidates', 0)
+        content = candidate.dig('content', 'parts', 0, 'text')
+
+        Result.new(
+          model: model,
+          content: content,
+          input_tokens: body.dig('usageMetadata', 'promptTokenCount'),
+          output_tokens: body.dig('usageMetadata', 'candidatesTokenCount'),
+          finish_reason: candidate['finishReason'],
+          raw_response: body
+        )
+      end
+    end
+  end
+end

data/lib/soka/llms/openai.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Soka
+  module LLMs
+    # OpenAI (GPT) LLM provider implementation
+    class OpenAI < Base
+      include Concerns::StreamingHandler
+
+      ENV_KEY = 'OPENAI_API_KEY'
+
+      private
+
+      def default_model
+        'gpt-4.1-mini'
+      end
+
+      def base_url
+        'https://api.openai.com'
+      end
+
+      def default_options
+        {
+          temperature: 0.7,
+          top_p: 1.0,
+          frequency_penalty: 0,
+          presence_penalty: 0,
+          max_tokens: 2048
+        }
+      end
+
+      public
+
+      def chat(messages, **params)
+        request_params = build_request_params(messages, params)
+
+        response = connection.post do |req|
+          req.url '/v1/chat/completions'
+          req.headers['Authorization'] = "Bearer #{api_key}"
+          req.body = request_params
+        end
+
+        parse_response(response)
+      rescue Faraday::Error => e
+        handle_error(e)
+      end
+
+      def supports_streaming?
+        true
+      end
+
+      # Streaming methods are in StreamingHandler module
+
+      private
+
+      def build_request_params(messages, params)
+        {
+          model: model,
+          messages: messages,
+          temperature: params[:temperature] || options[:temperature],
+          top_p: params[:top_p] || options[:top_p],
+          frequency_penalty: params[:frequency_penalty] || options[:frequency_penalty],
+          presence_penalty: params[:presence_penalty] || options[:presence_penalty],
+          max_tokens: params[:max_tokens] || options[:max_tokens]
+        }
+      end
+
+      def parse_response(response)
+        body = response.body
+        validate_response_status(response.status, body)
+        build_result_from_response(body)
+      end
+
+      def validate_response_status(status, body)
+        return if status == 200
+
+        error_message = body.dig('error', 'message') || 'Unknown error'
+        raise LLMError, "OpenAI API error: #{error_message}"
+      end
+
+      def build_result_from_response(body)
+        choice = body.dig('choices', 0)
+        message = choice['message']
+
+        Result.new(
+          model: body['model'],
+          content: message['content'],
+          input_tokens: body.dig('usage', 'prompt_tokens'),
+          output_tokens: body.dig('usage', 'completion_tokens'),
+          finish_reason: choice['finish_reason'],
+          raw_response: body
+        )
+      end
+
+      # Stream processing methods are in StreamingHandler module
+    end
+  end
+end

data/lib/soka/memory.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Soka
+  # Manages conversation history for agents
+  class Memory
+    attr_reader :messages
+
+    def initialize(initial_messages = [])
+      @messages = []
+
+      # Add initial messages if provided
+      return unless initial_messages.is_a?(Array)
+
+      initial_messages.each { |msg| add(**msg) }
+    end
+
+    def add(role:, content:)
+      validate_role!(role)
+      validate_content!(content)
+
+      @messages << {
+        role: role.to_s,
+        content: content,
+        timestamp: Time.now
+      }
+    end
+
+    def to_messages
+      @messages.map { |msg| { role: msg[:role], content: msg[:content] } }
+    end
+
+    def clear
+      @messages.clear
+    end
+
+    def size
+      @messages.size
+    end
+
+    def empty?
+      @messages.empty?
+    end
+
+    def last
+      @messages.last
+    end
+
+    def to_s
+      return '<Soka::Memory> []' if empty?
+
+      formatted_messages = @messages.map do |msg|
+        "  { role: '#{msg[:role]}', content: '#{truncate(msg[:content])}' }"
+      end.join(",\n")
+
+      "<Soka::Memory> [\n#{formatted_messages}\n]"
+    end
+
+    def inspect
+      to_s
+    end
+
+    private
+
+    def validate_role!(role)
+      valid_roles = %w[system user assistant]
+      return if valid_roles.include?(role.to_s)
+
+      raise MemoryError, "Invalid role: #{role}. Must be one of: #{valid_roles.join(', ')}"
+    end
+
+    def validate_content!(content)
+      return unless content.nil? || content.to_s.strip.empty?
+
+      raise MemoryError, 'Content cannot be nil or empty'
+    end
+
+    def truncate(text, length = 50)
+      return text if text.length <= length
+
+      "#{text[0..length]}..."
+    end
+  end
+end