google-adk 0.1.0

data/lib/google/adk/runner.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "async"
+
+module Google
+  module ADK
+    # Plugin base class for extending runner behavior
+    class Plugin
+      # Called when user sends a message
+      #
+      # @param context [InvocationContext] Current context
+      # @param message [String] User message
+      def on_user_message(context, message); end
+
+      # Called for each event
+      #
+      # @param context [InvocationContext] Current context
+      # @param event [Event] Current event
+      def on_event(context, event); end
+
+      # Called when agent starts
+      #
+      # @param context [InvocationContext] Current context
+      def on_agent_start(context); end
+
+      # Called when agent ends
+      #
+      # @param context [InvocationContext] Current context
+      def on_agent_end(context); end
+    end
+
+    # Main runner for orchestrating agent execution
+    class Runner
+      attr_reader :agent, :app_name, :session_service, :plugins
+
+      # Initialize a runner
+      #
+      # @param agent [BaseAgent] Root agent to run
+      # @param app_name [String] Application name
+      # @param session_service [BaseSessionService] Session service (optional)
+      # @param plugins [Array<Plugin>] Runner plugins (optional)
+      def initialize(agent:, app_name:, session_service: nil, plugins: [])
+        @agent = agent
+        @app_name = app_name
+        @session_service = session_service || InMemorySessionService.new
+        @plugins = plugins
+      end
+
+      # Run the agent synchronously
+      #
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID (optional)
+      # @param message [String] User message
+      # @param new_session [Boolean] Force new session (optional)
+      # @yield [Event] Events during execution
+      # @return [Enumerator<Event>] Event stream
+      def run(user_id:, message:, session_id: nil, new_session: false)
+        Enumerator.new do |yielder|
+          # Create or get session
+          session = if session_id && !new_session
+                      @session_service.get_session(
+                        app_name: @app_name,
+                        user_id: user_id,
+                        session_id: session_id
+                      )
+                    end
+
+          session ||= @session_service.create_session(
+            app_name: @app_name,
+            user_id: user_id
+          )
+
+          invocation_id = "inv-#{SecureRandom.uuid}"
+
+          # Create invocation context
+          context = InvocationContext.new(
+            session: session,
+            agent: @agent,
+            invocation_id: invocation_id,
+            session_service: @session_service
+          )
+
+          # Create and yield user event
+          user_event = Event.new(
+            invocation_id: invocation_id,
+            author: "user",
+            content: message
+          )
+          
+          # Plugin callback
+          @plugins.each { |p| p.on_user_message(context, message) }
+          
+          yielder << user_event
+          context.add_event(user_event)
+          @plugins.each { |p| p.on_event(context, user_event) }
+
+          # Update session
+          @session_service.append_event(
+            app_name: @app_name,
+            user_id: user_id,
+            session_id: session.id,
+            event: user_event
+          )
+
+          # Run agent
+          @plugins.each { |p| p.on_agent_start(context) }
+
+          begin
+            agent_events = @agent.run_async(message, context: context)
+            
+            # Process agent events
+            agent_events.each do |event|
+              yielder << event
+              context.add_event(event)
+              @plugins.each { |p| p.on_event(context, event) }
+
+              # Update session with event
+              @session_service.append_event(
+                app_name: @app_name,
+                user_id: user_id,
+                session_id: session.id,
+                event: event
+              )
+
+              # Handle state updates from event actions
+              if event.actions&.state_delta && !event.actions.state_delta.empty?
+                @session_service.update_session(
+                  app_name: @app_name,
+                  user_id: user_id,
+                  session_id: session.id,
+                  state_updates: event.actions.state_delta
+                )
+              end
+
+              # Handle agent transfers
+              if event.actions&.transfer_to_agent
+                # In a full implementation, would transfer to another agent
+                break
+              end
+            end
+          rescue StandardError => e
+            # Create error event
+            error_event = Event.new(
+              invocation_id: invocation_id,
+              author: "system",
+              content: "Error: #{e.message}"
+            )
+            yielder << error_event
+            context.add_event(error_event)
+          ensure
+            @plugins.each { |p| p.on_agent_end(context) }
+          end
+        end
+      end
+
+      # Run the agent asynchronously
+      #
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID (optional)
+      # @param message [String] User message
+      # @param new_session [Boolean] Force new session (optional)
+      # @return [Enumerator<Event>] Event stream
+      def run_async(user_id:, message:, session_id: nil, new_session: false)
+        # In this simplified version, we delegate to the sync method
+        # In a full implementation, this would use Async gem for true async
+        run(
+          user_id: user_id,
+          message: message,
+          session_id: session_id,
+          new_session: new_session
+        )
+      end
+
+      # Run in live/streaming mode (experimental)
+      #
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      def run_live(user_id:, session_id:)
+        raise NotImplementedError, "Live mode not yet implemented"
+      end
+
+      # Rewind session to previous state
+      #
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @param invocation_id [String] Invocation to rewind before
+      def rewind_async(user_id:, session_id:, invocation_id:)
+        raise NotImplementedError, "Rewind not yet implemented"
+      end
+    end
+
+    # In-memory runner with built-in session service
+    class InMemoryRunner < Runner
+      # Initialize in-memory runner
+      #
+      # @param agent [BaseAgent] Root agent
+      # @param app_name [String] Application name
+      # @param plugins [Array<Plugin>] Runner plugins (optional)
+      def initialize(agent:, app_name:, plugins: [])
+        super(
+          agent: agent,
+          app_name: app_name,
+          session_service: InMemorySessionService.new,
+          plugins: plugins
+        )
+      end
+    end
+  end
+end

