ask-core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9ab6b3602459d44db528b10dc551037f0c7da6d54d4876aeda87fc572ddbca91
+  data.tar.gz: 5500b00c8fc487780f7b96a5f574fde70e6c9af20ff9ced561ef18bf7a46316f
+SHA512:
+  metadata.gz: ab1f35dfe6939eca8df702e84a0321c3bbc88c3ce6415509f1f46f0cd3dc459167b9f21b01fdf51a31bd70247d4e3b60921962e3f8c4c1ea8612d58b41a5176b
+  data.tar.gz: e7f6df8a119b318362908287031051de6917fd9fc775732c45af33dec4a5ee15c6304cec2e9b6cf4a3ade75ca415b8a80213cb4ef068fb7fe9d86429ffd06f16

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kaka Ruto
+
+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,284 @@
+# ask-core
+
+Foundation gem for the ask-rb ecosystem. Provides the types and interfaces that every provider gem builds on.
+
+**Zero external dependencies.** Uses only Ruby stdlib (`json`, `net/http`, `date`, `time`).
+
+## Installation
+
+```ruby
+# In your Gemfile
+gem "ask-core"
+```
+
+## What it provides
+
+| Component | File | Purpose |
+|---|---|---|
+| `Ask::Provider` | `lib/ask/provider.rb` | Abstract base class for all LLM providers |
+| `Ask::Conversation` | `lib/ask/conversation.rb` | Message container with role normalization |
+| `Ask::Stream` / `Ask::Chunk` | `lib/ask/stream.rb` | Streaming primitives |
+| `Ask::ModelCatalog` | `lib/ask/models.rb` | Model name to provider resolution |
+| `Ask::ToolDef` | `lib/ask/tool_def.rb` | Immutable tool metadata struct |
+| `Ask::Result` | `lib/ask/result.rb` | Standardized tool return value |
+| `Ask::Error` | `lib/ask/errors.rb` | Structured error types |
+
+## Usage
+
+### Provider (abstract base class)
+
+Provider gems subclass `Ask::Provider` and implement the abstract methods:
+
+```ruby
+class MyProvider < Ask::Provider
+  def api_base
+    "https://api.example.com/v1"
+  end
+
+  def headers
+    { "Authorization" => "Bearer #{@config.api_key}" }
+  end
+
+  def chat(messages, model:, tools: nil, temperature: nil, stream: nil, schema: nil, **params, &block)
+    # Return an Ask::Message or yield Ask::Chunks
+  end
+
+  def embed(text, model:)
+    # Return an array of floats
+  end
+
+  def list_models
+    # Return an array of Ask::ModelInfo
+  end
+
+  class << self
+    def configuration_options
+      [:api_key, :api_base]
+    end
+
+    def configuration_requirements
+      [:api_key]
+    end
+  end
+end
+
+# Register the provider
+Ask::Provider.register(:my_provider, MyProvider)
+
+# Resolve by name
+Ask::Provider.resolve(:my_provider) # => MyProvider
+```
+
+### Conversation
+
+Build and manipulate conversations with role-normalized messages:
+
+```ruby
+conv = Ask::Conversation.new
+
+# Convenience methods
+conv.system("You are a helpful assistant.")
+conv.user("What's the weather in Tokyo?")
+conv.assistant("Let me check...", tool_calls: [{ name: "get_weather", arguments: { location: "Tokyo" } }])
+conv.tool_result("72°F, sunny", tool_call_id: "call_123")
+
+# Iteration
+conv.each { |msg| puts "#{msg.role}: #{msg.content}" }
+
+# Filtering by role
+conv.user_messages   # => [Ask::Message, ...]
+conv.system_messages # => [Ask::Message, ...]
+
+# Serialization
+conv.to_a # => [{ role: :user, content: "..." }, ...]
+```
+
+### Messages
+
+```ruby
+msg = Ask::Message.new(role: :user, content: "Hello")
+msg.user?      # => true
+msg.system?    # => false
+msg.assistant? # => false
+msg.tool?      # => false
+
+msg = Ask::Message.new(role: :assistant, tool_calls: [{ name: "f", arguments: {} }])
+msg.tool_call? # => true
+
+msg = Ask::Message.new(role: :tool, content: "result", tool_call_id: "call_1")
+msg.tool_result? # => true
+```
+
+Valid roles: `:system`, `:user`, `:assistant`, `:tool`
+
+### Streaming
+
+```ruby
+stream = Ask::Stream.new
+
+# Add chunks as they arrive from the provider
+stream.add(Ask::Chunk.new(content: "Hello "))
+stream.add(Ask::Chunk.new(content: "World"))
+stream.add(Ask::Chunk.new(content: "", finish_reason: "stop"))
+stream.finish!
+
+# Accumulate the full response
+stream.accumulated_text # => "Hello World"
+stream.to_s             # => "Hello World"
+
+# Track token usage
+stream.accumulated_usage # => { input_tokens: 10, output_tokens: 20 }
+
+# Iterate
+stream.each { |chunk| print chunk.content }
+```
+
+### Chunks
+
+```ruby
+chunk = Ask::Chunk.new(content: "Hello")
+chunk.content        # => "Hello"
+chunk.finished?      # => false
+chunk.tool_call?     # => false
+chunk.finish_reason  # => nil (or "stop", "length", "tool_calls")
+
+chunk = Ask::Chunk.new(tool_calls: [{ name: "get_weather" }])
+chunk.tool_call?     # => true
+
+chunk = Ask::Chunk.new(usage: { input_tokens: 10, output_tokens: 20 })
+chunk.usage          # => { input_tokens: 10, output_tokens: 20 }
+```
+
+### Model Catalog
+
+Query available models from the registry:
+
+```ruby
+catalog = Ask::ModelCatalog.new([
+  Ask::ModelInfo.new(id: "gpt-4o", provider: "openai", capabilities: ["function_calling", "vision"]),
+  Ask::ModelInfo.new(id: "claude-sonnet-4", provider: "anthropic", capabilities: ["function_calling", "reasoning"])
+])
+
+# Find by ID (prefers most common provider)
+catalog.find("gpt-4o")
+
+# Find with specific provider
+catalog.find("gpt-4o", "openai")
+
+# Filter by type
+catalog.chat_models
+catalog.embedding_models
+
+# Filter by provider or family
+catalog.by_provider("openai")
+catalog.by_family("gpt")
+
+# Singleton instance
+Ask::ModelCatalog.instance
+Ask::ModelCatalog.find("gpt-4o")
+```
+
+### ModelInfo
+
+```ruby
+info = Ask::ModelInfo.new(
+  id: "gpt-4o",
+  provider: "openai",
+  capabilities: ["function_calling", "vision"],
+  context_window: 128_000,
+  pricing: { text_tokens: { standard: { input_per_million: 2.5, output_per_million: 10 } } }
+)
+
+info.supports?(:function_calling)    # => true
+info.chat?                           # => true
+info.embedding?                      # => false
+info.context_window                  # => 128_000
+```
+
+### Tool Definitions
+
+Immutable tool metadata for provider function calling:
+
+```ruby
+tool = Ask::ToolDef.new(
+  name: "get_weather",
+  description: "Get current weather for a location",
+  parameters: {
+    type: "object",
+    properties: {
+      location: { type: "string", description: "City name" },
+      unit: { type: "string", enum: ["celsius", "fahrenheit"] }
+    },
+    required: ["location"]
+  }
+)
+
+tool.name         # => "get_weather"
+tool.description  # => "Get current weather for a location"
+
+# Provider-specific format
+tool.to_provider_format { |t| { type: "function", function: t.to_h } }
+```
+
+### Tool Results
+
+Standardized return values from tool execution:
+
+```ruby
+Ask::Result.success("Data processed")
+Ask::Result.success(updated_record, metadata: { duration: 1.2 })
+Ask::Result.failure("API returned 500", error: "Timeout")
+Ask::Result.aborted("Cancelled by sibling failure")
+Ask::Result.blocked("Permission denied")
+
+result = Ask::Result.success("OK")
+result.success?  # => true
+result.error?    # => false
+result.aborted?  # => false
+result.blocked?  # => false
+result.to_s      # => "OK"
+result.to_h      # => { content: "OK", status: :success, metadata: {} }
+```
+
+### Error Types
+
+```ruby
+Ask::Error                  # Base class (rescue Ask::Error to catch all)
+Ask::ConfigurationError     # Missing/incorrect configuration
+Ask::UnknownProvider        # Provider not registered
+Ask::ModelNotFound          # Model not in catalog
+Ask::InvalidRole            # Invalid message role
+Ask::InvalidToolDefinition  # Invalid tool name/definition
+Ask::ProviderError          # Provider API error (with status_code, response_body)
+Ask::ContextLengthExceeded  # Context window exceeded
+Ask::RateLimitError         # Rate limited
+Ask::Unauthorized           # Authentication failure
+Ask::ServerError            # 5xx server error
+Ask::ServiceUnavailable     # Service temporarily unavailable
+Ask::UnsupportedFeature     # Feature not supported by provider/model
+Ask::MissingCredential      # Required credential not found
+Ask::InvalidCredential      # Credential is invalid/expired
+```
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## Testing
+
+- Uses Minitest (not RSpec) — consistent with the ask-rb ecosystem.
+- Unit tests for every public method.
+- Run the full suite before every commit: `bundle exec rake test`.
+
+## Design Principles
+
+1. **Zero runtime dependencies** — stdlib only. Provider gems add their own HTTP clients.
+2. **Immutable value objects** — `Message`, `ToolDef`, `Result`, `Chunk`, and `ModelInfo` are frozen after construction.
+3. **Abstract interface** — `Ask::Provider` defines the contract. Provider gems implement the wire format.
+4. **Provider registry** — providers register themselves for runtime resolution by name.
+
+## License
+
+MIT

