simple_a2a 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d1b4e2d504e01c9511e9334010acfb9e1ea99314990586789aff6db82f7c31fd
+  data.tar.gz: eda5925b5f758c25980af95081f214d652387d9cc61bbd37f0bb6f31d2aa7dbc
+SHA512:
+  metadata.gz: 1074249a5196cd4f0c533ef12b4662f4897d03a64f9d626429f0e7cbbd1653c6822e566afa4467793fe3d934d5e9d2451079fdcd5e1ad00159b505af814f4e02
+  data.tar.gz: 003b13cec22786ee19363f1afa1bdeee064a79a0a600b0b73a3343df6167611dc5b93c8c45fc6522b637c5ae5fde6c322836d6b05743fd53a0a49275ce12786b

data/.github/workflows/deploy-github-pages.yml

@@ -0,0 +1,52 @@
+name: Deploy Documentation to GitHub Pages
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/deploy-github-pages.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+
+      - name: Install dependencies
+        run: |
+          pip install mkdocs
+          pip install mkdocs-material
+          pip install mkdocs-macros-plugin
+          pip install mike
+
+      - name: Configure Git
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+
+      - name: Build MkDocs site
+        run: mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site
+          keep_files: true

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-05-07
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Dewayne VanHoozer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,192 @@
+# simple_a2a
+
+A Ruby gem implementing the [Agent2Agent (A2A) protocol](https://a2a-protocol.org/latest/) — an open standard by Google and the Linux Foundation for interoperability between AI agents.
+
+`simple_a2a` provides a complete A2A client and server in a single package, built on the async Ruby ecosystem with [Falcon](https://github.com/socketry/falcon) as the recommended HTTP server.
+
+## Documentation
+
+The full documentation website is available at [https://madbomber.github.io/simple_a2a](https://madbomber.github.io/simple_a2a).
+
+## Lineage
+
+`simple_a2a` is the successor to my earlier Ruby gem, `simple_acp`. That gem implemented the Agent Communication Protocol (ACP), which IBM Research introduced through the BeeAI project for interoperable agent communication. ACP later merged into A2A under the Linux Foundation, with the ACP team contributing its technology and expertise to the A2A effort.
+
+A2A itself was created by Google and then donated to the Linux Foundation for neutral, open governance. The current A2A specification is maintained by the Linux Foundation-hosted [Agent2Agent project](https://github.com/a2aproject/A2A) and published at [a2a-protocol.org](https://a2a-protocol.org/latest/).
+
+> My opinion: the A2A specification is still a little jagged in places. A simple example is that it does not clearly cover whether an A2A server is expected to host only one agent or may host multiple agents. That is a minor example, but it points to the kind of operational detail the specification still needs to tighten up.
+
+References:
+
+- IBM Research: [Agent Communication Protocol](https://research.ibm.com/projects/agent-communication-protocol)
+- BeeAI announcement: [ACP Joins Forces with A2A Under the Linux Foundation](https://github.com/orgs/i-am-bee/discussions/5)
+- Linux Foundation: [Launch of the Agent2Agent Protocol Project](https://www.linuxfoundation.org/press/linux-foundation-launches-the-agent2agent-protocol-project-to-enable-secure-intelligent-communication-between-ai-agents)
+
+## Protocol Reference
+
+- **Official A2A Specification:** [https://a2a-protocol.org/latest/](https://a2a-protocol.org/latest/)
+- **A2A Project on GitHub:** [https://github.com/a2aproject/A2A](https://github.com/a2aproject/A2A)
+
+## Features
+
+- Full A2A v1.0 protocol support (backward compatible with v0.3)
+- JSON-RPC 2.0 over HTTP(S) — primary binding
+- Server-Sent Events (SSE) for streaming responses
+- Push notifications via webhooks (RS256 JWT)
+- Task lifecycle management (`submitted → working → completed/failed/canceled`)
+- AgentCard discovery endpoint at `GET /agentCard`
+- Multi-agent hosting with path-based routing via `A2A.multi_server`
+- Async-first via the `async` gem ecosystem (Falcon + async-http)
+- Rack-compatible server with Roda routing
+- Zeitwerk autoloading — top-level module is `A2A`
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "simple_a2a"
+```
+
+Or install directly:
+
+```bash
+gem install simple_a2a
+```
+
+## Quick start
+
+```ruby
+require "simple_a2a"
+
+# Define your agent logic
+class MyExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    input = ctx.message.text_content
+    ctx.task.complete!(artifacts: [
+      A2A::Models::Artifact.new(
+        parts: [A2A::Models::Part.text("You said: #{input}")]
+      )
+    ])
+  end
+end
+
+# Describe your agent
+card = A2A::Models::AgentCard.new(
+  name:         "MyAgent",
+  version:      "1.0",
+  capabilities: A2A::Models::AgentCapabilities.new,
+  skills:       [A2A::Models::AgentSkill.new(name: "reply")],
+  interfaces:   [A2A::Models::AgentInterface.new(
+    type: "json-rpc", url: "http://localhost:9292", version: "1.0"
+  )]
+)
+
+# Start the server (blocks — runs Falcon on port 9292)
+A2A.server(agent_card: card, executor: MyExecutor.new).run
+```
+
+```ruby
+# Client — talk to any A2A agent
+client = A2A.client(url: "http://localhost:9292")
+
+task = client.send_task(message: A2A::Models::Message.user("hello"))
+puts task.status.state                       # => "completed"
+puts task.artifacts.first.parts.first.text   # => "You said: hello"
+```
+
+## Task lifecycle
+
+```
+submitted → working → completed   (terminal)
+                    → failed      (terminal)
+                    → canceled    (terminal)
+                    → rejected    (terminal)
+                    → input_required  (interrupted)
+                    → auth_required   (interrupted)
+```
+
+Terminal tasks cannot be canceled. Interrupted tasks can be resumed by sending a new message.
+
+## Streaming
+
+```ruby
+# Server — emit incremental events
+class StreamingExecutor < A2A::Server::AgentExecutor
+  def call(ctx)
+    ctx.task.start!
+    ctx.emit_status
+
+    ctx.emit_artifact(A2A::Models::Artifact.new(
+      parts: [A2A::Models::Part.text("thinking… ")]
+    ))
+
+    ctx.task.complete!
+    ctx.emit_status(final: true)
+  end
+end
+```
+
+```ruby
+# Client — consume SSE events
+client = A2A.sse_client(url: "http://localhost:9292")
+
+client.send_subscribe(message: A2A::Models::Message.user("go")) do |event|
+  case event
+  when A2A::Models::TaskStatusUpdateEvent
+    puts "status: #{event.status.state}"
+  when A2A::Models::TaskArtifactUpdateEvent
+    print event.artifact.parts.map(&:text).join
+  end
+end
+```
+
+## Multi-agent server
+
+Use `A2A.multi_server` to host multiple A2A agents in one Falcon process, with each agent mounted at its own path:
+
+```ruby
+A2A.multi_server(
+  agents: {
+    "/research"  => { agent_card: research_card,  executor: ResearchExecutor.new },
+    "/evaluator" => { agent_card: evaluator_card, executor: EvaluatorExecutor.new }
+  },
+  port: 9292
+).run
+```
+
+Each mounted agent has its own AgentCard, executor, storage, and event router.
+
+## Examples
+
+The repository includes three runnable demo apps:
+
+| Demo | Shows |
+|---|---|
+| `01_basic_usage` | Agent discovery, `tasks/send`, task listing, task lookup, and error handling |
+| `02_streaming` | `tasks/sendSubscribe` with Server-Sent Events and incremental artifact chunks |
+| `03_llm_research` | Multi-agent routing, parallel streaming LLM calls, evaluator agent, and a Sinatra web client |
+
+Run the basic and streaming demos end-to-end:
+
+```bash
+bundle exec ruby examples/run 01_basic_usage
+bundle exec ruby examples/run 02_streaming
+```
+
+The LLM research demo requires `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and demo-specific gems. See the full documentation for setup details.
+
+## Development
+
+```bash
+bin/setup             # install dependencies
+bundle exec rake test # run the test suite
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at [https://github.com/MadBomber/simple_a2a](https://github.com/MadBomber/simple_a2a).
+
+## License
+
+Available as open source under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create do |t|
+  # Load SimpleCov before minitest/autorun so its at_exit fires AFTER
+  # Minitest's (LIFO order), meaning coverage is reported after tests run.
+  t.test_prelude = %(require_relative "test/test_helper")
+  t.framework    = ""  # test_helper already requires minitest/autorun
+end
+
+task default: :test

data/docs/api/client/index.md

@@ -0,0 +1,124 @@
+# Client API
+
+## Client::Base
+
+Synchronous JSON-RPC client backed by `async/http`. Works inside or outside an async reactor.
+
+```ruby
+client = A2A.client(url: "http://localhost:9292")
+# or
+client = A2A::Client::Base.new(
+  url:     "http://localhost:9292",
+  headers: { "Authorization" => "Bearer token" }
+)
+```
+
+### Methods
+
+#### `#agent_card` → `A2A::Models::AgentCard`
+
+Fetches and parses the AgentCard from `GET /agentCard`.
+
+```ruby
+card = client.agent_card
+puts card.name
+puts card.capabilities.streaming
+```
+
+#### `#send_task(message:, **opts)` → `A2A::Models::Task`
+
+Sends a `tasks/send` request and waits for the completed task.
+
+```ruby
+task = client.send_task(
+  message:    A2A::Models::Message.user("hello"),
+  task_id:    "my-task-id",    # optional — server assigns if omitted
+  context_id: "ctx-1",         # optional
+  metadata:   { source: "web" } # optional
+)
+puts task.status.state   # => "completed"
+```
+
+#### `#get_task(task_id)` → `A2A::Models::Task`
+
+Retrieves a task by ID (`tasks/get`). Raises `A2A::Error` if not found.
+
+```ruby
+task = client.get_task("abc-123")
+```
+
+#### `#list_tasks` → `[A2A::Models::Task]`
+
+Returns all tasks from the server (`tasks/list`).
+
+```ruby
+tasks = client.list_tasks
+tasks.each { |t| puts "#{t.id}: #{t.status.state}" }
+```
+
+#### `#cancel_task(task_id)` → `A2A::Models::Task`
+
+Cancels a non-terminal task (`tasks/cancel`). Raises `A2A::Error` if not cancelable.
+
+```ruby
+task = client.cancel_task("abc-123")
+puts task.status.state  # => "canceled"
+```
+
+### Error handling
+
+All RPC errors raise `A2A::Error` with the server's error message:
+
+```ruby
+begin
+  client.get_task("no-such-id")
+rescue A2A::Error => e
+  puts e.message   # => "Task no-such-id not found"
+end
+```
+
+---
+
+## Client::SSE
+
+Extends `Client::Base` with streaming support via `tasks/sendSubscribe`.
+
+```ruby
+client = A2A.sse_client(url: "http://localhost:9292")
+# or
+client = A2A::Client::SSE.new(url: "http://localhost:9292")
+```
+
+### `#send_subscribe(message:, **opts, &block)`
+
+Opens an SSE connection and yields events as they arrive. Blocks until the stream closes.
+
+```ruby
+client.send_subscribe(message: A2A::Models::Message.user("process this")) do |event|
+  case event
+  when A2A::Models::TaskStatusUpdateEvent
+    puts "Status: #{event.status.state} (final=#{event.final})"
+  when A2A::Models::TaskArtifactUpdateEvent
+    puts "Artifact chunk: #{event.artifact.parts.map(&:text).join}"
+  end
+end
+```
+
+Events are instances of:
+- `A2A::Models::TaskStatusUpdateEvent`
+- `A2A::Models::TaskArtifactUpdateEvent`
+- `Hash` — for unrecognized event types
+
+The stream ends when the server sends a `final: true` event. The block is not called for malformed or comment-only SSE frames.
+
+### Using inside an Async reactor
+
+Both `Base` and `SSE` detect whether they're already inside an `Async` reactor via `Async::Task.current?`. Inside a reactor, they call the underlying `Async::HTTP::Internet` directly. Outside, they wrap the call in `Async { }.wait`.
+
+```ruby
+Async do
+  client = A2A.client(url: "http://localhost:9292")
+  task   = client.send_task(message: A2A::Models::Message.user("hi"))
+  puts task.id
+end
+```

data/docs/api/index.md

@@ -0,0 +1,27 @@
+# API Reference
+
+## Namespaces
+
+| Namespace | Description |
+|---|---|
+| [`A2A::Models`](models/index.md) | Data classes — Task, Message, Part, Artifact, AgentCard, events |
+| [`A2A::Server`](server/index.md) | Server bootstrap, routing, executor base, context, event routing |
+| [`A2A::Client`](client/index.md) | HTTP client (sync JSON-RPC + SSE streaming) |
+| [`A2A::Storage`](storage/index.md) | Task persistence — Memory backend, pluggable base |
+| `A2A::JsonRpc` | JSON-RPC 2.0 request/response/error layer |
+
+## Top-level module
+
+```ruby
+A2A.logger = Logger.new($stdout)   # optional — logs internal warnings
+
+A2A.server(**opts)      # → A2A::Server::Base.new(**opts)
+A2A.client(**opts)      # → A2A::Client::Base.new(**opts)
+A2A.sse_client(**opts)  # → A2A::Client::SSE.new(**opts)
+```
+
+## Constants
+
+```ruby
+A2A::VERSION   # => "0.1.0"
+```

data/docs/api/models/index.md

@@ -0,0 +1,233 @@
+# Models
+
+All model classes live under `A2A::Models` and inherit from `A2A::Models::Base`, which provides a lightweight attribute DSL with camelCase JSON serialization.
+
+## Part
+
+The atomic content unit in a message or artifact.
+
+```ruby
+A2A::Models::Part.text("hello")                               # text part
+A2A::Models::Part.json({ key: "value" })                      # JSON data part
+A2A::Models::Part.from_url("https://…", media_type: "image/png")  # URL reference
+A2A::Models::Part.binary(File.binread("file.pdf"),
+                          media_type: "application/pdf",
+                          filename: "file.pdf")                # base64-encoded binary
+```
+
+| Attribute | Type | Description |
+|---|---|---|
+| `text` | String | Plain text content |
+| `data` | Hash | Structured JSON data |
+| `url` | String | URL reference |
+| `raw` | String | Base64-encoded binary |
+| `media_type` | String | MIME type |
+| `filename` | String | Suggested filename |
+| `metadata` | Hash | Arbitrary metadata |
+
+**Predicates:** `#text?`, `#json?`, `#url?`, `#raw?`, `#valid?`  
+**Decoding:** `#decoded_bytes` → binary string (Base64 decode of `raw`)
+
+---
+
+## Message
+
+A message from a user or agent, composed of one or more Parts.
+
+```ruby
+A2A::Models::Message.user("hello")                        # user message with text part
+A2A::Models::Message.user("prefix", Part.text("…"))      # mixed content
+A2A::Models::Message.agent("I understand")                # agent message
+```
+
+| Attribute | Type | Required | Description |
+|---|---|---|---|
+| `message_id` | String | auto | UUID, auto-generated |
+| `role` | String | yes | `"user"` or `"agent"` |
+| `parts` | [Part] | yes | Content parts |
+| `context_id` | String | | Task context ID |
+| `task_id` | String | | Task this message belongs to |
+| `reference_task_ids` | [String] | | Related task IDs |
+| `metadata` | Hash | | Arbitrary metadata |
+
+**Predicates:** `#user?`, `#agent?`, `#valid?`  
+**Helper:** `#text_content` → concatenates all text parts with newlines
+
+---
+
+## Artifact
+
+A structured output produced by an agent.
+
+```ruby
+A2A::Models::Artifact.new(
+  name:  "report",
+  parts: [A2A::Models::Part.text("The answer is 42")]
+)
+```
+
+| Attribute | Type | Description |
+|---|---|---|
+| `name` | String | Artifact identifier |
+| `description` | String | Human-readable description |
+| `parts` | [Part] | Content parts |
+| `index` | Integer | Position in artifact sequence |
+| `append` | Boolean | True if this is a streaming chunk appended to a prior artifact |
+| `last_chunk` | Boolean | True if this is the final streaming chunk |
+| `metadata` | Hash | Arbitrary metadata |
+
+---
+
+## Task
+
+Represents a unit of work. Tasks are created by the server on each `tasks/send` call.
+
+```ruby
+task = A2A::Models::Task.new(
+  status: A2A::Models::TaskStatus.new(state: "submitted")
+)
+```
+
+| Method | Description |
+|---|---|
+| `task.start!` | Transition to `working` |
+| `task.complete!(artifacts: […])` | Transition to `completed`, attach artifacts |
+| `task.fail!(message: "…")` | Transition to `failed` |
+| `task.cancel!` | Transition to `canceled` |
+| `task.reject!(message: "…")` | Transition to `rejected` |
+| `task.require_input!` | Transition to `input_required` |
+| `task.require_auth!` | Transition to `auth_required` |
+| `task.terminal?` | True if state is completed/failed/canceled/rejected |
+| `task.interrupted?` | True if state is input_required/auth_required |
+| `task.state` | Current state string |
+
+---
+
+## TaskStatus
+
+Attached to every Task. Created automatically on transition.
+
+| Attribute | Type | Description |
+|---|---|---|
+| `state` | String | One of the `Types::TaskState` constants |
+| `message` | Message | Optional status message |
+| `timestamp` | String | ISO 8601, auto-set to `Time.now.iso8601` |
+
+---
+
+## Types
+
+```ruby
+A2A::Models::Types::TaskState::SUBMITTED      # => "submitted"
+A2A::Models::Types::TaskState::WORKING        # => "working"
+A2A::Models::Types::TaskState::COMPLETED      # => "completed"
+A2A::Models::Types::TaskState::FAILED         # => "failed"
+A2A::Models::Types::TaskState::CANCELED       # => "canceled"
+A2A::Models::Types::TaskState::REJECTED       # => "rejected"
+A2A::Models::Types::TaskState::INPUT_REQUIRED # => "input_required"
+A2A::Models::Types::TaskState::AUTH_REQUIRED  # => "auth_required"
+
+A2A::Models::Types::TaskState.terminal?(state)    # => true/false
+A2A::Models::Types::TaskState.interrupted?(state) # => true/false
+A2A::Models::Types::TaskState.active?(state)      # => true/false
+
+A2A::Models::Types::Role::USER   # => "user"
+A2A::Models::Types::Role::AGENT  # => "agent"
+```
+
+---
+
+## AgentCard
+
+Describes an agent's identity and capabilities for discovery.
+
+```ruby
+card = A2A::Models::AgentCard.new(
+  name:         "MyAgent",
+  version:      "1.0",
+  description:  "An example agent",
+  capabilities: A2A::Models::AgentCapabilities.new(streaming: true),
+  skills:       [A2A::Models::AgentSkill.new(name: "greet")],
+  interfaces:   [A2A::Models::AgentInterface.new(
+    type: "json-rpc", url: "http://localhost:9292", version: "1.0"
+  )]
+)
+```
+
+### AgentCapabilities
+
+| Attribute | Type | Default | Description |
+|---|---|---|---|
+| `streaming` | Boolean | false | Supports `tasks/sendSubscribe` |
+| `push_notifications` | Boolean | false | Supports webhook push |
+| `state_transition_history` | Boolean | false | Preserves task history |
+
+### AgentSkill
+
+| Attribute | Description |
+|---|---|
+| `name` | Skill identifier |
+| `description` | Human-readable description |
+| `tags` | Searchable tags |
+| `examples` | Example prompts |
+
+### AgentInterface
+
+| Attribute | Description |
+|---|---|
+| `type` | Binding type: `"json-rpc"`, `"http"`, `"grpc"` |
+| `url` | Endpoint URL |
+| `version` | Protocol version |
+
+---
+
+## Events
+
+Events are emitted during streaming (`tasks/sendSubscribe`) and via push notifications.
+
+### TaskStatusUpdateEvent
+
+```ruby
+A2A::Models::TaskStatusUpdateEvent.new(
+  task_id:    task.id,
+  context_id: task.context_id,
+  status:     task.status,
+  final:      true
+)
+```
+
+### TaskArtifactUpdateEvent
+
+```ruby
+A2A::Models::TaskArtifactUpdateEvent.new(
+  task_id:    task.id,
+  context_id: task.context_id,
+  artifact:   artifact,
+  append:     false,
+  last_chunk: false
+)
+```
+
+---
+
+## Push notification models
+
+### PushNotificationConfig
+
+```ruby
+config = A2A::Models::PushNotificationConfig.new(
+  webhook_url:          "https://example.com/hook",
+  authentication_info:  A2A::Models::AuthenticationInfo.new(
+    scheme: "bearer"
+  )
+)
+config.valid?   # => true
+```
+
+### AuthenticationInfo
+
+| Attribute | Description |
+|---|---|
+| `scheme` | `"bearer"` (JWT), `"token"` (static), or custom |
+| `value` | Token value (used for `"token"` scheme) |
+| `header_name` | Override header name (default: `"Authorization"`) |