simple_acp 0.0.1

data/examples/README.md

@@ -0,0 +1,252 @@
+# SimpleAcp Examples
+
+> **CAUTION:** This project is under active development. The API and documentation may not necessarily reflect the current codebase.
+
+This directory contains example programs demonstrating SimpleAcp features.
+
+Each example is organized in its own subdirectory with both `server.rb` and `client.rb` files.
+
+## Quick Start
+
+Use the unified `run_demo.sh` script to run any demo:
+
+```bash
+# From the project root
+./examples/run_demo.sh 1      # Run demo 1 (01_basic)
+./examples/run_demo.sh 4      # Run demo 4 (04_rich_messages)
+
+# Or from the examples directory
+cd examples
+./run_demo.sh 1
+```
+
+### Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `./run_demo.sh <1-6>` | Run a specific demo by number |
+| `./run_demo.sh --list` | List all available demos |
+| `./run_demo.sh --all` | Run all demos sequentially |
+| `./run_demo.sh --help` | Show usage information |
+
+## Examples
+
+### 01_basic
+
+Basic server and client demonstrating core SimpleAcp functionality.
+
+**Server** (`01_basic/server.rb`) - Registers five agents:
+
+| Agent | Description |
+|-------|-------------|
+| `echo` | Echoes input messages back (demonstrates streaming with Enumerator) |
+| `greeter` | Greets the user by name (demonstrates simple responses) |
+| `counter` | Counts invocations (demonstrates session state) |
+| `gettysburg` | Recites the Gettysburg Address word by word with 0.5s delay (demonstrates streaming) |
+| `assistant` | Remembers conversation history (demonstrates multi-turn conversations) |
+
+**Client** (`01_basic/client.rb`) - Demonstrates:
+
+- Health check with `ping`
+- Listing available agents
+- Synchronous runs with `run_sync`
+- Streaming responses with `run_stream`
+- Session management for stateful interactions
+
+**Usage:**
+
+```bash
+./examples/run_demo.sh 1
+```
+
+---
+
+### 02_async_execution
+
+Demonstrates asynchronous (non-blocking) execution patterns.
+
+**Server** (`02_async_execution/server.rb`) - Registers:
+
+| Agent | Description |
+|-------|-------------|
+| `slow-worker` | Simulates a 3-second task with progress updates |
+| `quick-status` | Returns status immediately |
+
+**Client** (`02_async_execution/client.rb`) - Demonstrates:
+
+- Async execution with `run_async`
+- Manual polling with `run_status`
+- Waiting for completion with `wait_for_run`
+- Running multiple tasks concurrently
+
+**Usage:**
+
+```bash
+./examples/run_demo.sh 2
+```
+
+---
+
+### 03_run_management
+
+Demonstrates run lifecycle management including cancellation and event history.
+
+**Server** (`03_run_management/server.rb`) - Registers:
+
+| Agent | Description |
+|-------|-------------|
+| `cancellable-task` | A long-running task that checks for cancellation |
+| `event-generator` | Generates multiple events for history tracking |
+
+**Client** (`03_run_management/client.rb`) - Demonstrates:
+
+- Cancelling a running task with `run_cancel`
+- Checking `context.cancelled?` in the agent
+- Retrieving event history with `run_events`
+- Event pagination with limit and offset
+
+**Usage:**
+
+```bash
+./examples/run_demo.sh 3
+```
+
+---
+
+### 04_rich_messages
+
+Demonstrates different message part types and content negotiation.
+
+**Server** (`04_rich_messages/server.rb`) - Registers:
+
+| Agent | Description |
+|-------|-------------|
+| `json-data` | Returns structured JSON data |
+| `image-generator` | Generates SVG images as base64 |
+| `link-provider` | Returns URL references with metadata |
+| `multi-format` | Returns data in multiple formats (text, JSON, HTML) |
+
+**Client** (`04_rich_messages/client.rb`) - Demonstrates:
+
+- Receiving and parsing JSON content
+- Handling base64 encoded data
+- Working with URL references and metadata
+- Multi-part messages with different content types
+- Inspecting agent content type capabilities
+
+**Usage:**
+
+```bash
+./examples/run_demo.sh 4
+```
+
+---
+
+### 05_await_resume
+
+Demonstrates the await/resume pattern for interactive multi-step flows.
+
+**Server** (`05_await_resume/server.rb`) - Registers:
+
+| Agent | Description |
+|-------|-------------|
+| `greeter` | Asks for your name, then greets you |
+| `survey` | A multi-step survey collecting multiple pieces of information |
+| `confirmer` | Asks for confirmation before performing an action |
+
+**Client** (`05_await_resume/client.rb`) - Demonstrates:
+
+- Detecting when a run is in "awaiting" status
+- Resuming with `run_resume_sync`
+- Multi-step interactive flows using state
+- Confirmation dialogs
+- Streaming resume with `run_resume_stream`
+
+**Usage:**
+
+```bash
+./examples/run_demo.sh 5
+```
+
+---
+
+### 06_agent_metadata
+
+Demonstrates rich agent metadata and content type negotiation.
+
+**Server** (`06_agent_metadata/server.rb`) - Registers:
+
+| Agent | Description |
+|-------|-------------|
+| `text-analyzer` | Full-featured agent with comprehensive metadata |
+| `simple-echo` | Minimal agent for comparison |
+| `json-processor` | Agent with specific content type requirements |
+
+**Client** (`06_agent_metadata/client.rb`) - Demonstrates:
+
+- Retrieving full agent metadata with `agent(name)`
+- Inspecting author, contributors, capabilities, links
+- Content type negotiation (`accepts_content_type?`, `produces_content_type?`)
+- Metadata fields: documentation, license, domains, tags, dependencies
+
+**Usage:**
+
+```bash
+./examples/run_demo.sh 6
+```
+
+---
+
+## Running Examples
+
+### Using the Demo Runner (Recommended)
+
+The `run_demo.sh` script handles starting the server, waiting for it to be ready, running the client, and cleanup:
+
+```bash
+# Run a specific demo by number
+./examples/run_demo.sh 1
+
+# List available demos
+./examples/run_demo.sh --list
+
+# Run all demos sequentially
+./examples/run_demo.sh --all
+```
+
+The script can be executed from either the project root or from within the examples directory.
+
+### Running Manually
+
+You can also run server and client manually in separate terminals:
+
+```bash
+# Terminal 1: Start server
+ruby examples/01_basic/server.rb
+
+# Terminal 2: Run client
+ruby examples/01_basic/client.rb
+```
+
+## Feature Coverage
+
+| Feature | Example |
+|---------|---------|
+| Basic agent registration | 01_basic |
+| Streaming responses | 01_basic |
+| Session state | 01_basic |
+| Conversation history | 01_basic |
+| Async execution | 02_async_execution |
+| Polling (`run_status`, `wait_for_run`) | 02_async_execution |
+| Concurrent runs | 02_async_execution |
+| Run cancellation | 03_run_management |
+| Event history | 03_run_management |
+| JSON message parts | 04_rich_messages |
+| Binary/base64 data | 04_rich_messages |
+| URL references | 04_rich_messages |
+| Content type negotiation | 04_rich_messages, 06_agent_metadata |
+| Await/resume pattern | 05_await_resume |
+| Multi-step flows | 05_await_resume |
+| Agent metadata | 06_agent_metadata |
+| Author/contributor info | 06_agent_metadata |
+| Capabilities and dependencies | 06_agent_metadata |

