rasti-ai 1.2.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e8aa13644a19b41a31445f268339fb14a9521ce85538493768bc5ee985b2a40
-  data.tar.gz: 82bc0cf208f412df7958bb8b95f5bdfa2b5deec0b892834afe82d0675543179e
+  metadata.gz: dfad832d41e30e53127315f47de79582f43316453accba99c261bc0cf158902a
+  data.tar.gz: 0dfb5550e2e5732af21b49e9317ad844b1d962c860fee711c72e4b2e1c83a55d
 SHA512:
-  metadata.gz: 93490666739ff2b3dbc01a023149b947ee88e8ba503224194f968892b0070595bdc463332a22be3a0d77dbdae6ced218dbe62f6589fddb590def2ccc6a7e6fd2
-  data.tar.gz: 0c0ca23c2a085fdba7549ffa0696c8ffe8e492a626b5c123bf7259310a4088f6177acab70e14c7b856f8cb6d2a0743c5722fa18edc1e7f9bd7c84e1d4b2b45cd
+  metadata.gz: 30031fc6f74b996c9d39b72dc12027dc7ffa765e8227ea9d252dc46d92a951a2a29b06bf8ddebe33d75a17c4b71827992a078d4dc3034501f5254583f1e080b8
+  data.tar.gz: ebc68bbfeca92dd5f929ea6bb93bcb5077faca18a592ddc1e15e8f500e154c666d8cfe0de2828108d4c8d84f7640203b125c8836cd61a78c3dbad4a9b721eb8a

data/README.md

@@ -27,20 +27,44 @@ Or install it yourself as:
 ```ruby
 Rasti::AI.configure do |config|
   config.logger = Logger.new 'log/development.log'
+
+  # HTTP settings
+  config.http_connect_timeout = 60 # Default 60 seconds
+  config.http_read_timeout = 60    # Default 60 seconds
+  config.http_max_retries = 3      # Default 3 retries
+
+  # OpenAI
   config.openai_api_key = 'abcd12345' # Default ENV['OPENAI_API_KEY']
   config.openai_default_model = 'gpt-4o-mini' # Default ENV['OPENAI_DEFAULT_MODEL']
+
+  # Gemini
+  config.gemini_api_key = 'AIza12345' # Default ENV['GEMINI_API_KEY']
+  config.gemini_default_model = 'gemini-2.0-flash' # Default ENV['GEMINI_DEFAULT_MODEL']
+
+  # Usage tracking
+  config.usage_tracker = ->(usage) { puts "#{usage.provider}: #{usage.input_tokens} in / #{usage.output_tokens} out" }
 end
 ```
 
-### Open AI
+### Supported providers
+
+- **OpenAI** - `Rasti::AI::OpenAI::Assistant`
+- **Gemini** - `Rasti::AI::Gemini::Assistant`
+
+All providers share the same interface. The examples below use OpenAI, but apply equally to Gemini by replacing `OpenAI` with `Gemini`.
+
+### Assistant
 
-#### Assistant
 ```ruby
 assistant = Rasti::AI::OpenAI::Assistant.new
 assistant.call 'who is the best player' # => 'The best player is Lionel Messi'
 ```
 
-#### Tools
+### Tools
+
+Tools can be simple classes or inherit from `Rasti::AI::Tool`. Both approaches work with any provider.
+
+#### Simple tools
 ```ruby
 class GetCurrentTime
   def call(params={})
@@ -54,11 +78,41 @@ class GetCurrentWeather
   end
 
   def call(params={})
-    response = HTTP.get "https://api.wheater.com/?location=#{params['location']}"
-    response.body.to_s
+    "The wheather in #{params['location']} is sunny"
   end
 end
+```
+
+#### Tools inheriting from Rasti::AI::Tool
+```ruby
+class SumTool < Rasti::AI::Tool
+  class Form < Rasti::Form
+    attribute :number_a, Rasti::Types::Float, required: true, description: 'First number'
+    attribute :number_b, Rasti::Types::Float, required: true, description: 'Second number'
+  end
 
+  def self.description
+    'Sum two numbers'
+  end
+
+  def execute(form)
+    {result: form.number_a + form.number_b}
+  end
+end
+```
+
+Supported form attribute types:
+- `Rasti::Types::String` → `string`
+- `Rasti::Types::Integer` → `integer`
+- `Rasti::Types::Float` → `number`
+- `Rasti::Types::Boolean` → `boolean`
+- `Rasti::Types::Time` → `string (date)`
+- `Rasti::Types::Enum[:a, :b]` → `string (enum)`
+- `Rasti::Types::Array[Type]` → `array`
+- `Rasti::Types::Model[FormClass]` → nested `object`
+
+#### Using tools with an assistant
+```ruby
 tools = [
   GetCurrentTime.new,
   GetCurrentWeather.new
@@ -71,29 +125,72 @@ assistant.call 'what time is it' # => 'The current time is 3:03 PM on April 28,
 assistant.call 'what is the weather in Buenos Aires' # => 'In Buenos Aires it is 15 degrees'
 ```
 
