ask-core 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a806c5e8835fe74ef4bf8941a314ed462fa39bd3d607e6de112b92df9a8bbb8
-  data.tar.gz: a6301f23b50af2d5e508eb73e072951a2e3526a3c0c2776a92b24b281111ef93
+  metadata.gz: b2d67418e2412efacf4d0b5c35d1897826f0da1c0a52c159f7503e8b794d66f1
+  data.tar.gz: 2b39ea638d11e5147058a1f35e3aa3c130650972082330e2dd30a752eeb68a36
 SHA512:
-  metadata.gz: 685fd487472dcb656e7b928e32d8e972ce27b963e78c8a64b167fe3a76691268878b87cf3079ff39d530cd23082d33ad919e36b01d209a790a9225c89d26b3bf
-  data.tar.gz: ba3bae4f9839de021ac62c3aefb0e9675b159151e5d45c5b113e48c6ec042594c658568944e78075b0c38e9dc945c02be13c40dfd2cf6901ed181b7bf9184fe3
+  metadata.gz: 8910e469a984ca9f2758dc816b6b13714b5985fad2dbb0910b2d2d0b5313ff04abfcffad06e3fcf2de4a53eb2d3e34fda1292150867bae39d476b5ad4a3551e4
+  data.tar.gz: 6ed636a7ed4b15f423b5914708064e44ac286e6488b87857d271646e83fad113b8dec97a1a7082e95bbd598d1ee2c631a77bffa0d03595ebd7d10db9a965b2ab

data/CHANGELOG.md

@@ -1,3 +1,40 @@
+## [0.10.0] - 2026-08-05
+
+### Added
+
+- **`Ask::Result.pending`** — a new `:pending` status for async tool
+  execution. A tool returns pending to hand the turn back to the agent
+  (the interim message gets voiced) while the real work continues in the
+  background; the session completes it later. `Result#pending?` predicates
+  it; `to_h` keeps the tool shape.
+
+## [0.9.0] — 2026-08-03
+
+### Changed
+
+- **`Ask::Result` is now the single result type for the whole ecosystem** — it
+  supports both the foundational API (`success`/`failure`/`aborted`/`blocked`
+  with `content` and `status`) and the tool API (`ok`/`error` with `ok?`,
+  `output`, and `error_message`), including both constructor keyword sets.
+  Previously `ask-tools` defined its own incompatible `Ask::Result`; whichever
+  gem loaded last won, so `Ask::Result.success` raised `ArgumentError` in any
+  app loading both (e.g. every ask-agent app), and `ask-rag`'s `raw.output`
+  call failed on provider embedding results. ask-tools now depends on
+  ask-core instead of redefining the class.
+- `Result#to_h` now serializes to `{ok:, output:, error:, metadata:}` (the
+  tool shape). `Result#inspect` is `ok=true output=...` / `ok=false error=...`.
+
+  ```ruby
+  Ask::Result.success("Data processed").to_h
+  # => {ok: true, output: "Data processed", error: nil, metadata: {}}
+
+  Ask::Result.ok(data: "Data processed")   # same class, same result
+  ```
+
+### Tested
+
+- ask-core test suite: all pass.
+
 ## [0.8.0] — 2026-07-28
 
 ### Changed

data/README.md

@@ -1,284 +1,89 @@
 # ask-core
 
