rubyrana 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a23b823b6f21c5d8093c355b4c0a4fdcb8e5268b075163708d4e3d0042e556b0
-  data.tar.gz: f3b7ecd4ff79260a1d24fde0c8028dd496a89973212c356949fee339b9e612f4
+  metadata.gz: 34608dd47bf0508e17e5f98c2234ea030a853dadd0dfbb22e14770a179bcd09e
+  data.tar.gz: 32e051b98dcea4c2246eff0c77b1f5d8b0cf5c4f7cdb2c409cead771ade22db6
 SHA512:
-  metadata.gz: a540d2da6e926c6b9abd75761a978000785fb4b0951a95f6df641b222e34df7e62fb202013eb331f975422c7d55bea5ce7266ac667662119c3f5ce2deb1aa85d
-  data.tar.gz: 986c64f68ea2fab6cee3851649b28aa8c8fb14356bad86aa84962e2e01748e656671773c17f5b1664b22a6827009f4828c160737f14983343ef5b5448befc691
+  metadata.gz: 513bf981ad9bcf68f9891c94a81c3298c30e7b2fc25936c33789e9d10fa6e951afa883f740ccedc3e016749a43d327be4b8279f626d63e1c0ea026e4419fc9ca
+  data.tar.gz: 025dc718c6125ef006ad486bdb47f533e6372694ea664c9cd1dc3697773c02bfaf6837699c901e335c5d907c6e552774fc134cd5e7efa6b6d920f39d36d860e7

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.2.0
+- Add structured output support with retries and event loop integration
+- Expand hooks taxonomy and provider registration
+- Introduce session repository layer with in-memory, file, and Redis adapters
+- Add A2A agent implementation and types
+- Add event loop events, interrupts, and richer agent results
+- Add multi-agent graph execution helper
+- Reorganize docs/examples and move build artifacts/vendor snapshots
+
+## 0.1.1
+- Update gemspec homepage
+
 ## 0.1.0
 - Initial MVP scaffolding
 - Agent loop with tool calling

data/README.md

@@ -8,7 +8,7 @@
 
   <div align="center">
     <img alt="Gem version" src="https://img.shields.io/gem/v/rubyrana" />
-    <img alt="Ruby" src="https://img.shields.io/badge/ruby-%3E%3D%203.1-brightgreen" />
+    <img alt="Ruby" src="https://img.shields.io/badge/ruby-%3E%3D%203.4-brightgreen" />
     <img alt="License" src="https://img.shields.io/badge/license-Apache%202.0-blue" />
   </div>
 
@@ -165,10 +165,8 @@ puts agent.call("Explain agentic workflows in simple terms")
 
 ## Documentation
 
-- Getting Started
-- Core Concepts
-- Tools & MCP
-- Production Deployment
+- [docs/INDEX.md](docs/INDEX.md)
+- [examples/README.md](examples/README.md)
 
 ## Contributing
 

data/docs/INDEX.md

@@ -0,0 +1,16 @@
+# Documentation Index
+
+## Guides
+- [docs/guides/USAGE.md](docs/guides/USAGE.md)
+
+## Operations
+- [docs/operations/DEV_WORKFLOW.md](docs/operations/DEV_WORKFLOW.md)
+- [docs/operations/RELEASE.md](docs/operations/RELEASE.md)
+- [docs/operations/CHECKLIST.md](docs/operations/CHECKLIST.md)
+
+## Roadmap
+- [docs/roadmap/TASKS.md](docs/roadmap/TASKS.md)
+- [docs/roadmap/TODO.md](docs/roadmap/TODO.md)
+
+## Reports
+- [docs/reports/REPORT.md](docs/reports/REPORT.md)

data/docs/{USAGE.md → guides/USAGE.md}

@@ -46,6 +46,13 @@ Load tools from a directory:
 
 - agent = Rubyrana::Agent.new(load_tools_from: "./tools")
 
+## Memory Strategies
+
+Use a rolling window to cap context size:
+
+- strategy = Rubyrana::Memory::RollingWindow.new(max_messages: 20)
+- agent = Rubyrana::Agent.new(memory_strategy: strategy)
+
 ## MCP (Experimental)
 
 Use the MCP client to load tools:

data/docs/operations/DEV_WORKFLOW.md

