simple_acp 0.0.1

data/docs/storage/redis.md

@@ -0,0 +1,287 @@
+# Redis Storage
+
+Redis storage provides distributed, TTL-based storage suitable for production deployments with multiple server processes.
+
+## Features
+
+- **Distributed** - Share state across multiple processes
+- **TTL-based** - Automatic expiration of old data
+- **Fast** - Sub-millisecond operations
+- **Scalable** - Supports Redis clustering
+
+## Requirements
+
+Add the Redis gem to your Gemfile:
+
+```ruby
+gem 'redis', '~> 5.0'
+```
+
+## Usage
+
+### Basic Setup
+
+```ruby
+require 'simple_acp'
+require 'simple_acp/storage/redis'
+
+storage = SimpleAcp::Storage::Redis.new(
+  url: "redis://localhost:6379"
+)
+
+server = SimpleAcp::Server::Base.new(storage: storage)
+```
+
+### Configuration Options
+
+```ruby
+storage = SimpleAcp::Storage::Redis.new(
+  # Connection
+  url: "redis://localhost:6379",     # Redis URL
+  host: "localhost",                  # Or specify individually
+  port: 6379,
+  db: 0,
+  password: "secret",
+  ssl: false,
+
+  # Or use existing connection
+  redis: existing_redis_client,
+
+  # Behavior
+  ttl: 86400,                         # TTL in seconds (default: 24 hours)
+  prefix: "acp:"                      # Key prefix (default: "acp:")
+)
+```
+
+### Environment Variables
+
+```ruby
+# Uses REDIS_URL if not specified
+storage = SimpleAcp::Storage::Redis.new
+
+# Reads from:
+# ENV['REDIS_URL'] || "redis://localhost:6379"
+```
+
+## Data Model
+
+### Key Structure
+
+```
+acp:run:{run_id}              # Run data (JSON)
+acp:session:{session_id}      # Session data (JSON)
+acp:events:{run_id}           # Events list (JSON items)
+acp:agent_runs:{agent_name}   # Set of run IDs for agent
+acp:session_runs:{session_id} # Set of run IDs for session
+```
+
+### TTL Behavior
+
+All keys expire after the configured TTL:
+
+```ruby
+storage = SimpleAcp::Storage::Redis.new(
+  ttl: 3600  # 1 hour
+)
+
+# Run expires 1 hour after last update
+storage.save_run(run)
+```
+
+## Operations
+
+### Runs
+
+```ruby
+# Save (sets TTL)
+storage.save_run(run)
+
+# Get
+run = storage.get_run("run-id")
+
+# Delete (also removes from indexes)
+storage.delete_run("run-id")
+
+# List by agent
+result = storage.list_runs(agent_name: "echo")
+
+# List by session
+result = storage.list_runs(session_id: "session-123")
+```
+
+### Sessions
+
+```ruby
+# Save (sets TTL)
+storage.save_session(session)
+
+# Get
+session = storage.get_session("session-id")
+
+# Delete
+storage.delete_session("session-id")
+```
+
+### Events
+
+```ruby
+# Add (extends TTL)
+storage.add_event("run-id", event)
+
+# Get
+events = storage.get_events("run-id", limit: 100, offset: 0)
+```
+
+## Connection Management
+
+### Connection Pooling
+
+Use connection pooling in multi-threaded environments:
+
+```ruby
+require 'connection_pool'
+
+pool = ConnectionPool.new(size: 10) do
+  Redis.new(url: ENV['REDIS_URL'])
+end
+
+# Create storage with pooled connection
+storage = SimpleAcp::Storage::Redis.new(redis: pool)
+```
+
+### Close Connection
+
+```ruby
+storage.close
+```
+
+### Health Check
+
+```ruby
+if storage.ping
+  puts "Redis is healthy"
+else
+  puts "Redis connection failed"
+end
+```
+
+## Scaling
+
+### Redis Cluster
+
+For high availability and horizontal scaling:
+
+```ruby
+require 'redis-cluster-client'
+
+redis = RedisClient.cluster(
+  nodes: [
+    { host: "node1.example.com", port: 6379 },
+    { host: "node2.example.com", port: 6379 },
+    { host: "node3.example.com", port: 6379 }
+  ]
+).new_pool(timeout: 5, size: 10)
+
+storage = SimpleAcp::Storage::Redis.new(redis: redis)
+```
+
+### Multiple Processes
+
+Redis naturally supports multiple processes:
+
+```ruby
+# Process 1
+server1 = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::Redis.new(url: ENV['REDIS_URL'])
+)
+
+# Process 2 (shares data with Process 1)
+server2 = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::Redis.new(url: ENV['REDIS_URL'])
+)
+```
+
+## Production Configuration
+
+### Recommended Settings
+
+```ruby
+storage = SimpleAcp::Storage::Redis.new(
+  url: ENV['REDIS_URL'],
+  ttl: 86400 * 7,        # 7 days
+  prefix: "myapp:acp:"   # Namespace for your app
+)
+```
+
+### With Sentinel
+
+```ruby
+redis = Redis.new(
+  url: "redis://mymaster",
+  sentinels: [
+    { host: "sentinel1", port: 26379 },
+    { host: "sentinel2", port: 26379 },
+    { host: "sentinel3", port: 26379 }
+  ],
+  role: :master
+)
+
+storage = SimpleAcp::Storage::Redis.new(redis: redis)
+```
+
+## Maintenance
+
+### Clear All Data
+
+```ruby
+storage.clear!  # Deletes all keys with prefix
+```
+
+### Monitor Key Count
+
+```bash
+redis-cli KEYS "acp:*" | wc -l
+```
+
+### Check Memory Usage
+
+```bash
+redis-cli INFO memory
+```
+
+## Error Handling
+
+```ruby
+begin
+  run = storage.get_run("run-id")
+rescue Redis::CannotConnectError
+  puts "Redis connection failed"
+  # Fallback logic...
+rescue Redis::TimeoutError
+  puts "Redis timeout"
+  # Retry logic...
+end
+```
+
+## Best Practices
+
+1. **Use appropriate TTL** - Balance retention vs. memory usage
+2. **Use key prefix** - Namespace to avoid collisions
+3. **Monitor memory** - Watch Redis memory usage
+4. **Use connection pooling** - For multi-threaded apps
+5. **Set up replication** - For high availability
+
+## Comparison with Other Backends
+
+| Feature | Redis | Memory | PostgreSQL |
+|---------|-------|--------|------------|
+| Persistence | TTL | None | Permanent |
+| Multi-process | Yes | No | Yes |
+| Speed | Fast | Fastest | Moderate |
+| Query flexibility | Limited | None | Full SQL |
+
+## Next Steps
+
+- Learn about [PostgreSQL](postgresql.md) for permanent storage
+- Build a [Custom Backend](custom.md) for special needs
+- Review [Memory](memory.md) for development

