simple_acp 0.0.1

data/docs/client/sessions.md

@@ -0,0 +1,324 @@
+# Session Management
+
+Sessions enable stateful interactions across multiple runs, maintaining conversation history and custom state.
+
+## Using Sessions
+
+### Enable Session
+
+```ruby
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+# Set the session to use
+client.use_session("my-session-id")
+
+# All subsequent runs use this session
+client.run_sync(agent: "chat", input: [...])
+client.run_sync(agent: "chat", input: [...])
+```
+
+### Clear Session
+
+```ruby
+# Stop using the session
+client.clear_session
+
+# Runs are now sessionless
+client.run_sync(agent: "chat", input: [...])
+```
+
+### Check Active Session
+
+```ruby
+if client.session_id
+  puts "Using session: #{client.session_id}"
+else
+  puts "No session active"
+end
+```
+
+## Session IDs
+
+### Generate Session IDs
+
+```ruby
+# User-specific session
+client.use_session("user-#{user_id}")
+
+# Conversation-specific
+client.use_session("chat-#{SecureRandom.uuid}")
+
+# Time-based
+client.use_session("session-#{Time.now.to_i}")
+```
+
+### Meaningful Session IDs
+
+```ruby
+# Good: Traceable, meaningful
+client.use_session("user-42-support-ticket-123")
+client.use_session("api-key-abc123-chat")
+
+# Avoid: Random, untraceable
+client.use_session(SecureRandom.hex(32))
+```
+
+## Retrieving Session Data
+
+### Get Session Info
+
+```ruby
+session = client.session("my-session-id")
+
+puts "Session ID: #{session.id}"
+puts "History length: #{session.history.length}"
+puts "State: #{session.state.inspect}"
+```
+
+### Access History
+
+```ruby
+session = client.session("my-session-id")
+
+session.history.each do |message|
+  puts "#{message.role}: #{message.text_content}"
+end
+```
+
+### Access State
+
+```ruby
+session = client.session("my-session-id")
+
+if session.state
+  puts "Current step: #{session.state['step']}"
+  puts "User data: #{session.state['data'].inspect}"
+end
+```
+
+## Conversation Patterns
+
+### Multi-Turn Chat
+
+```ruby
+def chat_loop(client, agent)
+  client.use_session("chat-#{SecureRandom.uuid}")
+
+  loop do
+    print "You: "
+    input = gets.chomp
+    break if input.downcase == 'quit'
+
+    run = client.run_sync(
+      agent: agent,
+      input: [SimpleAcp::Models::Message.user(input)]
+    )
+
+    puts "Agent: #{run.output.first&.text_content}"
+  end
+
+  client.clear_session
+end
+```
+
+### Context-Aware Responses
+
+```ruby
+client.use_session("support-123")
+
+# First message
+client.run_sync(
+  agent: "support",
+  input: [SimpleAcp::Models::Message.user("My order is late")]
+)
+# Agent: "I'm sorry to hear that. Can you provide your order number?"
+
+# Follow-up (agent remembers context)
+client.run_sync(
+  agent: "support",
+  input: [SimpleAcp::Models::Message.user("It's #12345")]
+)
+# Agent: "I found order #12345. It's expected to arrive tomorrow."
+```
+
+### Resuming Conversations
+
+```ruby
+# Save session ID for later
+session_id = "user-#{user_id}-conversation"
+client.use_session(session_id)
+
+# ... user interacts ...
+
+# Later, resume the same conversation
+client = SimpleAcp::Client::Base.new(base_url: "...")
+client.use_session(session_id)
+
+# Continues where it left off
+run = client.run_sync(agent: "chat", input: [...])
+```
+
+## Session Lifecycle
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+    participant Storage
+
+    Client->>Client: use_session("id")
+    Client->>Server: run_sync (with session_id)
+    Server->>Storage: get_session("id")
+    Storage-->>Server: Session (or nil)
+    Server->>Server: Execute with history
+    Server->>Storage: save_session
+    Server-->>Client: Run result
+```
+
+## Managing Multiple Sessions
+
+### Per-User Sessions
+
+```ruby
+class ChatService
+  def initialize(base_url)
+    @clients = {}
+    @base_url = base_url
+  end
+
+  def get_client(user_id)
+    @clients[user_id] ||= begin
+      client = SimpleAcp::Client::Base.new(base_url: @base_url)
+      client.use_session("user-#{user_id}")
+      client
+    end
+  end
+
+  def chat(user_id, message)
+    client = get_client(user_id)
+    client.run_sync(
+      agent: "chat",
+      input: [SimpleAcp::Models::Message.user(message)]
+    )
+  end
+end
+```
+
+### Session Pool
+
+```ruby
+class SessionPool
+  def initialize(client)
+    @client = client
+    @sessions = {}
+  end
+
+  def with_session(session_id)
+    @client.use_session(session_id)
+    yield @client
+  ensure
+    @client.clear_session
+  end
+end
+
+# Usage
+pool = SessionPool.new(client)
+
+pool.with_session("user-123") do |c|
+  c.run_sync(agent: "chat", input: [...])
+end
+```
+
+## Session Expiration
+
+Sessions may expire based on storage backend:
+
+### Redis (TTL-based)
+
+```ruby
+# Sessions expire after TTL (default 24 hours)
+client.use_session("short-lived")
+# ... interact ...
+
+# After TTL, session is gone
+# New run starts fresh session
+```
+
+### PostgreSQL (Persistent)
+
+```ruby
+# Sessions persist until explicitly deleted
+client.use_session("persistent")
+# ... can resume days later ...
+```
+
+### Memory (Process Lifetime)
+
+```ruby
+# Sessions lost when server restarts
+```
+
+## Error Handling
+
+```ruby
+begin
+  session = client.session("unknown-session")
+rescue SimpleAcp::Error => e
+  if e.message.include?("not found")
+    puts "Session doesn't exist"
+  else
+    raise
+  end
+end
+```
+
+## Best Practices
+
+1. **Use meaningful IDs** - Include user/context info for debugging
+2. **Clean up sessions** - Delete when conversations end
+3. **Handle expiration** - Gracefully handle missing sessions
+4. **Scope appropriately** - One session per conversation, not per user
+5. **Monitor size** - Long sessions may have large history
+
+## Session Cleanup
+
+```ruby
+# After conversation ends
+def end_conversation(client, session_id)
+  client.clear_session
+
+  # Optionally delete server-side
+  # (if supported by your storage)
+end
+```
+
+## Testing with Sessions
+
+```ruby
+def test_multi_turn_conversation
+  client = SimpleAcp::Client::Base.new(base_url: test_server_url)
+  client.use_session("test-#{SecureRandom.uuid}")
+
+  # First turn
+  run1 = client.run_sync(
+    agent: "counter",
+    input: [SimpleAcp::Models::Message.user("increment")]
+  )
+  assert_includes run1.output.first.text_content, "1"
+
+  # Second turn (should remember)
+  run2 = client.run_sync(
+    agent: "counter",
+    input: [SimpleAcp::Models::Message.user("increment")]
+  )
+  assert_includes run2.output.first.text_content, "2"
+ensure
+  client.clear_session
+end
+```
+
+## Next Steps
+
+- Learn about [Sessions](../core-concepts/sessions.md) concept
+- Explore [Multi-Turn Conversations](../server/multi-turn.md)
+- Review [Storage Backends](../storage/index.md) for persistence options

data/docs/client/streaming.md

@@ -0,0 +1,345 @@
+# Streaming
+
+Streaming enables real-time delivery of agent responses via Server-Sent Events (SSE), providing immediate feedback and better user experience.
+
+## Basic Streaming
+
+```ruby
+client.run_stream(
+  agent: "chat",
+  input: [SimpleAcp::Models::Message.user("Tell me a story")]
+) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content
+    $stdout.flush
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\n--- Complete ---"
+  end
+end
+```
+
+## Event Types
+
+Handle different event types for full control:
+
+```ruby
+client.run_stream(agent: "processor", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::RunStartedEvent
+    puts "Run started: #{event.run_id}"
+
+  when SimpleAcp::Models::MessageCreatedEvent
+    puts "New message from: #{event.message.role}"
+
+  when SimpleAcp::Models::MessagePartEvent
+    # Content chunk - stream to output
+    print event.part.content
+
+  when SimpleAcp::Models::MessageCompletedEvent
+    puts "\n[Message complete]"
+
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "Run completed!"
+    puts "Output messages: #{event.run.output.length}"
+
+  when SimpleAcp::Models::RunFailedEvent
+    puts "Run failed: #{event.error.message}"
+
+  when SimpleAcp::Models::RunAwaitingEvent
+    puts "Run awaiting input..."
+    puts event.await_request.message.text_content
+  end
+end
+```
+
+## Collecting Output
+
+### Accumulate All Content
+
+```ruby
+output = ""
+
+client.run_stream(agent: "chat", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    output << event.part.content
+  end
+end
+
+puts "Full response: #{output}"
+```
+
+### Collect Messages
+
+```ruby
+messages = []
+
+client.run_stream(agent: "multi", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::MessageCompletedEvent
+    messages << event.message
+  end
+end
+
+puts "Received #{messages.length} messages"
+```
+
+## Progress Tracking
+
+### Simple Progress
+
+```ruby
+parts_received = 0
+
+client.run_stream(agent: "processor", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    parts_received += 1
+    print "\rReceived: #{parts_received} parts"
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\nDone!"
+  end
+end
+```
+
+### Detailed Progress
+
+```ruby
+def stream_with_progress(client, agent:, input:)
+  state = { started_at: nil, parts: 0, messages: 0 }
+
+  client.run_stream(agent: agent, input: input) do |event|
+    case event
+    when SimpleAcp::Models::RunStartedEvent
+      state[:started_at] = Time.now
+      puts "Processing..."
+
+    when SimpleAcp::Models::MessagePartEvent
+      state[:parts] += 1
+      print "."
+      $stdout.flush
+
+    when SimpleAcp::Models::MessageCompletedEvent
+      state[:messages] += 1
+
+    when SimpleAcp::Models::RunCompletedEvent
+      elapsed = Time.now - state[:started_at]
+      puts "\nComplete in #{elapsed.round(2)}s"
+      puts "#{state[:messages]} messages, #{state[:parts]} parts"
+    end
+  end
+end
+```
+
+## Error Handling
+
+### Basic Error Handling
+
+```ruby
+begin
+  client.run_stream(agent: "risky", input: [...]) do |event|
+    case event
+    when SimpleAcp::Models::RunFailedEvent
+      puts "Agent error: #{event.error.message}"
+    when SimpleAcp::Models::MessagePartEvent
+      print event.part.content
+    end
+  end
+rescue Faraday::TimeoutError
+  puts "Stream timed out"
+rescue Faraday::ConnectionFailed
+  puts "Connection lost"
+end
+```
+
+### Graceful Recovery
+
+```ruby
+def stream_with_retry(client, agent:, input:, max_retries: 3)
+  retries = 0
+
+  begin
+    client.run_stream(agent: agent, input: input) do |event|
+      yield event
+    end
+  rescue Faraday::ConnectionFailed, Faraday::TimeoutError => e
+    retries += 1
+    if retries <= max_retries
+      puts "Connection issue, retrying (#{retries}/#{max_retries})..."
+      sleep 2 ** retries  # Exponential backoff
+      retry
+    else
+      raise e
+    end
+  end
+end
+
+# Usage
+stream_with_retry(client, agent: "chat", input: [...]) do |event|
+  # Handle events
+end
+```
+
+## Streaming with Sessions
+
+```ruby
+client.use_session("conversation-123")
+
+# Stream with session context
+client.run_stream(agent: "chat", input: [Message.user("Hello")]) do |event|
+  # Handle events...
+end
+
+# Subsequent streams maintain history
+client.run_stream(agent: "chat", input: [Message.user("Continue")]) do |event|
+  # Has access to previous conversation
+end
+```
+
+## Resume Streaming
+
+For awaiting runs, resume with streaming:
+
+```ruby
+run = client.run_sync(agent: "questioner", input: [...])
+
+if run.awaiting?
+  puts run.await_request.message.text_content
+
+  # Resume with streaming
+  client.run_resume_stream(
+    run_id: run.run_id,
+    await_resume: SimpleAcp::Models::MessageAwaitResume.new(
+      message: SimpleAcp::Models::Message.user("My answer")
+    )
+  ) do |event|
+    case event
+    when SimpleAcp::Models::MessagePartEvent
+      print event.part.content
+    end
+  end
+end
+```
+
+## UI Integration
+
+### Terminal UI
+
+```ruby
+require 'io/console'
+
+def chat_interface(client, agent)
+  puts "Chat with #{agent} (type 'quit' to exit)"
+  puts "-" * 40
+
+  client.use_session("chat-#{SecureRandom.uuid}")
+
+  loop do
+    print "\nYou: "
+    input = gets.chomp
+    break if input.downcase == 'quit'
+
+    print "Agent: "
+    client.run_stream(
+      agent: agent,
+      input: [SimpleAcp::Models::Message.user(input)]
+    ) do |event|
+      case event
+      when SimpleAcp::Models::MessagePartEvent
+        print event.part.content
+        $stdout.flush
+      end
+    end
+    puts
+  end
+end
+
+chat_interface(client, "chat")
+```
+
+### Web Application
+
+```ruby
+# Sinatra example
+get '/stream' do
+  content_type 'text/event-stream'
+
+  stream(:keep_open) do |out|
+    client.run_stream(
+      agent: params[:agent],
+      input: [SimpleAcp::Models::Message.user(params[:input])]
+    ) do |event|
+      case event
+      when SimpleAcp::Models::MessagePartEvent
+        out << "data: #{event.part.content.to_json}\n\n"
+      when SimpleAcp::Models::RunCompletedEvent
+        out << "event: done\ndata: {}\n\n"
+      end
+    end
+  end
+end
+```
+
+## Performance Tips
+
+### Buffer Output
+
+```ruby
+buffer = []
+
+client.run_stream(agent: "fast", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    buffer << event.part.content
+
+    # Flush periodically
+    if buffer.length >= 10
+      print buffer.join
+      buffer.clear
+    end
+  when SimpleAcp::Models::RunCompletedEvent
+    print buffer.join unless buffer.empty?
+  end
+end
+```
+
+### Async Processing
+
+```ruby
+require 'concurrent'
+
+def stream_async(client, agent:, input:)
+  future = Concurrent::Future.execute do
+    result = []
+    client.run_stream(agent: agent, input: input) do |event|
+      result << event
+    end
+    result
+  end
+
+  future
+end
+
+# Start streaming in background
+future = stream_async(client, agent: "processor", input: [...])
+
+# Do other work...
+
+# Get results when ready
+events = future.value
+```
+
+## Best Practices
+
+1. **Flush output** - Call `$stdout.flush` for real-time display
+2. **Handle all events** - Don't ignore error events
+3. **Use timeouts** - Configure appropriate connection timeouts
+4. **Buffer intelligently** - Balance responsiveness with efficiency
+5. **Clean up** - Handle connection errors gracefully
+
+## Next Steps
+
+- Learn about [Session Management](sessions.md)
+- Explore [Events](../core-concepts/events.md) in depth
+- See [Server Streaming](../server/streaming.md) for server-side details