@@ -0,0 +1,16 @@
+# Dev Workflow
+
+## Install
+- `bundle install`
+
+## Run tests (fast feedback)
+- `scripts/run_tests.sh`
+
+## Run an example
+- `scripts/run_example.sh examples/quick_start.rb`
+
+## Suggested loop
+1) Implement a small change
+2) Run tests
+3) Run a relevant example
+4) Commit

data/docs/{RELEASE.md → operations/RELEASE.md}

@@ -9,7 +9,7 @@
 ## Release
 - Tag release in git (e.g., v0.1.0)
 - Build gem: `gem build rubyrana.gemspec`
-- Push gem: `gem push rubyrana-0.1.0.gem`
+- Push gem: `gem push dist/rubyrana-0.1.0.gem`
 
 ## Post-release
 - Update any version references

data/docs/roadmap/TASKS.md

@@ -0,0 +1,46 @@
+# Rubyrana Full‑Fledge Roadmap
+
+## 1) Anthropic Depth
+- Add system prompts support
+- Add tool_choice controls
+- Add thinking/analysis options
+- Add response format tuning
+- Map provider errors to friendly categories
+- Expand provider tests
+
+## 2) Tooling Parity
+- Add tool schema validation
+- Support structured tool results
+- Add tool choice policies
+- Improve tool debugging and tracing
+- Optional tool hot‑reload
+
+## 3) Memory & Context
+- Context window trimming
+- Summarization memory
+- Token budgeting
+- Memory strategy options (rolling, summary)
+
+## 4) Streaming Robustness
+- Partial chunk handling
+- Tool‑use streaming
+- Usage metadata during streaming
+- Streaming edge‑case tests
+
+## 5) Observability
+- Request/trace IDs
+- Metrics hooks
+- Structured logs
+- Provider/tool timing
+
+## 6) Tool Ecosystem
+- Split built‑in tools into packs
+- MCP tool discovery examples
+- Tool pack publishing guide
+
+## 7) Docs & Examples
+- Multi‑agent routing example
+- Safety filter example
+- Persistence example
+- MCP web search example
+- Deployment guide

data/docs/roadmap/TODO.md

@@ -0,0 +1,23 @@
+# Rubyrana Roadmap (Post-MVP)
+
+## Core Agent Capabilities
+- [x] Conversation memory and history management
+- [x] Structured tool-calling semantics per provider
+- [x] Native streaming for Anthropic
+- [x] Token usage + cost tracking
+
+## Developer Experience
+- [x] Rich examples (tools, MCP, streaming, providers)
+- [x] Error messages and retries tuned per provider
+- [x] Logging hooks and debug mode
+
+## Features Beyond MVP
+- [x] Multi-agent orchestration
+- [x] Task routing / tool selection policies
+- [x] Configurable safety filters
+- [x] Persistence adapters (file/redis)
+
+## Production Readiness
+- [x] Test coverage expansion
+- [x] CI enhancements (lint)
+- [x] Release automation

data/examples/README.md

@@ -0,0 +1,9 @@
+# Examples
+
+## Basic
+- [examples/basic/quick_start.rb](examples/basic/quick_start.rb)
+- [examples/basic/streaming.rb](examples/basic/streaming.rb)
+
+## Advanced
+- [examples/advanced/mcp.rb](examples/advanced/mcp.rb)
+- [examples/advanced/tools_loader.rb](examples/advanced/tools_loader.rb)

