legate 0.1.0

data/examples/02_multi_tool_agent.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# If running from project root: bundle exec ruby examples/02_multi_tool_agent.rb
+require_relative '../lib/legate'
+
+# Load .env and map GEMINI_API_KEY -> GOOGLE_API_KEY (as the `legate` CLI does).
+# The library never reads .env on its own; an application must opt in.
+Legate.load_environment
+
+puts '--- Multi-Tool Agent Example ---'
+
+# 1. --- Agent Definitions ---
+
+# Definition for the main multi-tool agent
+multi_tool_agent_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :multi_tool_agent
+  a.description 'An agent that can use multiple tools including echo, calculator, cat facts, the current time, and task delegation'
+  a.instruction 'You are a versatile assistant. Use the appropriate tool for the user\'s request. For calculations, use the calculator. For cat facts, use cat_facts. For the current date or time, use current_time. To delegate, use delegate_task.'
+  a.use_tool :echo
+  a.use_tool :calculator
+  a.use_tool :cat_facts      # Provided by Legate::Tools::CatFacts
+  a.use_tool :current_time   # Provided by Legate::Tools::CurrentTime
+  a.use_tool :delegate_task  # Provided by Legate::Tools::AgentTool
+end
+
+# Definition for the calculator agent that will be used for delegation
+calculator_agent_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :calculator_agent
+  a.description 'A calculator agent that can perform basic arithmetic operations'
+  a.instruction 'You are a calculator. Perform the requested calculation.'
+  a.model_name 'gemini-3.5-flash' # Optional: specify model for this agent
+  a.use_tool :calculator
+end
+
+# --- Register Calculator Agent Definition for AgentTool --- >
+# AgentTool will look up definitions in the GlobalDefinitionRegistry.
+Legate::GlobalDefinitionRegistry.register(calculator_agent_definition)
+puts "\nRegistered definition for '#{calculator_agent_definition.name}' in Legate::GlobalDefinitionRegistry."
+# <----------------------------------------------------------
+
+# Ensure all necessary tools are globally available/registered.
+# Standard tools like Echo, Calculator, AgentTool (delegate_task) are usually auto-registered.
+# For custom tools like CatFactsTool and RandomNumberTool, ensure they are loaded and registered
+# e.g., via `require` and `Legate::GlobalToolManager.register_tool(CatFactsTool)` if not already.
+# This example assumes they are available to the GlobalToolManager.
+
+# 2. --- Agent Instantiation ---
+agent = Legate::Agent.new(definition: multi_tool_agent_definition)
+
+puts "\nAgent '#{agent.name}' created with tools:"
+agent.tools.each { |tool| puts " - #{tool.name}" }
+
+# 3. --- Start Agent ---
+agent.start
+puts "\nAgent started:"
+puts " - #{agent.name}: Running: #{agent.running?}"
+
+# 4. --- Session Setup ---
+session_service = Legate::SessionService::InMemory.new
+session = session_service.create_session(app_name: agent.name, user_id: 'example_user')
+session_id = session.id
+puts "\nCreated session: #{session_id}"
+
+# 5. --- Task Execution Examples ---
+tasks = [
+  'Echo this message: Hello from multi-tool agent!',
+  'Calculate 15 * 7',
+  'Get me a cat fact',
+  'What is the current date and time?',
+  'Delegate this task to calculator_agent: what is 20 / 4'
+]
+
+# Array to store results for summary table
+task_results = []
+
+tasks.each_with_index do |task, index|
+  task_num = index + 1
+  puts "\n" + '=' * 40
+  puts "--- Task #{task_num}: '#{task}' ---"
+  puts '=' * 40
+
+  outcome_message = '[Execution Error]'
+  begin
+    result_event = agent.run_task(
+      session_id: session_id,
+      user_input: task,
+      session_service: session_service
+    )
+
+    # --- Extract final outcome for summary --- #
+    if result_event.is_a?(Legate::Event) && result_event.content.is_a?(Hash)
+      content = result_event.content
+      if content[:status] == :success
+        final_result = content[:result]
+        # Handle nested result from delegation
+        outcome_message = if final_result.is_a?(Hash) && final_result.key?(:status) && final_result[:status] == :success
+                            "Success: #{final_result[:result]}"
+                          else
+                            "Success: #{final_result}"
+                          end
+      elsif content[:status] == :error
+        outcome_message = "Error: #{content[:error_message]}"
+      else # Pending or other statuses
+        outcome_message = "Status: #{content[:status]}"
+        outcome_message += " (#{content[:message]})" if content[:message]
+      end
+    else
+      outcome_message = "[Unexpected Result Format]: #{result_event.inspect}"
+    end
+  rescue StandardError => e
+    outcome_message = "[Execution Error]: #{e.message}"
+    puts "\nError executing Task #{task_num}: #{e.class} - #{e.message}"
+    puts e.backtrace.first(5).join("\n")
+  end
+  # Store the result
+  task_results << { task: task, outcome: outcome_message }
+  puts '=' * 40 # End separator for this task's logs
+end
+
+# 6. --- Print Summary Table --- #
+puts "\n" + '#' * 50
+puts '### Task Execution Summary ###'
+puts '#' * 50
+# Determine column width (simple approach)
+max_task_len = task_results.map { |r| r[:task].length }.max || 40
+puts "
+| #{'Task'.ljust(max_task_len)} | Outcome                         |"
+puts "|#{'-' * (max_task_len + 2)}|---------------------------------|"
+task_results.each do |r|
+  puts "| #{r[:task].ljust(max_task_len)} | #{r[:outcome]} "
+end
+puts ''
+
+# 7. --- Stop Agent --- #
+agent.stop
+puts "\nAgents stopped:"
+puts " - #{agent.name}: Running: #{agent.running?}"
+
+puts "\n--- Example Complete ---"

