simple_acp 0.0.1

data/docs/core-concepts/runs.md

@@ -0,0 +1,278 @@
+# Runs
+
+A Run represents a single execution of an agent. It tracks the complete lifecycle from initiation to completion, including status, output, and any errors.
+
+## Run Lifecycle
+
+```mermaid
+stateDiagram-v2
+    [*] --> created
+    created --> in_progress
+    in_progress --> completed
+    in_progress --> failed
+    in_progress --> awaiting
+    in_progress --> cancelled
+    awaiting --> in_progress: resume
+    completed --> [*]
+    failed --> [*]
+    cancelled --> [*]
+```
+
+## Run States
+
+| Status | Description |
+|--------|-------------|
+| `created` | Run has been created but not started |
+| `in_progress` | Agent is currently executing |
+| `completed` | Agent finished successfully |
+| `failed` | Agent encountered an error |
+| `awaiting` | Agent is waiting for additional input |
+| `cancelled` | Run was cancelled by request |
+
+## Creating Runs
+
+### Synchronous
+
+Execute and wait for completion:
+
+```ruby
+run = client.run_sync(
+  agent: "echo",
+  input: [SimpleAcp::Models::Message.user("Hello")]
+)
+
+puts run.status        # => "completed"
+puts run.output.first  # => Message object
+```
+
+### Asynchronous
+
+Start execution and poll for results:
+
+```ruby
+run = client.run_async(
+  agent: "slow-processor",
+  input: [SimpleAcp::Models::Message.user("Process this")]
+)
+
+puts run.status  # => "in_progress"
+
+# Poll until complete
+loop do
+  run = client.run_status(run.run_id)
+  break if run.terminal?
+  sleep 1
+end
+
+puts run.output
+```
+
+### Streaming
+
+Receive real-time events:
+
+```ruby
+client.run_stream(
+  agent: "chat",
+  input: [SimpleAcp::Models::Message.user("Tell me a story")]
+) do |event|
+  case event
+  when SimpleAcp::Models::RunStartedEvent
+    puts "Started: #{event.run_id}"
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\nDone!"
+  end
+end
+```
+
+## Run Properties
+
+```ruby
+run = client.run_sync(agent: "echo", input: [...])
+
+# Identification
+run.run_id        # => "550e8400-e29b-41d4-a716-446655440000"
+run.agent_name    # => "echo"
+run.session_id    # => "session-123" or nil
+
+# Status
+run.status        # => "completed"
+run.terminal?     # => true
+run.completed?    # => true
+run.failed?       # => false
+run.awaiting?     # => false
+run.cancelled?    # => false
+
+# Output
+run.output        # => Array of Messages
+run.error         # => Error object or nil
+
+# Timestamps
+run.created_at    # => Time
+run.finished_at   # => Time or nil
+```
+
+## Handling Different States
+
+### Completed Runs
+
+```ruby
+run = client.run_sync(agent: "processor", input: [...])
+
+if run.completed?
+  run.output.each do |message|
+    puts message.text_content
+  end
+end
+```
+
+### Failed Runs
+
+```ruby
+run = client.run_sync(agent: "risky", input: [...])
+
+if run.failed?
+  puts "Error code: #{run.error.code}"
+  puts "Error message: #{run.error.message}"
+end
+```
+
+### Awaiting Runs
+
+```ruby
+run = client.run_sync(agent: "questioner", input: [...])
+
+if run.awaiting?
+  # The agent is waiting for more input
+  puts run.await_request.message.text_content
+
+  # Resume with a response
+  run = client.run_resume_sync(
+    run_id: run.run_id,
+    await_resume: SimpleAcp::Models::MessageAwaitResume.new(
+      message: SimpleAcp::Models::Message.user("My response")
+    )
+  )
+end
+```
+
+## Run Management
+
+### Get Run Status
+
+```ruby
+run = client.run_status("run-id-here")
+puts run.status
+```
+
+### Get Run Events
+
+```ruby
+events = client.run_events("run-id-here")
+events.each do |event|
+  puts "#{event.type}: #{event.inspect}"
+end
+```
+
+### Cancel a Run
+
+```ruby
+# Cancel an in-progress run
+client.run_cancel("run-id-here")
+```
+
+## Server-Side Runs
+
+On the server, runs are managed internally:
+
+```ruby
+# Create and execute a run programmatically
+run = server.run_sync(
+  agent_name: "processor",
+  input: [SimpleAcp::Models::Message.user("Data")],
+  session_id: "optional-session"
+)
+
+# Stream execution
+server.run_stream(
+  agent_name: "streamer",
+  input: messages
+) do |event|
+  # Handle events
+end
+```
+
+## Run with Sessions
+
+Associate runs with sessions for stateful interactions:
+
+```ruby
+# Client side
+client.use_session("conversation-123")
+
+# All runs now use this session
+run1 = client.run_sync(agent: "chat", input: [...])
+run2 = client.run_sync(agent: "chat", input: [...])
+
+# Server side
+run = server.run_sync(
+  agent_name: "chat",
+  input: messages,
+  session_id: "conversation-123"
+)
+```
+
+## Best Practices
+
+### Always Check Status
+
+```ruby
+run = client.run_sync(agent: "...", input: [...])
+
+case run.status
+when "completed"
+  process_output(run.output)
+when "failed"
+  handle_error(run.error)
+when "awaiting"
+  handle_await(run)
+else
+  log_unexpected_status(run.status)
+end
+```
+
+### Use Streaming for Long Operations
+
+```ruby
+# Better UX for slow operations
+client.run_stream(agent: "slow-agent", input: [...]) do |event|
+  show_progress(event)
+end
+```
+
+### Handle Timeouts
+
+```ruby
+run = client.run_async(agent: "slow", input: [...])
+timeout = Time.now + 60
+
+loop do
+  run = client.run_status(run.run_id)
+  break if run.terminal?
+
+  if Time.now > timeout
+    client.run_cancel(run.run_id)
+    raise "Run timed out"
+  end
+
+  sleep 1
+end
+```
+
+## Next Steps
+
+- Learn about [Sessions](sessions.md) for stateful runs
+- Explore [Events](events.md) for real-time updates
+- See [Client Streaming](../client/streaming.md) for advanced streaming patterns