-#### Context and state
+### Context and state
 ```ruby
-state = Rasti::AI::OpenAI::AssistantState.new context: 'Act as sports journalist'
+state = Rasti::AI::AssistantState.new context: 'Act as sports journalist'
 
 assistant = Rasti::AI::OpenAI::Assistant.new state: state
 
 assistant.call 'who is the best player'
 
-state.messages
-# [
-#   {
-#     role: 'system',
-#     content: 'Act as sports journalist'
-#   },
-#   {
-#     role: 'user',
-#     content: 'who is the best player'
-#   },
-#   {
-#     role: 'assistant',
-#     content: 'The best player is Lionel Messi'
-#   }
-# ]
+state.context  # => 'Act as sports journalist'
+state.messages # Array of provider-specific message hashes
+```
+
+The state keeps the conversation history, enabling multi-turn interactions. It also caches tool call results to avoid duplicate executions.
+
+### Structured responses (JSON Schema)
+```ruby
+assistant = Rasti::AI::OpenAI::Assistant.new json_schema: {
+  player: 'string',
+  sport: 'string'
+}
+
+response = assistant.call 'who is the best player'
+JSON.parse response # => {"player" => "Lionel Messi", "sport" => "Football"}
+```
+
+### Custom model and client
+```ruby
+# Override model
+assistant = Rasti::AI::OpenAI::Assistant.new model: 'gpt-4o'
+
+# Custom client with per-client HTTP settings
+client = Rasti::AI::OpenAI::Client.new(
+  http_connect_timeout: 120,
+  http_read_timeout: 120,
+  http_max_retries: 5
+)
+
+assistant = Rasti::AI::OpenAI::Assistant.new client: client
+```
+
+### Usage tracking
+
+Track token consumption across API calls (including tool calls):
+
+```ruby
+tracked_usage = []
+tracker = ->(usage) { tracked_usage << usage }
+
+assistant = Rasti::AI::OpenAI::Assistant.new usage_tracker: tracker
+assistant.call 'who is the best player'
+
+usage = tracked_usage.first
+usage.provider          # => :open_ai
+usage.model             # => 'gpt-4o-mini'
+usage.input_tokens      # => 150
+usage.output_tokens     # => 42
+usage.cached_tokens     # => 0
+usage.reasoning_tokens  # => 0
+```
+
+The tracker can also be configured globally:
+
+```ruby
+Rasti::AI.configure do |config|
+  config.usage_tracker = ->(usage) { MyMetrics.track(usage) }
+end
 ```
 
 ### MCP (Model Context Protocol)
@@ -129,17 +226,6 @@ class HelloWorldTool < Rasti::AI::Tool
   end
 end
 
-class SumTool < Rasti::AI::Tool
-  class Form < Rasti::Form
-    attribute :number_a, Rasti::Types::Float
-    attribute :number_b, Rasti::Types::Float
-  end
-
-  def execute(form)
-    {result: form.number_a + form.number_b}
-  end
-end
-
 # Register tools
 Rasti::AI::MCP::Server.register_tool HelloWorldTool.new
 Rasti::AI::MCP::Server.register_tool SumTool.new