data/examples/03_custom_tool.rb

@@ -0,0 +1,93 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Creating a Custom Tool
+#
+# This example shows how to build a custom tool from scratch using the
+# Legate::Tool DSL: define parameters, implement perform_execution,
+# and wire it into an agent.
+#
+# Run with: bundle exec ruby examples/03_custom_tool.rb
+
+require_relative '../lib/legate'
+
+# Load .env and map GEMINI_API_KEY -> GOOGLE_API_KEY (as the `legate` CLI does).
+# The library never reads .env on its own; an application must opt in.
+Legate.load_environment
+
+puts '--- Custom Tool Example ---'
+
+# 1. Define a custom tool by inheriting from Legate::Tool
+class GreetingTool < Legate::Tool
+  tool_description 'Generates a personalized greeting message.'
+
+  parameter :name, type: :string, required: true,
+                   description: 'The name of the person to greet'
+
+  parameter :style, type: :string, required: false,
+                    description: 'Greeting style: formal, casual, or pirate (default: casual)'
+
+  private
+
+  def perform_execution(params, _context)
+    name = params[:name]
+    style = (params[:style] || 'casual').downcase
+
+    greeting = case style
+               when 'formal'
+                 "Good day, #{name}. It is a pleasure to make your acquaintance."
+               when 'pirate'
+                 "Ahoy, #{name}! Welcome aboard, ye scurvy dog!"
+               else
+                 "Hey #{name}, nice to meet you!"
+               end
+
+    { status: :success, result: greeting }
+  rescue StandardError => e
+    { status: :error, error_message: "Greeting failed: #{e.message}" }
+  end
+end
+
+# 2. Register the tool globally so agents can find it by name
+Legate::GlobalToolManager.register_tool(GreetingTool)
+puts "Registered tool: #{GreetingTool.tool_name}"
+
+# 3. Use the tool directly (without an agent)
+puts "\n--- Direct Tool Usage ---"
+tool = GreetingTool.new
+context = Legate::ToolContext.new(
+  session_id: 'demo-session',
+  user_id: 'demo-user',
+  app_name: 'custom_tool_example'
+)
+
+%w[casual formal pirate].each do |style|
+  result = tool.execute({ name: 'Alice', style: style }, context)
+  puts "  #{style}: #{result[:result]}"
+end
+
+# 4. Wire the tool into an agent
+puts "\n--- Agent with Custom Tool ---"
+agent_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :greeter_agent
+  a.description 'An agent that greets people in different styles'
+  a.instruction 'You are a greeting specialist. Use the greeting tool to greet people. Choose the style that best fits the request.'
+  a.use_tool :greeting_tool
+end
+
+agent = Legate::Agent.new(definition: agent_definition)
+agent.start
+
+session_service = Legate::SessionService::InMemory.new
+session = session_service.create_session(app_name: agent.name, user_id: 'example_user')
+
+result = agent.run_task(
+  session_id: session.id,
+  user_input: 'Greet Captain Blackbeard in pirate style',
+  session_service: session_service
+)
+
+puts "Agent result: #{result.content.inspect}"
+
+agent.stop
+puts "\n--- Example Complete ---"

