simple_acp 0.0.1

data/docs/api/models.md

@@ -0,0 +1,286 @@
+# Models
+
+Data models for ACP entities.
+
+## Message
+
+Represents a message in the protocol.
+
+### Class: SimpleAcp::Models::Message
+
+#### Factory Methods
+
+```ruby
+# Create user message
+Message.user(*parts)
+Message.user("text")
+Message.user(MessagePart.text("text"), MessagePart.json({...}))
+
+# Create agent message
+Message.agent(*parts)
+Message.agent("response")
+
+# From hash
+Message.from_hash({ "role" => "user", "parts" => [...] })
+```
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `role` | `String` | `"user"` or `"agent"` |
+| `parts` | `Array<MessagePart>` | Content parts |
+
+#### Instance Methods
+
+```ruby
+message.text_content    # Combined text from all parts
+message.to_h            # Convert to hash
+message.to_json         # Convert to JSON
+```
+
+---
+
+## MessagePart
+
+Content within a message.
+
+### Class: SimpleAcp::Models::MessagePart
+
+#### Factory Methods
+
+```ruby
+# Text content
+MessagePart.text("Hello")
+
+# JSON content
+MessagePart.json({ key: "value" })
+
+# Image content (base64)
+MessagePart.image(base64_data, mime_type: "image/png")
+
+# URL reference
+MessagePart.from_url("https://...", content_type: "image/jpeg")
+```
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `content_type` | `String` | MIME type |
+| `content` | `String` | Inline content |
+| `content_url` | `String` | URL reference |
+| `content_encoding` | `String` | `"plain"` or `"base64"` |
+
+#### Instance Methods
+
+```ruby
+part.text?     # Is text/plain?
+part.json?     # Is application/json?
+part.image?    # Is image/*?
+part.to_h      # Convert to hash
+part.to_json   # Convert to JSON
+```
+
+---
+
+## Run
+
+Represents an agent execution.
+
+### Class: SimpleAcp::Models::Run
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `run_id` | `String` | Unique identifier (UUID) |
+| `agent_name` | `String` | Agent that executed |
+| `session_id` | `String` | Associated session |
+| `status` | `String` | Current status |
+| `output` | `Array<Message>` | Output messages |
+| `error` | `Error` | Error if failed |
+| `await_request` | `AwaitRequest` | Await details |
+| `created_at` | `Time` | Creation time |
+| `finished_at` | `Time` | Completion time |
+
+#### Status Values
+
+- `created` - Run created, not started
+- `in_progress` - Currently executing
+- `completed` - Finished successfully
+- `failed` - Encountered error
+- `awaiting` - Waiting for input
+- `cancelled` - Cancelled by request
+
+#### Instance Methods
+
+```ruby
+run.terminal?     # Is in final state?
+run.completed?    # Status is "completed"?
+run.failed?       # Status is "failed"?
+run.cancelled?    # Status is "cancelled"?
+run.awaiting?     # Status is "awaiting"?
+run.to_h          # Convert to hash
+run.to_json       # Convert to JSON
+```
+
+---
+
+## Session
+
+Maintains state across runs.
+
+### Class: SimpleAcp::Models::Session
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `String` | Unique identifier |
+| `history` | `Array<Message>` | Conversation history |
+| `state` | `Any` | Custom state data |
+
+#### Instance Methods
+
+```ruby
+session.add_messages(messages)  # Append to history
+session.to_h                    # Convert to hash
+session.to_json                 # Convert to JSON
+```
+
+---
+
+## AgentManifest
+
+Agent metadata and capabilities.
+
+### Class: SimpleAcp::Models::AgentManifest
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `String` | Agent name |
+| `description` | `String` | Human-readable description |
+| `input_content_types` | `Array<String>` | Accepted MIME types |
+| `output_content_types` | `Array<String>` | Produced MIME types |
+| `metadata` | `Hash` | Custom metadata |
+
+---
+
+## Error
+
+Error information.
+
+### Class: SimpleAcp::Models::Error
+
+#### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `code` | `String` | Error code |
+| `message` | `String` | Error message |
+
+---
+
+## Events
+
+Event types for streaming.
+
+### Event Classes
+
+| Class | Type | Description |
+|-------|------|-------------|
+| `RunStartedEvent` | `run_started` | Run began |
+| `MessageCreatedEvent` | `message_created` | New message |
+| `MessagePartEvent` | `message_part` | Message chunk |
+| `MessageCompletedEvent` | `message_completed` | Message done |
+| `RunCompletedEvent` | `run_completed` | Run finished |
+| `RunFailedEvent` | `run_failed` | Run errored |
+| `RunAwaitingEvent` | `run_awaiting` | Awaiting input |
+
+### Event Properties
+
+```ruby
+# All events
+event.type      # Event type string
+
+# RunStartedEvent
+event.run_id    # Run ID
+
+# MessageCreatedEvent, MessageCompletedEvent
+event.message   # Message object
+
+# MessagePartEvent
+event.part      # MessagePart object
+
+# RunCompletedEvent, RunFailedEvent, RunAwaitingEvent
+event.run       # Run object
+
+# RunFailedEvent
+event.error     # Error object
+
+# RunAwaitingEvent
+event.await_request  # AwaitRequest object
+```
+
+### Parsing Events
+
+```ruby
+event = SimpleAcp::Models::Events.from_hash({
+  "type" => "message_part",
+  "part" => { "content_type" => "text/plain", "content" => "Hello" }
+})
+```
+
+---
+
+## Await Types
+
+### AwaitRequest
+
+Request for additional input.
+
+```ruby
+await_request.type     # "message"
+await_request.message  # Prompt message
+```
+
+### AwaitResume
+
+Resume payload types.
+
+```ruby
+# Message resume
+resume = SimpleAcp::Models::MessageAwaitResume.new(
+  message: SimpleAcp::Models::Message.user("response")
+)
+resume.type     # "message"
+resume.message  # Message object
+```
+
+---
+
+## Base Model
+
+All models inherit from `SimpleAcp::Models::Base`.
+
+### Common Methods
+
+```ruby
+model.to_h      # Convert to hash
+model.to_json   # Convert to JSON string
+
+# Class methods
+Model.from_hash(hash)  # Create from hash
+```
+
+---
+
+## See Also
+
+- [Messages](../core-concepts/messages.md)
+- [Runs](../core-concepts/runs.md)
+- [Sessions](../core-concepts/sessions.md)
+- [Events](../core-concepts/events.md)

