ask-core

# In your Gemfile
gem "ask-core"

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

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: "..." }, ...]

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

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 }

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 }

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")

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 = 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 } }

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: {} }

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