ruby-pi 0.1.0

data/lib/ruby_pi/tools/result.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/tools/result.rb
+#
+# RubyPi::Tools::Result — Encapsulates the outcome of a tool execution.
+#
+# Every tool invocation (whether successful or failed) produces a Result object.
+# This provides a uniform interface for inspecting execution outcomes, including
+# the return value, any error messages, and timing information.
+#
+# Usage:
+#   result = RubyPi::Tools::Result.new(
+#     name: "create_post",
+#     success: true,
+#     value: { post_id: "123" },
+#     duration_ms: 42.5
+#   )
+#
+#   result.success?    # => true
+#   result.value       # => { post_id: "123" }
+#   result.error       # => nil
+#   result.duration_ms # => 42.5
+
+module RubyPi
+  module Tools
+    class Result
+      # @return [String] The name of the tool that was executed.
+      attr_reader :name
+
+      # @return [Object, nil] The return value of the tool (nil if execution failed).
+      attr_reader :value
+
+      # @return [String, nil] The error message if execution failed (nil if successful).
+      attr_reader :error
+
+      # @return [Float] The execution time in milliseconds.
+      attr_reader :duration_ms
+
+      # Creates a new Result instance.
+      #
+      # @param name [String, Symbol] The name of the tool that produced this result.
+      # @param success [Boolean] Whether the tool executed successfully.
+      # @param value [Object, nil] The return value from the tool (on success).
+      # @param error [String, nil] The error message (on failure).
+      # @param duration_ms [Float] How long the tool took to execute, in milliseconds.
+      def initialize(name:, success:, value: nil, error: nil, duration_ms: 0.0)
+        @name = name.to_s
+        @success = success
+        @value = value
+        @error = error
+        @duration_ms = duration_ms.to_f
+      end
+
+      # Returns whether the tool execution was successful.
+      #
+      # @return [Boolean] true if the tool completed without error.
+      def success?
+        @success
+      end
+
+      # Returns a hash representation of the result, useful for serialization.
+      #
+      # @return [Hash] A hash containing all result attributes.
+      def to_h
+        {
+          name: @name,
+          success: @success,
+          value: @value,
+          error: @error,
+          duration_ms: @duration_ms
+        }
+      end
+
+      # Provides a human-readable string representation of the result.
+      #
+      # @return [String] A summary string for debugging/logging.
+      def inspect
+        status = @success ? "success" : "failure"
+        "#<RubyPi::Tools::Result name=#{@name.inspect} status=#{status} duration_ms=#{@duration_ms}>"
+      end
+    end
+  end
+end

