agentdyne 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1c1119bd1943f2861ad02a8e489c4c3e6185712ff487d8800d1f8ce1133cb262
+  data.tar.gz: 01be54ee75e15986f9d3a830570d653794102ee88286c030ba2bbf4f77c83e74
+SHA512:
+  metadata.gz: '091bdb780213fa5b05438fa49a58690f5f3cc623959c548a54da0b52de7a9fae66bb014d7ac3b9fa16f9742c809e920cf72a7a4bb73f48a9770a8d901300fb75'
+  data.tar.gz: 9c89bf8c3d2b0843c90152536d61d17dfbcf96e1798180d3aee5627791d8de84176e2a7d53c51175181a280eb91e028ec3c23c5e348005ca39a9bb76a0fc3acc

data/README.md

@@ -0,0 +1,233 @@
+# agentdyne
+
+Official Ruby SDK for [AgentDyne](https://agentdyne.com) — The Global Microagent Marketplace.
+
+[![Gem Version](https://badge.fury.io/rb/agentdyne.svg)](https://rubygems.org/gems/agentdyne)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Installation
+
+```ruby
+# Gemfile
+gem "agentdyne"
+```
+
+```bash
+bundle install
+# or standalone:
+gem install agentdyne
+```
+
+## Quick Start
+
+```ruby
+require "agentdyne"
+
+client = AgentDyne.new(api_key: "agd_your_key_here")
+
+result = client.execute("agent_id", "Summarize this email thread...")
+puts result.output
+# => { "summary" => "...", "action_items" => [...] }
+
+puts "Latency: #{result.latency_ms}ms   Cost: $#{"%.6f" % result.cost}"
+```
+
+## Authentication
+
+```bash
+export AGENTDYNE_API_KEY=agd_your_key_here
+```
+
+```ruby
+# Reads from env automatically
+client = AgentDyne.new
+
+# Or pass directly
+client = AgentDyne.new(api_key: "agd_...")
+```
+
+## Usage
+
+### List Agents
+
+```ruby
+page = client.list_agents(category: "coding", sort: "rating", limit: 10)
+page.data.each do |agent|
+  puts "#{agent.name}  ★#{agent.average_rating}  #{agent.pricing_model}"
+end
+puts "Total: #{page.pagination.total}"
+```
+
+### Execute an Agent
+
+```ruby
+# String input
+result = client.execute("email-summarizer-pro", "Hi team, the Q4 report is attached...")
+
+# Structured input
+result = client.execute("code-review-agent", {
+  code: "def add(a, b)\n  a + b\nend",
+  language: "ruby"
+})
+
+# With idempotency key (safe to retry on network failure)
+result = client.execute("agent_id", "Hello", idempotency_key: SecureRandom.uuid)
+
+puts result.output
+puts "#{result.tokens.input} in / #{result.tokens.output} out tokens"
+```
+
+### Streaming
+
+```ruby
+client.stream("content-writer", "Write a blog post about AI agents in 2026") do |chunk|
+  case chunk.type
+  when "delta"
+    print chunk.delta
+    $stdout.flush
+  when "done"
+    puts "\n✓ Done (execution: #{chunk.execution_id})"
+  when "error"
+    warn "Stream error: #{chunk.error}"
+  end
+end
+```
+
+### Poll Execution
+
+```ruby
+# Start an execution (imagine it was async)
+exec = client.poll_execution("exec_id", interval: 0.5, timeout: 60)
+puts exec.status  # => "success"
+puts exec.output
+```
+
+### Paginate All Agents
+
+```ruby
+# Automatically pages through all results
+client.paginate_agents(category: "finance").each do |agent|
+  puts agent.name
+end
+```
+
+### User & Quota
+
+```ruby
+me = client.me
+puts me.subscription_plan  # => "pro"
+puts me.full_name
+
+quota = client.my_quota
+puts "#{quota.used}/#{quota.quota} calls used (#{quota.percent_used}%)"
+puts "Resets: #{quota.resets_at}"
+
+# Update profile
+client.update_profile(full_name: "Ada Lovelace", bio: "Building AI agents")
+```
+
+### Reviews
+
+```ruby
+# List reviews
+page = client.list_reviews("agent_id")
+page.data.each { |r| puts "★#{r.rating} — #{r.title}" }
+
+# Post a review (must have executed the agent first)
+review = client.create_review("agent_id",
+  rating: 5,
+  title:  "Incredible accuracy",
+  body:   "Handles every edge case I've thrown at it."
+)
+```
+
+### Webhooks
+
+```ruby
+# Rails controller
+class WebhooksController < ApplicationController
+  skip_before_action :verify_authenticity_token
+
+  def agentdyne
+    client = AgentDyne.new
+    event  = client.construct_webhook_event(
+      request.raw_post,
+      request.headers["X-AgentDyne-Signature"],
+      ENV["AGENTDYNE_WEBHOOK_SECRET"]
+    )
+
+    case event.type
+    when "execution.completed"
+      Rails.logger.info "Execution done: #{event.data["executionId"]}"
+    when "payout.processed"
+      Payout.record!(event.data)
+    end
+
+    head :ok
+
+  rescue AgentDyne::WebhookSignatureError
+    head :bad_request
+  end
+end
+```
+
+```ruby
+# Sinatra
+post "/webhook" do
+  client = AgentDyne.new
+  event  = client.construct_webhook_event(
+    request.body.read,
+    request.env["HTTP_X_AGENTDYNE_SIGNATURE"],
+    ENV["AGENTDYNE_WEBHOOK_SECRET"]
+  )
+  "OK"
+rescue AgentDyne::WebhookSignatureError
+  [400, "Invalid signature"]
+end
+```
+
+## Error Handling
+
+Every error inherits from `AgentDyne::AgentDyneError`:
+
+```ruby
+require "agentdyne"
+
+begin
+  result = client.execute("agent_id", "Hello")
+rescue AgentDyne::QuotaExceededError => e
+  puts "Upgrade at agentdyne.com/billing (plan: #{e.plan})"
+rescue AgentDyne::RateLimitError => e
+  sleep e.retry_after_seconds
+  retry
+rescue AgentDyne::SubscriptionRequiredError => e
+  puts "Subscribe to use agent: #{e.agent_id}"
+rescue AgentDyne::NotFoundError
+  puts "Agent not found"
+rescue AgentDyne::AuthenticationError
+  puts "Check your API key"
+rescue AgentDyne::AgentDyneError => e
+  puts "#{e.message} (HTTP #{e.status_code}, code=#{e.code})"
+end
+```
+
+## Configuration
+
+```ruby
+client = AgentDyne.new(
+  api_key:     "agd_...",
+  base_url:    "http://localhost:3000",  # local dev override
+  max_retries: 3,                        # retries on 429/5xx
+  timeout:     60                        # seconds
+)
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- No required dependencies (uses stdlib `net/http`, `openssl`, `json`)
+- Optional: `rack` gem for `secure_compare` in webhook verification
+
+## License
+
+MIT © 2026 AgentDyne, Inc.

data/agentdyne.gemspec

@@ -0,0 +1,29 @@
+Gem::Specification.new do |spec|
+  spec.name          = "agentdyne"
+  spec.version       = "1.0.0"
+  spec.authors       = ["AgentDyne, Inc."]
+  spec.email         = ["sdk@agentdyne.com"]
+  spec.summary       = "Official Ruby SDK for AgentDyne — The Global Microagent Marketplace"
+  spec.description   = "Discover, execute, and monetise AI agents with the AgentDyne Ruby SDK. Zero required dependencies."
+  spec.homepage      = "https://agentdyne.com"
+  spec.license       = "MIT"
+
+  spec.metadata = {
+    "homepage_uri"    => "https://agentdyne.com",
+    "source_code_uri" => "https://github.com/agentdyne/sdk-ruby",
+    "bug_tracker_uri" => "https://github.com/agentdyne/sdk-ruby/issues",
+    "documentation_uri" => "https://agentdyne.com/docs",
+  }
+
+  spec.required_ruby_version = ">= 3.1"
+  spec.files         = Dir["lib/**/*.rb", "README.md", "LICENSE", "agentdyne.gemspec"]
+  spec.require_paths = ["lib"]
+
+  # Zero required dependencies — uses Ruby's stdlib (net/http, openssl, json).
+  # Optional: rack for webhook secure_compare
+  spec.add_runtime_dependency "rack", ">= 2.0"
+
+  spec.add_development_dependency "rspec",     "~> 3.13"
+  spec.add_development_dependency "webmock",   "~> 3.23"
+  spec.add_development_dependency "rake",      "~> 13.2"
+end

data/lib/agentdyne/client.rb

@@ -0,0 +1,262 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+require "ostruct"
+
+module AgentDyne
+  # The main AgentDyne Ruby client.
+  #
+  # @example
+  #   client = AgentDyne::Client.new(api_key: "agd_...")
+  #   result = client.execute("agent_id", "Summarize this...")
+  #   puts result.output
+  #
+  class Client
+    TERMINAL_STATUSES = %w[success failed timeout].freeze
+
+    # @param api_key [String] Your AgentDyne API key. Falls back to
+    #   the AGENTDYNE_API_KEY environment variable.
+    # @param base_url [String] API base URL (default: https://api.agentdyne.com).
+    # @param max_retries [Integer] Retries on 429/5xx (default: 3).
+    # @param timeout [Integer] Request timeout in seconds (default: 60).
+    def initialize(
+      api_key: nil,
+      base_url: "https://api.agentdyne.com",
+      max_retries: 3,
+      timeout: 60
+    )
+      resolved_key = api_key || ENV["AGENTDYNE_API_KEY"]
+      raise ArgumentError, "AgentDyne API key is required. Pass api_key: or set AGENTDYNE_API_KEY." if resolved_key.nil? || resolved_key.empty?
+
+      @http = HttpClient.new(
+        api_key:     resolved_key,
+        base_url:    base_url,
+        timeout:     timeout,
+        max_retries: max_retries,
+      )
+    end
+
+    # ── Agents ──────────────────────────────────────────────────────────────
+
+    # List agents with optional filters.
+    #
+    # @param q [String, nil] Full-text search query.
+    # @param category [String, nil] Agent category.
+    # @param pricing [String, nil] Pricing model filter.
+    # @param sort [String, nil] Sort order ("popular", "rating", "newest").
+    # @param page [Integer] Page number (default: 1).
+    # @param limit [Integer] Results per page (default: 24, max: 100).
+    # @return [OpenStruct] with .data (Array) and .pagination.
+    #
+    # @example
+    #   page = client.list_agents(category: "coding", sort: "rating")
+    #   page.data.each { |a| puts "#{a['name']} ★#{a['average_rating']}" }
+    def list_agents(q: nil, category: nil, pricing: nil, sort: nil, page: 1, limit: 24)
+      params = { page: page, limit: limit }
+      params[:q]        = q        if q
+      params[:category] = category if category
+      params[:pricing]  = pricing  if pricing
+      params[:sort]     = sort     if sort
+      raw = @http.get("/v1/agents", params)
+      to_ostruct(raw)
+    end
+
+    # Get a single agent by ID.
+    #
+    # @return [OpenStruct]
+    def get_agent(agent_id)
+      to_ostruct(@http.get("/v1/agents/#{agent_id}"))
+    end
+
+    # Search agents by keyword.
+    def search_agents(query, **kwargs)
+      list_agents(q: query, **kwargs)
+    end
+
+    # Iterate through ALL matching agents across pages automatically.
+    #
+    # @example
+    #   client.paginate_agents(category: "finance").each { |a| puts a.name }
+    def paginate_agents(**kwargs)
+      Enumerator.new do |y|
+        p = 1
+        loop do
+          page = list_agents(page: p, **kwargs)
+          page.data.each { |item| y << to_ostruct(item) }
+          break unless page.pagination.has_next
+          p += 1
+        end
+      end
+    end
+
+    # ── Execution ────────────────────────────────────────────────────────────
+
+    # Execute an agent synchronously and return the output.
+    #
+    # @param agent_id [String]
+    # @param input [String, Hash, Array] Input to the agent.
+    # @param idempotency_key [String, nil] Optional UUID for safe retries.
+    # @return [OpenStruct] with .output, .latency_ms, .cost, .tokens, .execution_id
+    #
+    # @example
+    #   result = client.execute("code-review-agent", { code: "def f(): pass", language: "python" })
+    #   puts result.output
+    def execute(agent_id, input, idempotency_key: nil)
+      body = { input: input }
+      body[:idempotencyKey] = idempotency_key if idempotency_key
+      raw = @http.post("/v1/agents/#{agent_id}/execute", body)
+      to_ostruct(raw)
+    end
+
+    # Stream an agent's output.
+    # Yields StreamChunk-like OpenStructs with .type, .delta, .execution_id.
+    #
+    # @example
+    #   client.stream("content-writer", "Write a haiku about Ruby") do |chunk|
+    #     print chunk.delta if chunk.type == "delta"
+    #   end
+    def stream(agent_id, input, &block)
+      @http.stream("/v1/agents/#{agent_id}/execute", { input: input, stream: true }) do |raw_line|
+        begin
+          data  = JSON.parse(raw_line)
+          chunk = OpenStruct.new(
+            type:         data["type"] || "delta",
+            delta:        data["delta"],
+            execution_id: data["executionId"],
+            error:        data["error"],
+          )
+        rescue JSON::ParserError
+          chunk = OpenStruct.new(type: "delta", delta: raw_line)
+        end
+        block.call(chunk)
+        return if chunk.type == "done"
+      end
+    end
+
+    # ── Executions ───────────────────────────────────────────────────────────
+
+    # Get a single execution by ID.
+    def get_execution(execution_id)
+      to_ostruct(@http.get("/v1/executions/#{execution_id}"))
+    end
+
+    # List execution history.
+    def list_executions(agent_id: nil, status: nil, page: 1, limit: 20)
+      params = { page: page, limit: limit }
+      params[:agentId] = agent_id if agent_id
+      params[:status]  = status   if status
+      to_ostruct(@http.get("/v1/executions", params))
+    end
+
+    # Poll until an execution reaches a terminal state.
+    #
+    # @param interval [Float] Seconds between polls (default: 1.0).
+    # @param timeout [Float] Maximum seconds to wait (default: 120.0).
+    # @raise [AgentDyneError] if the execution does not complete in time.
+    #
+    # @example
+    #   exec = client.poll_execution("exec_id", interval: 0.5)
+    def poll_execution(execution_id, interval: 1.0, timeout: 120.0)
+      deadline = Time.now + timeout
+      loop do
+        ex = get_execution(execution_id)
+        return ex if TERMINAL_STATUSES.include?(ex.status)
+        raise AgentDyneError, "Execution \"#{execution_id}\" did not complete within #{timeout}s" if Time.now > deadline
+        sleep(interval)
+      end
+    end
+
+    # ── User ─────────────────────────────────────────────────────────────────
+
+    # Return the authenticated user's profile.
+    def me
+      to_ostruct(@http.get("/v1/user/me"))
+    end
+
+    # Return quota usage for the current billing period.
+    def my_quota
+      to_ostruct(@http.get("/v1/user/quota"))
+    end
+
+    # Update profile fields.
+    def update_profile(**updates)
+      to_ostruct(@http.patch("/v1/user/me", updates))
+    end
+
+    # ── Reviews ──────────────────────────────────────────────────────────────
+
+    # List approved reviews for an agent.
+    def list_reviews(agent_id, page: 1, limit: 20)
+      to_ostruct(@http.get("/v1/agents/#{agent_id}/reviews", { page: page, limit: limit }))
+    end
+
+    # Post a review for an agent.
+    def create_review(agent_id, rating:, title: nil, body: nil)
+      payload = { rating: rating }
+      payload[:title] = title if title
+      payload[:body]  = body  if body
+      to_ostruct(@http.post("/v1/agents/#{agent_id}/reviews", payload))
+    end
+
+    # ── Notifications ────────────────────────────────────────────────────────
+
+    # List your notifications.
+    def list_notifications
+      @http.get("/v1/notifications").fetch("notifications", []).map { |n| to_ostruct(n) }
+    end
+
+    # Mark all notifications as read.
+    def mark_notifications_read
+      @http.patch("/v1/notifications").fetch("ok", false)
+    end
+
+    # ── Webhooks ─────────────────────────────────────────────────────────────
+
+    # Verify and parse an incoming AgentDyne webhook.
+    #
+    # Raises WebhookSignatureError if the signature is invalid.
+    #
+    # @param payload [String] Raw request body.
+    # @param signature [String] Value of X-AgentDyne-Signature header.
+    # @param secret [String] Your webhook signing secret.
+    # @return [OpenStruct] Parsed event with .type and .data.
+    #
+    # @example (Sinatra)
+    #   post "/webhook" do
+    #     event = client.construct_webhook_event(
+    #       request.body.read,
+    #       request.env["HTTP_X_AGENTDYNE_SIGNATURE"],
+    #       ENV["WEBHOOK_SECRET"]
+    #     )
+    #     case event.type
+    #     when "execution.completed" then process_execution(event.data)
+    #     end
+    #     "OK"
+    #   end
+    def construct_webhook_event(payload, signature, secret)
+      sig_clean = signature.to_s.sub(/^sha256=/, "")
+      expected  = OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+
+      unless Rack::Utils.secure_compare(expected, sig_clean) rescue (expected == sig_clean)
+        raise WebhookSignatureError
+      end
+
+      begin
+        to_ostruct(JSON.parse(payload))
+      rescue JSON::ParserError
+        raise WebhookSignatureError, "Webhook payload is not valid JSON"
+      end
+    end
+
+    private
+
+    def to_ostruct(obj)
+      case obj
+      when Hash  then OpenStruct.new(obj.transform_values { |v| to_ostruct(v) })
+      when Array then obj.map { |item| to_ostruct(item) }
+      else            obj
+      end
+    end
+  end
+end

data/lib/agentdyne/errors.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module AgentDyne
+  # Base error for all AgentDyne SDK exceptions.
+  class AgentDyneError < StandardError
+    attr_reader :status_code, :code, :raw
+
+    def initialize(message, status_code: nil, code: nil, raw: nil)
+      super(message)
+      @status_code = status_code
+      @code        = code
+      @raw         = raw
+    end
+
+    def to_h
+      { error: self.class.name, message: message, status_code: status_code, code: code }
+    end
+  end
+
+  # HTTP 401 — API key missing, invalid, or revoked.
+  class AuthenticationError < AgentDyneError
+    def initialize(message = "Invalid or missing API key", raw: nil)
+      super(message, status_code: 401, code: "AUTHENTICATION_ERROR", raw: raw)
+    end
+  end
+
+  # HTTP 403 — insufficient permissions.
+  class PermissionDeniedError < AgentDyneError
+    def initialize(message = "Permission denied", raw: nil)
+      super(message, status_code: 403, code: "PERMISSION_DENIED", raw: raw)
+    end
+  end
+
+  # HTTP 403 / SUBSCRIPTION_REQUIRED — agent requires subscription.
+  class SubscriptionRequiredError < AgentDyneError
+    attr_reader :agent_id
+
+    def initialize(agent_id = nil, raw: nil)
+      msg = agent_id ? "Agent \"#{agent_id}\" requires an active subscription" : "Subscription required"
+      super(msg, status_code: 403, code: "SUBSCRIPTION_REQUIRED", raw: raw)
+      @agent_id = agent_id
+    end
+  end
+
+  # HTTP 404 — resource not found.
+  class NotFoundError < AgentDyneError
+    def initialize(message = "Resource not found", raw: nil)
+      super(message, status_code: 404, code: "NOT_FOUND", raw: raw)
+    end
+  end
+
+  # HTTP 400 — malformed request or missing required fields.
+  class ValidationError < AgentDyneError
+    attr_reader :fields
+
+    def initialize(message, fields: nil, raw: nil)
+      super(message, status_code: 400, code: "VALIDATION_ERROR", raw: raw)
+      @fields = fields || {}
+    end
+  end
+
+  # HTTP 429 — per-minute rate limit exceeded.
+  class RateLimitError < AgentDyneError
+    attr_reader :retry_after_seconds
+
+    def initialize(retry_after_seconds = 60.0, raw: nil)
+      super("Rate limit exceeded. Retry after #{retry_after_seconds.to_i}s",
+            status_code: 429, code: "RATE_LIMIT_EXCEEDED", raw: raw)
+      @retry_after_seconds = retry_after_seconds
+    end
+  end
+
+  # HTTP 429 / QUOTA_EXCEEDED — monthly execution quota exhausted.
+  class QuotaExceededError < AgentDyneError
+    attr_reader :plan
+
+    def initialize(plan = nil, raw: nil)
+      msg = plan ? "Monthly quota exceeded on \"#{plan}\" plan. Please upgrade." : "Monthly quota exceeded."
+      super(msg, status_code: 429, code: "QUOTA_EXCEEDED", raw: raw)
+      @plan = plan
+    end
+  end
+
+  # 5xx — unrecoverable server error.
+  class InternalServerError < AgentDyneError
+    def initialize(message = "Internal server error", raw: nil)
+      super(message, status_code: 500, code: "INTERNAL_SERVER_ERROR", raw: raw)
+    end
+  end
+
+  # Network-level failure (connection refused, DNS, TLS).
+  class NetworkError < AgentDyneError
+    def initialize(message, cause: nil)
+      super(message, code: "NETWORK_ERROR")
+      set_backtrace(cause&.backtrace)
+    end
+  end
+
+  # Webhook HMAC-SHA256 signature verification failed.
+  class WebhookSignatureError < AgentDyneError
+    def initialize(message = "Webhook signature verification failed")
+      super(message, code: "WEBHOOK_SIGNATURE_INVALID")
+    end
+  end
+end

data/lib/agentdyne/http.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+
+module AgentDyne
+  # Internal HTTP client. Not intended for direct use.
+  class HttpClient # :nodoc:
+    SDK_VERSION    = AgentDyne::VERSION
+    DEFAULT_TIMEOUT  = 60
+    NON_RETRYABLE   = [400, 401, 403, 404, 422].freeze
+
+    def initialize(api_key:, base_url:, timeout:, max_retries:)
+      @api_key     = api_key
+      @base_url    = URI(base_url.chomp("/"))
+      @timeout     = timeout
+      @max_retries = max_retries
+    end
+
+    def get(path, params = {})
+      request_with_retry(:get, path, params: params)
+    end
+
+    def post(path, body = nil)
+      request_with_retry(:post, path, body: body)
+    end
+
+    def patch(path, body = nil)
+      request_with_retry(:patch, path, body: body)
+    end
+
+    def delete(path)
+      request_with_retry(:delete, path)
+    end
+
+    # Yields raw SSE data lines.
+    def stream(path, body, &block)
+      uri = build_uri(path)
+      http = build_http(uri)
+
+      req = Net::HTTP::Post.new(uri)
+      apply_headers(req, stream: true)
+      req.body = JSON.generate(body)
+
+      http.request(req) do |resp|
+        raise_for_status(resp) unless resp.is_a?(Net::HTTPSuccess)
+        resp.read_body do |chunk|
+          chunk.each_line do |line|
+            line = line.strip
+            next unless line.start_with?("data: ")
+            data = line[6..]
+            return if data == "[DONE]"
+            block.call(data)
+          end
+        end
+      end
+    rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError => e
+      raise NetworkError.new(e.message, cause: e)
+    end
+
+    private
+
+    def request_with_retry(method, path, params: {}, body: nil)
+      last_error = nil
+
+      (@max_retries + 1).times do |attempt|
+        if attempt > 0
+          sleep(backoff_delay(attempt - 1))
+        end
+
+        begin
+          result = execute_request(method, path, params: params, body: body)
+          return result
+        rescue RateLimitError => e
+          sleep(e.retry_after_seconds) if attempt < @max_retries
+          last_error = e
+        rescue AgentDyneError => e
+          raise if NON_RETRYABLE.include?(e.status_code)
+          raise if e.status_code && e.status_code < 500
+          last_error = e
+        rescue NetworkError => e
+          last_error = e
+        end
+      end
+
+      raise last_error
+    end
+
+    def execute_request(method, path, params: {}, body: nil)
+      uri  = build_uri(path, params)
+      http = build_http(uri)
+      req  = build_request(method, uri, body)
+
+      resp = http.request(req)
+      raise_for_status(resp)
+
+      body_str = resp.body
+      return nil if body_str.nil? || body_str.empty?
+      JSON.parse(body_str)
+    rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, SocketError => e
+      raise NetworkError.new(e.message, cause: e)
+    end
+
+    def build_uri(path, params = {})
+      uri = URI.join(@base_url.to_s + "/", path.delete_prefix("/"))
+      unless params.empty?
+        uri.query = URI.encode_www_form(params.compact)
+      end
+      uri
+    end
+
+    def build_http(uri)
+      http              = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl      = uri.scheme == "https"
+      http.read_timeout = @timeout
+      http.open_timeout = @timeout
+      http
+    end
+
+    def build_request(method, uri, body)
+      klass = {
+        get:    Net::HTTP::Get,
+        post:   Net::HTTP::Post,
+        patch:  Net::HTTP::Patch,
+        delete: Net::HTTP::Delete,
+      }[method]
+      req = klass.new(uri)
+      apply_headers(req)
+      req.body = JSON.generate(body) if body
+      req
+    end
+
+    def apply_headers(req, stream: false)
+      req["Authorization"] = "Bearer #{@api_key}"
+      req["Content-Type"]  = "application/json"
+      req["Accept"]        = stream ? "text/event-stream" : "application/json"
+      req["User-Agent"]    = "agentdyne-ruby/#{SDK_VERSION}"
+      req["X-SDK-Language"]= "ruby"
+    end
+
+    def raise_for_status(resp)
+      return if resp.is_a?(Net::HTTPSuccess)
+
+      status   = resp.code.to_i
+      raw_body = resp.body.to_s
+      body     = begin; JSON.parse(raw_body); rescue JSON::ParserError; {}; end
+
+      message = body["error"] || body["message"] || "HTTP #{status}"
+      code    = body["code"]
+
+      case status
+      when 400 then raise ValidationError.new(message, fields: body["fields"], raw: body)
+      when 401 then raise AuthenticationError.new(message, raw: body)
+      when 403
+        if code == "SUBSCRIPTION_REQUIRED"
+          raise SubscriptionRequiredError.new(nil, raw: body)
+        end
+        raise PermissionDeniedError.new(message, raw: body)
+      when 404 then raise NotFoundError.new(message, raw: body)
+      when 429
+        if code == "QUOTA_EXCEEDED"
+          raise QuotaExceededError.new(nil, raw: body)
+        end
+        retry_after = (resp["Retry-After"] || "60").to_f
+        raise RateLimitError.new(retry_after, raw: body)
+      else
+        if status >= 500
+          raise InternalServerError.new(message, raw: body)
+        end
+        raise AgentDyneError.new(message, status_code: status, code: code, raw: body)
+      end
+    end
+
+    def backoff_delay(attempt)
+      base    = 0.5
+      cap     = 30.0
+      ceiling = [cap, base * (2**attempt)].min
+      rand * ceiling
+    end
+  end
+end

data/lib/agentdyne/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentDyne
+  VERSION = "1.0.0"
+end

data/lib/agentdyne.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# lib/agentdyne.rb — AgentDyne Ruby SDK main entry point.
+#
+# Quick start:
+#
+#   require "agentdyne"
+#
+#   client = AgentDyne::Client.new(api_key: "agd_...")
+#   result = client.execute("agent_id", "Summarize this email...")
+#   puts result.output
+#
+
+require_relative "agentdyne/version"
+require_relative "agentdyne/errors"
+require_relative "agentdyne/types"
+require_relative "agentdyne/http"
+require_relative "agentdyne/client"
+
+module AgentDyne
+  # Convenience constructor — mirrors Python and Node patterns.
+  #
+  #   client = AgentDyne.new(api_key: "agd_...")
+  #
+  def self.new(**kwargs)
+    Client.new(**kwargs)
+  end
+end

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: agentdyne
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- AgentDyne, Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-04-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.23'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.2'
+description: Discover, execute, and monetise AI agents with the AgentDyne Ruby SDK.
+  Zero required dependencies.
+email:
+- sdk@agentdyne.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- agentdyne.gemspec
+- lib/agentdyne.rb
+- lib/agentdyne/client.rb
+- lib/agentdyne/errors.rb
+- lib/agentdyne/http.rb
+- lib/agentdyne/version.rb
+homepage: https://agentdyne.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://agentdyne.com
+  source_code_uri: https://github.com/agentdyne/sdk-ruby
+  bug_tracker_uri: https://github.com/agentdyne/sdk-ruby/issues
+  documentation_uri: https://agentdyne.com/docs
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6.3
+signing_key: 
+specification_version: 4
+summary: Official Ruby SDK for AgentDyne — The Global Microagent Marketplace
+test_files: []