ask-core 0.1.0

data/lib/ask/result.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Ask
+  # Standardized return value from tool execution. Wraps the outcome of a tool
+  # call with status, content, and optional error metadata.
+  #
+  #   Ask::Result.success("Data processed")
+  #   Ask::Result.failure("API returned 500")
+  #
+  class Result
+    STATUSES = %i[success error aborted blocked short_circuited].freeze
+
+    class << self
+      # @!group Factory Methods
+
+      # Create a successful result.
+      # @param content [Object, nil] the result content
+      # @param metadata [Hash] additional metadata
+      # @return [Ask::Result]
+      def success(content = nil, metadata: {})
+        new(content: content, status: :success, metadata: metadata)
+      end
+
+      # Create a failure result.
+      # @param message [String] the error description
+      # @param error [Object, nil] the underlying error object
+      # @param metadata [Hash] additional metadata
+      # @return [Ask::Result]
+      def failure(message, error: nil, metadata: {})
+        new(content: message, status: :error, error: error, metadata: metadata)
+      end
+
+      # Create an aborted result (cancelled by sibling failure).
+      # @param reason [String] the abort reason
+      # @return [Ask::Result]
+      def aborted(reason = "Aborted")
+        new(content: reason, status: :aborted)
+      end
+
+      # Create a blocked result (prevented by a hook or guard).
+      # @param reason [String] the block reason
+      # @return [Ask::Result]
+      def blocked(reason)
+        new(content: reason, status: :blocked)
+      end
+      # @!endgroup
+    end
+
+    # @return [Object, nil] the result content
+    attr_reader :content
+
+    # @return [Symbol] the status (:success, :error, :aborted, :blocked, :short_circuited)
+    attr_reader :status
+
+    # @return [Object, nil] the underlying error, if any
+    attr_reader :error
+
+    # @return [Hash] additional metadata
+    attr_reader :metadata
+
+    def initialize(content: nil, status: :success, error: nil, metadata: {})
+      @content = content
+      @status = validate_status!(status)
+      @error = error
+      @metadata = metadata.dup.freeze
+      freeze
+    end
+
+    # @return [Boolean] true if status is :success
+    def success? = @status == :success
+
+    # @return [Boolean] true if status is :error
+    def error? = @status == :error
+
+    # @return [Boolean] true if status is :aborted
+    def aborted? = @status == :aborted
+
+    # @return [Boolean] true if status is :blocked
+    def blocked? = @status == :blocked
+
+    # @return [String] the content as a string
+    def to_s
+      @content.to_s
+    end
+
+    # @return [Hash] serialized representation
+    def to_h
+      {
+        content: @content,
+        status: @status,
+        error: @error,
+        metadata: @metadata
+      }.compact
+    end
+
+    # @return [String] human-readable representation
+    def inspect
+      "#<Ask::Result status=#{@status.inspect} content=#{@content.inspect}>"
+    end
+
+    private
+
+    def validate_status!(status)
+      return status if STATUSES.include?(status)
+
+      raise ArgumentError, "Invalid status #{status.inspect}. Valid: #{STATUSES.join(', ')}"
+    end
+  end
+end

data/lib/ask/stream.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Ask
+  # A single chunk of streaming output from an LLM provider.
+  # Yielded by {Ask::Stream} during a streaming response.
+  class Chunk
+    # @return [String, nil] text content of this chunk
+    attr_reader :content
+
+    # @return [Array<Hash>, nil] tool call invocations in this chunk
+    attr_reader :tool_calls
+
+    # @return [String, nil] reason the stream finished ("stop", "length", "tool_calls")
+    attr_reader :finish_reason
+
+    # @return [Hash, nil] token usage metadata
+    attr_reader :usage
+
+    # @return [Hash, nil] raw response data from the provider
+    attr_reader :raw
+
+    def initialize(content: nil, tool_calls: nil, finish_reason: nil, usage: nil, raw: nil)
+      @content = content
+      @tool_calls = tool_calls
+      @finish_reason = finish_reason
+      @usage = usage
+      @raw = raw
+    end
+
+    # @return [Boolean] true if this is the final chunk in a stream
+    def finished? = !@finish_reason.nil?
+
+    # @return [Boolean] true if this chunk contains tool calls
+    def tool_call? = @tool_calls&.any? == true
+
+    # @return [String] text content as a plain string
+    def to_s
+      @content.to_s
+    end
+
+    # @return [String] human-readable representation
+    def inspect
+      "#<Ask::Chunk content=#{@content.inspect} finish_reason=#{@finish_reason.inspect}>"
+    end
+  end
+
+  # Streaming response from an LLM provider. Wraps an enumerable of {Chunk}s and
+  # provides accumulation into a single string or message.
+  #
+  #   stream = Ask::Stream.new { |chunk| puts chunk.content }
+  #   stream.each { |chunk| ... }
+  #   stream.accumulated_text  # => "full response text"
+  #
+  class Stream
+    include Enumerable
+
+    # @param chunk_handler [Proc, nil] optional callback invoked for each chunk as it arrives
+    def initialize(&chunk_handler)
+      @chunks = []
+      @chunk_handler = chunk_handler
+      @accumulated = +""
+      @finished = false
+    end
+
+    # Iterate over all accumulated chunks.
+    # @yield [Chunk] each chunk
+    # @return [Enumerator] if no block given
+    def each(&block)
+      return enum_for(:each) unless block
+
+      @chunks.each(&block)
+      self
+    end
+
+    # Add a chunk to the stream.
+    # @param chunk [Chunk, String] chunk to add (strings are wrapped in Chunk)
+    # @return [Chunk] the added chunk
+    def add(chunk)
+      chunk = Chunk.new(content: chunk) if chunk.is_a?(String)
+
+      @chunks << chunk
+      @accumulated << chunk.content.to_s if chunk.content
+      @chunk_handler&.call(chunk)
+      chunk
+    end
+
+    # Mark the stream as finished.
+    def finish!
+      @finished = true
+    end
+
+    # @return [Boolean] true if the stream has been finished
+    def finished? = @finished
+
+    # @return [String] full accumulated text from all chunks
+    def accumulated_text
+      @accumulated.dup
+    end
+    alias to_s accumulated_text
+
+    # @return [Hash] accumulated usage across all chunks, merged by key
+    def accumulated_usage
+      @chunks
+        .map(&:usage)
+        .compact
+        .reduce({}) do |acc, u|
+          acc.merge(u) { |_key, old, new| old + new }
+        end
+    end
+
+    # @return [Array<Chunk>] a copy of all accumulated chunks
+    def chunks = @chunks.dup
+
+    # @return [Integer] number of chunks accumulated
+    def length = @chunks.length
+
+    # @return [String] human-readable representation
+    def inspect
+      finished = @finished ? "finished" : "streaming"
+      "#<Ask::Stream #{finished} chunks=#{@chunks.length}>"
+    end
+  end
+end

