legate 0.1.0

data/examples/07_async_jobs.rb

@@ -0,0 +1,112 @@
+# File: examples/07_async_jobs.rb
+# frozen_string_literal: true
+
+puts 'To see this work end-to-end:'
+puts '1. Run this script: bundle exec ruby examples/07_async_jobs.rb'
+
+# This example demonstrates how to use an Legate tool that starts
+# an asynchronous background job and how to check its status.
+
+# --- Setup ---
+# Load Legate and necessary components
+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
+
+# Load the custom tool class. Its definition (name, params) will be used by the GlobalToolManager.
+require_relative 'tools/sleepy_tool' # Provides :start_sleepy_job
+# Legate::Tools::CheckJobStatusTool (providing :check_job_status) is loaded by Legate core.
+
+puts '--- Async Job Example ---'
+
+# --- Agent Definition ---
+puts "\nSetting up agent definition..."
+async_job_runner_definition = Legate::AgentDefinition.new.define do |a|
+  a.name :async_job_runner
+  a.description 'An agent that can start and check background jobs.'
+  a.instruction 'You manage asynchronous jobs. Use start_sleepy_job to initiate them and check_job_status to monitor.'
+  a.use_tool :start_sleepy_job # Provided by SleepyTool
+  a.use_tool :check_job_status # Provided by CheckJobStatusTool
+end
+
+# --- Agent Instantiation ---
+agent = Legate::Agent.new(definition: async_job_runner_definition)
+
+# The check_job_status tool is now added via tool_classes
+puts "Agent Tools: #{agent.tools.map(&:name)}"
+
+# --- Session Setup ---
+# Use in-memory session for this example
+session_service = Legate::SessionService::InMemory.new
+session = session_service.create_session(app_name: agent.name, user_id: 'async_example_user')
+puts "Created session: #{session.id}"
+
+# --- Task Execution ---
+
+# Start the agent runtime
+agent.start
+
+# 1. Start the sleepy job
+task_input_start = "Start a sleepy job that waits 5 seconds with message 'Hello Async!'"
+puts "\nRunning task: '#{task_input_start}'"
+
+# Simulate planner choosing the sleepy_tool
+# In a real scenario, the planner would generate this plan:
+plan_start = [
+  { tool: :start_sleepy_job, params: { duration: 5, message: 'Hello Async!' } }
+]
+
+# Execute the plan step manually for demonstration
+# (Alternatively, use agent.run_task and provide prompt engineering for the LLM to generate the plan)
+puts "Executing plan step: #{plan_start.first.inspect}"
+
+# Need the session object for execute_step
+current_session = session_service.get_session(session_id: session.id)
+
+start_result_hash = agent.send(:execute_step, plan_start.first, current_session, session_service)
+
+puts "\nResult from starting the job:"
+puts JSON.pretty_generate(start_result_hash)
+
+unless start_result_hash[:status] == :pending && start_result_hash[:job_id]
+  puts "\nError: Expected pending status with job_id! Aborting."
+  agent.stop
+  exit 1
+end
+
+job_id = start_result_hash[:job_id]
+puts "\nJob enqueued with ID: #{job_id}"
+puts '(The job runs in a background thread and will complete after the specified duration)'
+
+# 2. Check the job status (immediately - likely still pending)
+task_input_check = "Check status for job #{job_id}"
+puts "\nRunning task: '#{task_input_check}'"
+
+plan_check = [
+  { tool: :check_job_status, params: { job_id: job_id } }
+]
+
+puts "Executing plan step: #{plan_check.first.inspect}"
+check_result_hash_1 = agent.send(:execute_step, plan_check.first, current_session, session_service)
+
+puts "\nResult from first status check:"
+puts JSON.pretty_generate(check_result_hash_1)
+
+# 3. Wait and check again
+wait_time = 7 # Wait longer than the job's sleep duration
+puts "\nWaiting #{wait_time} seconds for the job to likely complete..."
+sleep wait_time
+
+puts "\nRunning task: '#{task_input_check}' (again)"
+puts "Executing plan step: #{plan_check.first.inspect}"
+check_result_hash_2 = agent.send(:execute_step, plan_check.first, current_session, session_service)
+
+puts "\nResult from second status check:"
+puts JSON.pretty_generate(check_result_hash_2)
+
+# Stop the agent runtime
+agent.stop
+
+puts "\n--- Example Finished ---"

