simple_acp 0.0.1

data/examples/05_await_resume/server.rb

@@ -0,0 +1,114 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Await/Resume Example - Server
+#
+# Demonstrates the await/resume pattern for interactive multi-step flows.
+# The agent can pause execution and request input from the client.
+#
+# Run with: ruby examples/05_await_resume/server.rb
+# Then connect with: ruby examples/05_await_resume/client.rb
+
+require_relative "../../lib/simple_acp"
+
+server = SimpleAcp::Server::Base.new
+
+# Simple single-question agent
+server.agent("greeter",
+  description: "Asks for your name and greets you"
+) do |context|
+  if context.resume_message
+    # Resume: we have the client's response
+    name = context.resume_message.text_content
+    SimpleAcp::Models::Message.agent("Hello, #{name}! Nice to meet you!")
+  else
+    # Initial call: ask for input
+    context.await_message(
+      SimpleAcp::Models::Message.agent("What is your name?")
+    )
+  end
+end
+
+# Multi-step wizard using state to track progress
+server.agent("survey",
+  description: "A multi-step survey that collects information"
+) do |context|
+  # Use state to track current step and collected data
+  survey_state = context.state || { step: 0, answers: {} }
+  step = survey_state[:step]
+
+  case step
+  when 0
+    # Step 1: Ask for name
+    context.set_state({ step: 1, answers: {} })
+    context.await_message(
+      SimpleAcp::Models::Message.agent("Welcome to the survey! Question 1: What is your name?")
+    )
+
+  when 1
+    # Step 2: Got name, ask for favorite color
+    answers = survey_state[:answers].merge("name" => context.resume_message&.text_content)
+    context.set_state({ step: 2, answers: answers })
+    context.await_message(
+      SimpleAcp::Models::Message.agent("Thanks #{answers['name']}! Question 2: What is your favorite color?")
+    )
+
+  when 2
+    # Step 3: Got color, ask for favorite number
+    answers = survey_state[:answers].merge("color" => context.resume_message&.text_content)
+    context.set_state({ step: 3, answers: answers })
+    context.await_message(
+      SimpleAcp::Models::Message.agent("Great choice! Question 3: What is your favorite number?")
+    )
+
+  when 3
+    # Final step: Got all answers, return summary
+    answers = survey_state[:answers].merge("number" => context.resume_message&.text_content)
+    context.set_state({ step: 0, answers: {} })  # Reset for next survey
+
+    summary = <<~SUMMARY
+      Survey complete! Here are your answers:
+      - Name: #{answers['name']}
+      - Favorite color: #{answers['color']}
+      - Favorite number: #{answers['number']}
+      Thank you for participating!
+    SUMMARY
+
+    SimpleAcp::Models::Message.agent(summary)
+  end
+end
+
+# Confirmation agent - asks for yes/no confirmation
+server.agent("confirmer",
+  description: "Performs an action after confirmation"
+) do |context|
+  action = context.input.first&.text_content || "do something"
+  state = context.state || { confirmed: nil }
+
+  if state[:confirmed].nil?
+    # First call: ask for confirmation
+    context.set_state({ action: action, confirmed: false })
+    context.await_message(
+      SimpleAcp::Models::Message.agent("Are you sure you want to '#{action}'? (yes/no)")
+    )
+  else
+    # Resume: check confirmation
+    response = context.resume_message&.text_content&.downcase&.strip
+    context.set_state(nil)  # Clear state
+
+    if %w[yes y sure ok].include?(response)
+      SimpleAcp::Models::Message.agent("Action '#{state[:action]}' confirmed and executed!")
+    else
+      SimpleAcp::Models::Message.agent("Action '#{state[:action]}' cancelled.")
+    end
+  end
+end
+
+puts "Starting Await/Resume Demo Server..."
+puts "Available agents:"
+server.agents.each do |name, agent|
+  puts "  - #{name}: #{agent.description}"
+end
+puts
+
+server.run(port: 8000)

data/examples/06_agent_metadata/client.rb