data/examples/04_agent_instructions.rb

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Agent Instructions (System Prompts)
+#
+# Demonstrates defining an agent with specific instructions (system prompt)
+# that guide its behavior during planning.
+#
+# Run with: bundle exec ruby examples/04_agent_instructions.rb
+
+$LOAD_PATH.unshift(File.expand_path('../lib', __dir__))
+
+require 'legate'
+
+# Load .env and map GEMINI_API_KEY -> GOOGLE_API_KEY (as the `legate` CLI does).
+# The library never reads .env on its own; an application must opt in.
+Legate.load_environment
+require 'legate/tools/echo'       # Ensure tool classes are loaded for GlobalToolManager
+require 'legate/tools/calculator' # to find them by name.
+
+# 1. Define the Agent with Instructions
+# =====================================
+
+# Create the AgentDefinition object first
+concise_calculator_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :concise_calculator # Use symbol for name
+  a.description 'A calculator agent that tries to be concise.'
+  # Provide instructions to the planner
+  a.instruction 'You are a calculator assistant. When asked to calculate, use the calculator tool. Respond only with the final numerical result, no extra words.'
+  # Add necessary tools by name
+  a.use_tool :calculator
+  a.use_tool :echo # Echo might be used by fallback or if planner chooses it
+end
+
+# Instantiate the Agent using the definition
+agent = Legate::Agent.new(definition: concise_calculator_definition)
+
+# 2. Setup Session Service
+# ========================
+session_service = Legate::SessionService::InMemory.new
+session = session_service.create_session(app_name: agent.name, user_id: 'instruct_user')
+
+# 3. Start Agent and Run Task
+# ==========================
+begin
+  puts "Starting agent '#{agent.name}'..."
+  agent.start
+
+  task = 'What is 5 plus 12?'
+  puts "\nRunning task: '#{task}'"
+
+  # The planner will receive the instruction along with the task and tool list.
+  # The LLM should ideally follow the instruction to generate a plan
+  # that results in a concise response (though the final response formatting
+  # also depends on the tool's output and agent logic).
+  result_event = agent.run_task(
+    session_id: session.id,
+    user_input: task,
+    session_service: session_service
+  )
+
+  puts "\n--- Agent Response ---"
+  puts "  Role: #{result_event.role}"
+  puts "  Content: #{result_event.content.inspect}"
+
+  # Example of a task the instructions might prevent (if LLM obeys)
+  task_inappropriate = 'Tell me a long story about the number 7.'
+  puts "\nRunning task: '#{task_inappropriate}' (Agent instructed to only calculate)"
+  result_event_2 = agent.run_task(
+    session_id: session.id,
+    user_input: task_inappropriate,
+    session_service: session_service
+  )
+  puts "\n--- Agent Response (Second Task) ---"
+  puts "  Role: #{result_event_2.role}"
+  puts "  Content: #{result_event_2.content.inspect}"
+  # Expected: Agent might respond with planning failure because the task doesn't match its instructions.
+ensure
+  puts "\nStopping agent '#{agent.name}'..."
+  agent.stop
+  puts 'Agent stopped.'
+end
+
+puts "\nExample finished."

