simple_acp 0.0.1

data/docs/getting-started/configuration.md

@@ -0,0 +1,166 @@
+# Configuration
+
+SimpleAcp can be configured at multiple levels: global configuration, server options, and client options.
+
+## Global Configuration
+
+Use the global configure block to set default options:
+
+```ruby
+SimpleAcp.configure do |config|
+  config.default_storage = :memory  # :memory, :redis, or :postgresql
+  config.logger = Logger.new(STDOUT)
+end
+```
+
+## Server Configuration
+
+### Basic Options
+
+```ruby
+server = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::Memory.new
+)
+```
+
+### Storage Backend
+
+Choose the appropriate storage backend for your deployment:
+
+=== "Memory (Default)"
+
+    ```ruby
+    storage = SimpleAcp::Storage::Memory.new
+    server = SimpleAcp::Server::Base.new(storage: storage)
+    ```
+
+    Best for: Development, testing, single-process deployments
+
+=== "Redis"
+
+    ```ruby
+    require 'simple_acp/storage/redis'
+
+    storage = SimpleAcp::Storage::Redis.new(
+      url: ENV['REDIS_URL'] || 'redis://localhost:6379',
+      ttl: 86400,      # 24 hours (default)
+      prefix: 'acp:'   # Key prefix (default)
+    )
+    server = SimpleAcp::Server::Base.new(storage: storage)
+    ```
+
+    Best for: Multi-process deployments, horizontal scaling
+
+=== "PostgreSQL"
+
+    ```ruby
+    require 'simple_acp/storage/postgresql'
+
+    storage = SimpleAcp::Storage::PostgreSQL.new(
+      url: ENV['DATABASE_URL'] || 'postgres://localhost/simple_acp',
+      skip_setup: false  # Auto-create tables (default: false)
+    )
+    server = SimpleAcp::Server::Base.new(storage: storage)
+    ```
+
+    Best for: Production deployments, data persistence
+
+### HTTP Server Options
+
+When running the HTTP server with Falcon:
+
+```ruby
+server.run(
+  port: 8000,              # Listen port
+  host: '0.0.0.0'          # Bind address
+)
+```
+
+Falcon uses fiber-based concurrency, efficiently handling thousands of concurrent SSE connections without manual thread configuration.
+
+## Client Configuration
+
+### Basic Options
+
+```ruby
+client = SimpleAcp::Client::Base.new(
+  base_url: 'http://localhost:8000',
+  timeout: 30  # Request timeout in seconds
+)
+```
+
+### With Authentication
+
+```ruby
+client = SimpleAcp::Client::Base.new(
+  base_url: 'http://localhost:8000',
+  headers: {
+    'Authorization' => "Bearer #{ENV['API_TOKEN']}"
+  }
+)
+```
+
+### Session Configuration
+
+```ruby
+# Use a specific session for stateful interactions
+client.use_session("user-123-session")
+
+# All subsequent requests will use this session
+client.run_sync(agent: "stateful-agent", input: "...")
+client.run_sync(agent: "stateful-agent", input: "...")
+
+# Clear when done
+client.clear_session
+```
+
+## Environment Variables
+
+SimpleAcp respects these environment variables:
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `REDIS_URL` | Redis connection URL | `redis://localhost:6379` |
+| `DATABASE_URL` | PostgreSQL connection URL | `postgres://localhost/acp` |
+
+## Agent Configuration
+
+When registering agents, you can configure:
+
+```ruby
+server.agent(
+  "my-agent",
+  description: "Description shown in manifest",
+  input_content_types: ["text/plain", "application/json"],
+  output_content_types: ["text/plain"]
+) do |context|
+  # Agent logic
+end
+```
+
+### Agent Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `description` | String | Human-readable description |
+| `input_content_types` | Array | Accepted input MIME types |
+| `output_content_types` | Array | Output MIME types produced |
+| `metadata` | Hash | Custom metadata |
+
+## Logging
+
+Configure logging for debugging:
+
+```ruby
+# Enable debug logging
+SimpleAcp.configure do |config|
+  config.logger = Logger.new(STDOUT)
+  config.logger.level = Logger::DEBUG
+end
+```
+
+## Next Steps
+
+- Explore [Core Concepts](../core-concepts/index.md)
+- Learn about [Storage Backends](../storage/index.md) in detail
+- Read the [Server Guide](../server/index.md) for advanced features

