simple_acp 0.0.1

data/docs/api/storage.md

@@ -0,0 +1,347 @@
+# Storage
+
+Storage backend interface and implementations.
+
+## Interface
+
+All storage backends extend `SimpleAcp::Storage::Base`.
+
+### Class: SimpleAcp::Storage::Base
+
+#### Constructor
+
+```ruby
+SimpleAcp::Storage::Base.new(options = {})
+```
+
+#### Abstract Methods
+
+These methods must be implemented by subclasses:
+
+---
+
+##### #get_run
+
+Retrieve a run by ID.
+
+```ruby
+storage.get_run(run_id)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `run_id` | `String` | Run ID |
+
+**Returns:** `Models::Run` or `nil`
+
+---
+
+##### #save_run
+
+Save a run.
+
+```ruby
+storage.save_run(run)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `run` | `Models::Run` | Run to save |
+
+**Returns:** `Models::Run`
+
+---
+
+##### #delete_run
+
+Delete a run and its events.
+
+```ruby
+storage.delete_run(run_id)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `run_id` | `String` | Run ID |
+
+**Returns:** `void`
+
+---
+
+##### #list_runs
+
+List runs with optional filtering.
+
+```ruby
+storage.list_runs(agent_name: nil, session_id: nil, limit: 10, offset: 0)
+```
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `agent_name` | `String` | `nil` | Filter by agent |
+| `session_id` | `String` | `nil` | Filter by session |
+| `limit` | `Integer` | `10` | Max results |
+| `offset` | `Integer` | `0` | Skip count |
+
+**Returns:** `Hash` with `:runs` and `:total`
+
+```ruby
+{ runs: [Run, ...], total: 42 }
+```
+
+---
+
+##### #get_session
+
+Retrieve a session by ID.
+
+```ruby
+storage.get_session(session_id)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | `String` | Session ID |
+
+**Returns:** `Models::Session` or `nil`
+
+---
+
+##### #save_session
+
+Save a session.
+
+```ruby
+storage.save_session(session)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session` | `Models::Session` | Session to save |
+
+**Returns:** `Models::Session`
+
+---
+
+##### #delete_session
+
+Delete a session.
+
+```ruby
+storage.delete_session(session_id)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `session_id` | `String` | Session ID |
+
+**Returns:** `void`
+
+---
+
+##### #add_event
+
+Add an event to a run.
+
+```ruby
+storage.add_event(run_id, event)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `run_id` | `String` | Run ID |
+| `event` | `Event` | Event to add |
+
+**Returns:** `Event`
+
+---
+
+##### #get_events
+
+Get events for a run.
+
+```ruby
+storage.get_events(run_id, limit: 100, offset: 0)
+```
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `run_id` | `String` | required | Run ID |
+| `limit` | `Integer` | `100` | Max events |
+| `offset` | `Integer` | `0` | Skip count |
+
+**Returns:** `Array<Event>`
+
+---
+
+#### Optional Methods
+
+These have default implementations:
+
+##### #close
+
+Close the storage connection.
+
+```ruby
+storage.close
+```
+
+**Default:** No-op
+
+---
+
+##### #ping
+
+Check if storage is accessible.
+
+```ruby
+storage.ping
+```
+
+**Returns:** `Boolean`
+
+**Default:** Returns `true`
+
+---
+
+## Implementations
+
+### Memory
+
+```ruby
+storage = SimpleAcp::Storage::Memory.new
+```
+
+**Additional Methods:**
+
+```ruby
+storage.clear!   # Clear all data
+storage.stats    # Get counts { runs: N, sessions: N, events: N }
+```
+
+---
+
+### Redis
+
+```ruby
+require 'simple_acp/storage/redis'
+
+storage = SimpleAcp::Storage::Redis.new(
+  url: "redis://localhost:6379",
+  ttl: 86400,        # TTL in seconds (default: 24 hours)
+  prefix: "acp:",    # Key prefix (default: "acp:")
+  redis: nil         # Existing Redis connection
+)
+```
+
+**Additional Methods:**
+
+```ruby
+storage.clear!   # Delete all keys with prefix
+```
+
+---
+
+### PostgreSQL
+
+```ruby
+require 'simple_acp/storage/postgresql'
+
+storage = SimpleAcp::Storage::PostgreSQL.new(
+  url: "postgres://localhost/simple_acp",
+  skip_setup: false,  # Skip table creation (default: false)
+  db: nil             # Existing Sequel database
+)
+```
+
+**Additional Methods:**
+
+```ruby
+storage.clear!   # Truncate all tables
+```
+
+---
+
+## Custom Implementation
+
+```ruby
+class MyStorage < SimpleAcp::Storage::Base
+  def initialize(options = {})
+    super
+    # Setup
+  end
+
+  def get_run(run_id)
+    # Implementation
+  end
+
+  def save_run(run)
+    # Implementation
+  end
+
+  def delete_run(run_id)
+    # Implementation
+  end
+
+  def list_runs(agent_name: nil, session_id: nil, limit: 10, offset: 0)
+    # Implementation
+  end
+
+  def get_session(session_id)
+    # Implementation
+  end
+
+  def save_session(session)
+    # Implementation
+  end
+
+  def delete_session(session_id)
+    # Implementation
+  end
+
+  def add_event(run_id, event)
+    # Implementation
+  end
+
+  def get_events(run_id, limit: 100, offset: 0)
+    # Implementation
+  end
+
+  def close
+    # Cleanup
+  end
+
+  def ping
+    # Health check
+    true
+  end
+end
+```
+
+---
+
+## See Also
+
+- [Storage Overview](../storage/index.md)
+- [Memory Storage](../storage/memory.md)
+- [Redis Storage](../storage/redis.md)
+- [PostgreSQL Storage](../storage/postgresql.md)
+- [Custom Backends](../storage/custom.md)