data/lib/ask/conversation.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Ask
+  # A single message in a conversation. Immutable after creation.
+  # Valid roles are: +:system+, +:user+, +:assistant+, +:tool+.
+  class Message
+    VALID_ROLES = %i[system user assistant tool].freeze
+
+    # @return [Symbol] message role (:system, :user, :assistant, :tool)
+    attr_reader :role
+
+    # @return [String, nil] message text content
+    attr_reader :content
+
+    # @return [String, nil] optional participant name (for multi-agent scenarios)
+    attr_reader :name
+
+    # @return [String, nil] tool call ID this message is responding to
+    attr_reader :tool_call_id
+
+    # @return [Array<Hash>, nil] tool calls included in this message
+    attr_reader :tool_calls
+
+    # @return [Hash] arbitrary metadata attached to this message
+    attr_reader :metadata
+
+    def initialize(role:, content: nil, name: nil, tool_call_id: nil, tool_calls: nil, metadata: {})
+      @role = normalize_role!(role)
+      @content = content
+      @name = normalize_name(name)
+      @tool_call_id = tool_call_id
+      @tool_calls = tool_calls
+      @metadata = metadata.dup.freeze
+      validate!
+      freeze
+    end
+
+    # @return [Boolean] true if this message contains tool calls
+    def tool_call? = @tool_calls&.any? == true
+
+    # @return [Boolean] true if this is a tool result message
+    def tool_result? = !@tool_call_id.nil?
+
+    # @return [Boolean] true if role is :system
+    def system? = @role == :system
+
+    # @return [Boolean] true if role is :user
+    def user? = @role == :user
+
+    # @return [Boolean] true if role is :assistant
+    def assistant? = @role == :assistant
+
+    # @return [Boolean] true if role is :tool
+    def tool? = @role == :tool
+
+    # Convert to a hash suitable for provider wire format serialization.
+    # Omits nil-valued keys.
+    # @return [Hash]
+    def to_h
+      base = { role: @role }
+      base[:content] = @content if @content
+      base[:name] = @name if @name
+      base[:tool_call_id] = @tool_call_id if @tool_call_id
+      base[:tool_calls] = @tool_calls if @tool_calls
+      base
+    end
+
+    # @return [Boolean] true if role, content, name, and tool metadata all match
+    def ==(other)
+      return false unless other.is_a?(Message)
+
+      @role == other.role && @content == other.content &&
+        @name == other.name && @tool_call_id == other.tool_call_id &&
+        @tool_calls == other.tool_calls
+    end
+    alias eql? ==
+
+    def hash
+      [@role, @content, @name, @tool_call_id, @tool_calls].hash
+    end
+
+    # @return [String]
+    def inspect
+      "#<Ask::Message role=#{@role.inspect} content=#{@content && @content.length > 57 ? @content[0,57].inspect + "..." : @content.inspect}>"
+    end
+
+    private
+
+    def normalize_role!(role)
+      sym = role.to_s.downcase.to_sym
+      raise InvalidRole, "Invalid role: #{role.inspect}. Valid: #{VALID_ROLES.join(', ')}" unless VALID_ROLES.include?(sym)
+
+      sym
+    end
+
+    def normalize_name(name)
+      return nil if name.nil?
+      name.to_s.strip.empty? ? nil : name.to_s.strip
+    end
+
+    def validate!
+      # Allow nil content for assistant messages with tool calls
+    end
+  end
+
+  # Ordered collection of messages comprising a conversation with an LLM.
+  # Provides role normalization, serialization helpers, and Enumerable access.
+  #
+  #   conv = Ask::Conversation.new
+  #   conv << Ask::Message.new(role: :user, content: "Hello")
+  #   conv.system("Be helpful")
+  #   conv.to_a  # => [{ role: :user, content: "Hello" }, ...]
+  #
+  class Conversation
+    include Enumerable
+
+    # @param messages [Array<Ask::Message>] initial messages
+    def initialize(messages = [])
+      @messages = []
+      messages.each { |m| self << m }
+    end
+
+    # Add a message by object or by attributes.
+    # @param message [Ask::Message, Hash, String] message or attributes
+    # @return [self]
+    def <<(message)
+      msg = message.is_a?(Message) ? message : build_message(message)
+      @messages << msg
+      self
+    end
+    alias add <<
+
+    # Add a system message.
+    # @param text [String] message content
+    # @return [self]
+    def system(text, **options)
+      self << Message.new(role: :system, content: text, **options)
+    end
+
+    # Add a user message.
+    # @param text [String] message content
+    # @return [self]
+    def user(text, **options)
+      self << Message.new(role: :user, content: text, **options)
+    end
+
+    # Add an assistant message.
+    # @param text [String, nil] message content (nil when tool_calls are present)
+    # @param tool_calls [Array<Hash>, nil] tool call invocations
+    # @return [self]
+    def assistant(text = nil, tool_calls: nil, **options)
+      self << Message.new(role: :assistant, content: text, tool_calls: tool_calls, **options)
+    end
+
+    # Add a tool result message.
+    # @param content [String] tool output
+    # @param tool_call_id [String] ID of the tool call this result is for
+    # @return [self]
+    def tool_result(content, tool_call_id:, **options)
+      self << Message.new(role: :tool, content: content, tool_call_id: tool_call_id, **options)
+    end
+
+    # @yield [Message] yields each message in order
+    # @return [Enumerator] if no block given
+    def each(&block)
+      @messages.each(&block)
+    end
+
+    # @return [Ask::Message, Array<Ask::Message>] last message or last n messages
+    def last(n = nil)
+      n ? @messages.last(n) : @messages.last
+    end
+
+    # @return [Integer] number of messages
+    def length = @messages.length
+    alias size length
+
+    # @return [Boolean] true if there are no messages
+    def empty? = @messages.empty?
+
+    # Remove all messages.
+    # @return [self]
+    def clear
+      @messages.clear
+      self
+    end
+
+    # Access message by index.
+    # @param index [Integer] zero-based index
+    # @return [Ask::Message, nil]
+    def [](index)
+      @messages[index]
+    end
+
+    # @return [Array<Hash>] messages as an array of hashes
+    def to_a
+      @messages.map(&:to_h)
+    end
+
+    # @param role [Symbol, String] role to filter by
+    # @return [Array<Ask::Message>] messages with the given role
+    def by_role(role)
+      @messages.select { |m| m.role == role.to_sym }
+    end
+
+    # @return [Array<Ask::Message>] system messages
+    def system_messages = by_role(:system)
+
+    # @return [Array<Ask::Message>] user messages
+    def user_messages = by_role(:user)
+
+    # @return [Array<Ask::Message>] assistant messages
+    def assistant_messages = by_role(:assistant)
+
+    # @return [Array<Ask::Message>] tool messages
+    def tool_messages = by_role(:tool)
+
+    # Deep copy of this conversation.
+    # @return [Ask::Conversation]
+    def dup
+      Conversation.new(@messages.map { |m| Message.new(**m.to_h) })
+    end
+
+    # @return [String]
+    def inspect
+      "#<Ask::Conversation messages=#{@messages.length}>"
+    end
+
+    private
+
+    def build_message(attrs)
+      attrs.is_a?(Hash) ? Message.new(**attrs) : Message.new(role: :user, content: attrs.to_s)
+    end
+  end
+end