data/lib/rubyrana/a2a/agent.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Rubyrana
+  module A2A
+    class Agent
+      DEFAULT_TIMEOUT = 300
+
+      attr_reader :endpoint, :timeout, :name, :description
+
+      def initialize(endpoint:, name: nil, description: nil, timeout: DEFAULT_TIMEOUT, a2a_client_factory: nil, card_resolver: nil)
+        @endpoint = endpoint
+        @name = name
+        @description = description
+        @timeout = timeout
+        @agent_card = nil
+        @a2a_client_factory = a2a_client_factory
+        @card_resolver = card_resolver
+      end
+
+      def call(prompt = nil, **_kwargs)
+        invoke(prompt)
+      end
+
+      def invoke(prompt = nil, **_kwargs)
+        result = nil
+        stream(prompt) do |event|
+          result = event[:result] if event[:result]
+        end
+        raise RuntimeError, "No response received from A2A agent" unless result
+
+        result
+      end
+
+      def stream(prompt = nil, **_kwargs)
+        raise ArgumentError, "prompt is required" if prompt.nil?
+
+        last_event = nil
+        last_complete_event = nil
+        enumerator = _send_message(prompt)
+
+        if block_given?
+          enumerator.each do |event|
+            last_event = event
+            last_complete_event = event if complete_event?(event)
+            yield({ type: "a2a_stream", event: event })
+          end
+          final_event = last_complete_event || last_event
+          if final_event
+            result = Rubyrana::A2A::Converters.convert_response_to_agent_result(final_event)
+            yield({ result: result })
+          end
+          return
+        end
+
+        Enumerator.new do |yielder|
+          enumerator.each do |event|
+            last_event = event
+            last_complete_event = event if complete_event?(event)
+            yielder << { type: "a2a_stream", event: event }
+          end
+
+          final_event = last_complete_event || last_event
+          if final_event
+            result = Rubyrana::A2A::Converters.convert_response_to_agent_result(final_event)
+            yielder << { result: result }
+          end
+        end
+      end
+
+      def get_agent_card
+        return @agent_card if @agent_card
+
+        resolver = @card_resolver || Rubyrana::A2A::CardResolver.new(base_url: endpoint)
+        @agent_card = resolver.get_agent_card
+
+        @name ||= @agent_card.name
+        @description ||= @agent_card.description
+
+        @agent_card
+      end
+
+      private
+
+      def _send_message(prompt)
+        message = Rubyrana::A2A::Converters.convert_input_to_message(prompt)
+        client = a2a_client
+        client.send_message(message)
+      end
+
+      def a2a_client
+        agent_card = get_agent_card
+        factory = @a2a_client_factory || Rubyrana::A2A::ClientFactory.new
+        factory.create(agent_card)
+      end
+
+      def complete_event?(event)
+        return true if event.is_a?(Rubyrana::A2A::Message)
+
+        if event.is_a?(Array) && event.length == 2
+          task, update_event = event
+          return true if update_event.nil?
+
+          if update_event.is_a?(Rubyrana::A2A::TaskArtifactUpdateEvent)
+            return update_event.last_chunk unless update_event.last_chunk.nil?
+            return false
+          end
+
+          if update_event.is_a?(Rubyrana::A2A::TaskStatusUpdateEvent)
+            return update_event.status.state == "completed" if update_event.status&.state
+          end
+
+          return false
+        end
+
+        false
+      end
+    end
+  end
+end

data/lib/rubyrana/a2a/client.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+
+module Rubyrana
+  module A2A
+    class CardResolver
+      def initialize(base_url:, http_client: nil)
+        @base_url = base_url
+        @http_client = http_client
+      end
+
+      def get_agent_card
+        uri = URI.join(@base_url, "/.well-known/agent-card")
+        response = http_client.get(uri)
+        raise Rubyrana::ProviderError, "A2A agent card request failed (status #{response.code})" unless response.is_a?(Net::HTTPSuccess)
+
+        body = JSON.parse(response.body)
+        Rubyrana::A2A::AgentCard.new(
+          name: body["name"],
+          description: body["description"],
+          url: body["url"],
+          version: body["version"],
+          capabilities: body["capabilities"],
+          default_input_modes: body["default_input_modes"] || [],
+          default_output_modes: body["default_output_modes"] || [],
+          skills: body["skills"] || []
+        )
+      rescue JSON::ParserError => e
+        raise Rubyrana::ProviderError, e.message
+      end
+
+      private
+
+      def http_client
+        @http_client ||= Net::HTTP
+      end
+    end
+
+    class ClientFactory
+      def initialize(http_client: nil, streaming: true)
+        @http_client = http_client
+        @streaming = streaming
+      end
+
+      def create(agent_card)
+        Client.new(agent_card.url, http_client: @http_client, streaming: @streaming)
+      end
+    end
+
+    class Client
+      def initialize(base_url, http_client: nil, streaming: true)
+        @base_url = base_url
+        @http_client = http_client || Net::HTTP
+        @streaming = streaming
+      end
+
+      def send_message(message)
+        response = post_message(message)
+        parsed = parse_message_response(response)
+
+        Enumerator.new do |yielder|
+          yielder << parsed
+        end
+      end
+
+      private
+
+      def post_message(message)
+        uri = URI.join(@base_url, "/messages")
+        request = Net::HTTP::Post.new(uri)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.dump({ message: serialize_message(message) })
+
+        @http_client.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+          http.request(request)
+        end
+      end
+
+      def parse_message_response(response)
+        raise Rubyrana::ProviderError, "A2A message request failed (status #{response.code})" unless response.is_a?(Net::HTTPSuccess)
+
+        body = JSON.parse(response.body)
+        message = body["message"] || body
+        parts = Array(message["parts"]).map { |part| Rubyrana::A2A::Part.new(kind: part["kind"], text: part["text"]) }
+        Rubyrana::A2A::Message.new(
+          message_id: message["message_id"] || SecureRandom.uuid,
+          role: message["role"] || "agent",
+          parts: parts
+        )
+      rescue JSON::ParserError => e
+        raise Rubyrana::ProviderError, e.message
+      end
+
+      def serialize_message(message)
+        {
+          message_id: message.message_id,
+          role: message.role,
+          parts: message.parts.map { |part| { kind: part.kind, text: part.text } }
+        }
+      end
+    end
+  end
+end