data/docs/api/server-base.md

@@ -0,0 +1,379 @@
+# Server::Base
+
+The main server class for hosting ACP agents.
+
+## Class: SimpleAcp::Server::Base
+
+### Constructor
+
+```ruby
+SimpleAcp::Server::Base.new(storage: nil)
+```
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `storage` | `Storage::Base` | `Storage::Memory.new` | Storage backend |
+
+**Example:**
+
+```ruby
+# Default memory storage
+server = SimpleAcp::Server::Base.new
+
+# With Redis storage
+server = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::Redis.new(url: ENV['REDIS_URL'])
+)
+```
+
+---
+
+### Instance Methods
+
+#### #agent
+
+Register an agent using a block.
+
+```ruby
+server.agent(name, description: nil, **options, &block)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Unique agent name |
+| `description` | `String` | Human-readable description |
+| `input_content_types` | `Array<String>` | Accepted MIME types |
+| `output_content_types` | `Array<String>` | Produced MIME types |
+| `metadata` | `Hash` | Custom metadata |
+| `&block` | `Block` | Handler block receiving Context |
+
+**Returns:** `Agent`
+
+**Example:**
+
+```ruby
+server.agent("echo", description: "Echoes input") do |context|
+  SimpleAcp::Models::Message.agent(context.input.first&.text_content)
+end
+```
+
+---
+
+#### #register
+
+Register an agent with a callable object.
+
+```ruby
+server.register(name, handler, description: nil, **options)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Unique agent name |
+| `handler` | `#call` | Object responding to `call(context)` |
+| `description` | `String` | Human-readable description |
+| `**options` | `Hash` | Same options as `#agent` |
+
+**Returns:** `Agent`
+
+**Example:**
+
+```ruby
+class MyAgent
+  def call(context)
+    SimpleAcp::Models::Message.agent("Hello!")
+  end
+end
+
+server.register("my-agent", MyAgent.new, description: "My agent")
+```
+
+---
+
+#### #unregister
+
+Remove a registered agent.
+
+```ruby
+server.unregister(name)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `name` | `String` | Agent name to remove |
+
+**Returns:** `Agent` or `nil`
+
+---
+
+#### #agents
+
+Get all registered agents.
+
+```ruby
+server.agents
+```
+
+**Returns:** `Hash<String, Agent>`
+
+---
+
+#### #run_sync
+
+Execute an agent synchronously.
+
+```ruby
+server.run_sync(agent_name:, input:, session_id: nil)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `agent_name` | `String` | Agent to execute |
+| `input` | `Array<Message>` | Input messages |
+| `session_id` | `String` | Optional session ID |
+
+**Returns:** `Models::Run`
+
+**Example:**
+
+```ruby
+run = server.run_sync(
+  agent_name: "echo",
+  input: [SimpleAcp::Models::Message.user("Hello")]
+)
+puts run.output.first.text_content
+```
+
+---
+
+#### #run_async
+
+Start an agent execution without waiting.
+
+```ruby
+server.run_async(agent_name:, input:, session_id: nil)
+```
+
+**Parameters:** Same as `#run_sync`
+
+**Returns:** `Models::Run` (status will be `in_progress`)
+
+---
+
+#### #run_stream
+
+Execute an agent with streaming events.
+
+```ruby
+server.run_stream(agent_name:, input:, session_id: nil, &block)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `agent_name` | `String` | Agent to execute |
+| `input` | `Array<Message>` | Input messages |
+| `session_id` | `String` | Optional session ID |
+| `&block` | `Block` | Event handler |
+
+**Returns:** `Models::Run`
+
+**Example:**
+
+```ruby
+server.run_stream(
+  agent_name: "chat",
+  input: messages
+) do |event|
+  case event
+  when SimpleAcp::Models::MessagePartEvent
+    print event.part.content
+  end
+end
+```
+
+---
+
+#### #resume_sync
+
+Resume an awaiting run synchronously.
+
+```ruby
+server.resume_sync(run_id:, await_resume:)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `run_id` | `String` | Run to resume |
+| `await_resume` | `AwaitResume` | Resume payload |
+
+**Returns:** `Models::Run`
+
+---
+
+#### #resume_stream
+
+Resume an awaiting run with streaming.
+
+```ruby
+server.resume_stream(run_id:, await_resume:, &block)
+```
+
+**Parameters:** Same as `#resume_sync` plus event block
+
+**Returns:** `Models::Run`
+
+---
+
+#### #cancel_run
+
+Cancel an in-progress run.
+
+```ruby
+server.cancel_run(run_id)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `run_id` | `String` | Run to cancel |
+
+**Returns:** `Models::Run`
+
+---
+
+#### #to_app
+
+Get the Rack application.
+
+```ruby
+server.to_app
+```
+
+**Returns:** `Rack::Builder`
+
+**Example:**
+
+```ruby
+# In config.ru
+run server.to_app
+```
+
+---
+
+#### #run
+
+Start the HTTP server.
+
+```ruby
+server.run(port: 8000, host: '0.0.0.0', **options)
+```
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `port` | `Integer` | `8000` | Listen port |
+| `host` | `String` | `'0.0.0.0'` | Bind address |
+
+**Example:**
+
+```ruby
+server.run(port: 3000)
+```
+
+---
+
+## Class: SimpleAcp::Server::Context
+
+Execution context passed to agent handlers.
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `input` | `Array<Message>` | Input messages |
+| `session` | `Session` | Current session or nil |
+| `session_id` | `String` | Session ID or nil |
+| `history` | `Array<Message>` | Session history |
+| `state` | `Any` | Session state |
+| `run_id` | `String` | Current run ID |
+| `agent_name` | `String` | Current agent name |
+
+### Methods
+
+#### #set_state
+
+Update session state.
+
+```ruby
+context.set_state(new_state)
+```
+
+#### #await_message
+
+Request additional input (for streaming handlers).
+
+```ruby
+result = context.await_message(prompt_message)
+```
+
+#### #resume_message
+
+Get the message from a resume operation.
+
+```ruby
+message = context.resume_message
+```
+
+---
+
+## Class: SimpleAcp::Server::RunYield
+
+Wrapper for yielded messages in streaming handlers.
+
+### Constructor
+
+```ruby
+SimpleAcp::Server::RunYield.new(messages)
+```
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `messages` | `Message` or `Array<Message>` | Messages to yield |
+
+---
+
+## Class: SimpleAcp::Server::RunYieldAwait
+
+Signal to await client input.
+
+### Constructor
+
+```ruby
+SimpleAcp::Server::RunYieldAwait.new(await_request)
+```
+
+---
+
+## See Also
+
+- [Creating Agents](../server/creating-agents.md)
+- [Streaming Responses](../server/streaming.md)
+- [HTTP Endpoints](../server/http-endpoints.md)