simple_acp 0.0.1

data/docs/server/multi-turn.md

@@ -0,0 +1,329 @@
+# Multi-Turn Conversations
+
+Multi-turn conversations allow agents to maintain context across multiple interactions, request additional input, and build stateful experiences.
+
+## Using Sessions
+
+Sessions maintain history and state:
+
+```ruby
+server.agent("chat") do |context|
+  # Access conversation history
+  history = context.history
+
+  # Build context from history
+  all_messages = history + context.input
+
+  # Generate response considering full context
+  response = generate_response(all_messages)
+
+  SimpleAcp::Models::Message.agent(response)
+end
+```
+
+## Session History
+
+History automatically accumulates:
+
+```ruby
+# First interaction
+# history: []
+# input: [user: "Hello"]
+# After: history becomes [user: "Hello", agent: "Hi!"]
+
+# Second interaction
+# history: [user: "Hello", agent: "Hi!"]
+# input: [user: "How are you?"]
+# After: history becomes [user: "Hello", agent: "Hi!", user: "How are you?", agent: "I'm good!"]
+```
+
+## Session State
+
+Custom state persists across turns:
+
+```ruby
+server.agent("counter") do |context|
+  count = context.state || 0
+  count += 1
+  context.set_state(count)
+
+  SimpleAcp::Models::Message.agent("Turn #{count}")
+end
+```
+
+### Complex State
+
+```ruby
+server.agent("form") do |context|
+  state = context.state || { step: 1, data: {} }
+
+  case state[:step]
+  when 1
+    context.set_state(state.merge(step: 2))
+    SimpleAcp::Models::Message.agent("Enter your name:")
+  when 2
+    state[:data][:name] = context.input.first&.text_content
+    context.set_state(state.merge(step: 3))
+    SimpleAcp::Models::Message.agent("Enter your email:")
+  when 3
+    state[:data][:email] = context.input.first&.text_content
+    context.set_state(state.merge(step: :done))
+    SimpleAcp::Models::Message.agent(
+      "Thanks #{state[:data][:name]}! We'll contact you at #{state[:data][:email]}"
+    )
+  else
+    SimpleAcp::Models::Message.agent("Form complete!")
+  end
+end
+```
+
+## Awaiting Input
+
+For synchronous input requests within a single run:
+
+```ruby
+server.agent("questioner") do |context|
+  Enumerator.new do |yielder|
+    # Ask first question
+    result = context.await_message(
+      SimpleAcp::Models::Message.agent("What is your name?")
+    )
+    yielder << result
+
+    # After resume, get the answer
+    name = context.resume_message&.text_content
+
+    # Ask second question
+    result = context.await_message(
+      SimpleAcp::Models::Message.agent("What is your favorite color, #{name}?")
+    )
+    yielder << result
+
+    color = context.resume_message&.text_content
+
+    # Final response
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Great choice, #{name}! #{color} is nice.")
+    )
+  end
+end
+```
+
+### Await Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+    participant Agent
+
+    Client->>Server: run_sync (input)
+    Server->>Agent: execute
+    Agent-->>Server: await_message("Name?")
+    Server-->>Client: Run (awaiting)
+
+    Client->>Server: run_resume (name)
+    Server->>Agent: continue with resume
+    Agent-->>Server: await_message("Color?")
+    Server-->>Client: Run (awaiting)
+
+    Client->>Server: run_resume (color)
+    Server->>Agent: continue with resume
+    Agent-->>Server: final response
+    Server-->>Client: Run (completed)
+```
+
+### Client-Side Await Handling
+
+```ruby
+run = client.run_sync(agent: "questioner", input: [...])
+
+while run.awaiting?
+  puts run.await_request.message.text_content
+
+  answer = gets.chomp
+
+  run = client.run_resume_sync(
+    run_id: run.run_id,
+    await_resume: SimpleAcp::Models::MessageAwaitResume.new(
+      message: SimpleAcp::Models::Message.user(answer)
+    )
+  )
+end
+
+puts "Final: #{run.output.last.text_content}"
+```
+
+## Conversation Patterns
+
+### Contextual Responses
+
+```ruby
+server.agent("assistant") do |context|
+  # Build full conversation
+  conversation = context.history.map do |msg|
+    { role: msg.role, content: msg.text_content }
+  end
+
+  conversation << {
+    role: "user",
+    content: context.input.first&.text_content
+  }
+
+  # Use LLM with full context
+  response = llm.chat(conversation)
+
+  SimpleAcp::Models::Message.agent(response)
+end
+```
+
+### Memory Management
+
+Limit history for efficiency:
+
+```ruby
+server.agent("bounded-chat") do |context|
+  # Only use last 10 messages
+  recent_history = context.history.last(10)
+
+  conversation = recent_history + context.input
+
+  response = generate_response(conversation)
+
+  SimpleAcp::Models::Message.agent(response)
+end
+```
+
+### Summarization
+
+```ruby
+server.agent("summarizing-chat") do |context|
+  state = context.state || { summary: nil }
+
+  if context.history.length > 20
+    # Summarize older history
+    old_messages = context.history[0..-11]
+    state[:summary] = summarize(old_messages)
+    context.set_state(state)
+  end
+
+  # Use summary + recent history
+  conversation_context = [
+    state[:summary] ? "Previous context: #{state[:summary]}" : nil,
+    *context.history.last(10).map(&:text_content),
+    context.input.first&.text_content
+  ].compact
+
+  response = generate_response(conversation_context)
+
+  SimpleAcp::Models::Message.agent(response)
+end
+```
+
+### Conversation Reset
+
+```ruby
+server.agent("resettable") do |context|
+  command = context.input.first&.text_content
+
+  if command&.downcase == "reset"
+    context.set_state(nil)
+    return SimpleAcp::Models::Message.agent("Conversation reset!")
+  end
+
+  # Normal processing...
+end
+```
+
+## Interactive Workflows
+
+### Quiz Game
+
+```ruby
+server.agent("quiz") do |context|
+  state = context.state || {
+    score: 0,
+    question_index: 0,
+    questions: load_questions
+  }
+
+  if state[:question_index] > 0
+    # Check previous answer
+    answer = context.input.first&.text_content
+    correct = state[:questions][state[:question_index] - 1][:answer]
+
+    if answer&.downcase == correct.downcase
+      state[:score] += 1
+    end
+  end
+
+  if state[:question_index] >= state[:questions].length
+    context.set_state(nil)
+    return SimpleAcp::Models::Message.agent(
+      "Quiz complete! Score: #{state[:score]}/#{state[:questions].length}"
+    )
+  end
+
+  question = state[:questions][state[:question_index]]
+  state[:question_index] += 1
+  context.set_state(state)
+
+  SimpleAcp::Models::Message.agent(question[:text])
+end
+```
+
+### Shopping Assistant
+
+```ruby
+server.agent("shop") do |context|
+  cart = context.state || { items: [], total: 0.0 }
+  command = context.input.first&.text_content&.downcase
+
+  response = case command
+  when /^add (.+)/
+    item = find_product($1)
+    if item
+      cart[:items] << item
+      cart[:total] += item[:price]
+      "Added #{item[:name]} ($#{item[:price]})"
+    else
+      "Product not found"
+    end
+  when /^remove (.+)/
+    item = cart[:items].find { |i| i[:name].downcase.include?($1) }
+    if item
+      cart[:items].delete(item)
+      cart[:total] -= item[:price]
+      "Removed #{item[:name]}"
+    else
+      "Item not in cart"
+    end
+  when "cart"
+    items_list = cart[:items].map { |i| "- #{i[:name]}: $#{i[:price]}" }.join("\n")
+    "Cart:\n#{items_list}\nTotal: $#{cart[:total]}"
+  when "checkout"
+    total = cart[:total]
+    context.set_state(nil)
+    "Order placed! Total: $#{total}"
+  else
+    "Commands: add <item>, remove <item>, cart, checkout"
+  end
+
+  context.set_state(cart)
+  SimpleAcp::Models::Message.agent(response)
+end
+```
+
+## Best Practices
+
+1. **Limit history size** - Don't let history grow unbounded
+2. **Use state wisely** - Store minimal necessary data
+3. **Handle resets** - Allow users to start fresh
+4. **Validate state** - Check for expected structure
+5. **Test edge cases** - Empty history, missing state, etc.
+
+## Next Steps
+
+- Review [Sessions](../core-concepts/sessions.md) concept
+- See [Client Sessions](../client/sessions.md) for client-side handling
+- Explore [HTTP Endpoints](http-endpoints.md) for session APIs

data/docs/server/streaming.md

@@ -0,0 +1,315 @@
+# Streaming Responses
+
+Streaming enables real-time delivery of agent responses via Server-Sent Events (SSE). This provides a better user experience for long-running operations.
+
+## Why Streaming?
+
+- **Immediate Feedback**: Users see responses as they're generated
+- **Progress Visibility**: Track long operations in real-time
+- **Resource Efficiency**: Process data incrementally
+- **Better UX**: No waiting for complete responses
+
+## Basic Streaming
+
+Return an `Enumerator` to enable streaming:
+
+```ruby
+server.agent("streamer") do |context|
+  Enumerator.new do |yielder|
+    5.times do |i|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("Message #{i + 1}")
+      )
+      sleep 0.5
+    end
+  end
+end
+```
+
+## RunYield
+
+`RunYield` wraps messages for streaming:
+
+```ruby
+# Single message
+yielder << SimpleAcp::Server::RunYield.new(
+  SimpleAcp::Models::Message.agent("Hello")
+)
+
+# Multiple messages
+yielder << SimpleAcp::Server::RunYield.new(
+  [
+    SimpleAcp::Models::Message.agent("First"),
+    SimpleAcp::Models::Message.agent("Second")
+  ]
+)
+```
+
+## Streaming Patterns
+
+### Token-by-Token
+
+Stream individual tokens for typing effect:
+
+```ruby
+server.agent("typer") do |context|
+  text = context.input.first&.text_content || "Hello World"
+
+  Enumerator.new do |yielder|
+    text.chars.each do |char|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(char)
+      )
+      sleep 0.05
+    end
+  end
+end
+```
+
+### Word-by-Word
+
+```ruby
+server.agent("word-stream") do |context|
+  text = context.input.first&.text_content || ""
+
+  Enumerator.new do |yielder|
+    text.split.each do |word|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(word + " ")
+      )
+      sleep 0.1
+    end
+  end
+end
+```
+
+### Progress Updates
+
+```ruby
+server.agent("processor") do |context|
+  items = parse_items(context.input)
+  total = items.length
+
+  Enumerator.new do |yielder|
+    items.each_with_index do |item, i|
+      # Process item
+      result = process(item)
+
+      # Report progress
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(
+          "Processing #{i + 1}/#{total}: #{result}"
+        )
+      )
+    end
+
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Complete!")
+    )
+  end
+end
+```
+
+### LLM Integration
+
+Stream responses from language models:
+
+```ruby
+server.agent("chat") do |context|
+  messages = context.history + context.input
+
+  Enumerator.new do |yielder|
+    llm.stream_chat(messages) do |chunk|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(chunk)
+      )
+    end
+  end
+end
+```
+
+### Mixed Content
+
+Stream different content types:
+
+```ruby
+server.agent("analyzer") do |context|
+  data = parse_data(context.input)
+
+  Enumerator.new do |yielder|
+    # Text update
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Analyzing data...")
+    )
+
+    result = analyze(data)
+
+    # JSON result
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent(
+        SimpleAcp::Models::MessagePart.json(result)
+      )
+    )
+
+    # Summary text
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Analysis complete!")
+    )
+  end
+end
+```
+
+## Event Types
+
+Streaming produces these events:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+
+    Server-->>Client: RunStartedEvent
+    Server-->>Client: MessageCreatedEvent
+    Server-->>Client: MessagePartEvent
+    Server-->>Client: MessageCompletedEvent
+    Note over Server,Client: Repeat for each message
+    Server-->>Client: RunCompletedEvent
+```
+
+## HTTP Streaming
+
+The server uses SSE for HTTP streaming:
+
+```
+POST /runs HTTP/1.1
+Accept: text/event-stream
+Content-Type: application/json
+
+{"agent_name": "chat", "input": [...]}
+
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+
+event: run_started
+data: {"run_id":"abc123"}
+
+event: message_created
+data: {"message":{"role":"agent","parts":[]}}
+
+event: message_part
+data: {"part":{"content_type":"text/plain","content":"Hello"}}
+
+event: message_completed
+data: {"message":{"role":"agent","parts":[...]}}
+
+event: run_completed
+data: {"run":{...}}
+```
+
+## Server-Side Streaming
+
+Execute streaming runs programmatically:
+
+```ruby
+server.run_stream(
+  agent_name: "chat",
+  input: messages
+) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\nDone!"
+  end
+end
+```
+
+## Error Handling
+
+Handle errors during streaming:
+
+```ruby
+server.agent("safe-streamer") do |context|
+  Enumerator.new do |yielder|
+    begin
+      process_stream(context.input) do |chunk|
+        yielder << SimpleAcp::Server::RunYield.new(
+          SimpleAcp::Models::Message.agent(chunk)
+        )
+      end
+    rescue StreamError => e
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("Stream error: #{e.message}")
+      )
+    end
+  end
+end
+```
+
+## Buffering
+
+For high-frequency updates, consider buffering:
+
+```ruby
+server.agent("buffered") do |context|
+  Enumerator.new do |yielder|
+    buffer = []
+
+    process_items(context.input) do |item|
+      buffer << item
+
+      # Flush every 10 items
+      if buffer.length >= 10
+        yielder << SimpleAcp::Server::RunYield.new(
+          SimpleAcp::Models::Message.agent(buffer.join)
+        )
+        buffer.clear
+      end
+    end
+
+    # Flush remaining
+    unless buffer.empty?
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(buffer.join)
+      )
+    end
+  end
+end
+```
+
+## Best Practices
+
+1. **Yield frequently** - Don't wait too long between yields
+2. **Handle errors** - Catch and report errors gracefully
+3. **Use appropriate chunking** - Balance frequency with overhead
+4. **Test streaming** - Verify event order and content
+5. **Monitor memory** - Stream large responses to avoid memory issues
+
+## Testing Streaming
+
+```ruby
+def test_streaming_agent
+  events = []
+
+  server.run_stream(
+    agent_name: "streamer",
+    input: [SimpleAcp::Models::Message.user("test")]
+  ) do |event|
+    events << event
+  end
+
+  # Verify event sequence
+  assert events.first.is_a?(SimpleAcp::Models::RunStartedEvent)
+  assert events.last.is_a?(SimpleAcp::Models::RunCompletedEvent)
+
+  # Check message events
+  message_events = events.select { |e| e.is_a?(SimpleAcp::Models::MessagePartEvent) }
+  assert message_events.length > 0
+end
+```
+
+## Next Steps
+
+- Learn about [Multi-Turn Conversations](multi-turn.md)
+- See [Client Streaming](../client/streaming.md) for consuming streams
+- Review [Events](../core-concepts/events.md) for event details