data/examples/01_basic/client.rb

@@ -0,0 +1,88 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic SimpleAcp Client Example
+#
+# First start the server: ruby examples/01_basic/server.rb
+# Then run this client: ruby examples/01_basic/client.rb
+
+require_relative "../../lib/simple_acp"
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+puts "=== SimpleAcp Client Example ==="
+puts
+
+# Check server health
+if client.ping
+  puts "✓ Server is healthy"
+else
+  puts "✗ Server is not responding"
+  exit 1
+end
+puts
+
+# List available agents
+puts "Available agents:"
+agents = client.agents
+agents.agents.each do |agent|
+  puts "  - #{agent.name}: #{agent.description}"
+end
+puts
+
+# Test echo agent
+puts "--- Testing echo agent ---"
+run = client.run_sync(agent: "echo", input: "Hello, SimpleAcp!")
+puts "Input: Hello, SimpleAcp!"
+puts "Output: #{run.output.first.text_content}"
+puts
+
+# Test greeter agent
+puts "--- Testing greeter agent ---"
+run = client.run_sync(agent: "greeter", input: "Ruby Developer")
+puts "Input: Ruby Developer"
+puts "Output: #{run.output.first.text_content}"
+puts
+
+# Test counter agent with session
+puts "--- Testing counter agent with session ---"
+session_id = SecureRandom.uuid
+client.use_session(session_id)
+
+3.times do |i|
+  run = client.run_sync(agent: "counter", input: "increment")
+  puts "Call #{i + 1}: #{run.output.first.text_content}"
+end
+client.clear_session
+puts
+
+# Test streaming with Gettysburg Address (word by word with 0.5s delay)
+puts "--- Testing streaming (Gettysburg Address) ---"
+puts
+print "  "
+client.run_stream(agent: "gettysburg", input: "recite") do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content
+    $stdout.flush
+  when SimpleAcp::Models::RunCompletedEvent
+    puts
+    puts
+    puts "[Streaming complete]"
+  end
+end
+puts
+
+# Test assistant with history
+puts "--- Testing assistant with history ---"
+session_id = SecureRandom.uuid
+client.use_session(session_id)
+
+["Hi!", "Tell me more", "Thanks!"].each do |msg|
+  run = client.run_sync(agent: "assistant", input: msg)
+  puts "User: #{msg}"
+  puts "Agent: #{run.output.first.text_content}"
+  puts
+end
+
+puts "=== All tests completed ==="

