simple_acp 0.0.1

data/docs/server/http-endpoints.md

@@ -0,0 +1,411 @@
+# HTTP Endpoints
+
+The SimpleAcp server exposes HTTP endpoints for agent discovery, run management, and session handling.
+
+## Endpoint Overview
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/ping` | Health check |
+| `GET` | `/agents` | List all agents |
+| `GET` | `/agents/:name` | Get agent manifest |
+| `POST` | `/runs` | Create a run |
+| `GET` | `/runs/:id` | Get run status |
+| `POST` | `/runs/:id` | Resume awaited run |
+| `POST` | `/runs/:id/cancel` | Cancel a run |
+| `GET` | `/runs/:id/events` | Get run events |
+| `GET` | `/session/:id` | Get session info |
+
+## Health Check
+
+### GET /ping
+
+Check server health.
+
+**Request:**
+```bash
+curl http://localhost:8000/ping
+```
+
+**Response:**
+```json
+{
+  "status": "ok"
+}
+```
+
+## Agent Discovery
+
+### GET /agents
+
+List all registered agents.
+
+**Request:**
+```bash
+curl http://localhost:8000/agents
+```
+
+**Response:**
+```json
+{
+  "agents": [
+    {
+      "name": "echo",
+      "description": "Echoes input back",
+      "input_content_types": ["text/plain"],
+      "output_content_types": ["text/plain"],
+      "metadata": {}
+    },
+    {
+      "name": "analyzer",
+      "description": "Analyzes JSON data",
+      "input_content_types": ["application/json"],
+      "output_content_types": ["application/json"],
+      "metadata": {"version": "1.0"}
+    }
+  ]
+}
+```
+
+### GET /agents/:name
+
+Get a specific agent's manifest.
+
+**Request:**
+```bash
+curl http://localhost:8000/agents/echo
+```
+
+**Response:**
+```json
+{
+  "name": "echo",
+  "description": "Echoes input back",
+  "input_content_types": ["text/plain"],
+  "output_content_types": ["text/plain"],
+  "metadata": {}
+}
+```
+
+**Error (404):**
+```json
+{
+  "error": {
+    "code": "agent_not_found",
+    "message": "Agent 'unknown' not found"
+  }
+}
+```
+
+## Run Management
+
+### POST /runs
+
+Create and execute a run.
+
+**Request (Synchronous):**
+```bash
+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!"}
+        ]
+      }
+    ]
+  }'
+```
+
+**Response:**
+```json
+{
+  "run_id": "550e8400-e29b-41d4-a716-446655440000",
+  "agent_name": "echo",
+  "status": "completed",
+  "output": [
+    {
+      "role": "agent",
+      "parts": [
+        {"content_type": "text/plain", "content": "Echo: Hello!"}
+      ]
+    }
+  ],
+  "created_at": "2025-01-21T10:30:00Z",
+  "finished_at": "2025-01-21T10:30:01Z"
+}
+```
+
+**Request (Streaming):**
+```bash
+curl -X POST http://localhost:8000/runs \
+  -H "Content-Type: application/json" \
+  -H "Accept: text/event-stream" \
+  -d '{"agent_name": "chat", "input": [...]}'
+```
+
+**Response (SSE Stream):**
+```
+event: run_started
+data: {"run_id":"550e8400-..."}
+
+event: message_created
+data: {"message":{"role":"agent","parts":[]}}
+
+event: message_part
+data: {"part":{"content_type":"text/plain","content":"Hello"}}
+
+event: message_completed
+data: {"message":{"role":"agent","parts":[...]}}
+
+event: run_completed
+data: {"run":{...}}
+```
+
+**Request with Session:**
+```bash
+curl -X POST http://localhost:8000/runs \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent_name": "chat",
+    "session_id": "conversation-123",
+    "input": [...]
+  }'
+```
+
+### GET /runs/:id
+
+Get run status.
+
+**Request:**
+```bash
+curl http://localhost:8000/runs/550e8400-e29b-41d4-a716-446655440000
+```
+
+**Response:**
+```json
+{
+  "run_id": "550e8400-e29b-41d4-a716-446655440000",
+  "agent_name": "processor",
+  "status": "in_progress",
+  "output": [],
+  "created_at": "2025-01-21T10:30:00Z"
+}
+```
+
+**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
+
+### POST /runs/:id
+
+Resume an awaited run.
+
+**Request:**
+```bash
+curl -X POST http://localhost:8000/runs/550e8400-... \
+  -H "Content-Type: application/json" \
+  -d '{
+    "await_resume": {
+      "type": "message",
+      "message": {
+        "role": "user",
+        "parts": [
+          {"content_type": "text/plain", "content": "My response"}
+        ]
+      }
+    }
+  }'
+```
+
+**Response:**
+```json
+{
+  "run_id": "550e8400-...",
+  "status": "completed",
+  "output": [...]
+}
+```
+
+### POST /runs/:id/cancel
+
+Cancel a running execution.
+
+**Request:**
+```bash
+curl -X POST http://localhost:8000/runs/550e8400-.../cancel
+```
+
+**Response:**
+```json
+{
+  "run_id": "550e8400-...",
+  "status": "cancelled"
+}
+```
+
+### GET /runs/:id/events
+
+Get events for a run.
+
+**Request:**
+```bash
+curl "http://localhost:8000/runs/550e8400-.../events?limit=100&offset=0"
+```
+
+**Response:**
+```json
+{
+  "events": [
+    {
+      "type": "run_started",
+      "run_id": "550e8400-..."
+    },
+    {
+      "type": "message_part",
+      "part": {"content_type": "text/plain", "content": "Hello"}
+    },
+    {
+      "type": "run_completed",
+      "run": {...}
+    }
+  ]
+}
+```
+
+## Session Management
+
+### GET /session/:id
+
+Get session information.
+
+**Request:**
+```bash
+curl http://localhost:8000/session/conversation-123
+```
+
+**Response:**
+```json
+{
+  "id": "conversation-123",
+  "history": [
+    {"role": "user", "parts": [...]},
+    {"role": "agent", "parts": [...]}
+  ],
+  "state": {"step": 2, "data": {"name": "Alice"}}
+}
+```
+
+## Error Responses
+
+All errors follow a consistent format:
+
+```json
+{
+  "error": {
+    "code": "error_code",
+    "message": "Human-readable message"
+  }
+}
+```
+
+### Error Codes
+
+| Code | HTTP Status | Description |
+|------|-------------|-------------|
+| `agent_not_found` | 404 | Agent doesn't exist |
+| `run_not_found` | 404 | Run doesn't exist |
+| `session_not_found` | 404 | Session doesn't exist |
+| `invalid_input` | 400 | Malformed request |
+| `run_not_awaiting` | 400 | Resume on non-awaiting run |
+| `internal_error` | 500 | Server error |
+
+## Request Headers
+
+| Header | Purpose |
+|--------|---------|
+| `Content-Type: application/json` | Required for POST requests |
+| `Accept: text/event-stream` | Request SSE streaming |
+
+## Query Parameters
+
+### /runs/:id/events
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `limit` | integer | 100 | Max events to return |
+| `offset` | integer | 0 | Events to skip |
+
+## Authentication
+
+SimpleAcp doesn't include built-in authentication. Add it via middleware:
+
+```ruby
+# config.ru
+require 'simple_acp'
+
+server = SimpleAcp::Server::Base.new
+# ... register agents
+
+# Add auth middleware
+use Rack::Auth::Basic do |username, password|
+  username == ENV['API_USER'] && password == ENV['API_PASS']
+end
+
+run server.to_app
+```
+
+## CORS
+
+For browser access, add CORS headers:
+
+```ruby
+# config.ru
+require 'rack/cors'
+
+use Rack::Cors do
+  allow do
+    origins '*'
+    resource '*',
+      headers: :any,
+      methods: [:get, :post, :options],
+      expose: ['Content-Type']
+  end
+end
+
+run server.to_app
+```
+
+## Testing Endpoints
+
+```bash
+# Health check
+curl http://localhost:8000/ping | jq
+
+# List agents
+curl http://localhost:8000/agents | jq
+
+# Run 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":"test"}]}]}' | jq
+
+# Stream run
+curl -X POST http://localhost:8000/runs \
+  -H "Content-Type: application/json" \
+  -H "Accept: text/event-stream" \
+  -d '{"agent_name":"chat","input":[...]}'
+```
+
+## Next Steps
+
+- See [Client Guide](../client/index.md) for using these endpoints
+- Review [API Reference](../api/server-base.md) for programmatic usage
+- Explore [Storage](../storage/index.md) for data persistence

data/docs/server/index.md

@@ -0,0 +1,218 @@
+# Server Guide
+
+The SimpleAcp server hosts agents and handles HTTP requests from clients. This guide covers everything you need to build robust agent servers.
+
+## Overview
+
+```mermaid
+graph TB
+    subgraph Server
+        S[Server::Base]
+        A[App - Roda]
+        AG1[Agent 1]
+        AG2[Agent 2]
+        ST[(Storage)]
+    end
+
+    C1[Client 1] -->|HTTP| A
+    C2[Client 2] -->|HTTP| A
+    A --> S
+    S --> AG1
+    S --> AG2
+    S --> ST
+```
+
+## Quick Start
+
+```ruby
+require 'simple_acp'
+
+server = SimpleAcp::Server::Base.new
+
+server.agent("hello") do |context|
+  SimpleAcp::Models::Message.agent("Hello from SimpleAcp!")
+end
+
+server.run(port: 8000)
+```
+
+## In This Section
+
+<div class="grid cards" markdown>
+
+-   :material-robot:{ .lg .middle } **Creating Agents**
+
+    ---
+
+    Learn patterns for building effective agents
+
+    [:octicons-arrow-right-24: Creating Agents](creating-agents.md)
+
+-   :material-play-speed:{ .lg .middle } **Streaming Responses**
+
+    ---
+
+    Implement real-time streaming with SSE
+
+    [:octicons-arrow-right-24: Streaming](streaming.md)
+
+-   :material-chat-processing:{ .lg .middle } **Multi-Turn Conversations**
+
+    ---
+
+    Build stateful, context-aware agents
+
+    [:octicons-arrow-right-24: Multi-Turn](multi-turn.md)
+
+-   :material-api:{ .lg .middle } **HTTP Endpoints**
+
+    ---
+
+    Reference for all server endpoints
+
+    [:octicons-arrow-right-24: HTTP Endpoints](http-endpoints.md)
+
+</div>
+
+## Server Architecture
+
+### Components
+
+| Component | Purpose |
+|-----------|---------|
+| `Server::Base` | Core server managing agents and runs |
+| `Server::App` | Roda HTTP application |
+| `Server::Context` | Execution context passed to agents |
+| `Server::Agent` | Agent wrapper with metadata |
+
+### Server Lifecycle
+
+```ruby
+# 1. Create server with optional storage
+server = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::Memory.new
+)
+
+# 2. Register agents
+server.agent("name", description: "...") do |context|
+  # Handler logic
+end
+
+# 3. Start HTTP server (uses Falcon)
+server.run(port: 8000)
+```
+
+### Programmatic Usage
+
+Use the server without HTTP:
+
+```ruby
+# Create runs directly
+run = server.run_sync(
+  agent_name: "processor",
+  input: [SimpleAcp::Models::Message.user("Data")]
+)
+
+# Stream events
+server.run_stream(agent_name: "streamer", input: messages) do |event|
+  # Handle events
+end
+```
+
+## Configuration
+
+### Storage
+
+```ruby
+# Memory (default)
+server = SimpleAcp::Server::Base.new
+
+# Redis
+server = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::Redis.new(url: ENV['REDIS_URL'])
+)
+
+# PostgreSQL
+server = SimpleAcp::Server::Base.new(
+  storage: SimpleAcp::Storage::PostgreSQL.new(url: ENV['DATABASE_URL'])
+)
+```
+
+### HTTP Server Options
+
+```ruby
+server.run(
+  port: 8000,
+  host: '0.0.0.0'
+)
+```
+
+Falcon uses fiber-based concurrency, efficiently handling thousands of concurrent connections without the need for thread pool configuration.
+
+## Best Practices
+
+### Agent Organization
+
+```ruby
+# Group related agents
+class MyServer
+  def initialize
+    @server = SimpleAcp::Server::Base.new
+    register_chat_agents
+    register_utility_agents
+  end
+
+  private
+
+  def register_chat_agents
+    @server.agent("chat") { |ctx| ... }
+    @server.agent("summarize") { |ctx| ... }
+  end
+
+  def register_utility_agents
+    @server.agent("ping") { |ctx| ... }
+    @server.agent("echo") { |ctx| ... }
+  end
+end
+```
+
+### Error Handling
+
+```ruby
+server.agent("safe") do |context|
+  begin
+    risky_operation(context.input)
+  rescue ValidationError => e
+    SimpleAcp::Models::Message.agent("Invalid input: #{e.message}")
+  rescue ExternalServiceError => e
+    # Log and return friendly error
+    logger.error("External service failed: #{e}")
+    SimpleAcp::Models::Message.agent("Service temporarily unavailable")
+  end
+end
+```
+
+### Logging
+
+```ruby
+server.agent("logged") do |context|
+  logger.info("Processing request", {
+    run_id: context.run_id,
+    agent: context.agent_name,
+    input_count: context.input.length
+  })
+
+  result = process(context.input)
+
+  logger.info("Request completed", {
+    run_id: context.run_id,
+    output_count: result.length
+  })
+
+  result
+end
+```
+
+## Next Steps
+
+Start with [Creating Agents](creating-agents.md) to learn agent development patterns.