data/examples/08_loop_agent.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+# Example demonstrating the Legate::Agents::LoopAgent which executes sub-agents in a loop
+# until a termination condition is met or max iterations are reached.
+
+$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/agents/loop_agent'
+
+# First, define sub-agents that will be used in the loop
+
+# 1. Counter agent - increments a counter in session state
+counter_agent = Legate::AgentDefinition.new.define do |a|
+  a.name :counter_agent
+  a.description 'Increments a counter in session state'
+  a.instruction 'You increment a counter and report the new count.'
+  a.use_tool :echo
+  a.output_key :counter_result
+end
+
+# Register the agent definition so it can be found by name
+Legate::GlobalDefinitionRegistry.register(counter_agent)
+
+# 2. Check condition agent - examines count and decides if we need to continue
+condition_agent = Legate::AgentDefinition.new.define do |a|
+  a.name :condition_agent
+  a.description 'Checks if loop should continue based on count'
+  a.instruction 'Check the counter and set done to true if target is reached.'
+  a.use_tool :echo
+  a.output_key :done
+end
+
+# Register the agent definition
+Legate::GlobalDefinitionRegistry.register(condition_agent)
+
+# Now define the loop agent that uses the sub-agents
+loop_agent = Legate::AgentDefinition.new.define do |a|
+  a.name :loop_demo_agent
+  a.description 'Demonstrates loop agent functionality'
+  a.instruction 'You run a loop that counts until a condition is met.'
+  a.agent_type :loop # This is important - specifies this is a loop agent
+
+  # Sub-agents to execute in each loop iteration (in sequence)
+  a.loop_sub_agents %i[counter_agent condition_agent]
+
+  # Maximum number of iterations (safety valve)
+  a.loop_max_iterations 5
+
+  # Loop termination condition
+  a.loop_condition(:done, true)
+
+  # Store final result
+  a.output_key :loop_result
+end
+
+# Register the loop agent definition
+Legate::GlobalDefinitionRegistry.register(loop_agent)
+
+puts 'Agent definitions registered. Creating session and agent instances...'
+
+# Create a session service for state management
+session_service = Legate::SessionService::InMemory.new
+user_id = 'demo-user'
+app_name = 'loop-example'
+
+# Create a session
+session = session_service.create_session(
+  app_name: app_name,
+  user_id: user_id,
+  initial_state: { count: 0 }
+)
+session_id = session.id
+
+puts "Created session with ID: #{session_id}"
+
+# Create agent instances
+
+# 1. Counter Agent implementation
+counter_agent_instance = Legate::Agent.new(definition: counter_agent)
+
+# Override execute_plan to implement the counting logic
+def counter_agent_instance.execute_plan(_plan, session, session_service, _invocation_id = nil)
+  # Get the session ID from the session object
+  session_id = session.id
+
+  # Get current count from session state
+  current_count = session_service.get_state(session_id: session_id, key: :count) || 0
+
+  # Increment count
+  new_count = current_count + 1
+
+  # Update session state with new count
+  session_service.set_state(session_id: session_id, key: :count, value: new_count)
+
+  # Create success result with count info
+  result_hash = {
+    status: :success,
+    result: "Counter incremented to #{new_count}"
+  }
+
+  # Return the details and the result in the format expected by the parent method
+  { details: [result_hash], last_result: result_hash }
+end
+
+# 2. Condition Agent implementation
+condition_agent_instance = Legate::Agent.new(definition: condition_agent)
+
+# Override execute_plan to implement the condition check
+def condition_agent_instance.execute_plan(_plan, session, session_service, _invocation_id = nil)
+  # Get the session ID from the session object
+  session_id = session.id
+
+  # Get current count
+  current_count = session_service.get_state(session_id: session_id, key: :count) || 0
+
+  # Check if we've reached our target count (3 for this example)
+  target = 3
+  done = current_count >= target
+
+  # Set the done flag in session state to control loop termination
+  session_service.set_state(session_id: session_id, key: :done, value: done)
+
+  # Create success result
+  result_hash = {
+    status: :success,
+    result: if done
+              "Target count reached (#{current_count} >= #{target}). Loop should terminate."
+            else
+              "Target count not yet reached (#{current_count} < #{target}). Loop should continue."
+            end
+  }
+
+  # Return the details and the result in the format expected by the parent method
+  { details: [result_hash], last_result: result_hash }
+end
+
+# Create the loop agent that will coordinate the whole process
+loop_agent_instance = Legate::Agents::LoopAgent.new(
+  definition: loop_agent,
+  sub_agents: [counter_agent_instance, condition_agent_instance]
+)
+
+# Start all agents
+puts 'Starting agents...'
+counter_agent_instance.start
+condition_agent_instance.start
+loop_agent_instance.start
+
+puts 'Starting loop agent execution...'
+puts 'Loop will continue until count reaches 3 or 5 max iterations...'
+puts '------------------------------'
+
+# Execute the loop agent
+result = loop_agent_instance.run_task(
+  session_id: session_id,
+  user_input: 'Start counting loop',
+  session_service: session_service
+)
+
+puts 'Loop agent execution complete!'
+puts '------------------------------'
+puts "Final result: #{result.content[:status]}"
+puts "Iterations completed: #{result.content[:iterations_completed] || 'N/A'}"
+puts "Loop condition met? #{result.content[:loop_condition_met] || 'N/A'}"
+puts
+
+if result.content[:status] == :error
+  puts "Error: #{result.content[:error_message]}"
+else
+  puts 'Iteration details:'
+
+  # Print details from each iteration if available
+  if result.content[:iterations]
+    result.content[:iterations].each_with_index do |iteration, i|
+      puts "Iteration #{i + 1}:"
+
+      # Print each sub-agent's results in this iteration
+      iteration[:results].each do |sub_result|
+        puts "  - #{sub_result[:agent]}: #{sub_result[:result][:result]}"
+      end
+      puts
+    end
+  else
+    puts 'No iteration details available.'
+  end
+
+  # Check final state values
+  final_count = session_service.get_state(session_id: session_id, key: :count)
+  puts "Final count in session state: #{final_count}"
+  puts "Done flag in session state: #{session_service.get_state(session_id: session_id, key: :done)}"
+end
+
+puts '------------------------------'