data/docs/core-concepts/sessions.md

@@ -0,0 +1,281 @@
+# Sessions
+
+Sessions enable stateful interactions across multiple runs. They maintain conversation history and custom state data, allowing agents to remember context from previous interactions.
+
+## What is a Session?
+
+A session is a container for:
+
+- **History**: Previous messages in the conversation
+- **State**: Custom data persisted across runs
+- **Identity**: A unique session ID
+
+```mermaid
+graph TB
+    subgraph Session
+        H[History] --> R1[Run 1]
+        H --> R2[Run 2]
+        H --> R3[Run 3]
+        S[State]
+    end
+```
+
+## Creating Sessions
+
+### Client-Side Sessions
+
+```ruby
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+# Use a specific session
+client.use_session("user-123-conversation")
+
+# All subsequent runs use this session
+client.run_sync(agent: "chat", input: [...])
+client.run_sync(agent: "chat", input: [...])
+
+# Clear when done
+client.clear_session
+```
+
+### Server-Side Sessions
+
+```ruby
+# Specify session when creating a run
+run = server.run_sync(
+  agent_name: "chat",
+  input: messages,
+  session_id: "conversation-456"
+)
+```
+
+## Session History
+
+History automatically accumulates messages across runs:
+
+```ruby
+# First run
+client.use_session("my-session")
+client.run_sync(agent: "chat", input: [Message.user("Hello")])
+# History: [user: "Hello", agent: "Hi there!"]
+
+# Second run
+client.run_sync(agent: "chat", input: [Message.user("How are you?")])
+# History: [user: "Hello", agent: "Hi there!", user: "How are you?", agent: "I'm good!"]
+```
+
+### Accessing History in Agents
+
+```ruby
+server.agent("contextual") do |context|
+  # Get all previous messages
+  history = context.history
+
+  # Build context from history
+  conversation = history.map do |msg|
+    "#{msg.role}: #{msg.text_content}"
+  end.join("\n")
+
+  SimpleAcp::Models::Message.agent(
+    "Based on our conversation:\n#{conversation}\n\nContinuing..."
+  )
+end
+```
+
+## Session State
+
+Custom state data persists across runs:
+
+```ruby
+server.agent("counter") do |context|
+  # Read current state (nil if first run)
+  count = context.state || 0
+
+  # Increment
+  count += 1
+
+  # Save new state
+  context.set_state(count)
+
+  SimpleAcp::Models::Message.agent("Count: #{count}")
+end
+```
+
+### Complex State
+
+State can be any JSON-serializable data:
+
+```ruby
+server.agent("quiz") do |context|
+  state = context.state || { score: 0, questions_asked: 0 }
+
+  # Update state
+  state[:questions_asked] += 1
+  if correct_answer?(context.input)
+    state[:score] += 1
+  end
+
+  context.set_state(state)
+
+  SimpleAcp::Models::Message.agent(
+    "Score: #{state[:score]}/#{state[:questions_asked]}"
+  )
+end
+```
+
+## Session Properties
+
+```ruby
+session = client.session("session-id")
+
+session.id       # => "session-id"
+session.history  # => Array of Messages
+session.state    # => Custom state data or nil
+```
+
+## Session Storage
+
+Sessions are persisted by the storage backend:
+
+=== "Memory"
+
+    ```ruby
+    # Sessions lost on restart
+    storage = SimpleAcp::Storage::Memory.new
+    ```
+
+=== "Redis"
+
+    ```ruby
+    # Sessions expire after TTL
+    storage = SimpleAcp::Storage::Redis.new(
+      ttl: 86400  # 24 hours
+    )
+    ```
+
+=== "PostgreSQL"
+
+    ```ruby
+    # Sessions persist indefinitely
+    storage = SimpleAcp::Storage::PostgreSQL.new(
+      url: ENV['DATABASE_URL']
+    )
+    ```
+
+## Common Patterns
+
+### Multi-Turn Conversation
+
+```ruby
+server.agent("assistant") do |context|
+  # Build prompt with history
+  messages = context.history + context.input
+
+  # Call LLM with full context
+  response = llm.chat(messages)
+
+  SimpleAcp::Models::Message.agent(response)
+end
+```
+
+### User Preferences
+
+```ruby
+server.agent("personalized") do |context|
+  state = context.state || { preferences: {} }
+
+  # Check for preference updates
+  if context.input.first&.text_content&.start_with?("set preference")
+    key, value = parse_preference(context.input.first.text_content)
+    state[:preferences][key] = value
+    context.set_state(state)
+    return SimpleAcp::Models::Message.agent("Preference saved!")
+  end
+
+  # Use preferences
+  prefs = state[:preferences]
+  # ...
+end
+```
+
+### Shopping Cart
+
+```ruby
+server.agent("cart") do |context|
+  cart = context.state || { items: [], total: 0 }
+
+  command = context.input.first&.text_content
+
+  case command
+  when /^add (.+)/
+    item = $1
+    cart[:items] << item
+    cart[:total] += get_price(item)
+  when /^remove (.+)/
+    item = $1
+    cart[:items].delete(item)
+    cart[:total] -= get_price(item)
+  when "checkout"
+    # Process order...
+    cart = { items: [], total: 0 }
+  end
+
+  context.set_state(cart)
+
+  SimpleAcp::Models::Message.agent(
+    "Cart: #{cart[:items].join(', ')} - Total: $#{cart[:total]}"
+  )
+end
+```
+
+## Best Practices
+
+### Generate Meaningful Session IDs
+
+```ruby
+# Good: Meaningful, traceable
+client.use_session("user-#{user_id}-chat-#{timestamp}")
+
+# Avoid: Random, hard to debug
+client.use_session(SecureRandom.uuid)
+```
+
+### Clean Up Sessions
+
+```ruby
+# When conversation ends
+client.clear_session
+
+# Or delete server-side
+storage.delete_session(session_id)
+```
+
+### Limit History Size
+
+```ruby
+server.agent("bounded") do |context|
+  # Only use recent history
+  recent = context.history.last(10)
+  # ...
+end
+```
+
+### Handle Missing State
+
+```ruby
+server.agent("safe") do |context|
+  # Always provide defaults
+  state = context.state || default_state
+
+  # Validate state structure
+  state[:version] ||= 1
+  state[:data] ||= {}
+  # ...
+end
+```
+
+## Next Steps
+
+- Learn about [Events](events.md) for real-time updates
+- Explore [Multi-Turn Conversations](../server/multi-turn.md)
+- See [Session Management](../client/sessions.md) in the client guide