data/examples/run_demo.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+# Run a SimpleAcp demo by number
+#
+# Usage: ./examples/run_demo.sh <demo_number>
+#        ./examples/run_demo.sh --list
+#
+# Examples:
+#   ./examples/run_demo.sh 1      # Run 01_basic demo
+#   ./examples/run_demo.sh 4      # Run 04_rich_messages demo
+#   ./examples/run_demo.sh --list # List available demos
+
+set -e
+
+# Calculate project directory ONCE at script start (before any cd commands)
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd -P)"
+PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+# Demo directory mapping
+declare -A DEMOS=(
+    [1]="01_basic"
+    [2]="02_async_execution"
+    [3]="03_run_management"
+    [4]="04_rich_messages"
+    [5]="05_await_resume"
+    [6]="06_agent_metadata"
+)
+
+# Demo descriptions
+declare -A DESCRIPTIONS=(
+    [1]="Basic - echo, greeter, counter, streaming, sessions"
+    [2]="Async Execution - run_async, polling, wait_for_run"
+    [3]="Run Management - cancellation, event history"
+    [4]="Rich Messages - JSON, images, URLs, multi-part"
+    [5]="Await/Resume - interactive multi-step flows"
+    [6]="Agent Metadata - full manifests, content types"
+)
+
+show_usage() {
+    cat <<EOF
+Usage: $0 <demo_number|--list|--all>
+
+Options:
+  <number>   Run demo 1-6
+  --list     List available demos
+  --all      Run all demos sequentially
+
+Available demos:
+EOF
+    for i in {1..6}; do
+        echo "  $i) ${DEMOS[$i]} - ${DESCRIPTIONS[$i]}"
+    done
+}
+
+run_demo() {
+    local demo_num=$1
+    local demo_dir=${DEMOS[$demo_num]}
+
+    if [[ -z "$demo_dir" ]]; then
+        echo "Error: Invalid demo number '$demo_num'"
+        echo "Valid options: 1-6"
+        exit 1
+    fi
+
+    cd "$PROJECT_DIR"
+
+    # Check if demo directory exists
+    if [[ ! -d "examples/$demo_dir" ]]; then
+        echo "Error: Demo directory 'examples/$demo_dir' not found"
+        exit 1
+    fi
+
+    echo "=========================================="
+    echo "Running Demo $demo_num: $demo_dir"
+    echo "${DESCRIPTIONS[$demo_num]}"
+    echo "=========================================="
+    echo
+
+    # Clean up any leftover process on port 8000
+    lsof -ti:8000 | xargs kill -9 2>/dev/null || true
+
+    echo "Starting server..."
+    ruby "examples/$demo_dir/server.rb" &
+    SERVER_PID=$!
+
+    # Wait for server to be ready
+    echo "Waiting for server to start..."
+    for i in {1..30}; do
+        if curl -s http://localhost:8000/ping >/dev/null 2>&1; then
+            echo "Server is ready."
+            break
+        fi
+        sleep 0.1
+    done
+
+    # Run the client
+    echo ""
+    ruby "examples/$demo_dir/client.rb"
+    CLIENT_EXIT=$?
+
+    # Clean up
+    echo ""
+    echo "Stopping server..."
+    kill $SERVER_PID 2>/dev/null || true
+    wait $SERVER_PID 2>/dev/null || true
+
+    return $CLIENT_EXIT
+}
+
+# Main
+case "${1:-}" in
+--list | -l)
+    show_usage
+    ;;
+--all | -a)
+    echo "Running all demos..."
+    echo
+    for i in {1..6}; do
+        run_demo $i
+        echo
+    done
+    echo "All demos completed!"
+    ;;
+--help | -h | "")
+    show_usage
+    exit 0
+    ;;
+*)
+    if [[ "$1" =~ ^[1-6]$ ]]; then
+        run_demo "$1"
+    else
+        echo "Error: Invalid argument '$1'"
+        echo
+        show_usage
+        exit 1
+    fi
+    ;;
+esac