-Foundation gem for the ask-rb ecosystem. Provides the types and interfaces that every provider gem builds on.
+[![Gem Version](https://badge.fury.io/rb/ask-core.svg)](https://badge.fury.io/rb/ask-core)
 
-**Zero external dependencies.** Uses only Ruby stdlib (`json`, `net/http`, `date`, `time`).
+Foundation gem for the ask-rb ecosystem. Provides the value objects and interfaces every other gem builds on: messages, conversations, streaming primitives, the provider contract, model catalog, tool definitions, and structured errors. Zero external dependencies, Ruby stdlib only (`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:
+## Quick Start
 
 ```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:
+require "ask-core"
 
-```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, ...]
+conv.last.role    # => :user
+conv.last.user?   # => true
 
-# Serialization
-conv.to_a # => [{ role: :user, content: "..." }, ...]
+# Serialize for a provider API
+conv.to_a         # => [{ role: :user, content: "..." }, ...]
 ```
 
-### Messages
+## The core types
 
-```ruby
-msg = Ask::Message.new(role: :user, content: "Hello")
-msg.user?      # => true
-msg.system?    # => false
-msg.assistant? # => false
-msg.tool?      # => false
+| Type | Purpose |
+|---|---|
+| `Ask::Conversation`, `Ask::Message` | Message container with role normalization (`:system`, `:user`, `:assistant`, `:tool`) and immutable message value objects |
+| `Ask::Stream`, `Ask::Chunk` | Streaming primitives with text accumulation and usage tracking |
+| `Ask::Provider` | Abstract base class for LLM providers, with a thread-safe registry (`register` / `resolve`) |
+| `Ask::ModelCatalog`, `Ask::ModelInfo` | Model metadata: find by ID/provider, filter by family, refresh from models.dev |
+| `Ask::ToolDef` | Immutable tool metadata for provider function calling |
+| `Ask::Result` | Standardized tool return value: `success`, `failure`, `aborted`, `blocked` |
+| `Ask::Content` | Multi-modal content blocks: `Text`, `Image`, `Audio`, `Video`, `File` |
+| `Ask::Document` | Text + metadata value object for RAG pipelines |
+| `Ask::ProviderTool` | Provider-executed tools (e.g. `web_search`, `file_search`) |
+| `Ask::State::Adapter` | Abstract contract for state backends (implemented by ask-state-providers) |
+| `Ask::Error` and subclasses | Structured errors (`ConfigurationError`, `RateLimitError`, `ProviderError`, and more) |
 
-msg = Ask::Message.new(role: :assistant, tool_calls: [{ name: "f", arguments: {} }])
-msg.tool_call? # => true
+## Defining a provider
 
-msg = Ask::Message.new(role: :tool, content: "result", tool_call_id: "call_1")
-msg.tool_result? # => true
-```
-
-Valid roles: `:system`, `:user`, `:assistant`, `:tool`
-
-### Streaming
+Provider gems subclass `Ask::Provider`, implement the abstract methods, and register themselves:
 
 ```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"
+class MyProvider < Ask::Provider
+  def api_base = "https://api.example.com/v1"
+  def chat(messages, model:, **opts) = Ask::Message.new(role: :assistant, content: "Hello")
+  def embed(text, model:) = [0.1, 0.2, 0.3]
+  def list_models = [Ask::ModelInfo.new(id: "my-model", provider: "my_provider")]
+end
 
-# Provider-specific format
-tool.to_provider_format { |t| { type: "function", function: t.to_h } }
+Ask::Provider.register(:my_provider, MyProvider)
+Ask::Provider.resolve(:my_provider)  # => MyProvider
 ```
 
-### Tool Results
+## Architecture & ownership
 
-Standardized return values from tool execution:
+ask-core owns the shared value objects and base contracts (`Ask::Message`,
+`Ask::Conversation`, `Ask::Content`, `Ask::Stream`, `Ask::Provider`,
+`Ask::Result`, `Ask::ModelCatalog`, `Ask::ToolDef`, `Ask::Document`, the
+`Ask::Error` hierarchy). It is zero-dependency on purpose: `ask-llm-providers`,
+`ask-rag`, `ask-graph`, and `ask-state-providers` depend on it *without*
+pulling in the tool framework.
 
-```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")
+Feature gems extend what ask-core provides — they never redefine it.
+`Ask::Result` is the single result type for the whole ecosystem: foundational
+API (`success`/`failure`/`aborted`/`blocked`) and tool API (`ok`/`error`) in
+one class. See
+[Architecture & Ownership](https://ask-rb.github.io/ask-docs/reference/architecture).
 
-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: {} }
-```
+## Full documentation
 
-### 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
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. [ask-core in depth](https://ask-rb.github.io/ask-docs/core/ask-core) covers the types, streaming, and the provider contract. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
+```
+bundle install
 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/result.rb

@@ -1,14 +1,24 @@
 # 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.
+  # Standardized return value from tool execution.
+  #
+  # This is the single +Ask::Result+ for the whole ecosystem. It supports both
+  # the foundational API (+success+/+failure+/+aborted+/+blocked+ with
+  # +content+ and +status+) and the tool API (+ok+/+error+ with +ok?+,
+  # +output+, and +error_message+):
   #
   #   Ask::Result.success("Data processed")
-  #   Ask::Result.failure("API returned 500")
+  #   Ask::Result.ok(data: "Data processed")
+  #
+  # Both are the same class and share the same +to_h+ shape, so a result
+  # created by a provider's +embed+ or a tool's +execute+ can be inspected
+  # uniformly.
   #
+  # Feature gems extend this class or build on it — they never redefine it.
+  # See ask-docs "Architecture & ownership" for the rule.
   class Result
-    STATUSES = %i[success error aborted blocked short_circuited].freeze
+    STATUSES = %i[success error aborted blocked short_circuited pending].freeze
 
     class << self
       # @!group Factory Methods
@@ -23,11 +33,12 @@ module Ask
 
       # Create a failure result.
       # @param message [String] the error description
-      # @param error [Object, nil] the underlying error object
+      # @param error [Object, nil] the underlying error object (defaults to
+      #   +message+ so `failure(msg).error` reads as the message)
       # @param metadata [Hash] additional metadata
       # @return [Ask::Result]
       def failure(message, error: nil, metadata: {})
-        new(content: message, status: :error, error: error, metadata: metadata)
+        new(content: message, status: :error, error: error.nil? ? message : error, metadata: metadata)
       end
 
       # Create an aborted result (cancelled by sibling failure).
@@ -43,24 +54,69 @@ module Ask
       def blocked(reason)
         new(content: reason, status: :blocked)
       end
+
+      # Create a pending result (async tool): the work continues in the
+      # background and the session completes it later via
+      # +Ask::Agent::Session#complete_pending_tool+. The agent voices the
+      # tool's interim message immediately and keeps talking.
+      # @param message [String] interim status the model can voice
+      # @param metadata [Hash] additional metadata
+      # @return [Ask::Result]
+      def pending(message, metadata: {})
+        new(content: message, status: :pending, metadata: metadata)
+      end
+
+      # Create a successful result (tool API — alias for +success+).
+      # @param data [Object] the tool's output
+      # @param metadata [Hash] optional metadata
+      # @return [Ask::Result]
+      def ok(data:, metadata: {})
+        new(content: data, status: :success, metadata: metadata)
+      end
+
+      # Create a failed result (tool API).
+      # @param message [String] description of the failure
+      # @param metadata [Hash] optional metadata
+      # @return [Ask::Result]
+      def error(message:, metadata: {})
+        new(content: message, status: :error, error: message, metadata: metadata)
+      end
       # @!endgroup
     end
 
-    # @return [Object, nil] the result content
+    # @return [Object, nil] the result content (for +success+/+ok+ results,
+    #   this is the payload; for +failure+ it is the error message)
     attr_reader :content
 
     # @return [Symbol] the status (:success, :error, :aborted, :blocked, :short_circuited)
     attr_reader :status
 
-    # @return [Object, nil] the underlying error, if any
+    # @return [Object, nil] the error message or underlying error object, 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)
+    # Accepts both the foundational keywords (+content+, +status+) and the
+    # tool keywords (+ok+, +output+). +ok:+ derives the status: +true+ means
+    # +:success+, +false+ means +:error+.
+    #
+    # @param content [Object, nil] result content
+    # @param output [Object, nil] tool output (takes precedence over +content+)
+    # @param status [Symbol] result status
+    # @param ok [Boolean, nil] whether the result is a success (derives status)
+    # @param error [Object, nil] error message or underlying error object
+    # @param metadata [Hash] additional metadata
+    def initialize(content: nil, output: nil, status: :success, ok: nil, error: nil, metadata: {})
+      @content = output.nil? ? content : output
+      @status = if ok == true
+                  :success
+                elsif ok == false
+                  :error
+                else
+                  status
+                end
+      @status = validate_status!(@status)
       @error = error
       @metadata = metadata.dup.freeze
       freeze
@@ -69,6 +125,15 @@ module Ask
     # @return [Boolean] true if status is :success
     def success? = @status == :success
 
+    # @return [Boolean] true if the result is a success (tool API)
+    def ok? = @status == :success
+
+    # @return [Boolean] true if the result is pending (async tool running)
+    def pending? = @status == :pending
+
+    # @return [Boolean] true if the result is a success (tool API)
+    def ok = @status == :success
+
     # @return [Boolean] true if status is :error
     def error? = @status == :error
 
@@ -78,7 +143,13 @@ module Ask
     # @return [Boolean] true if status is :blocked
     def blocked? = @status == :blocked
 
-    # @return [String] the content as a string
+    # @return [Object, nil] the output data when successful, nil otherwise (tool API)
+    def output = @status == :success ? @content : nil
+
+    # @return [Object, nil] the error message or underlying error object
+    def error_message = @error
+
+    # @return [String] the content as a string (for failures, the message)
     def to_s
       @content.to_s
     end
@@ -86,16 +157,20 @@ module Ask
     # @return [Hash] serialized representation
     def to_h
       {
-        content: @content,
-        status: @status,
+        ok: @status == :success,
+        output: @status == :success ? @content : nil,
         error: @error,
         metadata: @metadata
-      }.compact
+      }
     end
 
     # @return [String] human-readable representation
     def inspect
-      "#<Ask::Result status=#{@status.inspect} content=#{@content.inspect}>"
+      if @status == :success
+        "#<Ask::Result ok=true output=#{@content.inspect}>"
+      else
+        "#<Ask::Result ok=false error=#{@error.inspect} status=#{@status.inspect}>"
+      end
     end
 
     private

data/lib/ask/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-core
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Kaka Ruto