data/examples/01_basic/server.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Basic SimpleAcp Server Example
+#
+# Run with: ruby examples/01_basic/server.rb
+# Then connect with: ruby examples/01_basic/client.rb
+
+require_relative "../../lib/simple_acp"
+
+server = SimpleAcp::Server::Base.new
+
+# Simple echo agent
+server.agent("echo", description: "Echoes everything you send") do |context|
+  Enumerator.new do |yielder|
+    context.input.each do |message|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(message.text_content)
+      )
+    end
+  end
+end
+
+# Greeting agent
+server.agent("greeter", description: "Greets the user by name") do |context|
+  name = context.input.first&.text_content&.strip
+  name = "World" if name.nil? || name.empty?
+
+  SimpleAcp::Models::Message.agent("Hello, #{name}! Welcome to SimpleAcp.")
+end
+
+# Stateful counter agent
+server.agent("counter", description: "Counts how many times you've called it") do |context|
+  count = (context.state || 0) + 1
+  context.set_state(count)
+
+  SimpleAcp::Models::Message.agent("You have called me #{count} time(s).")
+end
+
+# Streaming demonstration agent - recites the Gettysburg Address word by word
+server.agent("gettysburg", description: "Recites the Gettysburg Address word by word") do |context|
+  address = <<~TEXT
+    Four score and seven years ago our fathers brought forth on this continent, a new nation, conceived in Liberty, and dedicated to the proposition that all men are created equal.
+    Now we are engaged in a great civil war, testing whether that nation, or any nation so conceived and so dedicated, can long endure.
+    We are met on a great battle-field of that war.
+    We have come to dedicate a portion of that field, as a final resting place for those who here gave their lives that that nation might live.
+    It is altogether fitting and proper that we should do this.
+    But, in a larger sense, we can not dedicate — we can not consecrate — we can not hallow — this ground.
+    The brave men, living and dead, who struggled here, have consecrated it, far above our poor power to add or detract.
+    The world will little note, nor long remember what we say here, but it can never forget what they did here.
+    It is for us the living, rather, to be dedicated here to the unfinished work which they who fought here have thus far so nobly advanced.
+    It is rather for us to be here dedicated to the great task remaining before us — that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion — that we here highly resolve that these dead shall not have died in vain — that this nation, under God, shall have a new birth of freedom — and that government of the people, by the people, for the people, shall not perish from the earth.
+  TEXT
+
+  words = address.split
+
+  Enumerator.new do |yielder|
+    words.each do |word|
+      # Use fiber-aware sleep for Async/Falcon compatibility
+      if defined?(Async::Task) && Async::Task.current?
+        Async::Task.current.sleep(0.3)
+      else
+        sleep(0.3)
+      end
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(word + " ")
+      )
+    end
+  end
+end
+
+# Multi-turn conversation agent
+server.agent("assistant",
+  description: "A simple assistant that remembers conversation history",
+  input_content_types: ["text/plain", "application/json"],
+  output_content_types: ["text/plain"]
+) do |context|
+  # Access conversation history
+  history_count = context.history.length
+
+  response = if history_count.zero?
+    "Hello! This is our first conversation. How can I help you?"
+  else
+    "I see we've had #{history_count} previous messages. What else can I help with?"
+  end
+
+  SimpleAcp::Models::Message.agent(response)
+end
+
+########################################################
+## main line
+#
+puts "Starting SimpleAcp Server..."
+puts "Available agents:"
+server.agents.each do |name, agent|
+  puts "  - #{name}: #{agent.description}"
+end
+puts
+
+server.run(port: 8000)