data/examples/09_sequential_workflow.rb

@@ -0,0 +1,40 @@
+# examples/09_sequential_workflow.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
+
+# 1. Define Worker Agents
+Legate::Agent.define do |agent|
+  agent.name :data_gatherer
+  agent.instruction 'Gather data about the topic.'
+  agent.use_tool :echo # Simulation
+  agent.output_key :gathered_data
+end
+
+Legate::Agent.define do |agent|
+  agent.name :data_processor
+  agent.instruction 'Process the gathered data.'
+  agent.use_tool :echo # Simulation
+  agent.output_key :processed_data
+end
+
+Legate::Agent.define do |agent|
+  agent.name :report_writer
+  agent.instruction 'Write a report based on processed data.'
+  agent.use_tool :echo # Simulation
+end
+
+# 2. Define Sequential Workflow
+Legate::Agent.define do |agent|
+  agent.name :report_pipeline
+  agent.agent_type :sequential
+  agent.description 'A pipeline to gather, process, and write reports.'
+  agent.instruction 'Execute the pipeline.'
+
+  # Order matters!
+  agent.sequential_sub_agents :data_gatherer, :data_processor, :report_writer
+end
+
+puts 'Defined Sequential Workflow: :report_pipeline'

data/examples/10_parallel_workflow.rb