data/examples/05_state_and_sessions.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Session State Management
+#
+# This example demonstrates how Legate manages state:
+# - Creating sessions with initial state
+# - Reading and writing state via the session service
+# - How tools produce state deltas that agents apply
+# - Inspecting event history after task execution
+#
+# Run with: bundle exec ruby examples/05_state_and_sessions.rb
+
+require_relative '../lib/legate'
+
+# Load .env and map GEMINI_API_KEY -> GOOGLE_API_KEY (as the `legate` CLI does).
+# The library never reads .env on its own; an application must opt in.
+Legate.load_environment
+
+puts '--- State & Sessions Example ---'
+
+# 1. Create a session service and session with initial state
+session_service = Legate::SessionService::InMemory.new
+session = session_service.create_session(
+  app_name: 'state_example',
+  user_id: 'demo_user',
+  initial_state: { visits: 0, greeting: 'Welcome!' }
+)
+session_id = session.id
+
+puts "Created session: #{session_id}"
+puts 'Initial state:'
+session.state.each_pair { |k, v| puts "  #{k}: #{v.inspect}" }
+
+# 2. Direct state manipulation via session service
+puts "\n--- Session Service State Operations ---"
+session_service.set_state(session_id: session_id, key: :visits, value: 1)
+session_service.set_state(session_id: session_id, key: :preference, value: 'dark_mode')
+
+visits = session_service.get_state(session_id: session_id, key: :visits)
+pref = session_service.get_state(session_id: session_id, key: :preference)
+puts "  visits: #{visits}"
+puts "  preference: #{pref}"
+
+# 3. How tools interact with state
+puts "\n--- Tool State Pattern ---"
+puts '  Tools use context.state_get/state_set to read/write state.'
+puts "  state_set accumulates a 'pending delta' that the agent applies"
+puts '  to the session after the tool completes. This ensures state'
+puts '  changes are tracked alongside events.'
+
+# 4. Create an agent and run a task to see events and state in action
+puts "\n--- Agent Task with Events ---"
+agent_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :state_demo_agent
+  a.description 'Demonstrates state in agent context'
+  a.instruction 'You are a helpful agent. Echo back what the user says.'
+  a.use_tool :echo
+end
+
+agent = Legate::Agent.new(definition: agent_definition)
+agent.start
+
+result = agent.run_task(
+  session_id: session_id,
+  user_input: 'Remember that I visited the examples page',
+  session_service: session_service
+)
+
+puts "  Task result: #{result.content.inspect}"
+
+# 5. Inspect event history
+puts "\n--- Event History ---"
+final_session = session_service.get_session(session_id: session_id)
+puts "  Total events: #{final_session.events.size}"
+final_session.events.each_with_index do |event, i|
+  role = event.role
+  content_preview = case event.content
+                    when String then event.content[0..60]
+                    when Hash then event.content[:status] || event.content.keys.first
+                    else event.content.class
+                    end
+  puts "  #{i + 1}. [#{role}] #{content_preview}"
+end
+
+# 6. Final state
+puts "\n--- Final State ---"
+final_session.state.each_pair { |k, v| puts "  #{k}: #{v.inspect}" }
+
+agent.stop
+puts "\n--- Example Complete ---"

data/examples/06_callbacks.rb

