simple_acp 0.0.1

data/docs/core-concepts/events.md

@@ -0,0 +1,337 @@
+# Events
+
+Events provide real-time updates during run execution. They enable streaming responses, progress tracking, and reactive client applications.
+
+## Event Types
+
+```mermaid
+graph LR
+    R[Run] --> E1[RunStartedEvent]
+    R --> E2[MessageCreatedEvent]
+    R --> E3[MessagePartEvent]
+    R --> E4[RunCompletedEvent]
+    R --> E5[RunFailedEvent]
+    R --> E6[RunAwaitingEvent]
+```
+
+### RunStartedEvent
+
+Emitted when a run begins execution:
+
+```ruby
+event.type     # => "run_started"
+event.run_id   # => "550e8400-..."
+```
+
+### MessageCreatedEvent
+
+Emitted when a new message is created:
+
+```ruby
+event.type     # => "message_created"
+event.message  # => Message object
+```
+
+### MessagePartEvent
+
+Emitted for each part of a message (enables streaming):
+
+```ruby
+event.type  # => "message_part"
+event.part  # => MessagePart object
+```
+
+### MessageCompletedEvent
+
+Emitted when a message is fully assembled:
+
+```ruby
+event.type     # => "message_completed"
+event.message  # => Complete Message object
+```
+
+### RunCompletedEvent
+
+Emitted when a run finishes successfully:
+
+```ruby
+event.type   # => "run_completed"
+event.run    # => Completed Run object
+```
+
+### RunFailedEvent
+
+Emitted when a run encounters an error:
+
+```ruby
+event.type   # => "run_failed"
+event.run    # => Failed Run object
+event.error  # => Error object
+```
+
+### RunAwaitingEvent
+
+Emitted when a run needs additional input:
+
+```ruby
+event.type          # => "run_awaiting"
+event.run           # => Run object
+event.await_request # => AwaitRequest object
+```
+
+## Consuming Events
+
+### Streaming Client
+
+```ruby
+client.run_stream(agent: "chat", input: messages) do |event|
+  case event
+  when SimpleAcp::Models::RunStartedEvent
+    puts "Run #{event.run_id} started"
+
+  when SimpleAcp::Models::MessageCreatedEvent
+    puts "New message from #{event.message.role}"
+
+  when SimpleAcp::Models::MessagePartEvent
+    # Stream content as it arrives
+    print event.part.content
+    $stdout.flush
+
+  when SimpleAcp::Models::MessageCompletedEvent
+    puts "\n--- Message complete ---"
+
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\nRun completed!"
+
+  when SimpleAcp::Models::RunFailedEvent
+    puts "\nError: #{event.error.message}"
+
+  when SimpleAcp::Models::RunAwaitingEvent
+    puts "\nAwaiting input..."
+  end
+end
+```
+
+### Fetching Historical Events
+
+```ruby
+events = client.run_events(run_id)
+
+events.each do |event|
+  puts "#{event.type}: #{event.inspect}"
+end
+```
+
+## Server-Side Events
+
+### Yielding Events
+
+Agents emit events by yielding from an Enumerator:
+
+```ruby
+server.agent("streamer") do |context|
+  Enumerator.new do |yielder|
+    words = context.input.first&.text_content&.split || []
+
+    words.each do |word|
+      # Each yield creates events
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent(word + " ")
+      )
+      sleep 0.1
+    end
+  end
+end
+```
+
+### Event Flow
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+    participant Agent
+
+    Client->>Server: run_stream
+    Server->>Agent: execute
+
+    Agent-->>Server: yield message
+    Server-->>Client: RunStartedEvent
+    Server-->>Client: MessageCreatedEvent
+    Server-->>Client: MessagePartEvent
+
+    Agent-->>Server: yield message
+    Server-->>Client: MessageCreatedEvent
+    Server-->>Client: MessagePartEvent
+
+    Agent-->>Server: return
+    Server-->>Client: RunCompletedEvent
+```
+
+## Server-Sent Events (SSE)
+
+When using HTTP streaming, events are delivered via Server-Sent Events:
+
+```
+GET /runs HTTP/1.1
+Accept: text/event-stream
+
+HTTP/1.1 200 OK
+Content-Type: text/event-stream
+
+event: run_started
+data: {"run_id":"550e8400-..."}
+
+event: message_part
+data: {"part":{"content_type":"text/plain","content":"Hello"}}
+
+event: run_completed
+data: {"run":{...}}
+```
+
+### Raw SSE Handling
+
+```ruby
+require 'faraday'
+
+conn = Faraday.new(url: 'http://localhost:8000')
+
+conn.post('/runs') do |req|
+  req.headers['Accept'] = 'text/event-stream'
+  req.body = { agent_name: 'chat', input: [...] }.to_json
+
+  req.options.on_data = proc do |chunk, _|
+    # Parse SSE format
+    chunk.split("\n\n").each do |event_text|
+      # Process event...
+    end
+  end
+end
+```
+
+## Common Patterns
+
+### Progress Indicator
+
+```ruby
+total = 0
+client.run_stream(agent: "processor", input: data) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    total += 1
+    print "\rProcessed: #{total} items"
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\nDone!"
+  end
+end
+```
+
+### Collecting All Output
+
+```ruby
+messages = []
+
+client.run_stream(agent: "chat", input: question) do |event|
+  case event
+  when SimpleAcp::Models::MessageCompletedEvent
+    messages << event.message
+  end
+end
+
+puts "Received #{messages.length} messages"
+```
+
+### Error Recovery
+
+```ruby
+begin
+  client.run_stream(agent: "risky", input: data) do |event|
+    case event
+    when SimpleAcp::Models::RunFailedEvent
+      log_error(event.error)
+      # Don't raise, handle gracefully
+    end
+  end
+rescue Faraday::TimeoutError
+  puts "Stream timed out"
+  # Retry logic...
+end
+```
+
+### Building Real-Time UI
+
+```ruby
+# In a web application
+def stream_response(agent, input)
+  response.headers['Content-Type'] = 'text/event-stream'
+
+  client.run_stream(agent: agent, input: input) do |event|
+    case event
+    when SimpleAcp::Models::MessagePartEvent
+      response.write("data: #{event.part.content.to_json}\n\n")
+    when SimpleAcp::Models::RunCompletedEvent
+      response.write("event: done\ndata: {}\n\n")
+    end
+  end
+end
+```
+
+## Event Persistence
+
+Events are stored and can be retrieved later:
+
+```ruby
+# Run completes
+run = client.run_sync(agent: "logger", input: [...])
+
+# Later, retrieve events
+events = client.run_events(run.run_id)
+events.each { |e| puts e.type }
+```
+
+## Best Practices
+
+### Handle All Event Types
+
+```ruby
+client.run_stream(agent: "...", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::RunStartedEvent
+    # Handle start
+  when SimpleAcp::Models::MessagePartEvent
+    # Handle streaming content
+  when SimpleAcp::Models::RunCompletedEvent
+    # Handle completion
+  when SimpleAcp::Models::RunFailedEvent
+    # Handle errors
+  when SimpleAcp::Models::RunAwaitingEvent
+    # Handle await
+  else
+    # Log unknown events
+    logger.warn("Unknown event: #{event.type}")
+  end
+end
+```
+
+### Use Events for UX
+
+```ruby
+# Show typing indicator
+client.run_stream(agent: "chat", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::RunStartedEvent
+    show_typing_indicator
+  when SimpleAcp::Models::MessagePartEvent
+    hide_typing_indicator
+    append_content(event.part.content)
+  when SimpleAcp::Models::RunCompletedEvent
+    mark_complete
+  end
+end
+```
+
+## Next Steps
+
+- Explore [Client Streaming](../client/streaming.md) for advanced patterns
+- Learn about [Server Streaming](../server/streaming.md) for generating events
+- See the [API Reference](../api/models.md) for event model details

data/docs/core-concepts/index.md

@@ -0,0 +1,147 @@
+# Core Concepts
+
+Understanding the core concepts of the Agent Communication Protocol (ACP) is essential for building effective agent systems with SimpleAcp.
+
+## Overview
+
+ACP defines a standardized way for agents, applications, and humans to communicate. The protocol centers around these key concepts:
+
+```mermaid
+graph TB
+    subgraph "Core Concepts"
+        M[Messages] --> R[Runs]
+        A[Agents] --> R
+        R --> S[Sessions]
+        R --> E[Events]
+    end
+```
+
+## The Building Blocks
+
+### Messages
+
+[Messages](messages.md) are the fundamental unit of communication. They carry content between users and agents.
+
+```ruby
+# User sends a message
+message = SimpleAcp::Models::Message.user("What's the weather?")
+
+# Agent responds with a message
+response = SimpleAcp::Models::Message.agent("It's sunny and 72°F")
+```
+
+### Agents
+
+[Agents](agents.md) are the processing units that receive input and produce output. They're registered on servers and can be invoked by clients.
+
+```ruby
+server.agent("weather", description: "Gets weather information") do |context|
+  # Process context.input and return response
+end
+```
+
+### Runs
+
+[Runs](runs.md) represent a single execution of an agent. They track the lifecycle from start to completion, including any errors or awaiting states.
+
+```ruby
+run = client.run_sync(agent: "weather", input: [...])
+puts run.status      # "completed"
+puts run.output      # Response messages
+```
+
+### Sessions
+
+[Sessions](sessions.md) maintain state across multiple runs, enabling multi-turn conversations and stateful interactions.
+
+```ruby
+client.use_session("conversation-123")
+# All subsequent runs share this session
+```
+
+### Events
+
+[Events](events.md) provide real-time updates during run execution, enabling streaming responses and progress tracking.
+
+```ruby
+client.run_stream(agent: "...", input: [...]) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content  # Stream as it arrives
+  end
+end
+```
+
+## How They Work Together
+
+Here's how these concepts interact in a typical flow:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Server
+    participant Agent
+    participant Storage
+
+    Client->>Server: Create Run (Messages)
+    Server->>Storage: Store Run
+    Server->>Agent: Execute with Context
+    Agent-->>Server: Events (streaming)
+    Server-->>Client: Events (SSE)
+    Agent->>Server: Output Messages
+    Server->>Storage: Update Run
+    Server->>Client: Run Completed
+```
+
+1. **Client** creates a run by sending input messages to the server
+2. **Server** creates a Run record and invokes the appropriate agent
+3. **Agent** processes the input through its handler, optionally yielding events
+4. **Events** stream back to the client in real-time
+5. **Run** completes with output messages
+6. **Session** (if used) maintains state for subsequent runs
+
+## Deep Dives
+
+<div class="grid cards" markdown>
+
+-   :material-message-text:{ .lg .middle } **Messages**
+
+    ---
+
+    Learn about message structure, parts, and content types
+
+    [:octicons-arrow-right-24: Messages](messages.md)
+
+-   :material-robot:{ .lg .middle } **Agents**
+
+    ---
+
+    Understand agent registration and the handler pattern
+
+    [:octicons-arrow-right-24: Agents](agents.md)
+
+-   :material-play-circle:{ .lg .middle } **Runs**
+
+    ---
+
+    Explore run lifecycle, status, and execution modes
+
+    [:octicons-arrow-right-24: Runs](runs.md)
+
+-   :material-history:{ .lg .middle } **Sessions**
+
+    ---
+
+    Master stateful interactions and conversation history
+
+    [:octicons-arrow-right-24: Sessions](sessions.md)
+
+-   :material-lightning-bolt:{ .lg .middle } **Events**
+
+    ---
+
+    Handle real-time streaming updates
+
+    [:octicons-arrow-right-24: Events](events.md)
+
+</div>

data/docs/core-concepts/messages.md

@@ -0,0 +1,211 @@
+# Messages
+
+Messages are the fundamental unit of communication in ACP. They carry content between users and agents.
+
+## Message Structure
+
+Every message has two essential properties:
+
+- **role**: Either `"user"` or `"agent"`
+- **parts**: An array of content parts
+
+```ruby
+message = SimpleAcp::Models::Message.new(
+  role: "user",
+  parts: [
+    SimpleAcp::Models::MessagePart.text("Hello!")
+  ]
+)
+```
+
+## Creating Messages
+
+### Factory Methods
+
+The simplest way to create messages:
+
+```ruby
+# User message with text
+user_msg = SimpleAcp::Models::Message.user("What's the weather?")
+
+# Agent message with text
+agent_msg = SimpleAcp::Models::Message.agent("It's sunny and 72°F")
+```
+
+### Multiple Parts
+
+Messages can contain multiple content parts:
+
+```ruby
+message = SimpleAcp::Models::Message.user(
+  SimpleAcp::Models::MessagePart.text("Here's my data:"),
+  SimpleAcp::Models::MessagePart.json({ values: [1, 2, 3] })
+)
+```
+
+### From Hash
+
+Parse messages from JSON/hash data:
+
+```ruby
+message = SimpleAcp::Models::Message.from_hash({
+  "role" => "user",
+  "parts" => [
+    { "content_type" => "text/plain", "content" => "Hello" }
+  ]
+})
+```
+
+## Message Parts
+
+Each part has a content type and content payload.
+
+### Text Content
+
+Plain text is the most common content type:
+
+```ruby
+part = SimpleAcp::Models::MessagePart.text("Hello, world!")
+
+part.content_type  # => "text/plain"
+part.content       # => "Hello, world!"
+part.text?         # => true
+```
+
+### JSON Content
+
+Structured data as JSON:
+
+```ruby
+part = SimpleAcp::Models::MessagePart.json({
+  temperature: 72,
+  conditions: "sunny",
+  humidity: 45
+})
+
+part.content_type  # => "application/json"
+part.content       # => "{\"temperature\":72,...}"
+part.json?         # => true
+```
+
+### Image Content
+
+Base64-encoded images:
+
+```ruby
+image_data = File.read("photo.png")
+part = SimpleAcp::Models::MessagePart.image(
+  Base64.strict_encode64(image_data),
+  mime_type: "image/png"
+)
+
+part.content_type      # => "image/png"
+part.content_encoding  # => "base64"
+part.image?            # => true
+```
+
+### URL References
+
+Reference external content by URL:
+
+```ruby
+part = SimpleAcp::Models::MessagePart.from_url(
+  "https://example.com/image.jpg",
+  content_type: "image/jpeg"
+)
+
+part.content_url  # => "https://example.com/image.jpg"
+```
+
+## Accessing Content
+
+### Text Content
+
+Get combined text from all parts:
+
+```ruby
+message = SimpleAcp::Models::Message.user(
+  SimpleAcp::Models::MessagePart.text("Hello "),
+  SimpleAcp::Models::MessagePart.text("World!")
+)
+
+message.text_content  # => "Hello World!"
+```
+
+### Individual Parts
+
+Access parts directly:
+
+```ruby
+message.parts.each do |part|
+  puts "Type: #{part.content_type}"
+  puts "Content: #{part.content}"
+end
+```
+
+### Type Checking
+
+Check content types:
+
+```ruby
+part.text?   # Is text/plain?
+part.json?   # Is application/json?
+part.image?  # Is image/*?
+```
+
+## Serialization
+
+Messages can be serialized to JSON:
+
+```ruby
+message = SimpleAcp::Models::Message.user("Hello")
+
+# To hash
+hash = message.to_h
+# => { role: "user", parts: [...] }
+
+# To JSON
+json = message.to_json
+# => '{"role":"user","parts":[...]}'
+```
+
+## Common Patterns
+
+### Echo Agent
+
+```ruby
+server.agent("echo") do |context|
+  context.input.map do |msg|
+    SimpleAcp::Models::Message.agent(msg.text_content)
+  end
+end
+```
+
+### Transform Content
+
+```ruby
+server.agent("uppercase") do |context|
+  text = context.input.first&.text_content || ""
+  SimpleAcp::Models::Message.agent(text.upcase)
+end
+```
+
+### Multi-Part Response
+
+```ruby
+server.agent("analysis") do |context|
+  SimpleAcp::Models::Message.agent(
+    SimpleAcp::Models::MessagePart.text("Analysis complete:"),
+    SimpleAcp::Models::MessagePart.json({
+      word_count: 150,
+      sentiment: "positive"
+    })
+  )
+end
+```
+
+## Next Steps
+
+- Learn about [Agents](agents.md) that process messages
+- Understand [Runs](runs.md) that execute agent logic
+- Explore [Events](events.md) for streaming message delivery