@@ -0,0 +1,34 @@
+# examples/10_parallel_workflow.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
+
+# 1. Define Specialized Analysts
+Legate::Agent.define do |agent|
+  agent.name :market_analyst
+  agent.instruction 'Analyze market trends.'
+  agent.use_tool :echo
+  agent.output_key :market_analysis
+end
+
+Legate::Agent.define do |agent|
+  agent.name :tech_analyst
+  agent.instruction 'Analyze technology trends.'
+  agent.use_tool :echo
+  agent.output_key :tech_analysis
+end
+
+# 2. Define Parallel Workflow
+Legate::Agent.define do |agent|
+  agent.name :comprehensive_analysis
+  agent.agent_type :parallel
+  agent.description 'Run analyses concurrently.'
+  agent.instruction 'Analyze the sector.'
+
+  # Will run at the same time
+  agent.parallel_sub_agents :market_analyst, :tech_analyst
+end
+
+puts 'Defined Parallel Workflow: :comprehensive_analysis'

data/examples/11_agent_delegation.rb

@@ -0,0 +1,24 @@
+# examples/11_agent_delegation.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
+
+# 1. Define a Specialist
+Legate::Agent.define do |agent|
+  agent.name :math_expert
+  agent.instruction 'You are a math expert. Solve math problems.'
+  agent.use_tool :calculator
+end
+
+# 2. Define a Manager who delegates
+Legate::Agent.define do |agent|
+  agent.name :project_manager
+  agent.instruction 'You manage the project. If you see a math problem, delegate it to the math expert.'
+
+  # Allow delegation
+  agent.can_delegate_to :math_expert
+end
+
+puts 'Defined Delegation System: :project_manager can delegate to :math_expert'

data/examples/12_http_client_tool.rb