data/lib/ask/errors.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Ask
+  # Base error class for all ask-rb errors.
+  class Error < StandardError; end
+
+  # Raised when a provider is not configured properly.
+  class ConfigurationError < Error; end
+
+  # Raised when a required credential is missing.
+  class MissingCredential < Error; end
+
+  # Raised when a credential is invalid or expired.
+  class InvalidCredential < Error; end
+
+  # Raised when an unknown provider is requested.
+  class UnknownProvider < Error; end
+
+  # Raised when a model is not found in the catalog.
+  class ModelNotFound < Error; end
+
+  # Raised when a message has an invalid role.
+  class InvalidRole < Error; end
+
+  # Raised when a tool definition is invalid.
+  class InvalidToolDefinition < Error; end
+
+  # Raised when the context window is exceeded.
+  class ContextLengthExceeded < Error; end
+
+  # Raised when the API rate limit is hit.
+  class RateLimitError < Error; end
+
+  # Raised when authentication fails.
+  class Unauthorized < Error; end
+
+  # Raised when the server returns a 5xx error.
+  class ServerError < Error; end
+
+  # Raised when the service is unavailable.
+  class ServiceUnavailable < Error; end
+
+  # Raised when a provider's API returns an unexpected response.
+  # @!attribute [r] status_code
+  #   @return [Integer, nil] the HTTP status code
+  # @!attribute [r] response_body
+  #   @return [String, nil] the raw response body
+  class ProviderError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message = nil, status_code: nil, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+
+  # Raised when a conversation operation receives an invalid state.
+  class ConversationError < Error; end
+
+  # Raised when streaming encounters an error.
+  class StreamError < Error; end
+
+  # Raised when a feature is not supported by the selected provider/model.
+  class UnsupportedFeature < Error; end
+end