Project

ask-core

0.0
The project is in a healthy, maintained state
ask-coreask-rb/ask-coreHomepageDocumentationSource CodeBug Tracker
Provides Ask::Provider (abstract interface), Ask::Conversation, Ask::Stream, Ask::ModelCatalog, Ask::ToolDef, Ask::Result, and structured error types. Zero runtime dependencies.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
9,310
Stars
0
Forks
0
Watchers
0
 Releases
Current version
0.11.3
Total releases
24
First release
2026-06-09
Latest release
2026-08-14
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2026-07-03
Reverse Dependencies
12

 Dependencies

Development

minitest
~> 5.25
mocha
~> 3.1
rake
~> 13.0

Runtime

base64
~> 0.2
 Project Readme

ask-core

Gem Version

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

gem "ask-core"

Quick Start

require "ask-core"

conv = Ask::Conversation.new
conv.system("You are a helpful assistant.")
conv.user("What's the weather in Tokyo?")

conv.last.role    # => :user
conv.last.user?   # => true

# Serialize for a provider API
conv.to_a         # => [{ role: :user, content: "..." }, ...]

The core types

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)

Defining a provider

Provider gems subclass Ask::Provider, implement the abstract methods, and register themselves:

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

Ask::Provider.register(:my_provider, MyProvider)
Ask::Provider.resolve(:my_provider)  # => MyProvider

Architecture & ownership

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.

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.

Full documentation

The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs. ask-core in depth covers the types, streaming, and the provider contract. API reference: https://ask-rb.github.io/ask-docs/reference/api.

Development

bundle install
bundle exec rake test

License

MIT