data/examples/02_async_execution/client.rb

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Async Execution Example - Client
+#
+# Demonstrates:
+# - Async (non-blocking) execution with run_async
+# - Polling run status with run_status
+# - Waiting for completion with wait_for_run
+# - Running multiple tasks concurrently
+#
+# First start the server: ruby examples/02_async_execution/server.rb
+# Then run this client: ruby examples/02_async_execution/client.rb
+
+require_relative "../../lib/simple_acp"
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+puts "=== Async Execution Demo ==="
+puts
+
+# Verify server is running
+unless client.ping
+  puts "Server is not responding"
+  exit 1
+end
+puts "Server is healthy"
+puts
+
+# --- Demo 1: Async execution with manual polling ---
+puts "--- Demo 1: Async Execution with Manual Polling ---"
+puts
+
+puts "Starting slow-worker asynchronously..."
+run = client.run_async(agent: "slow-worker", input: "data analysis")
+puts "Run started with ID: #{run.run_id}"
+puts "Initial status: #{run.status}"
+puts
+
+puts "Polling for status..."
+loop do
+  status = client.run_status(run.run_id)
+  puts "  Status: #{status.status}"
+
+  break if status.terminal?
+
+  sleep(0.5)
+end
+
+puts
+puts "Run completed! Final output:"
+final_run = client.run_status(run.run_id)
+final_run.output.each do |message|
+  puts "  #{message.text_content}"
+end
+puts
+
+# --- Demo 2: Using wait_for_run for simpler polling ---
+puts "--- Demo 2: Using wait_for_run ---"
+puts
+
+puts "Starting another slow-worker..."
+run = client.run_async(agent: "slow-worker", input: "report generation")
+puts "Run ID: #{run.run_id}"
+puts
+
+puts "Waiting for completion (timeout: 10s)..."
+completed_run = client.wait_for_run(run.run_id, timeout: 10)
+
+if completed_run.status == "completed"
+  puts "Success! Output:"
+  completed_run.output.each do |message|
+    puts "  #{message.text_content}"
+  end
+else
+  puts "Run ended with status: #{completed_run.status}"
+end
+puts
+
+# --- Demo 3: Running multiple tasks concurrently ---
+puts "--- Demo 3: Concurrent Async Execution ---"
+puts
+
+puts "Starting 3 tasks concurrently..."
+runs = []
+%w[task_alpha task_beta task_gamma].each do |task_name|
+  run = client.run_async(agent: "slow-worker", input: task_name)
+  runs << run
+  puts "  Started: #{task_name} (#{run.run_id[0..7]}...)"
+end
+puts
+
+puts "Waiting for all tasks to complete..."
+start_time = Time.now
+
+runs.each do |run|
+  completed = client.wait_for_run(run.run_id, timeout: 15)
+  task_name = completed.output.last&.text_content || "unknown"
+  puts "  Completed: #{task_name}"
+end
+
+elapsed = (Time.now - start_time).round(2)
+puts
+puts "All 3 tasks completed in #{elapsed}s (ran concurrently, not 9s sequentially)"
+puts
+
+puts "=== Async Execution Demo Complete ==="

data/examples/02_async_execution/server.rb

@@ -0,0 +1,56 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Async Execution Example - Server
+#
+# Demonstrates async (non-blocking) execution with polling.
+#
+# Run with: ruby examples/02_async_execution/server.rb
+# Then connect with: ruby examples/02_async_execution/client.rb
+
+require_relative "../../lib/simple_acp"
+
+server = SimpleAcp::Server::Base.new
+
+# Slow worker agent - simulates a long-running task
+server.agent("slow-worker", description: "Simulates a long-running task (3 seconds)") do |context|
+  task_name = context.input.first&.text_content || "default task"
+
+  # Simulate work with progress updates
+  Enumerator.new do |yielder|
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Starting task: #{task_name}")
+    )
+
+    # Simulate 3 seconds of work
+    3.times do |i|
+      if defined?(Async::Task) && Async::Task.current?
+        Async::Task.current.sleep(1)
+      else
+        sleep(1)
+      end
+
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("Progress: #{(i + 1) * 33}%")
+      )
+    end
+
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Task '#{task_name}' completed!")
+    )
+  end
+end
+
+# Quick status agent - returns immediately
+server.agent("quick-status", description: "Returns status immediately") do |context|
+  SimpleAcp::Models::Message.agent("Status: All systems operational at #{Time.now}")
+end
+
+puts "Starting Async Execution Demo Server..."
+puts "Available agents:"
+server.agents.each do |name, agent|
+  puts "  - #{name}: #{agent.description}"
+end
+puts
+
+server.run(port: 8000)