data/lib/ask/tool_def.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Ask
+  # Immutable value object representing a tool (function) definition that can be
+  # passed to LLM providers. Describes a callable tool's name, description, and
+  # parameter schema.
+  #
+  #   ToolDef.new(
+  #     name: "get_weather",
+  #     description: "Get current weather for a location",
+  #     parameters: {
+  #       type: "object",
+  #       properties: { location: { type: "string" } },
+  #       required: ["location"]
+  #     }
+  #   )
+  #
+  class ToolDef
+    class << self
+      # Build a ToolDef from an object that responds to #name, #description,
+      # #params_schema, and #provider_params.
+      # @param tool [#name, #description, #params_schema] a tool-like object
+      # @return [Ask::ToolDef]
+      def from_tool(tool)
+        schema = tool.params_schema
+        new(
+          name: tool.name,
+          description: tool.description,
+          parameters: schema,
+          provider_params: tool.provider_params
+        )
+      end
+    end
+
+    # @return [String] tool name (must match /\\A[a-zA-Z_][a-zA-Z0-9_-]*\\z/)
+    attr_reader :name
+
+    # @return [String] description of what the tool does
+    attr_reader :description
+
+    # @return [Hash, nil] JSON Schema parameter definition
+    attr_reader :parameters
+
+    # @return [Hash] provider-specific parameters (e.g. concurrency limits)
+    attr_reader :provider_params
+
+    def initialize(name:, description: "", parameters: nil, provider_params: {})
+      @name = validate_name!(name)
+      @description = description.to_s
+      @parameters = parameters
+      @provider_params = provider_params.dup.freeze
+      freeze
+    end
+
+    # Convert to a provider-specific format.
+    # @yield [self] yields the tool def for custom formatting
+    # @return [Hash] provider-ready parameters
+    def to_provider_format(&block)
+      return @parameters || default_parameters unless block
+
+      block.call(self)
+    end
+
+    # Two ToolDefs are equal if they have the same name.
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(ToolDef)
+
+      name == other.name
+    end
+    alias eql? ==
+
+    def hash
+      name.hash
+    end
+
+    # @return [Hash] serialized representation
+    def to_h
+      {
+        name: @name,
+        description: @description,
+        parameters: @parameters,
+        provider_params: @provider_params
+      }
+    end
+
+    # @return [String]
+    def inspect
+      "#<Ask::ToolDef name=#{@name.inspect}>"
+    end
+
+    private
+
+    def validate_name!(name)
+      raise InvalidToolDefinition, "Tool name is required" if name.nil? || name.to_s.strip.empty?
+
+      normalized = name.to_s.strip
+      unless normalized.match?(/\A[a-zA-Z_][a-zA-Z0-9_-]*\z/)
+        raise InvalidToolDefinition,
+              "Tool name must start with a letter or underscore and contain only " \
+              "letters, numbers, hyphens, and underscores: #{normalized.inspect}"
+      end
+      normalized
+    end
+
+    def default_parameters
+      {
+        type: "object",
+        properties: {},
+        required: []
+      }
+    end
+  end
+end

data/lib/ask/version.rb

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

data/lib/ask.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "ask/version"
+
+# Main namespace for the ask-rb ecosystem.
+#
+# Ask::Provider is the abstract base class for LLM providers.
+# Ask::Conversation is a message container with role normalization.
+# Ask::Stream provides streaming primitives for incremental responses.
+# Ask::ModelCatalog resolves model names to provider metadata.
+# Ask::ToolDef is an immutable tool definition struct.
+# Ask::Result standardizes tool execution return values.
+# Ask::Error provides structured error types.
+module Ask
+end
+
+require_relative "ask/errors"
+require_relative "ask/tool_def"
+require_relative "ask/result"
+require_relative "ask/stream"
+require_relative "ask/conversation"
+require_relative "ask/provider"
+require_relative "ask/models"

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: ask-core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaka Ruto
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !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: Provides Ask::Provider (abstract interface), Ask::Conversation, Ask::Stream,
+  Ask::ModelCatalog, Ask::ToolDef, Ask::Result, and structured error types. Zero runtime
+  dependencies.
+email:
+- kaka@myrrlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ask.rb
+- lib/ask/conversation.rb
+- lib/ask/errors.rb
+- lib/ask/models.rb
+- lib/ask/provider.rb
+- lib/ask/result.rb
+- lib/ask/stream.rb
+- lib/ask/tool_def.rb
+- lib/ask/version.rb
+homepage: https://github.com/ask-rb/ask-core
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Foundation gem for the ask-rb ecosystem
+test_files: []