@@ -0,0 +1,188 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Agent Metadata Example - Client
+#
+# Demonstrates:
+# - Retrieving full agent metadata
+# - Inspecting capabilities, author, links
+# - Content type negotiation
+# - Using the agent(name) endpoint
+#
+# First start the server: ruby examples/06_agent_metadata/server.rb
+# Then run this client: ruby examples/06_agent_metadata/client.rb
+
+require_relative "../../lib/simple_acp"
+require "json"
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+puts "=== Agent Metadata Demo ==="
+puts
+
+# Verify server is running
+unless client.ping
+  puts "Server is not responding"
+  exit 1
+end
+puts "Server is healthy"
+puts
+
+# --- Demo 1: List all agents with basic info ---
+puts "--- Demo 1: List Agents Overview ---"
+puts
+
+agents_response = client.agents
+puts "Found #{agents_response.agents.length} agents:"
+puts
+agents_response.agents.each do |agent|
+  puts "#{agent.name}"
+  puts "  Description: #{agent.description}"
+  puts "  Input types: #{agent.input_content_types.join(', ')}"
+  puts "  Output types: #{agent.output_content_types.join(', ')}"
+  puts
+end
+
+# --- Demo 2: Get detailed agent metadata ---
+puts "--- Demo 2: Detailed Agent Metadata ---"
+puts
+
+agent = client.agent("text-analyzer")
+
+puts "Agent: #{agent.name}"
+puts "Description: #{agent.description}"
+puts
+
+if agent.metadata
+  meta = agent.metadata
+
+  puts "Documentation:"
+  puts "  #{meta.documentation}"
+  puts
+
+  if meta.author
+    puts "Author:"
+    puts "  Name: #{meta.author.name}"
+    puts "  Email: #{meta.author.email}" if meta.author.email
+    puts "  URL: #{meta.author.url}" if meta.author.url
+    puts
+  end
+
+  if meta.contributors&.any?
+    puts "Contributors:"
+    meta.contributors.each do |contrib|
+      puts "  - #{contrib.name}"
+      puts "    Email: #{contrib.email}" if contrib.email
+      puts "    URL: #{contrib.url}" if contrib.url
+    end
+    puts
+  end
+
+  if meta.capabilities&.any?
+    puts "Capabilities:"
+    meta.capabilities.each do |cap|
+      puts "  - #{cap.name}: #{cap.description}"
+    end
+    puts
+  end
+
+  if meta.links&.any?
+    puts "Links:"
+    meta.links.each do |link|
+      puts "  - #{link.type}: #{link.url}"
+    end
+    puts
+  end
+
+  if meta.dependencies&.any?
+    puts "Dependencies:"
+    meta.dependencies.each do |dep|
+      puts "  - #{dep.type}: #{dep.name}"
+    end
+    puts
+  end
+
+  puts "Additional Info:"
+  puts "  License: #{meta.license}" if meta.license
+  puts "  Language: #{meta.programming_language}" if meta.programming_language
+  puts "  Framework: #{meta.framework}" if meta.framework
+  puts "  Natural languages: #{meta.natural_languages.join(', ')}" if meta.natural_languages&.any?
+  puts "  Domains: #{meta.domains.join(', ')}" if meta.domains&.any?
+  puts "  Tags: #{meta.tags.join(', ')}" if meta.tags&.any?
+  puts "  Created: #{meta.created_at}" if meta.created_at
+  puts "  Updated: #{meta.updated_at}" if meta.updated_at
+  puts "  Recommended models: #{meta.recommended_models.join(', ')}" if meta.recommended_models&.any?
+else
+  puts "(No detailed metadata)"
+end
+puts
+
+# --- Demo 3: Content Type Negotiation ---
+puts "--- Demo 3: Content Type Checking ---"
+puts
+
+agent = client.agent("text-analyzer")
+
+test_types = ["text/plain", "text/markdown", "application/json", "image/png", "text/html"]
+
+puts "Testing input content types for #{agent.name}:"
+test_types.each do |type|
+  accepts = agent.accepts_content_type?(type)
+  puts "  #{type}: #{accepts ? 'accepted' : 'rejected'}"
+end
+puts
+
+puts "Testing output content types for #{agent.name}:"
+test_types.each do |type|
+  produces = agent.produces_content_type?(type)
+  puts "  #{type}: #{produces ? 'produced' : 'not produced'}"
+end
+puts
+
+# --- Demo 4: Compare agents with different metadata levels ---
+puts "--- Demo 4: Metadata Comparison ---"
+puts
+
+%w[text-analyzer simple-echo json-processor].each do |name|
+  agent = client.agent(name)
+  puts "#{name}:"
+  puts "  Has metadata: #{agent.metadata ? 'yes' : 'no'}"
+  if agent.metadata
+    puts "  Domains: #{agent.metadata.domains&.join(', ') || 'none'}"
+    puts "  Tags: #{agent.metadata.tags&.join(', ') || 'none'}"
+    puts "  Capabilities: #{agent.metadata.capabilities&.length || 0}"
+    puts "  Links: #{agent.metadata.links&.length || 0}"
+  end
+  puts
+end
+
+# --- Demo 5: Using the text analyzer ---
+puts "--- Demo 5: Using Text Analyzer Agent ---"
+puts
+
+sample_text = "Ruby is a wonderful programming language. It has great syntax and an amazing community. I love writing code in Ruby because it makes me happy and productive."
+
+puts "Analyzing text:"
+puts "  \"#{sample_text[0..60]}...\""
+puts
+
+run = client.run_sync(agent: "text-analyzer", input: sample_text)
+
+run.output.each do |message|
+  message.parts.each do |part|
+    case part.content_type
+    when "application/json"
+      data = JSON.parse(part.content)
+      puts "Results:"
+      puts "  Word count: #{data['word_count']}"
+      puts "  Sentiment: #{data['sentiment']}"
+      puts "  Keywords: #{data['keywords'].join(', ')}"
+      puts "  Summary: #{data['summary']}"
+    when "text/plain"
+      puts "  #{part.content}"
+    end
+  end
+end
+puts
+
+puts "=== Agent Metadata Demo Complete ==="

