ruby-pi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 766afd01deb469fa6f86f35844e7dd4e100c2de2deb2ce593e07fa75b3ae4637
+  data.tar.gz: 8a72e80d2448359004909ed3afcf5b01fbd41429c2538dc5c8e6b84b6d18326b
+SHA512:
+  metadata.gz: 0cadf39edb5c0a83e3f1bf27f503bc9d682b9a4f264eb8a0fbb026609ce66508839acef3151ce53541aee62f1068819a1f8953bddca1c076eb7011c148799cb2
+  data.tar.gz: 861befb924a6dbf153f755fff18cf7c579bb175e5ebc227623591e1dfea637e444e041a795d5f750d77de2bec621147e903ae76dae12dd76b87e4936507e94fe

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-28
+
+### Added
+
+- `RubyPi::LLM` with Gemini, Anthropic, and OpenAI providers
+- Unified `Response`, `ToolCall`, and `StreamEvent` value objects
+- `BaseProvider` with automatic retry and exponential backoff with jitter
+- Streaming support via Faraday SSE parsing for all providers
+- `RubyPi::LLM::Fallback` for automatic provider failover
+- `RubyPi::LLM::Model` descriptor for deferred provider construction
+- `RubyPi::Tools::Definition` with `RubyPi::Tool.define` convenience API
+- `RubyPi::Schema` DSL for building JSON Schema parameter definitions
+- `RubyPi::Tools::Registry` -- thread-safe tool store with category filtering and subset extraction
+- `RubyPi::Tools::Executor` -- parallel and sequential tool dispatch with per-tool timeouts
+- `RubyPi::Tools::Result` -- execution outcome with value/error and timing
+- `RubyPi::Agent` with think-act-observe loop
+- Event system (`text_delta`, `tool_execution_start`, `tool_execution_end`, `turn_start`, `turn_end`, `before_tool_call`, `after_tool_call`, `agent_end`, `error`)
+- `RubyPi::Context::Compaction` for long-context management
+- `RubyPi::Context::Transform` helpers for message list preprocessing
+- `RubyPi::Extensions::Base` hook DSL for cross-cutting agent behavior
+- `RubyPi::Configuration` with API keys, retry settings, timeouts, and default models
+- Typed error hierarchy (`ApiError`, `AuthenticationError`, `RateLimitError`, `TimeoutError`, `ProviderError`)
+- Full RSpec test suite with WebMock (unit + integration)
+- GitHub Actions CI for Ruby 3.2 and 3.3

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EJ White
+
+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,415 @@
+# RubyPi
+
+[![Gem Version](https://badge.fury.io/rb/ruby-pi.svg)](https://rubygems.org/gems/ruby-pi)
+[![CI](https://github.com/ejwhite7/ruby-pi/actions/workflows/ci.yml/badge.svg)](https://github.com/ejwhite7/ruby-pi/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Ruby](https://img.shields.io/badge/Ruby-%3E%3D%203.2-red.svg)](https://www.ruby-lang.org)
+
+**A minimal, composable toolkit for building LLM-powered agents in Ruby.**
+
+RubyPi is an anti-framework. Instead of imposing a sprawling abstraction layer, it gives you small, focused modules you can compose however you like: swap providers, define tools, run agent loops, manage context -- all without buying into a monolithic architecture. Every piece works on its own, and they snap together when you need them to.
+
+---
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [API Reference](#api-reference)
+  - [RubyPi::LLM](#rubypillm)
+  - [RubyPi::Tools](#rubypitools)
+  - [RubyPi::Agent](#rubypiagent)
+  - [RubyPi::Context](#rubypicontext)
+  - [RubyPi::Extensions](#rubypiextensions)
+- [Configuration](#configuration)
+- [Contributing](#contributing)
+- [License](#license)
+
+---
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ruby-pi"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Or install directly:
+
+```bash
+gem install ruby-pi
+```
+
+---
+
+## Quick Start
+
+```ruby
+require "ruby_pi"
+
+# 1. Configure
+RubyPi.configure do |c|
+  c.gemini_api_key = ENV["GEMINI_API_KEY"]
+end
+
+# 2. Define a tool
+weather = RubyPi::Tool.define(
+  name: :get_weather,
+  description: "Get the current weather for a city",
+  parameters: RubyPi::Schema.object(
+    city: RubyPi::Schema.string("City name", required: true)
+  )
+) { |args| { temp: 72, condition: "sunny", city: args["city"] } }
+
+# 3. Build a registry and an agent
+registry = RubyPi::Tools::Registry.new
+registry.register(weather)
+
+model = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
+agent = RubyPi::Agent.new(model: model, tools: registry, stream: true)
+
+# 4. Subscribe to events
+agent.on(:text_delta) { |e| print e[:data] }
+agent.on(:tool_execution_end) { |e| puts "\n[Tool] #{e[:name]} => #{e[:result]}" }
+
+# 5. Run
+result = agent.run("What's the weather in San Francisco?")
+puts "\nDone: #{result.output}"
+```
+
+---
+
+## API Reference
+
+### RubyPi::LLM
+
+The LLM module provides a provider-agnostic interface for text generation, streaming, and tool calling across Gemini, Anthropic, and OpenAI.
+
+#### Model Factory
+
+```ruby
+# Build a provider instance
+model = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
+model = RubyPi::LLM.model(:anthropic, "claude-sonnet-4-20250514")
+model = RubyPi::LLM.model(:openai, "gpt-4o")
+```
+
+#### Completions
+
+```ruby
+response = model.complete(
+  messages: [{ role: "user", content: "Hello!" }],
+  tools: [],       # optional tool definitions
+  stream: false    # set true for streaming
+)
+
+response.content       # => "Hi there!"
+response.tool_calls    # => [] or [ToolCall, ...]
+response.tool_calls?   # => false
+response.usage         # => { prompt_tokens: 10, completion_tokens: 20, total_tokens: 30 }
+response.finish_reason # => "stop"
+```
+
+#### Streaming
+
+```ruby
+model.complete(messages: messages, stream: true) do |event|
+  case event.type
+  when :text_delta
+    print event.data           # incremental text chunk
+  when :tool_call_delta
+    handle_fragment(event.data) # partial tool call JSON
+  when :done
+    puts "\nStream finished"
+  end
+end
+```
+
+#### Response & ToolCall
+
+| Class | Attributes |
+|---|---|
+| `RubyPi::LLM::Response` | `content`, `tool_calls`, `usage`, `finish_reason`, `tool_calls?` |
+| `RubyPi::LLM::ToolCall` | `id`, `name`, `arguments` |
+| `RubyPi::LLM::StreamEvent` | `type`, `data`, `text_delta?`, `tool_call_delta?`, `done?` |
+
+#### Fallback
+
+Automatically fail over to a backup provider when the primary is unavailable:
+
+```ruby
+primary  = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
+backup   = RubyPi::LLM.model(:openai, "gpt-4o")
+provider = RubyPi::LLM::Fallback.new(primary: primary, fallback: backup)
+
+# Uses Gemini; if it 500s or times out, retries with OpenAI
+response = provider.complete(messages: messages)
+```
+
+Authentication errors (401/403) are **not** retried with the fallback -- they indicate a configuration problem, not a transient failure.
+
+---
+
+### RubyPi::Tools
+
+A lightweight DSL for defining tools (functions) that LLMs can call, plus a registry and executor for dispatching them.
+
+#### Defining Tools
+
+```ruby
+tool = RubyPi::Tool.define(
+  name: :create_post,
+  description: "Create a social media post",
+  category: :content,
+  parameters: RubyPi::Schema.object(
+    content: RubyPi::Schema.string("Post body", required: true),
+    tags: RubyPi::Schema.array(
+      description: "Tags",
+      items: RubyPi::Schema.string("A tag")
+    )
+  )
+) do |args|
+  { post_id: SecureRandom.uuid, status: "published" }
+end
+```
+
+#### Schema DSL
+
+Build JSON Schema hashes with a fluent Ruby API:
+
+```ruby
+RubyPi::Schema.string("A label", required: true, enum: ["a", "b"])
+RubyPi::Schema.integer("Count", minimum: 0, maximum: 100)
+RubyPi::Schema.number("Price", minimum: 0.0)
+RubyPi::Schema.boolean("Active")
+RubyPi::Schema.array(description: "Items", items: RubyPi::Schema.string)
+RubyPi::Schema.object(name: RubyPi::Schema.string("Name", required: true))
+```
+
+#### Registry
+
+```ruby
+registry = RubyPi::Tools::Registry.new
+registry.register(tool)
+
+registry.find(:create_post)          # => Definition or nil
+registry.registered?(:create_post)   # => true
+registry.names                       # => [:create_post]
+registry.size                        # => 1
+registry.by_category(:content)       # => [Definition, ...]
+registry.subset([:create_post])      # => new Registry with just that tool
+registry.all                         # => [Definition, ...]
+```
+
+#### Executor
+
+Run tool calls in parallel or sequentially with automatic error handling and timeouts:
+
+```ruby
+executor = RubyPi::Tools::Executor.new(registry, mode: :parallel, timeout: 30)
+
+results = executor.execute([
+  { name: "create_post", arguments: { content: "Hello" } },
+  { name: "get_analytics", arguments: { period: "7d" } }
+])
+
+results.each do |r|
+  if r.success?
+    puts "#{r.name}: #{r.value}"
+  else
+    puts "#{r.name} failed: #{r.error} (#{r.duration_ms}ms)"
+  end
+end
+```
+
+| `Result` attribute | Description |
+|---|---|
+| `name` | Tool name |
+| `success?` | Whether the call succeeded |
+| `value` | Return value (on success) |
+| `error` | Error message (on failure) |
+| `duration_ms` | Execution time in milliseconds |
+
+---
+
+### RubyPi::Agent
+
+The Agent implements a **think-act-observe** loop: send messages to the LLM, execute any tool calls it requests, feed results back, and repeat until the model produces a final text response or hits the iteration limit.
+
+#### Creating an Agent
+
+```ruby
+agent = RubyPi::Agent.new(
+  model: model,                        # required: an LLM provider instance
+  tools: registry,                     # optional: a Tools::Registry
+  stream: false,                       # optional: enable streaming
+  max_iterations: 10,                  # optional: loop safety limit
+  context_compaction: compaction,      # optional: Context::Compaction instance
+  context_transform: transform,        # optional: Context::Transform instance
+  extensions: [my_extension]           # optional: Extension instances
+)
+```
+
+#### Running the Agent
+
+```ruby
+# Single run
+result = agent.run("What is the weather in Tokyo?")
+result.output            # => "The weather in Tokyo is..."
+result.messages          # => full conversation history
+result.tool_calls_made   # => [{ name: "get_weather", ... }, ...]
+result.iterations        # => 2
+result.stop_reason       # => :complete or :max_iterations
+
+# Continue the conversation
+result2 = agent.continue("And in London?")
+```
+
+#### Event Subscriptions
+
+Subscribe to lifecycle events for logging, monitoring, or custom behavior:
+
+```ruby
+agent.on(:turn_start)          { |e| puts "Turn #{e[:iteration]} starting" }
+agent.on(:turn_end)            { |e| puts "Turn #{e[:iteration]} ended" }
+agent.on(:text_delta)          { |e| print e[:data] }
+agent.on(:tool_execution_start){ |e| puts "Calling #{e[:tool_name]}" }
+agent.on(:tool_execution_end)  { |e| puts "#{e[:name]} => #{e[:result]}" }
+agent.on(:before_tool_call)    { |e| puts "About to call #{e[:tool_name]}" }
+agent.on(:after_tool_call)     { |e| puts "Finished #{e[:tool_name]}" }
+agent.on(:agent_end)           { |e| puts "Agent finished" }
+agent.on(:error)               { |e| warn "Error: #{e[:error].message}" }
+```
+
+---
+
+### RubyPi::Context
+
+Utilities for managing conversation context, especially in long-running or multi-turn agents.
+
+#### Compaction
+
+Prevent unbounded context growth by compacting older messages:
+
+```ruby
+compaction = RubyPi::Context::Compaction.new(
+  max_tokens: 4000,         # trigger compaction above this threshold
+  strategy: :truncate       # :truncate removes oldest messages
+)
+
+agent = RubyPi::Agent.new(model: model, context_compaction: compaction)
+```
+
+#### Transform
+
+Apply arbitrary transformations to the message list before each LLM call:
+
+```ruby
+transform = RubyPi::Context::Transform.new do |messages|
+  # Inject a system prompt at the beginning
+  [{ role: "system", content: "You are a helpful Ruby assistant." }] + messages
+end
+
+agent = RubyPi::Agent.new(model: model, context_transform: transform)
+```
+
+---
+
+### RubyPi::Extensions
+
+Extensions hook into the agent's event system to add cross-cutting behavior (logging, metrics, guardrails) without modifying the core loop.
+
+#### Defining an Extension
+
+```ruby
+class MetricsExtension < RubyPi::Extensions::Base
+  on_event :turn_start do |event|
+    @turn_timer = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
+
+  on_event :turn_end do |event|
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @turn_timer
+    puts "Turn #{event[:iteration]} took #{elapsed.round(2)}s"
+  end
+
+  on_event :agent_end do |event|
+    puts "Agent completed in #{event[:iterations]} iterations"
+  end
+end
+```
+
+#### Registering Extensions
+
+```ruby
+agent = RubyPi::Agent.new(
+  model: model,
+  extensions: [MetricsExtension.new, AnotherExtension.new]
+)
+```
+
+Extensions receive the same event payloads as `agent.on(...)` callbacks. Use them when you want reusable, self-contained behavior modules.
+
+---
+
+## Configuration
+
+All settings are managed through a global configuration block:
+
+```ruby
+RubyPi.configure do |config|
+  # API keys
+  config.gemini_api_key    = ENV["GEMINI_API_KEY"]
+  config.anthropic_api_key = ENV["ANTHROPIC_API_KEY"]
+  config.openai_api_key    = ENV["OPENAI_API_KEY"]
+
+  # Retry behavior
+  config.max_retries      = 3      # retries for transient errors
+  config.retry_base_delay = 1.0    # base delay (seconds) for exponential backoff
+  config.retry_max_delay  = 30.0   # cap on retry delay
+
+  # Timeouts
+  config.request_timeout = 120     # HTTP request timeout (seconds)
+  config.open_timeout    = 10      # connection open timeout (seconds)
+
+  # Default models (used when you omit the model name)
+  config.default_gemini_model    = "gemini-2.0-flash"
+  config.default_anthropic_model = "claude-sonnet-4-20250514"
+  config.default_openai_model    = "gpt-4o"
+
+  # Logging
+  config.logger = Logger.new($stdout)
+end
+```
+
+You can also reset configuration to defaults:
+
+```ruby
+RubyPi.reset_configuration!
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Write tests for your changes
+4. Ensure all tests pass: `bundle exec rspec`
+5. Commit your changes (`git commit -am 'Add my feature'`)
+6. Push to the branch (`git push origin feature/my-feature`)
+7. Open a Pull Request
+
+Please follow the existing code style and include tests for any new functionality.
+
+---
+
+## License
+
+Released under the [MIT License](LICENSE).

data/lib/ruby_pi/agent/core.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/agent/core.rb
+#
+# RubyPi::Agent::Core — The main Agent class and public entry point.
+#
+# Core orchestrates the full agent lifecycle: it manages state, includes the
+# EventEmitter for event subscriptions, delegates to Loop for the think-act-observe
+# cycle, and supports extensions via the `use` method. This is the class users
+# instantiate and interact with when building agentic workflows.
+#
+# Usage:
+#   agent = RubyPi::Agent::Core.new(
+#     system_prompt: "You are a helpful assistant.",
+#     model: RubyPi::LLM.model(:gemini, "gemini-2.0-flash"),
+#     tools: registry
+#   )
+#   agent.on(:text_delta) { |d| print d[:content] }
+#   result = agent.run("Tell me about Ruby")
+
+module RubyPi
+  module Agent
+    # The main agent class. Wraps State, Loop, and EventEmitter into a cohesive
+    # interface for running agentic LLM interactions with tool use, streaming,
+    # and lifecycle hooks.
+    #
+    # @example Full lifecycle
+    #   agent = RubyPi::Agent::Core.new(
+    #     system_prompt: "You are Olli, an AI assistant.",
+    #     model: RubyPi::LLM.model(:gemini, "gemini-2.0-flash"),
+    #     tools: registry,
+    #     max_iterations: 10,
+    #     before_tool_call: ->(tc) { puts "Calling #{tc.name}" },
+    #     after_tool_call: ->(tc, r) { puts "Done: #{r.success?}" }
+    #   )
+    #
+    #   agent.on(:text_delta) { |d| stream.write(d[:content]) }
+    #   agent.on(:agent_end) { |_| stream.close }
+    #
+    #   result = agent.run("Create a LinkedIn post")
+    #   result = agent.continue("Make it shorter")
+    class Core
+      include EventEmitter
+
+      # @return [RubyPi::Agent::State] the agent's mutable state
+      attr_reader :state
+
+      # Creates a new Agent instance.
+      #
+      # @param system_prompt [String] the system-level instruction prompt
+      # @param model [RubyPi::LLM::BaseProvider] the LLM provider instance
+      # @param tools [RubyPi::Tools::Registry, nil] tool registry
+      # @param max_iterations [Integer] max think-act-observe cycles (default: 10)
+      # @param transform_context [Proc, nil] context transform hook
+      # @param before_tool_call [Proc, nil] pre-tool-execution hook
+      # @param after_tool_call [Proc, nil] post-tool-execution hook
+      # @param compaction [RubyPi::Context::Compaction, nil] compaction strategy
+      # @param user_data [Hash] arbitrary data bag for transforms/extensions
+      def initialize(
+        system_prompt:,
+        model:,
+        tools: nil,
+        max_iterations: 10,
+        transform_context: nil,
+        before_tool_call: nil,
+        after_tool_call: nil,
+        compaction: nil,
+        user_data: {}
+      )
+        @state = State.new(
+          system_prompt: system_prompt,
+          model: model,
+          tools: tools,
+          max_iterations: max_iterations,
+          transform_context: transform_context,
+          before_tool_call: before_tool_call,
+          after_tool_call: after_tool_call,
+          user_data: user_data
+        )
+        @compaction = compaction
+        @extensions = []
+      end
+
+      # Runs the agent with an initial user prompt. Adds the prompt to the
+      # conversation history, executes the think-act-observe loop, emits
+      # :agent_end when done, and returns the result.
+      #
+      # @param prompt [String] the user's initial message
+      # @return [RubyPi::Agent::Result] the outcome of the agent run
+      def run(prompt)
+        @state.add_message(role: :user, content: prompt)
+        execute_loop
+      end
+
+      # Continues the conversation with a follow-up user message. Preserves
+      # the existing conversation history and appends the new prompt before
+      # resuming the loop.
+      #
+      # @param prompt [String] the follow-up user message
+      # @return [RubyPi::Agent::Result] the outcome of the continued run
+      def continue(prompt)
+        # Reset the iteration counter for the new run while keeping history
+        @state.instance_variable_set(:@iteration, 0)
+        @state.add_message(role: :user, content: prompt)
+        execute_loop
+      end
+
+      # Registers an extension with this agent. The extension's hooks are
+      # automatically subscribed to the agent's events.
+      #
+      # @param extension_class [Class] a subclass of RubyPi::Extensions::Base
+      # @return [void]
+      # @raise [ArgumentError] if the argument is not a valid extension class
+      def use(extension_class)
+        unless extension_class.respond_to?(:hooks)
+          raise ArgumentError,
+                "Expected an extension class with a .hooks method, got #{extension_class.inspect}"
+        end
+
+        # Subscribe each hook to the corresponding event
+        extension_class.hooks.each do |event, handlers|
+          handlers.each do |handler|
+            on(event) do |data|
+              handler.call(data, self)
+            end
+          end
+        end
+
+        @extensions << extension_class
+      end
+
+      private
+
+      # Creates a Loop instance and executes it, emitting :agent_end when
+      # the loop completes.
+      #
+      # @return [RubyPi::Agent::Result]
+      def execute_loop
+        loop_runner = Loop.new(
+          state: @state,
+          emitter: self,
+          compaction: @compaction
+        )
+
+        result = loop_runner.run
+
+        emit(:agent_end, result: result, success: result.success?)
+
+        result
+      end
+    end
+  end
+
+  # Module-level convenience method for creating Agent instances without
+  # referencing Agent::Core directly. Allows `RubyPi::Agent.new(...)`.
+  module Agent
+    class << self
+      # Creates a new Agent::Core instance. This is the recommended entry
+      # point for building agents.
+      #
+      # @param args [Hash] constructor arguments forwarded to Agent::Core.new
+      # @return [RubyPi::Agent::Core] a new agent instance
+      #
+      # @example
+      #   agent = RubyPi::Agent.new(
+      #     system_prompt: "You are helpful.",
+      #     model: model,
+      #     tools: registry
+      #   )
+      def new(**args)
+        Core.new(**args)
+      end
+    end
+  end
+end