data/lib/google/adk/session.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Google
+  module ADK
+    # Represents a conversation session
+    class Session
+      attr_accessor :id, :app_name, :user_id, :state, :events, :last_update_time
+
+      # Initialize a session
+      #
+      # @param id [String] Session ID
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param state [Hash] Session state (default: {})
+      # @param events [Array<Event>] Session events (default: [])
+      # @param last_update_time [Time] Last update timestamp (default: current time)
+      def initialize(id:, app_name:, user_id:, state: {}, events: [], last_update_time: nil)
+        @id = id
+        @app_name = app_name
+        @user_id = user_id
+        @state = state
+        @events = events
+        @last_update_time = last_update_time || Time.now
+      end
+
+      # Convert to hash representation
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          id: @id,
+          app_name: @app_name,
+          user_id: @user_id,
+          state: @state,
+          events: @events.map(&:to_h),
+          last_update_time: @last_update_time.iso8601
+        }
+      end
+
+      # Create session from hash
+      #
+      # @param hash [Hash] Hash representation
+      # @return [Session] New session instance
+      def self.from_h(hash)
+        new(
+          id: hash[:id],
+          app_name: hash[:app_name],
+          user_id: hash[:user_id],
+          state: hash[:state] || {},
+          events: (hash[:events] || []).map { |e| Event.new(**e) },
+          last_update_time: Time.parse(hash[:last_update_time])
+        )
+      end
+    end
+
+    # Base class for session services
+    class BaseSessionService
+      # Create a new session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param initial_state [Hash] Initial state (optional)
+      # @return [Session] Created session
+      def create_session(app_name: nil, user_id: nil, initial_state: nil)
+        raise NotImplementedError, "Subclasses must implement #create_session"
+      end
+
+      # Get a session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @return [Session, nil] Session or nil if not found
+      def get_session(app_name: nil, user_id: nil, session_id: nil)
+        raise NotImplementedError, "Subclasses must implement #get_session"
+      end
+
+      # Update session state
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @param state_updates [Hash] State updates
+      # @return [Session, nil] Updated session or nil if not found
+      def update_session(app_name: nil, user_id: nil, session_id: nil, state_updates: nil)
+        raise NotImplementedError, "Subclasses must implement #update_session"
+      end
+
+      # Append event to session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @param event [Event] Event to append
+      # @return [Session, nil] Updated session or nil if not found
+      def append_event(app_name: nil, user_id: nil, session_id: nil, event: nil)
+        raise NotImplementedError, "Subclasses must implement #append_event"
+      end
+
+      # Delete a session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @return [Boolean] True if deleted, false otherwise
+      def delete_session(app_name: nil, user_id: nil, session_id: nil)
+        raise NotImplementedError, "Subclasses must implement #delete_session"
+      end
+
+      # List sessions for a user
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @return [Array<Session>] List of sessions
+      def list_sessions(app_name: nil, user_id: nil)
+        raise NotImplementedError, "Subclasses must implement #list_sessions"
+      end
+    end
+
+    # In-memory session service for development/testing
+    class InMemorySessionService < BaseSessionService
+      def initialize
+        # Structure: { app_name => { user_id => { session_id => session } } }
+        @sessions = {}
+        @user_state = {}
+        @app_state = {}
+      end
+
+      # Create a new session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param initial_state [Hash] Initial state (optional)
+      # @return [Session] Created session
+      def create_session(app_name:, user_id:, initial_state: nil)
+        session = Session.new(
+          id: "session-#{SecureRandom.uuid}",
+          app_name: app_name,
+          user_id: user_id,
+          state: initial_state || {}
+        )
+
+        # Ensure nested structure exists
+        @sessions[app_name] ||= {}
+        @sessions[app_name][user_id] ||= {}
+        @sessions[app_name][user_id][session.id] = session
+
+        session
+      end
+
+      # Get a session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @return [Session, nil] Session or nil if not found
+      def get_session(app_name:, user_id:, session_id:)
+        @sessions.dig(app_name, user_id, session_id)
+      end
+
+      # Update session state
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @param state_updates [Hash] State updates
+      # @return [Session, nil] Updated session or nil if not found
+      def update_session(app_name:, user_id:, session_id:, state_updates:)
+        session = get_session(app_name: app_name, user_id: user_id, session_id: session_id)
+        return nil unless session
+
+        session.state.merge!(state_updates)
+        session.last_update_time = Time.now
+        session
+      end
+
+      # Append event to session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @param event [Event] Event to append
+      # @return [Session, nil] Updated session or nil if not found
+      def append_event(app_name:, user_id:, session_id:, event:)
+        session = get_session(app_name: app_name, user_id: user_id, session_id: session_id)
+        return nil unless session
+
+        session.events << event
+        session.last_update_time = Time.now
+        session
+      end
+
+      # Delete a session
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param session_id [String] Session ID
+      # @return [Boolean] True if deleted, false otherwise
+      def delete_session(app_name:, user_id:, session_id:)
+        return false unless @sessions.dig(app_name, user_id, session_id)
+
+        @sessions[app_name][user_id].delete(session_id)
+        true
+      end
+
+      # List sessions for a user
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @return [Array<Session>] List of sessions
+      def list_sessions(app_name:, user_id:)
+        sessions_hash = @sessions.dig(app_name, user_id)
+        return [] unless sessions_hash
+
+        sessions_hash.values
+      end
+
+      # Get user state
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @return [Hash] User state
+      def get_user_state(app_name:, user_id:)
+        @user_state.dig(app_name, user_id) || {}
+      end
+
+      # Update user state
+      #
+      # @param app_name [String] Application name
+      # @param user_id [String] User ID
+      # @param state_updates [Hash] State updates
+      # @return [Hash] Updated user state
+      def update_user_state(app_name:, user_id:, state_updates:)
+        @user_state[app_name] ||= {}
+        @user_state[app_name][user_id] ||= {}
+        @user_state[app_name][user_id].merge!(state_updates)
+      end
+
+      # Get app state
+      #
+      # @param app_name [String] Application name
+      # @return [Hash] App state
+      def get_app_state(app_name:)
+        @app_state[app_name] || {}
+      end
+
+      # Update app state
+      #
+      # @param app_name [String] Application name
+      # @param state_updates [Hash] State updates
+      # @return [Hash] Updated app state
+      def update_app_state(app_name:, state_updates:)
+        @app_state[app_name] ||= {}
+        @app_state[app_name].merge!(state_updates)
+      end
+    end
+  end
+end