data/docs/client/index.md

@@ -0,0 +1,279 @@
+# Client Guide
+
+The SimpleAcp client provides a clean interface for communicating with ACP servers over HTTP.
+
+## Overview
+
+```mermaid
+graph LR
+    C[Client::Base] -->|HTTP| S[Server]
+    C -->|SSE| S
+    C --> A[Agents]
+    C --> R[Runs]
+    C --> SE[Sessions]
+```
+
+## Quick Start
+
+```ruby
+require 'simple_acp'
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+# Check connection
+puts client.ping ? "Connected!" : "Failed"
+
+# List agents
+agents = client.agents
+puts agents.agents.map(&:name)
+
+# Run an agent
+run = client.run_sync(
+  agent: "echo",
+  input: [SimpleAcp::Models::Message.user("Hello!")]
+)
+puts run.output.first.text_content
+```
+
+## In This Section
+
+<div class="grid cards" markdown>
+
+-   :material-sync:{ .lg .middle } **Sync & Async**
+
+    ---
+
+    Learn about synchronous and asynchronous execution
+
+    [:octicons-arrow-right-24: Sync & Async](sync-async.md)
+
+-   :material-play-speed:{ .lg .middle } **Streaming**
+
+    ---
+
+    Handle real-time streaming responses
+
+    [:octicons-arrow-right-24: Streaming](streaming.md)
+
+-   :material-history:{ .lg .middle } **Session Management**
+
+    ---
+
+    Maintain state across interactions
+
+    [:octicons-arrow-right-24: Sessions](sessions.md)
+
+</div>
+
+## Client Configuration
+
+### Basic Setup
+
+```ruby
+client = SimpleAcp::Client::Base.new(
+  base_url: "http://localhost:8000"
+)
+```
+
+### With Timeout
+
+```ruby
+client = SimpleAcp::Client::Base.new(
+  base_url: "http://localhost:8000",
+  timeout: 60  # seconds
+)
+```
+
+### With Headers
+
+```ruby
+client = SimpleAcp::Client::Base.new(
+  base_url: "http://localhost:8000",
+  headers: {
+    "Authorization" => "Bearer #{ENV['API_TOKEN']}",
+    "X-Request-ID" => SecureRandom.uuid
+  }
+)
+```
+
+## Discovery Methods
+
+### Health Check
+
+```ruby
+if client.ping
+  puts "Server is healthy"
+else
+  puts "Server unavailable"
+end
+```
+
+### List Agents
+
+```ruby
+response = client.agents
+response.agents.each do |agent|
+  puts "#{agent.name}: #{agent.description}"
+end
+```
+
+### Get Agent Details
+
+```ruby
+manifest = client.agent("echo")
+puts manifest.name
+puts manifest.description
+puts manifest.input_content_types
+puts manifest.output_content_types
+```
+
+## Execution Methods
+
+### Synchronous
+
+Wait for completion:
+
+```ruby
+run = client.run_sync(
+  agent: "processor",
+  input: [SimpleAcp::Models::Message.user("Process this")]
+)
+
+case run.status
+when "completed"
+  puts run.output.first.text_content
+when "failed"
+  puts "Error: #{run.error.message}"
+when "awaiting"
+  # Handle await...
+end
+```
+
+### Asynchronous
+
+Start and poll:
+
+```ruby
+run = client.run_async(
+  agent: "slow-processor",
+  input: [SimpleAcp::Models::Message.user("Data")]
+)
+
+puts "Started: #{run.run_id}"
+
+# Poll until complete
+loop do
+  run = client.run_status(run.run_id)
+  break if run.terminal?
+  sleep 1
+end
+
+puts run.output
+```
+
+### Streaming
+
+Real-time events:
+
+```ruby
+client.run_stream(
+  agent: "chat",
+  input: [SimpleAcp::Models::Message.user("Hello")]
+) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\nDone!"
+  end
+end
+```
+
+## Run Management
+
+### Get Status
+
+```ruby
+run = client.run_status("run-id-here")
+puts run.status
+```
+
+### Get Events
+
+```ruby
+events = client.run_events("run-id-here")
+events.each do |event|
+  puts event.type
+end
+```
+
+### Cancel Run
+
+```ruby
+client.run_cancel("run-id-here")
+```
+
+### Resume Awaited Run
+
+```ruby
+run = client.run_resume_sync(
+  run_id: "run-id-here",
+  await_resume: SimpleAcp::Models::MessageAwaitResume.new(
+    message: SimpleAcp::Models::Message.user("My response")
+  )
+)
+```
+
+## Session Management
+
+### Use a Session
+
+```ruby
+client.use_session("my-session-id")
+
+# All runs now use this session
+client.run_sync(agent: "chat", input: [...])
+client.run_sync(agent: "chat", input: [...])
+```
+
+### Clear Session
+
+```ruby
+client.clear_session
+```
+
+### Get Session Info
+
+```ruby
+session = client.session("my-session-id")
+puts session.history.length
+puts session.state
+```
+
+## Error Handling
+
+```ruby
+begin
+  run = client.run_sync(agent: "unknown", input: [...])
+rescue SimpleAcp::Error => e
+  puts "ACP Error: #{e.message}"
+rescue Faraday::TimeoutError
+  puts "Request timed out"
+rescue Faraday::ConnectionFailed
+  puts "Could not connect to server"
+end
+```
+
+## Best Practices
+
+1. **Reuse clients** - Create one client and reuse it
+2. **Handle errors** - Always catch and handle exceptions
+3. **Use appropriate mode** - Sync for quick ops, async/stream for long ops
+4. **Manage sessions** - Clear sessions when done
+5. **Set timeouts** - Configure appropriate timeout values
+
+## Next Steps
+
+- Learn about [Sync & Async](sync-async.md) execution
+- Master [Streaming](streaming.md) responses
+- Explore [Session Management](sessions.md)