data/docs/getting-started/index.md

@@ -0,0 +1,62 @@
+# Getting Started
+
+Welcome to SimpleAcp! This section will help you get up and running with the Agent Communication Protocol in Ruby.
+
+## What You'll Learn
+
+- [**Installation**](installation.md) - How to add SimpleAcp to your project
+- [**Quick Start**](quick-start.md) - Build your first agent in minutes
+- [**Configuration**](configuration.md) - Customize SimpleAcp for your needs
+
+## Prerequisites
+
+Before you begin, ensure you have:
+
+- **Ruby 3.0 or later** - SimpleAcp uses modern Ruby features
+- **Bundler** - For managing gem dependencies
+
+## Installation Overview
+
+Add SimpleAcp to your Gemfile:
+
+```ruby
+gem 'simple_acp'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+That's it! You're ready to create your first agent.
+
+## Next Steps
+
+<div class="grid cards" markdown>
+
+-   :material-download:{ .lg .middle } **Installation**
+
+    ---
+
+    Detailed installation instructions and optional dependencies
+
+    [:octicons-arrow-right-24: Install](installation.md)
+
+-   :material-rocket-launch:{ .lg .middle } **Quick Start**
+
+    ---
+
+    Create your first agent server and client
+
+    [:octicons-arrow-right-24: Start building](quick-start.md)
+
+-   :material-cog:{ .lg .middle } **Configuration**
+
+    ---
+
+    Learn about configuration options
+
+    [:octicons-arrow-right-24: Configure](configuration.md)
+
+</div>

data/docs/getting-started/installation.md

@@ -0,0 +1,95 @@
+# Installation
+
+## Requirements
+
+- Ruby 3.0 or later
+- Bundler (recommended)
+
+## Basic Installation
+
+### Using Bundler (Recommended)
+
+Add SimpleAcp to your `Gemfile`:
+
+```ruby
+gem 'simple_acp'
+```
+
+Then install dependencies:
+
+```bash
+bundle install
+```
+
+### Direct Installation
+
+Install the gem directly:
+
+```bash
+gem install simple_acp
+```
+
+## Optional Dependencies
+
+SimpleAcp has optional dependencies for different storage backends:
+
+### Redis Storage
+
+For distributed deployments with Redis:
+
+```ruby
+gem 'simple_acp'
+gem 'redis', '~> 5.0'
+```
+
+### PostgreSQL Storage
+
+For persistent storage with PostgreSQL:
+
+```ruby
+gem 'simple_acp'
+gem 'sequel', '~> 5.0'
+gem 'pg', '~> 1.5'
+```
+
+## Verifying Installation
+
+Create a simple test file to verify the installation:
+
+```ruby
+# test_install.rb
+require 'simple_acp'
+
+server = SimpleAcp::Server::Base.new
+
+server.agent("test") do |context|
+  SimpleAcp::Models::Message.agent("SimpleAcp is working!")
+end
+
+puts "SimpleAcp version: #{SimpleAcp::VERSION}"
+puts "Registered agents: #{server.agents.keys.join(', ')}"
+```
+
+Run it:
+
+```bash
+ruby test_install.rb
+# SimpleAcp version: 0.1.0
+# Registered agents: test
+```
+
+## Dependencies
+
+SimpleAcp depends on these gems (automatically installed):
+
+| Gem | Purpose |
+|-----|---------|
+| `roda` | HTTP routing and request handling |
+| `falcon` | Fiber-based web server for efficient concurrency |
+| `async` | Asynchronous I/O framework |
+| `faraday` | HTTP client for agent clients |
+| `concurrent-ruby` | Thread-safe data structures |
+
+## Next Steps
+
+Now that you have SimpleAcp installed, proceed to the [Quick Start](quick-start.md) guide to create your first agent.

data/docs/getting-started/quick-start.md

@@ -0,0 +1,189 @@
+# Quick Start
+
+This guide walks you through creating your first ACP server and client.
+
+## Creating an Agent Server
+
+### Step 1: Create a Basic Server
+
+```ruby
+# server.rb
+require 'simple_acp'
+
+# Create the server
+server = SimpleAcp::Server::Base.new
+
+# Register a simple echo agent
+server.agent("echo", description: "Echoes back your message") do |context|
+  text = context.input.first&.text_content || "Nothing to echo"
+  SimpleAcp::Models::Message.agent("You said: #{text}")
+end
+
+# Start the server
+server.run(port: 8000)
+```
+
+Run the server:
+
+```bash
+ruby server.rb
+# ACP Server (Falcon) running on http://0.0.0.0:8000
+# Registered agents: echo
+```
+
+### Step 2: Test with curl
+
+```bash
+# Check server health
+curl http://localhost:8000/ping
+# {"status":"ok"}
+
+# List available agents
+curl http://localhost:8000/agents
+# {"agents":[{"name":"echo","description":"Echoes back your message",...}]}
+
+# Run the agent
+curl -X POST http://localhost:8000/runs \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent_name": "echo",
+    "input": [{"role": "user", "parts": [{"content_type": "text/plain", "content": "Hello!"}]}]
+  }'
+# {"run_id":"...","status":"completed","output":[{"role":"agent","parts":[{"content":"You said: Hello!"}]}]}
+```
+
+## Using the Ruby Client
+
+### Step 1: Create a Client
+
+```ruby
+# client.rb
+require 'simple_acp'
+
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+# Check connection
+puts client.ping ? "Connected!" : "Connection failed"
+
+# List available agents
+response = client.agents
+puts "Available agents: #{response.agents.map(&:name).join(', ')}"
+```
+
+### Step 2: Run Agents
+
+```ruby
+# Synchronous execution
+run = client.run_sync(
+  agent: "echo",
+  input: [SimpleAcp::Models::Message.user("Hello, SimpleAcp!")]
+)
+
+puts "Status: #{run.status}"
+puts "Response: #{run.output.first.text_content}"
+```
+
+### Step 3: Use Streaming
+
+```ruby
+# Streaming execution with events
+client.run_stream(agent: "echo", input: "Streaming test") do |event|
+  case event
+  when SimpleAcp::Models::RunStartedEvent
+    puts "Run started: #{event.run_id}"
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content
+  when SimpleAcp::Models::RunCompletedEvent
+    puts "\nCompleted!"
+  end
+end
+```
+
+## Adding More Agents
+
+### A Greeting Agent
+
+```ruby
+server.agent("greeter", description: "Personalized greetings") do |context|
+  name = context.input.first&.text_content || "World"
+  SimpleAcp::Models::Message.agent("Hello, #{name}! Welcome to SimpleAcp.")
+end
+```
+
+### A Multi-Response Agent
+
+Agents can return multiple messages using an Enumerator:
+
+```ruby
+server.agent("countdown", description: "Counts down from a number") do |context|
+  n = context.input.first&.text_content.to_i
+  n = 5 if n <= 0
+
+  Enumerator.new do |yielder|
+    n.downto(1) do |i|
+      yielder << SimpleAcp::Server::RunYield.new(
+        SimpleAcp::Models::Message.agent("#{i}...")
+      )
+      sleep 0.5
+    end
+    yielder << SimpleAcp::Server::RunYield.new(
+      SimpleAcp::Models::Message.agent("Liftoff!")
+    )
+  end
+end
+```
+
+## Complete Example
+
+Here's a complete example with both server and client:
+
+=== "Server"
+
+    ```ruby
+    # examples/server.rb
+    require 'simple_acp'
+
+    server = SimpleAcp::Server::Base.new
+
+    server.agent("echo") do |context|
+      text = context.input.first&.text_content
+      SimpleAcp::Models::Message.agent("Echo: #{text}")
+    end
+
+    server.agent("reverse") do |context|
+      text = context.input.first&.text_content || ""
+      SimpleAcp::Models::Message.agent(text.reverse)
+    end
+
+    server.agent("upcase") do |context|
+      text = context.input.first&.text_content || ""
+      SimpleAcp::Models::Message.agent(text.upcase)
+    end
+
+    puts "Starting server on port 8000..."
+    server.run(port: 8000)
+    ```
+
+=== "Client"
+
+    ```ruby
+    # examples/client.rb
+    require 'simple_acp'
+
+    client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+    # Test each agent
+    %w[echo reverse upcase].each do |agent_name|
+      run = client.run_sync(
+        agent: agent_name,
+        input: [SimpleAcp::Models::Message.user("Hello World")]
+      )
+      puts "#{agent_name}: #{run.output.first.text_content}"
+    end
+    ```
+
+## Next Steps
+
+- Learn about [Configuration](configuration.md) options
+- Understand [Core Concepts](../core-concepts/index.md) like messages, runs, and sessions
+- Dive into the [Server Guide](../server/index.md) for advanced agent development

data/docs/index.md

@@ -0,0 +1,119 @@
+# SimpleAcp
+
+!!! warning "CAUTION"
+    This project is under active development. The API and documentation may not necessarily reflect the current codebase.
+
+<div class="grid" markdown>
+
+<div markdown>
+
+![SimpleAcp](assets/images/simple_acp.jpg){ width="100%" }
+
+</div>
+
+<div markdown>
+
+**A Ruby implementation of the Agent Communication Protocol (ACP)**
+
+SimpleAcp provides an open protocol for communication between AI agents, applications, and humans. Build agent servers, connect with HTTP clients, and stream responses in real-time.
+
+| | |
+|---|---|
+| :material-robot: Full ACP Protocol | :material-sync: Sync/Async/Stream |
+| :material-message-text: Session Management | :material-image: Multimodal Messages |
+| :material-database: Pluggable Storage | :material-lightning-bolt: SSE Streaming |
+
+</div>
+
+</div>
+
+<p align="center" markdown>
+[:material-download: Install](getting-started/installation.md){ .md-button .md-button--primary }
+[:material-rocket-launch: Quick Start](getting-started/quick-start.md){ .md-button }
+</p>
+
+---
+
+## Features
+
+- **Full ACP Protocol Support**: Complete implementation including agents, runs, sessions, and events
+- **Multiple Run Modes**: Synchronous, asynchronous, and streaming execution patterns
+- **Session Management**: Maintain state and conversation history across interactions
+- **Multimodal Messages**: Support for text, JSON, images, and URL references
+- **Pluggable Storage**: In-memory, Redis, and PostgreSQL backends included
+- **SSE Streaming**: Server-Sent Events for real-time response streaming
+- **Falcon Server**: Fiber-based concurrency for efficient handling of thousands of concurrent connections
+
+## Quick Example
+
+```ruby
+require 'simple_acp'
+
+# Create a server with an agent
+server = SimpleAcp::Server::Base.new
+
+server.agent("greeter", description: "Greets users") do |context|
+  name = context.input.first&.text_content || "World"
+  SimpleAcp::Models::Message.agent("Hello, #{name}!")
+end
+
+server.run(port: 8000)
+```
+
+```ruby
+# Connect with a client
+client = SimpleAcp::Client::Base.new(base_url: "http://localhost:8000")
+
+run = client.run_sync(
+  agent: "greeter",
+  input: [SimpleAcp::Models::Message.user("Alice")]
+)
+
+puts run.output.first.text_content
+# => "Hello, Alice!"
+```
+
+## Architecture Overview
+
+```mermaid
+graph LR
+    subgraph Client
+        C[Client::Base]
+    end
+
+    subgraph Server
+        S[Server::Base]
+        A1[Agent 1]
+        A2[Agent 2]
+        ST[(Storage)]
+    end
+
+    C -->|HTTP/SSE| S
+    S --> A1
+    S --> A2
+    S --> ST
+```
+
+SimpleAcp follows a client-server architecture:
+
+- **Server**: Hosts agents and handles HTTP requests via Roda/Falcon
+- **Agents**: Process input and produce output messages
+- **Client**: Communicates with servers over HTTP with optional SSE streaming
+- **Storage**: Persists runs, sessions, and events
+
+## Getting Started
+
+Ready to build your first agent? Head to the [Installation](getting-started/installation.md) guide to get started.
+
+[Get Started :material-arrow-right:](getting-started/installation.md){ .md-button .md-button--primary }
+[View on GitHub :material-github:](https://github.com/MadBomber/simple_acp){ .md-button }
+
+---
+
+## A Note on ACP as a Standard
+
+This gem implements the Agent Communication Protocol specification, but I have reservations about ACP becoming "the" standard for agent-to-agent communication. Like MCP before it, ACP suffers from conceptual ambiguity—the protocol designers seem unable to clearly distinguish between what constitutes an "agent" versus a "tool." This fundamental confusion permeates both protocols.
+
+Whether ACP achieves the same de facto adoption that MCP has gained remains to be seen. MCP's prevalence stems largely from momentum and network effects rather than technical superiority. ACP may follow the same path simply because it exists and others adopt it, not because it represents the best possible design for inter-agent communication.
+
+For now, this implementation provides a practical way to work with ACP-compatible systems while we wait to see how the agent communication landscape evolves.