data/lib/ruby_pi/tools/schema.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/tools/schema.rb
+#
+# RubyPi::Schema — A DSL for building JSON Schema Draft 7 hashes.
+#
+# This module provides a fluent, Ruby-idiomatic interface for constructing
+# JSON Schema objects used to describe tool parameters. Each builder method
+# (`.string`, `.integer`, `.number`, `.boolean`, `.array`, `.object`) returns
+# a plain Ruby hash that conforms to JSON Schema Draft 7.
+#
+# The `required: true` option on individual property builders is a metadata
+# flag consumed by `.object` to populate the top-level "required" array.
+# It is stripped from the property's own schema hash before inclusion.
+#
+# Usage:
+#   schema = RubyPi::Schema.object(
+#     name: RubyPi::Schema.string("User's name", required: true),
+#     age:  RubyPi::Schema.integer("User's age", minimum: 0)
+#   )
+#
+# Produces:
+#   {
+#     type: "object",
+#     properties: {
+#       name: { type: "string", description: "User's name" },
+#       age:  { type: "integer", description: "User's age", minimum: 0 }
+#     },
+#     required: ["name"]
+#   }
+
+module RubyPi
+  module Schema
+    class << self
+      # Builds a JSON Schema for a string property.
+      #
+      # @param description [String] Human-readable description of the property.
+      # @param required [Boolean] Whether this property is required (used by `.object`).
+      # @param enum [Array<String>, nil] Allowed values for the string.
+      # @param format [String, nil] JSON Schema format hint (e.g. "date-time", "email").
+      # @param min_length [Integer, nil] Minimum string length.
+      # @param max_length [Integer, nil] Maximum string length.
+      # @param pattern [String, nil] Regex pattern the string must match.
+      # @return [Hash] A JSON Schema hash for a string type.
+      def string(description = nil, required: false, enum: nil, format: nil,
+                 min_length: nil, max_length: nil, pattern: nil)
+        schema = { type: "string" }
+        schema[:description] = description if description
+        schema[:enum] = enum if enum
+        schema[:format] = format if format
+        schema[:minLength] = min_length if min_length
+        schema[:maxLength] = max_length if max_length
+        schema[:pattern] = pattern if pattern
+        schema[:_required] = true if required
+        schema
+      end
+
+      # Builds a JSON Schema for an integer property.
+      #
+      # @param description [String] Human-readable description.
+      # @param required [Boolean] Whether this property is required.
+      # @param minimum [Integer, nil] Minimum value (inclusive).
+      # @param maximum [Integer, nil] Maximum value (inclusive).
+      # @param enum [Array<Integer>, nil] Allowed integer values.
+      # @return [Hash] A JSON Schema hash for an integer type.
+      def integer(description = nil, required: false, minimum: nil, maximum: nil, enum: nil)
+        schema = { type: "integer" }
+        schema[:description] = description if description
+        schema[:minimum] = minimum if minimum
+        schema[:maximum] = maximum if maximum
+        schema[:enum] = enum if enum
+        schema[:_required] = true if required
+        schema
+      end
+
+      # Builds a JSON Schema for a number (float/decimal) property.
+      #
+      # @param description [String] Human-readable description.
+      # @param required [Boolean] Whether this property is required.
+      # @param minimum [Numeric, nil] Minimum value (inclusive).
+      # @param maximum [Numeric, nil] Maximum value (inclusive).
+      # @param enum [Array<Numeric>, nil] Allowed numeric values.
+      # @return [Hash] A JSON Schema hash for a number type.
+      def number(description = nil, required: false, minimum: nil, maximum: nil, enum: nil)
+        schema = { type: "number" }
+        schema[:description] = description if description
+        schema[:minimum] = minimum if minimum
+        schema[:maximum] = maximum if maximum
+        schema[:enum] = enum if enum
+        schema[:_required] = true if required
+        schema
+      end
+
+      # Builds a JSON Schema for a boolean property.
+      #
+      # @param description [String] Human-readable description.
+      # @param required [Boolean] Whether this property is required.
+      # @return [Hash] A JSON Schema hash for a boolean type.
+      def boolean(description = nil, required: false)
+        schema = { type: "boolean" }
+        schema[:description] = description if description
+        schema[:_required] = true if required
+        schema
+      end
+
+      # Builds a JSON Schema for an array property.
+      #
+      # @param description [String, nil] Human-readable description.
+      # @param required [Boolean] Whether this property is required.
+      # @param items [Hash, nil] JSON Schema hash describing each array element.
+      # @param min_items [Integer, nil] Minimum number of items.
+      # @param max_items [Integer, nil] Maximum number of items.
+      # @param unique_items [Boolean, nil] Whether items must be unique.
+      # @return [Hash] A JSON Schema hash for an array type.
+      def array(description: nil, required: false, items: nil,
+                min_items: nil, max_items: nil, unique_items: nil)
+        schema = { type: "array" }
+        schema[:description] = description if description
+        # Strip internal _required flag from item schemas if present
+        schema[:items] = sanitize(items) if items
+        schema[:minItems] = min_items if min_items
+        schema[:maxItems] = max_items if max_items
+        schema[:uniqueItems] = unique_items unless unique_items.nil?
+        schema[:_required] = true if required
+        schema
+      end
+
+      # Builds a JSON Schema for an object with named properties.
+      #
+      # Each keyword argument key is a property name, and its value is a schema
+      # hash produced by one of the other builder methods (`.string`, `.integer`,
+      # etc.). Properties marked with `required: true` are collected into the
+      # top-level "required" array.
+      #
+      # @param properties [Hash{Symbol => Hash}] Property name to schema mappings.
+      # @return [Hash] A JSON Schema hash for an object type.
+      def object(**properties)
+        required_fields = []
+        cleaned_properties = {}
+
+        properties.each do |name, prop_schema|
+          # Extract and consume the internal _required flag
+          if prop_schema[:_required]
+            required_fields << name.to_s
+          end
+          # Store a sanitized copy (without _required) under the property name
+          cleaned_properties[name] = sanitize(prop_schema)
+        end
+
+        schema = {
+          type: "object",
+          properties: cleaned_properties
+        }
+        schema[:required] = required_fields unless required_fields.empty?
+        schema
+      end
+
+      private
+
+      # Removes internal metadata keys (prefixed with underscore) from a schema hash.
+      # Returns a new hash without mutating the original.
+      #
+      # @param schema [Hash] A schema hash potentially containing internal keys.
+      # @return [Hash] A clean copy suitable for JSON Schema output.
+      def sanitize(schema)
+        schema.reject { |key, _| key.to_s.start_with?("_") }
+      end
+    end
+  end
+end

data/lib/ruby_pi/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi/version.rb
+#
+# Defines the current version of the RubyPi gem. This constant is referenced
+# by the gemspec and can be queried at runtime via RubyPi::VERSION.
+
+module RubyPi
+  # The current version of the RubyPi gem, following Semantic Versioning.
+  VERSION = "0.1.0"
+end