data/lib/google/adk/tools/agent_tool.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module Google
+  module ADK
+    # Tool that wraps another agent
+    class AgentTool < BaseTool
+      attr_reader :agent
+
+      # Initialize an agent tool
+      #
+      # @param agent [BaseAgent] The agent to wrap
+      def initialize(agent:)
+        super(name: agent.name, description: agent.description)
+        @agent = agent
+      end
+
+      # Execute the wrapped agent
+      #
+      # @param params [Hash] Parameters (should include 'message')
+      # @return [Object] Agent response
+      def call(params = {})
+        message = params[:message] || params["message"] || ""
+        context = params[:context]
+
+        # In a real implementation, this would run the agent
+        # and collect its response
+        if @agent.respond_to?(:run_async)
+          # Collect all events from the agent
+          events = []
+          @agent.run_async(message, context: context).each do |event|
+            events << event
+          end
+
+          # Return the last event's content as the result
+          events.last&.content || "No response"
+        else
+          "Agent #{@agent.name} cannot be executed"
+        end
+      end
+
+      # Get parameter schema
+      #
+      # @return [Hash] JSON schema for agent invocation
+      def schema
+        {
+          "type" => "object",
+          "properties" => {
+            "message" => {
+              "type" => "string",
+              "description" => "Message to send to the agent"
+            }
+          },
+          "required" => ["message"]
+        }
+      end
+    end
+  end
+end

