karu

karu is the Quechua word for far.

Batched byte-range reads from local files, HTTP, S3, GCS, Azure, Hugging Face and Source Cooperative.

Features

• URIs or GDAL VSI paths for every backend, such as s3://bucket/key or /vsis3/bucket/key.
• Batched reads that merge nearby ranges, fetch in parallel and complete one by one.
• Stateless reads that name their object, offset and buffer, so they can be reordered and retried.
• Version pinning with stat and if_match, so a changed object fails instead of mixing versions.
• Retries and resumable transfers within a per-request deadline.
• Credential discovery for every backend, plus custom providers.
• Per-path configuration, for example anonymous for one bucket and a profile for another.

Quick start

#include <karu/karu.hpp>

auto client = karu::Client::create(karu::Config::from_environment().value()).value();
auto object = karu::Object::parse(
    "hf://datasets/asterisk-labs/rumi-api-fixtures/data/s2-00-tile.rumi").value();
auto bytes = client.read(object, 0, 4096).value();

Installation

Prebuilt packages for Linux, macOS and Windows are on the releases page, and CMake finds them with find_package.

find_package(karu CONFIG REQUIRED)
target_link_libraries(app PRIVATE karu::karu)

Documentation

Guide · Configuration · Changelog

Coding agents can install the Karu skill with npx skills add asterisk-labs/karu.

License

MIT. See LICENSE.

Made with ♥ by