data/examples/06_agent_metadata/server.rb

@@ -0,0 +1,192 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Agent Metadata Example - Server
+#
+# Demonstrates rich agent metadata including:
+# - Author and contributor information
+# - Links to documentation and source code
+# - Capabilities and domains
+# - Dependencies
+# - Content type negotiation
+#
+# Run with: ruby examples/06_agent_metadata/server.rb
+# Then connect with: ruby examples/06_agent_metadata/client.rb
+
+require_relative "../../lib/simple_acp"
+
+server = SimpleAcp::Server::Base.new
+
+# Agent with full metadata
+metadata = SimpleAcp::Models::Metadata.new(
+  documentation: "A comprehensive text analysis agent that can summarize, analyze sentiment, and extract keywords from text.",
+  license: "MIT",
+  programming_language: "ruby",
+  natural_languages: ["en", "es", "fr"],
+  framework: "SimpleAcp",
+  created_at: "2024-01-15T10:00:00Z",
+  updated_at: "2024-06-20T14:30:00Z",
+  author: SimpleAcp::Models::Author.new(
+    name: "Alice Developer",
+    email: "alice@example.com",
+    url: "https://github.com/alicedev"
+  ),
+  contributors: [
+    SimpleAcp::Models::Contributor.new(
+      name: "Bob Contributor",
+      email: "bob@example.com"
+    ),
+    SimpleAcp::Models::Contributor.new(
+      name: "Charlie Helper",
+      url: "https://github.com/charliehelper"
+    )
+  ],
+  capabilities: [
+    SimpleAcp::Models::Capability.new(
+      name: "summarize",
+      description: "Summarize long text into key points"
+    ),
+    SimpleAcp::Models::Capability.new(
+      name: "sentiment",
+      description: "Analyze the sentiment (positive/negative/neutral)"
+    ),
+    SimpleAcp::Models::Capability.new(
+      name: "keywords",
+      description: "Extract important keywords and phrases"
+    )
+  ],
+  domains: ["nlp", "text-analysis", "ai"],
+  tags: ["text", "analysis", "nlp", "summarization", "sentiment"],
+  links: [
+    SimpleAcp::Models::Link.new(
+      type: "documentation",
+      url: "https://example.com/docs/text-analyzer"
+    ),
+    SimpleAcp::Models::Link.new(
+      type: "source-code",
+      url: "https://github.com/example/text-analyzer"
+    ),
+    SimpleAcp::Models::Link.new(
+      type: "homepage",
+      url: "https://example.com/text-analyzer"
+    )
+  ],
+  dependencies: [
+    SimpleAcp::Models::Dependency.new(type: "agent", name: "tokenizer"),
+    SimpleAcp::Models::Dependency.new(type: "model", name: "gpt-4")
+  ],
+  recommended_models: ["gpt-4", "claude-3", "llama-2"]
+)
+
+server.agent("text-analyzer",
+  description: "Analyzes text for sentiment, keywords, and provides summaries",
+  input_content_types: ["text/plain", "text/markdown", "application/json"],
+  output_content_types: ["application/json", "text/plain"],
+  metadata: metadata
+) do |context|
+  text = context.input.first&.text_content || ""
+  operation = "full"
+
+  # Parse operation from JSON if provided
+  if context.input.first&.parts&.first&.content_type == "application/json"
+    begin
+      data = JSON.parse(context.input.first.parts.first.content)
+      text = data["text"] || text
+      operation = data["operation"] || "full"
+    rescue JSON::ParserError
+      # Use text as-is
+    end
+  end
+
+  # Simulate text analysis
+  words = text.split(/\s+/)
+  word_count = words.length
+
+  # Simple keyword extraction (just take unique words > 4 chars)
+  keywords = words.map(&:downcase).uniq.select { |w| w.length > 4 }.first(5)
+
+  # Simple sentiment (just check for positive/negative words)
+  positive_words = %w[good great excellent amazing wonderful happy love best fantastic]
+  negative_words = %w[bad terrible awful horrible sad hate worst disappointing]
+
+  positive_count = words.count { |w| positive_words.include?(w.downcase) }
+  negative_count = words.count { |w| negative_words.include?(w.downcase) }
+
+  sentiment = if positive_count > negative_count
+    "positive"
+  elsif negative_count > positive_count
+    "negative"
+  else
+    "neutral"
+  end
+
+  result = {
+    text_length: text.length,
+    word_count: word_count,
+    keywords: keywords,
+    sentiment: sentiment,
+    summary: words.first(20).join(" ") + (words.length > 20 ? "..." : "")
+  }
+
+  SimpleAcp::Models::Message.new(
+    role: "agent",
+    parts: [
+      SimpleAcp::Models::MessagePart.json(result),
+      SimpleAcp::Models::MessagePart.text(
+        "Analysis complete: #{word_count} words, sentiment: #{sentiment}"
+      )
+    ]
+  )
+end
+
+# Minimal agent for comparison
+server.agent("simple-echo",
+  description: "A simple echo agent with minimal metadata"
+) do |context|
+  input = context.input.first&.text_content || ""
+  SimpleAcp::Models::Message.agent("Echo: #{input}")
+end
+
+# Agent with specific content types
+server.agent("json-processor",
+  description: "Processes JSON input and returns JSON output",
+  input_content_types: ["application/json"],
+  output_content_types: ["application/json"],
+  metadata: SimpleAcp::Models::Metadata.new(
+    documentation: "A JSON processor that transforms input data",
+    domains: ["data-processing"],
+    tags: ["json", "transform"]
+  )
+) do |context|
+  begin
+    input_data = JSON.parse(context.input.first&.text_content || "{}")
+    output = {
+      received: input_data,
+      processed_at: Time.now.iso8601,
+      keys: input_data.keys
+    }
+    SimpleAcp::Models::Message.new(
+      role: "agent",
+      parts: [SimpleAcp::Models::MessagePart.json(output)]
+    )
+  rescue JSON::ParserError => e
+    SimpleAcp::Models::Message.new(
+      role: "agent",
+      parts: [SimpleAcp::Models::MessagePart.json({ error: e.message })]
+    )
+  end
+end
+
+puts "Starting Agent Metadata Demo Server..."
+puts "Available agents:"
+server.agents.each do |name, agent|
+  puts "  - #{name}: #{agent.description}"
+  puts "    Input types: #{agent.manifest.input_content_types.join(', ')}"
+  puts "    Output types: #{agent.manifest.output_content_types.join(', ')}"
+  if agent.manifest.metadata
+    puts "    Has metadata: author, capabilities, links, etc."
+  end
+end
+puts
+
+server.run(port: 8000)