data/lib/google/adk/tools/base_tool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Google
+  module ADK
+    # Base class for all tools
+    class BaseTool
+      attr_reader :name, :description
+
+      # Initialize base tool
+      #
+      # @param name [String] Tool name (optional)
+      # @param description [String] Tool description (optional)
+      def initialize(name: nil, description: nil)
+        @name = name
+        @description = description
+      end
+
+      # Execute the tool with given parameters
+      #
+      # @param params [Hash] Tool parameters
+      # @return [Object] Tool result
+      def call(params = {})
+        raise NotImplementedError, "Subclasses must implement #call"
+      end
+
+      # Get the tool's parameter schema
+      #
+      # @return [Hash] JSON schema for parameters
+      def schema
+        raise NotImplementedError, "Subclasses must implement #schema"
+      end
+    end
+  end
+end

data/lib/google/adk/tools/function_tool.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require_relative "base_tool"
+
+module Google
+  module ADK
+    # Tool that wraps a Ruby callable (Proc, Method, etc.)
+    class FunctionTool < BaseTool
+      attr_reader :callable, :parameters_schema
+
+      # Initialize a function tool
+      #
+      # @param name [String] Tool name
+      # @param description [String] Tool description (optional)
+      # @param callable [Proc, Method] The function to wrap
+      # @param parameters_schema [Hash] JSON schema for parameters (optional)
+      def initialize(name:, description: nil, callable:, parameters_schema: nil)
+        super(name: name, description: description)
+        @callable = callable
+        @parameters_schema = parameters_schema # Don't default here, let to_gemini_schema handle it
+      end
+
+      # Execute the wrapped function
+      #
+      # @param params [Hash] Function parameters
+      # @return [Object] Function result
+      def call(params = {})
+        if @callable.parameters.empty?
+          @callable.call
+        else
+          # Convert hash params to keyword arguments if the callable expects them
+          if expects_keyword_args?
+            @callable.call(**params)
+          else
+            @callable.call(params)
+          end
+        end
+      end
+
+      # Get parameter schema
+      #
+      # @return [Hash] JSON schema
+      def schema
+        @parameters_schema
+      end
+      
+      # Convert to Gemini API schema format
+      #
+      # @return [Hash] Gemini function declaration
+      def to_gemini_schema
+        # Try to infer parameters from method signature if no schema provided
+        schema = @parameters_schema || infer_schema_from_callable
+        
+        {
+          "name" => @name,
+          "description" => @description || "Function tool",
+          "parameters" => schema
+        }
+      end
+
+      private
+
+      # Check if callable expects keyword arguments
+      #
+      # @return [Boolean] True if expects kwargs
+      def expects_keyword_args?
+        @callable.parameters.any? { |type, _name| %i[key keyreq keyrest].include?(type) }
+      end
+
+      # Generate default schema
+      #
+      # @return [Hash] Default empty schema
+      def default_schema
+        {
+          "type" => "object",
+          "properties" => {},
+          "required" => []
+        }
+      end
+      
+      # Infer schema from callable parameters
+      #
+      # @return [Hash] Inferred JSON schema
+      def infer_schema_from_callable
+        properties = {}
+        required = []
+        
+        @callable.parameters.each do |type, name|
+          next if type == :block
+          
+          param_name = name.to_s
+          
+          # Determine type based on parameter name patterns
+          param_type = case param_name
+                      when /amount|rate|fee|price|cost/
+                        "number"
+                      when /days|count|limit/
+                        "integer"
+                      else
+                        "string"
+                      end
+          
+          properties[param_name] = {
+            "type" => param_type,
+            "description" => generate_param_description(param_name)
+          }
+          
+          # Required if it's a required positional or keyword arg
+          if [:req, :keyreq].include?(type)
+            required << param_name
+          end
+        end
+        
+        {
+          "type" => "object",
+          "properties" => properties,
+          "required" => required
+        }
+      end
+      
+      # Generate descriptive parameter descriptions
+      def generate_param_description(param_name)
+        case param_name
+        when "from"
+          "Source currency code (e.g., USD, EUR, GBP)"
+        when "to"
+          "Target currency code (e.g., USD, EUR, GBP)"
+        when "amount"
+          "Amount of money to convert (number)"
+        when "city"
+          "City name for weather information"
+        when "days"
+          "Number of days for forecast (1-3)"
+        else
+          "Parameter: #{param_name}"
+        end
+      end
+    end
+  end
+end