data/lib/rubyrana/a2a/converters.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Rubyrana
+  module A2A
+    module Converters
+      module_function
+
+      def convert_input_to_message(prompt)
+        return prompt if prompt.is_a?(Rubyrana::A2A::Message)
+
+        if prompt.is_a?(Hash)
+          role = prompt[:role] || prompt["role"] || "user"
+          content = prompt[:content] || prompt["content"] || ""
+          return build_message(role, content)
+        end
+
+        if prompt.is_a?(Array)
+          return build_message("user", prompt)
+        end
+
+        build_message("user", prompt.to_s)
+      end
+
+      def convert_response_to_agent_result(event)
+        message = extract_message(event)
+        text = extract_text_from_message(message)
+        Rubyrana::Types::AgentResult.new(
+          text: text,
+          message: message,
+          stop_reason: "end_turn",
+          tool_results: [],
+          tool_uses: [],
+          interrupts: []
+        )
+      end
+
+      def build_message(role, content)
+        parts = normalize_parts(content)
+        Rubyrana::A2A::Message.new(
+          message_id: SecureRandom.uuid,
+          role: role,
+          parts: parts
+        )
+      end
+
+      def normalize_parts(content)
+        return content.map { |item| to_part(item) } if content.is_a?(Array)
+
+        [to_part(content)]
+      end
+
+      def to_part(item)
+        return item if item.is_a?(Rubyrana::A2A::Part) || item.is_a?(Rubyrana::A2A::TextPart)
+
+        if item.is_a?(Hash)
+          kind = item[:kind] || item["kind"] || "text"
+          text = item[:text] || item["text"] || item[:content] || item["content"] || item.to_s
+          return Rubyrana::A2A::Part.new(kind: kind, text: text)
+        end
+
+        Rubyrana::A2A::TextPart.new(kind: "text", text: item.to_s)
+      end
+
+      def extract_message(event)
+        return message_to_hash(event) if event.is_a?(Rubyrana::A2A::Message)
+
+        if event.is_a?(Array) && event.length == 2
+          task = event[0]
+          return message_to_hash(task.message) if task.respond_to?(:message) && task.message
+        end
+
+        if event.is_a?(Hash)
+          return event if event.key?(:role) || event.key?("role")
+          return event[:message] || event["message"] if event[:message] || event["message"]
+        end
+
+        { role: "assistant", content: [{ text: event.to_s }] }
+      end
+
+      def message_to_hash(message)
+        content = message.parts.to_a.map { |part| { text: part.text } }
+        { role: message.role, content: content }
+      end
+
+      def extract_text_from_message(message)
+        content = message[:content] || message["content"] || []
+        content.map { |item| item[:text] || item["text"] }.compact.join
+      end
+    end
+  end
+end

data/lib/rubyrana/a2a/types.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rubyrana
+  module A2A
+    AgentCard = Struct.new(
+      :name,
+      :description,
+      :url,
+      :version,
+      :capabilities,
+      :default_input_modes,
+      :default_output_modes,
+      :skills,
+      keyword_init: true
+    )
+
+    TextPart = Struct.new(:kind, :text, keyword_init: true)
+    Part = Struct.new(:kind, :text, keyword_init: true)
+
+    Message = Struct.new(:message_id, :role, :parts, keyword_init: true)
+
+    Task = Struct.new(:id, :status, :message, keyword_init: true)
+    TaskStatus = Struct.new(:state, keyword_init: true)
+    TaskStatusUpdateEvent = Struct.new(:status, keyword_init: true)
+    TaskArtifactUpdateEvent = Struct.new(:last_chunk, keyword_init: true)
+  end
+end