@@ -0,0 +1,186 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# If running from project root: bundle exec ruby examples/06_callbacks.rb
+require_relative '../lib/legate'
+
+# Load .env and map GEMINI_API_KEY -> GOOGLE_API_KEY (as the `legate` CLI does).
+# The library never reads .env on its own; an application must opt in.
+Legate.load_environment
+
+puts '--- Legate Callbacks Basic Example ---'
+
+# Helper method to safely inspect objects
+def inspect_object(obj)
+  return 'nil' if obj.nil?
+
+  if obj.is_a?(Hash) || obj.is_a?(Array)
+    obj.inspect
+  else
+    # For other objects, get their instance variables and methods
+    vars = obj.instance_variables.map { |v| "#{v}=#{obj.instance_variable_get(v).inspect}" }
+    methods = obj.public_methods(false).sort.map(&:to_s)
+    "Object of class #{obj.class}\nInstance vars: #{vars.join(', ')}\nMethods: #{methods.join(', ')}"
+  end
+end
+
+# 1. --- Define our callback functions ---
+
+# Agent callbacks
+before_agent_callback = lambda do |context|
+  puts "\n[AGENT CALLBACK] Before agent processes request"
+  puts "  Context structure: #{inspect_object(context)}"
+  puts "  Session ID: #{context.session_id}" if context.respond_to?(:session_id)
+end
+
+# The documentation mentioned only 1 parameter, but the error suggests 2 are passed
+after_agent_callback = lambda do |context, *args|
+  puts "\n[AGENT CALLBACK] After agent completed request"
+  puts "  Context structure: #{inspect_object(context)}"
+  puts "  Additional args: #{args.inspect}" if args.any?
+end
+
+# Model callbacks - expecting 2 arguments
+before_model_callback = lambda do |context, prompt|
+  puts "\n[MODEL CALLBACK] Before sending prompt to LLM"
+  puts "  Context structure: #{inspect_object(context)}"
+
+  if prompt.is_a?(String)
+    preview = prompt.length > 100 ? "#{prompt[0, 100]}..." : prompt
+    puts "  Prompt: #{preview}"
+  else
+    puts "  Prompt: #{prompt.inspect}"
+  end
+
+  # Return the prompt unchanged
+  prompt
+end
+
+after_model_callback = lambda do |context, response|
+  puts "\n[MODEL CALLBACK] After receiving response from LLM"
+  puts "  Context structure: #{inspect_object(context)}"
+
+  if response.is_a?(String)
+    preview = response.length > 100 ? "#{response[0, 100]}..." : response
+    puts "  Response: #{preview}"
+  else
+    puts "  Response: #{response.inspect}"
+  end
+
+  # Return the response unchanged
+  response
+end
+
+# Tool callbacks - expecting 3 arguments
+before_tool_callback = lambda do |context, tool, params|
+  puts "\n[TOOL CALLBACK] Before executing tool"
+  puts "  Context structure: #{inspect_object(context)}"
+  puts "  Tool: #{tool.name}" if tool.respond_to?(:name)
+  puts "  Parameters: #{params.inspect}"
+
+  # Return the original parameters, not the context or tool
+  # The expected parameters format is a Hash like {message: "Hello, world"}
+  if params.is_a?(Hash)
+    params
+  elsif params.is_a?(Legate::ToolContext)
+    # If we're passed a ToolContext object, try to extract parameters from session
+    puts '  WARNING: Received ToolContext instead of params hash'
+
+    # Get parameters from the session events if possible
+    if params.respond_to?(:session_id) && params.session_id && defined?($session_service)
+      begin
+        session = $session_service.get_session(session_id: params.session_id)
+        if session
+          events = session.events
+          # Find the most recent tool_request event for this tool
+          tool_name = tool.respond_to?(:name) ? tool.name.to_s : nil
+          if tool_name
+            # The tool field might be stored in different ways
+            tool_request = events.reverse.find do |e|
+              e.role == :tool_request &&
+                ((e.respond_to?(:tool) && e.tool == tool_name) ||
+                 (e.respond_to?(:[]) && e[:tool] == tool_name))
+            end
+
+            if tool_request && tool_request.respond_to?(:content) && tool_request.content.is_a?(Hash)
+              # We found the parameters in the session events
+              return tool_request.content
+            end
+          end
+        end
+      rescue StandardError => e
+        puts "  WARNING: Error getting session events: #{e.message}"
+      end
+    end
+
+    # Default fallback for echo tool
+    { message: 'Hello, world! This is a callback example.' }
+  else
+    # If all else fails, return empty params
+    puts "  WARNING: Unexpected params type: #{params.class}"
+    {}
+  end
+end
+
+after_tool_callback = lambda do |context, tool, result|
+  puts "\n[TOOL CALLBACK] After executing tool"
+  puts "  Context structure: #{inspect_object(context)}"
+  puts "  Tool: #{tool.name}" if tool.respond_to?(:name)
+  puts "  Result: #{result.inspect}"
+
+  # Return the result unchanged
+  result
+end
+
+# 2. --- Agent Definition with Callbacks ---
+echo_agent_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :echo_with_callbacks
+  a.description 'An echo agent that demonstrates callbacks'
+  a.instruction 'You are an echo agent. Your task is to repeat the user\'s input exactly.'
+
+  # Register the callbacks
+  a.before_agent_callback(&before_agent_callback)
+  a.after_agent_callback(&after_agent_callback)
+
+  a.before_model_callback(&before_model_callback)
+  a.after_model_callback(&after_model_callback)
+
+  a.before_tool_callback(&before_tool_callback)
+  a.after_tool_callback(&after_tool_callback)
+
+  a.use_tool :echo
+end
+
+# 3. --- Agent Instantiation ---
+agent = Legate::Agent.new(definition: echo_agent_definition)
+puts "\nAgent '#{agent.name}' created with callbacks registered"
+
+# 4. --- Start Agent and Setup Session ---
+agent.start
+session_service = Legate::SessionService::InMemory.new
+# Make session_service accessible to callbacks
+$session_service = session_service
+session = session_service.create_session(app_name: agent.name, user_id: 'callback_example_user')
+session_id = session.id
+puts "\nCreated session: #{session_id}"
+
+# 5. --- Execute Task and Observe Callbacks ---
+task = 'Hello, world! This is a callback example.'
+puts "\nExecuting task: '#{task}'"
+
+begin
+  result = agent.run_task(
+    session_id: session_id,
+    user_input: task,
+    session_service: session_service
+  )
+
+  puts "\nFinal result: #{result.content.inspect}"
+rescue StandardError => e
+  puts "\nError executing task: #{e.class} - #{e.message}"
+  puts e.backtrace.first(5).join("\n")
+end
+
+# 6. --- Stop Agent ---
+agent.stop
+puts "\n--- Example Complete ---"