data/lib/ruby_pi.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+# lib/ruby_pi.rb
+#
+# Main entry point for the RubyPi gem. Requiring this file loads the complete
+# public API, including configuration, error classes, all LLM provider
+# implementations, tool definitions, agent core, context management, and
+# extensions. This file also exposes module-level convenience methods for
+# configuration and model construction.
+
+require "json"
+require "faraday"
+require "faraday/retry"
+require "faraday/net_http"
+require "concurrent-ruby"
+
+require_relative "ruby_pi/version"
+require_relative "ruby_pi/configuration"
+require_relative "ruby_pi/errors"
+require_relative "ruby_pi/llm/response"
+require_relative "ruby_pi/llm/tool_call"
+require_relative "ruby_pi/llm/stream_event"
+require_relative "ruby_pi/llm/model"
+require_relative "ruby_pi/llm/base_provider"
+require_relative "ruby_pi/llm/gemini"
+require_relative "ruby_pi/llm/anthropic"
+require_relative "ruby_pi/llm/openai"
+require_relative "ruby_pi/llm/fallback"
+
+# Tools
+require_relative "ruby_pi/tools/schema"
+require_relative "ruby_pi/tools/definition"
+require_relative "ruby_pi/tools/registry"
+require_relative "ruby_pi/tools/result"
+require_relative "ruby_pi/tools/executor"
+
+# Agent
+require_relative "ruby_pi/agent/events"
+require_relative "ruby_pi/agent/state"
+require_relative "ruby_pi/agent/result"
+require_relative "ruby_pi/agent/loop"
+require_relative "ruby_pi/agent/core"
+
+# Context
+require_relative "ruby_pi/context/compaction"
+require_relative "ruby_pi/context/transform"
+
+# Extensions
+require_relative "ruby_pi/extensions/base"
+
+# Top-level namespace for the RubyPi framework.
+module RubyPi
+  class << self
+    # Returns the global configuration object.
+    #
+    # @return [RubyPi::Configuration] the current global configuration
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Yields the global configuration object to a block for mutation.
+    #
+    # @yield [configuration] the global configuration instance
+    # @return [RubyPi::Configuration] the updated configuration
+    #
+    # @example Configure API keys
+    #   RubyPi.configure do |config|
+    #     config.openai_api_key = ENV["OPENAI_API_KEY"]
+    #     config.max_retries = 5
+    #   end
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+
+    # Resets the global configuration to default values.
+    #
+    # @return [void]
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+
+  # Namespace for large language model providers and related abstractions.
+  module LLM
+    class << self
+      # Factory method for constructing a provider instance from a provider name
+      # and model identifier.
+      #
+      # @param provider [Symbol, String] provider identifier (:gemini, :anthropic, :openai)
+      # @param name [String] the model name to use with the provider
+      # @param options [Hash] provider-specific initialization options
+      # @return [RubyPi::LLM::BaseProvider] configured provider instance
+      # @raise [ArgumentError] if the provider is unsupported
+      #
+      # @example Build a Gemini model
+      #   model = RubyPi::LLM.model(:gemini, "gemini-2.0-flash")
+      def model(provider, name, **options)
+        case provider.to_sym
+        when :gemini
+          Gemini.new(model: name, **options)
+        when :anthropic
+          Anthropic.new(model: name, **options)
+        when :openai
+          OpenAI.new(model: name, **options)
+        else
+          raise ArgumentError, "Unsupported provider: #{provider}"
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,192 @@
+--- !ruby/object:Gem::Specification
+name: ruby-pi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- RubyPi Contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  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: faraday-retry
+  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: faraday-net_http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: RubyPi provides idiomatic Ruby patterns for building AI agents. It offers
+  a unified interface to multiple LLM providers (Gemini, Anthropic, OpenAI) with streaming
+  support, tool calling, automatic retries, and fallback strategies.
+email:
+- ruby-pi@example.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/ruby_pi.rb
+- lib/ruby_pi/agent/core.rb
+- lib/ruby_pi/agent/events.rb
+- lib/ruby_pi/agent/loop.rb
+- lib/ruby_pi/agent/result.rb
+- lib/ruby_pi/agent/state.rb
+- lib/ruby_pi/configuration.rb
+- lib/ruby_pi/context/compaction.rb
+- lib/ruby_pi/context/transform.rb
+- lib/ruby_pi/errors.rb
+- lib/ruby_pi/extensions/base.rb
+- lib/ruby_pi/llm/anthropic.rb
+- lib/ruby_pi/llm/base_provider.rb
+- lib/ruby_pi/llm/fallback.rb
+- lib/ruby_pi/llm/gemini.rb
+- lib/ruby_pi/llm/model.rb
+- lib/ruby_pi/llm/openai.rb
+- lib/ruby_pi/llm/response.rb
+- lib/ruby_pi/llm/stream_event.rb
+- lib/ruby_pi/llm/tool_call.rb
+- lib/ruby_pi/tools/definition.rb
+- lib/ruby_pi/tools/executor.rb
+- lib/ruby_pi/tools/registry.rb
+- lib/ruby_pi/tools/result.rb
+- lib/ruby_pi/tools/schema.rb
+- lib/ruby_pi/version.rb
+homepage: https://github.com/ejwhite7/ruby-pi
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ejwhite7/ruby-pi
+  source_code_uri: https://github.com/ejwhite7/ruby-pi
+  changelog_uri: https://github.com/ejwhite7/ruby-pi/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: A Ruby agent harness inspired by Pi — minimal, composable, production-ready.
+test_files: []