@@ -224,26 +310,21 @@ client = Rasti::AI::MCP::Client.new(
 )
 ```
 
-##### Integration with OpenAI Assistant
+##### Integration with Assistants
 
-You can use MCP clients as tools for the OpenAI Assistant:
+You can use MCP clients as tools for any assistant:
 
 ```ruby
-# Create an MCP client
 mcp_client = Rasti::AI::MCP::Client.new(
   url: 'https://mcp.server.ai/mcp'
 )
 
-# Use it with the assistant
 assistant = Rasti::AI::OpenAI::Assistant.new(
-  mcp_servers: {
-    my_mcp: mcp_client
-  }
+  mcp_servers: {my_mcp: mcp_client}
 )
 
 # The assistant can now call tools from the MCP server
 assistant.call 'What is 5 plus 3?'
-# The assistant will use the sum_tool from the MCP server
 ```
 
 ## Contributing
@@ -252,4 +333,4 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/gabyna
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/lib/rasti/ai/assistant.rb

@@ -0,0 +1,161 @@
+module Rasti
+  module AI
+    class Assistant
+
+      attr_reader :state
+
+      def initialize(client:nil, json_schema:nil, state:nil, model:nil, tools:[], mcp_servers:{}, logger:nil, usage_tracker:nil)
+        @client = client || build_default_client
+        @json_schema = json_schema
+        @state = state || AssistantState.new
+        @model = model
+        @tools = {}
+        @serialized_tools = []
+        @logger = logger || Rasti::AI.logger
+        @usage_tracker = usage_tracker || Rasti::AI.usage_tracker
+
+        register_tools(tools)
+        register_mcp_servers(mcp_servers)
+      end
+
+      def call(prompt)
+        messages << build_user_message(prompt)
+
+        loop do
+          response = request_completion
+          track_usage response
+
+          tool_calls = parse_tool_calls(response)
+
+          if tool_calls.any?
+            messages << build_assistant_tool_calls_message(response)
+
+            tool_calls.each do |tool_call|
+              name, args = extract_tool_call_info(tool_call)
+              result = call_tool(name, args)
+              messages << build_tool_result_message(tool_call, name, result)
+            end
+          else
+            content = parse_content(response)
+
+            messages << build_assistant_message(content)
+
+            return content if finished?(response)
+          end
+        end
+      end
+
+      private
+
+      attr_reader :client, :json_schema, :model, :tools, :serialized_tools, :logger, :usage_tracker
+
+      def messages
+        state.messages
+      end
+
+      def track_usage(response)
+        return unless usage_tracker
+        usage = parse_usage response
+        usage_tracker.call usage if usage
+      end
+
+      # --- Shared behavior ---
+
+      def register_tools(tools)
+        tools.each do |tool|
+          serialization = wrap_tool_serialization(ToolSerializer.serialize(tool.class))
+          name = extract_tool_name(serialization)
+          @tools[name] = tool
+          @serialized_tools << serialization
+        end
+      end
+
+      def register_mcp_servers(mcp_servers)
+        mcp_servers.each do |server_name, mcp|
+          mcp.list_tools.each do |tool|
+            prefixed_name = "#{server_name}_#{tool['name']}"
+            raw = tool.merge('name' => prefixed_name)
+            serialization = wrap_tool_serialization(raw)
+            @tools[prefixed_name] = ->(args) { mcp.call_tool tool['name'], args }
+            @serialized_tools << serialization
+          end
+        end
+      end
+
+      def call_tool(name, args)
+        raise Errors::UndefinedTool.new(name) unless tools.key? name
+
+        key = "#{name} -> #{args}"
+
+        state.fetch(key) do
+          logger.info(self.class) { "Calling function #{name} with #{args}" }
+
+          result = tools[name].call args
+
+          logger.info(self.class) { "Function result: #{result}" }
+
+          result
+        end
+
+      rescue => ex
+        logger.warn(self.class) { "Function failed: #{ex.message}\n#{ex.backtrace.join("\n")}" }
+        "Error: #{ex.message}"
+      end
+
+      # --- Template methods ---
+
+      def build_default_client
+        raise NotImplementedError
+      end
+
+      def build_user_message(prompt)
+        raise NotImplementedError
+      end
+
+      def build_assistant_message(content)
+        raise NotImplementedError
+      end
+
+      def build_assistant_tool_calls_message(response)
+        raise NotImplementedError
+      end
+
+      def build_tool_result_message(tool_call, name, result)
+        raise NotImplementedError
+      end
+
+      def request_completion
+        raise NotImplementedError
+      end
+
+      def parse_tool_calls(response)
+        raise NotImplementedError
+      end
+
+      def parse_content(response)
+        raise NotImplementedError
+      end
+
+      def finished?(response)
+        raise NotImplementedError
+      end
+
+      def parse_usage(response)
+        raise NotImplementedError
+      end
+
+      def extract_tool_call_info(tool_call)
+        raise NotImplementedError
+      end
+
+      def wrap_tool_serialization(raw)
+        raise NotImplementedError
+      end
+
+      def extract_tool_name(wrapped)
+        raise NotImplementedError
+      end
+
+    end
+  end
+end

data/lib/rasti/ai/assistant_state.rb

@@ -0,0 +1,24 @@
+module Rasti
+  module AI
+    class AssistantState
+
+      attr_reader :messages, :context
+
+      def initialize(context:nil)
+        @messages = []
+        @cache = {}
+        @context = context
+      end
+
+      def fetch(key, &block)
+        cache[key] = block.call unless cache.key? key
+        cache[key]
+      end
+
+      private
+
+      attr_reader :cache
+
+    end
+  end
+end

data/lib/rasti/ai/client.rb

@@ -0,0 +1,81 @@
+module Rasti
+  module AI
+    class Client
+
+      RETRYABLE_STATUS_CODES = [502, 503, 504].freeze
+
+      def initialize(api_key:nil, logger:nil, http_connect_timeout:nil, http_read_timeout:nil, http_max_retries:nil)
+        @api_key = api_key || default_api_key
+        @logger = logger || Rasti::AI.logger
+        @http_connect_timeout = http_connect_timeout || Rasti::AI.http_connect_timeout
+        @http_read_timeout = http_read_timeout || Rasti::AI.http_read_timeout
+        @http_max_retries = http_max_retries || Rasti::AI.http_max_retries
+      end
+
+      private
+
+      attr_reader :api_key, :logger, :http_connect_timeout, :http_read_timeout, :http_max_retries
+
+      def default_api_key
+        raise NotImplementedError
+      end
+
+      def base_url
+        raise NotImplementedError
+      end
+
+      def build_url(relative_url)
+        "#{base_url}#{relative_url}"
+      end
+
+      def build_request(uri)
+        request = Net::HTTP::Post.new uri
+        request['Content-Type'] = 'application/json'
+        request
+      end
+
+      def post(relative_url, body)
+        max_retries = http_max_retries
+        retry_count = 0
+
+        begin
+          url = build_url(relative_url)
+          uri = URI.parse url
+
+          logger.info(self.class) { "POST #{url}" }
+          logger.debug(self.class) { JSON.pretty_generate(body) }
+
+          request = build_request(uri)
+          request.body = JSON.dump body
+
+          http = Net::HTTP.new uri.host, uri.port
+          http.use_ssl = (uri.scheme == 'https')
+
+          http.open_timeout = http_connect_timeout
+          http.read_timeout = http_read_timeout
+
+          response = http.request request
+
+          logger.info(self.class) { "Response #{response.code}" }
+          logger.debug(self.class) { response.body }
+
+          if !response.is_a?(Net::HTTPSuccess) || RETRYABLE_STATUS_CODES.include?(response.code.to_i)
+            raise Errors::RequestFail.new(url, body, response)
+          end
+
+          JSON.parse response.body
+
+        rescue SocketError, Net::OpenTimeout, Net::ReadTimeout, Errors::RequestFail => e
+          if retry_count < max_retries
+            retry_count += 1
+            logger.warn(self.class) { "#{e.class.name}: #{e.message} (#{retry_count}/#{max_retries})" }
+            sleep retry_count
+            retry
+          end
+          raise
+        end
+      end
+
+    end
+  end
+end

data/lib/rasti/ai/gemini/assistant.rb

@@ -0,0 +1,112 @@
+module Rasti
+  module AI
+    module Gemini
+      class Assistant < Rasti::AI::Assistant
+
+        private
+
+        def build_default_client
+          Client.new
+        end
+
+        def build_user_message(prompt)
+          {role: Roles::USER, parts: [{text: prompt}]}
+        end
+
+        def build_assistant_message(content)
+          {role: Roles::MODEL, parts: [{text: content}]}
+        end
+
+        def build_assistant_tool_calls_message(response)
+          response['candidates'][0]['content']
+        end
+
+        def build_tool_result_message(tool_call, name, result)
+          {
+            role: Roles::FUNCTION,
+            parts: [{
+              functionResponse: {
+                name: name,
+                response: {content: result}
+              }
+            }]
+          }
+        end
+
+        def request_completion
+          system_inst = if state.context
+            {parts: [{text: state.context}]}
+          end
+
+          client.generate_content contents: messages,
+                                  model: model,
+                                  tools: serialized_tools_payload,
+                                  system_instruction: system_inst,
+                                  generation_config: generation_config
+        end
+
+        def parse_tool_calls(response)
+          parts = response.dig('candidates', 0, 'content', 'parts') || []
+          parts.select { |p| p.key?('functionCall') }
+        end
+
+        def parse_content(response)
+          parts = response.dig('candidates', 0, 'content', 'parts') || []
+          text_part = parts.find { |p| p.key?('text') }
+          text_part['text']
+        end
+
+        def finished?(response)
+          response.dig('candidates', 0, 'finishReason') == 'STOP'
+        end
+
+        def parse_usage(response)
+          usage = response['usageMetadata']
+          return unless usage
+          Usage.new(
+            provider: :gemini,
+            model: response['modelVersion'],
+            input_tokens: usage['promptTokenCount'],
+            output_tokens: usage['candidatesTokenCount'],
+            cached_tokens: usage['cachedContentTokenCount'] || 0,
+            reasoning_tokens: usage['thoughtsTokenCount'] || 0
+          )
+        end
+
+        def extract_tool_call_info(tool_call)
+          fc = tool_call['functionCall']
+          [fc['name'], fc['args'] || {}]
+        end
+
+        def wrap_tool_serialization(raw)
+          result = raw.dup
+          if result.key?(:inputSchema)
+            result[:parameters] = result.delete(:inputSchema)
+          elsif result.key?('inputSchema')
+            result['parameters'] = result.delete('inputSchema')
+          end
+          result
+        end
+
+        def extract_tool_name(wrapped)
+          wrapped[:name] || wrapped['name']
+        end
+
+        def serialized_tools_payload
+          return [] if serialized_tools.empty?
+          [{function_declarations: serialized_tools}]
+        end
+
+        def generation_config
+          return nil if json_schema.nil?
+
+          {
+            response_mime_type: 'application/json',
+            response_schema: json_schema
+          }
+        end
+
+      end
+    end
+  end
+end

data/lib/rasti/ai/gemini/client.rb

@@ -0,0 +1,35 @@
+module Rasti
+  module AI
+    module Gemini
+      class Client < Rasti::AI::Client
+
+        def generate_content(contents:, model:nil, tools:[], system_instruction:nil, generation_config:nil)
+          model_name = model || Rasti::AI.gemini_default_model
+
+          body = {contents: contents}
+
+          body[:tools] = tools unless tools.empty?
+          body[:system_instruction] = system_instruction unless system_instruction.nil?
+          body[:generation_config] = generation_config unless generation_config.nil?
+
+          post "/models/#{model_name}:generateContent", body
+        end
+
+        private
+
+        def default_api_key
+          Rasti::AI.gemini_api_key
+        end
+
+        def base_url
+          'https://generativelanguage.googleapis.com/v1beta'
+        end
+
+        def build_url(relative_url)
+          "#{base_url}#{relative_url}?key=#{api_key}"
+        end
+
+      end
+    end
+  end
+end

data/lib/rasti/ai/gemini/roles.rb

@@ -0,0 +1,13 @@
+module Rasti
+  module AI
+    module Gemini
+      module Roles
+
+        MODEL = 'model'.freeze
+        USER = 'user'.freeze
+        FUNCTION = 'function'.freeze
+
+      end
+    end
+  end
+end