@@ -0,0 +1,156 @@
+# File: examples/12_http_client_tool.rb
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'legate' # Load Legate framework
+
+# 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/base/http_client' # Load the HttpClient module
+
+# --- Define the Custom Tool ---
+class JsonPlaceholderTool < Legate::Tool
+  include Legate::Tools::Base::HttpClient # Include the mixin
+
+  # --- Tool Metadata ---
+  tool_name # Infer name from class: json_placeholder_tool
+  tool_description 'Fetches or creates posts on JSONPlaceholder API.'
+
+  parameter :action, type: :string, required: true, description: 'Action to perform: "get" or "create".'
+  parameter :post_id, type: :integer, required: false, description: 'The ID of the post to fetch (required for "get").'
+  parameter :post_data, type: :hash, required: false,
+                        description: 'Data for the new post (required for "create"). Example: { title: "foo", body: "bar", userId: 1 }'
+  # --- End Metadata ---
+
+  API_BASE_URL = 'https://jsonplaceholder.typicode.com/'
+
+  def initialize(**options)
+    super(**options)
+    # Setup the client for JSONPlaceholder
+    # Use default options (timeouts, persistent connection, etc.)
+    # Specify default Accept header
+    setup_http_client(
+      base_url: API_BASE_URL,
+      headers: { 'Accept' => 'application/json' }
+      # options: { read_timeout: 5 } # Example: Override default timeout
+    )
+    Legate.logger.info 'JsonPlaceholderTool initialized.'
+  end
+
+  private
+
+  # Main logic for the tool
+  def perform_execution(params, context)
+    action = params.fetch(:action).downcase
+
+    case action
+    when 'get'
+      fetch_post(params, context)
+    when 'create'
+      create_post(params, context)
+    else
+      raise Legate::ToolArgumentError, "Invalid action specified: '#{action}'. Use 'get' or 'create'."
+    end
+
+  # Rescue ToolErrors raised by HttpClient or argument validation
+  rescue Legate::ToolError => e
+    Legate.logger.error("JsonPlaceholderTool Error: #{e.class} - #{e.message}")
+    # You might want more specific handling based on e.g., e.is_a?(Legate::ToolHttpError)
+    { status: :error, error_message: "API operation failed: #{e.message}" }
+  end
+
+  # --- Helper Methods ---
+
+  def fetch_post(params, _context)
+    post_id = params[:post_id]
+    raise Legate::ToolArgumentError, "Missing required parameter: post_id for action 'get'" unless post_id
+
+    Legate.logger.info "Fetching post with ID: #{post_id}"
+    # Use the http_get helper from HttpClient
+    response = http_get("posts/#{post_id}") # Path relative to base_url
+
+    # Parse the response body
+    begin
+      data = JSON.parse(response.body)
+      { status: :success, result: data }
+    rescue JSON::ParserError => e
+      raise Legate::ToolError, "Failed to parse JSON response: #{e.message}"
+    end
+  end
+
+  def create_post(params, _context)
+    post_data = params[:post_data]
+    unless post_data.is_a?(Hash) && !post_data.empty?
+      raise Legate::ToolArgumentError,
+            "Missing required parameter: post_data for action 'create'"
+    end
+
+    Legate.logger.info "Creating post with data: #{post_data.inspect}"
+    # Use the http_post helper. Payload is a Hash, HttpClient handles JSON encoding
+    # and sets Content-Type: application/json automatically.
+    response = http_post('posts', body: post_data)
+
+    # Check response status (optional, HttpClient raises ToolHttpError for 4xx/5xx)
+    # Here we just return the parsed response body which includes the new ID
+    begin
+      created_post = JSON.parse(response.body)
+      { status: :success, result: created_post }
+    rescue JSON::ParserError => e
+      raise Legate::ToolError, "Failed to parse JSON response after creating post: #{e.message}"
+    end
+  end
+end
+
+# --- Example Usage ---
+
+# Ensure Legate logger is setup (usually done in main application)
+Legate.logger.level = Logger::INFO
+
+# Create an instance of the tool
+placeholder_tool = JsonPlaceholderTool.new
+
+# Create a dummy context (provide required keywords)
+dummy_context = Legate::ToolContext.new(
+  session_id: 'dummy-session-123',
+  user_id: 'example-user',
+  app_name: 'http_client_example'
+)
+
+# Example 1: Fetch post with ID 1
+puts "\n--- Fetching Post 1 ---"
+fetch_params = { action: 'get', post_id: 1 }
+fetch_result = placeholder_tool.execute(fetch_params, context: dummy_context)
+puts "Result: #{fetch_result.inspect}"
+
+puts "\n--- Fetching Non-existent Post 999 ---"
+fetch_params_bad = { action: 'get', post_id: 999 }
+fetch_result_bad = placeholder_tool.execute(fetch_params_bad, context: dummy_context)
+puts "Result: #{fetch_result_bad.inspect}" # Expects :error status due to 404
+
+# Example 2: Create a new post
+puts "\n--- Creating New Post ---"
+create_params = {
+  action: 'create',
+  post_data: {
+    title: 'Legate Test Post',
+    body: 'This post was created by the Legate HttpClient example.',
+    userId: 5
+  }
+}
+create_result = placeholder_tool.execute(create_params, context: dummy_context)
+puts "Result: #{create_result.inspect}" # Expects :success with new post data (including ID)
+
+# Example 3: Invalid action
+puts "\n--- Invalid Action (Expected Error) ---"
+puts '(This demonstrates the tool raising ToolArgumentError for unsupported actions)'
+invalid_params = { action: 'delete', post_id: 1 } # Action not supported by our tool
+invalid_result = placeholder_tool.execute(invalid_params, context: dummy_context)
+puts "Result: #{invalid_result.inspect}" # Expects :error status
+
+# Example 4: Missing required param
+puts "\n--- Missing Parameter (Expected Error) ---"
+puts '(This demonstrates the tool raising ToolArgumentError for missing required params)'
+missing_params = { action: 'get' } # Missing post_id
+missing_result = placeholder_tool.execute(missing_params, context: dummy_context)
+puts "Result: #{missing_result.inspect}" # Expects :error status