moondream-client 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 307f9a7735718231a95a7a68764c0958bd7e1f1183ceefd24bf1b89b82050e64
+  data.tar.gz: 21646d85a3be9d0eed1682e0038fb005dc3949de31538804e6a14dcbecf7010e
+SHA512:
+  metadata.gz: d2703bc5d2f4db1db9fa20686c8b43ac0acc16b70f137ecea334f4d9a289d0703ac54a27231d2f71e6cebdb03420c53e345c26c4d9bc0f2d19dcc6b7d6851f9c
+  data.tar.gz: 03becd543a92f77ad0b75b1e848df1c09dff3c66d3bc966e988cce05e767d44a91b9fec90914bd35e0545b88878da957e1e95a5797f5e09585e0d793362a7704

data/.env.example

@@ -0,0 +1 @@
+MOONDREAM_ACCESS_TOKEN=

data/.rubocop.yml

@@ -0,0 +1,42 @@
+AllCops:
+  TargetRubyVersion: 3.3.9
+  NewCops: enable
+  SuggestExtensions: false
+
+Style/Documentation:
+  Enabled: false
+
+Bundler/OrderedGems:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/FrozenStringLiteralComment:
+  SafeAutoCorrect: true
+  EnforcedStyle: always_true
+
+Metrics/MethodLength:
+  Enabled: false
+
+Style/AccessorGrouping:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/ParameterLists:
+  Enabled: false
+
+Metrics/ClassLength:
+  Enabled: false
+
+Style/HashSyntax:
+  Enabled: false
+
+Naming/FileName:
+  Exclude:
+    - "lib/moondream-client.rb"

data/.ruby-version

@@ -0,0 +1 @@
+3.3.0

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+gem "minitest", "~> 5.0"
+gem "rake", "~> 13.0"
+gem "rubocop", "~> 1.21"
+gem "dotenv"

data/Gemfile.lock

@@ -0,0 +1,68 @@
+PATH
+  remote: .
+  specs:
+    moondream-client (0.0.1)
+      base64
+      faraday (>= 1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    base64 (0.2.0)
+    dotenv (3.1.8)
+    faraday (2.14.0)
+      faraday-net_http (>= 2.0, < 3.5)
+      json
+      logger
+    faraday-net_http (3.4.1)
+      net-http (>= 0.5.0)
+    json (2.15.1)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (5.25.5)
+    net-http (0.6.0)
+      uri
+    parallel (1.27.0)
+    parser (3.3.9.0)
+      ast (~> 2.4.1)
+      racc
+    prism (1.5.1)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.0)
+    regexp_parser (2.11.3)
+    rubocop (1.81.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.47.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.4)
+    ruby-progressbar (1.13.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.1.0)
+    uri (1.0.4)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  dotenv
+  minitest (~> 5.0)
+  moondream-client!
+  rake (~> 13.0)
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.5.7

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 851 Inc.
+
+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,132 @@
+# MoondreamClient
+
+Ruby client for the Moondream API, providing typed classes for Caption, Query, Detect, and Point, plus streaming captions.
+
+## Installation
+
+Install the gem and add to the application"s Gemfile by executing:
+
+    $ bundle add moondream-client
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install moondream-client
+
+## Usage
+
+### Configuration
+
+Configure the client once at boot (e.g., in Rails an initializer) using `MoondreamClient.configure`.
+
+Get an access token from the Moondream Cloud: https://moondream.ai/c/cloud/api-keys.
+
+```ruby
+MoondreamClient.configure do |config|
+  config.access_token = ENV["MOONDREAM_ACCESS_TOKEN"]
+  config.uri_base = "https://api.moondream.ai/v1" # Optional (default: https://api.moondream.ai/v1)
+  config.request_timeout = 120 # Optional (default: 120)
+end
+```
+
+### Caption
+
+Create captions via the `/caption` endpoint. If you pass an `http(s)` image URL, the client will download it and convert it to a base64 data URL automatically.
+
+```ruby
+caption = MoondreamClient::Caption.create!(
+  image_url: "data:image/jpeg;base64,..." # or https URL,
+  length: "short" # or "normal",
+  stream: false
+)
+caption.caption       # => String caption text
+caption.request_id    # => String request id
+```
+
+#### Streaming captions
+
+You can stream caption chunks and get a final `Caption` object at the end:
+
+```ruby
+final = MoondreamClient::Caption.stream!(
+  image_url: "data:image/jpeg;base64,...", # or https URL
+  length: "short"
+) do |chunk|
+  print chunk # chunk is a String
+end
+
+final.caption # => String final caption
+```
+
+### Query
+
+Ask questions about an image via `/query`. `http(s)` URLs are automatically converted to base64 data URLs.
+
+```ruby
+query = MoondreamClient::Query.create!(
+  image_url: "data:image/jpeg;base64,...",
+  question: "What color is the car?"
+)
+query.answer          # => String answer text
+query.request_id      # => String request id
+```
+
+### Detect
+
+Detect objects and return bounding boxes via `/detect`. `http(s)` URLs are automatically converted to base64 data URLs.
+
+```ruby
+detect = MoondreamClient::Detect.create!(
+  image_url: "data:image/jpeg;base64,...",
+  object: "person"
+)
+detect.objects        # => [#<BoundingBox x_min y_min x_max y_max>]
+detect.request_id     # => String request id
+```
+
+### Point
+
+Locate center points for objects via `/point`. `http(s)` URLs are automatically converted to base64 data URLs.
+
+```ruby
+point = MoondreamClient::Point.create!(
+  image_url: "data:image/jpeg;base64,...",
+  object: "face"
+)
+point.points          # => [#<Coordinate x y>]
+point.request_id      # => String request id
+```
+
+### Error handling
+
+HTTP and API errors raise typed exceptions:
+
+- `MoondreamClient::UnauthorizedError` (401)
+- `MoondreamClient::ForbiddenError` (403)
+- `MoondreamClient::NotFoundError` (404)
+- `MoondreamClient::ServerError` (other non-success)
+
+Rescue them as needed:
+
+```ruby
+begin
+  MoondreamClient::Caption.create!(
+    image_url: "data:image/jpeg;base64,...",
+    length: "short"
+  )
+rescue MoondreamClient::UnauthorizedError
+  # handle invalid/missing token
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to rubygems.org.
+
+For local development, copy the example environment file and set your API token so `bin/console` can load it automatically:
+
+```
+cp .env.example .env
+echo 'MOONDREAM_ACCESS_TOKEN=your_api_token_here' >> .env
+```

data/Rakefile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/moondream-client/caption.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module MoondreamClient
+  class Caption
+    # @return [String] The server-generated request identifier.
+    attr_reader :request_id
+
+    # @return [String] The generated caption text.
+    attr_reader :caption
+
+    # Initialize a new Caption result object.
+    #
+    # @param attributes [Hash] Raw attributes from the /caption endpoint response.
+    # @param client [MoondreamClient::Client]
+    def initialize(attributes, client: MoondreamClient.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Create a caption for an image.
+      # Corresponds to POST /caption
+      #
+      # @param image_url [String] A URL or data URL for the image.
+      # @param length [String] "short" or "normal" (default).
+      # @param stream [Boolean] Whether to stream the response (default: false).
+      # @param client [MoondreamClient::Client]
+      #
+      # @return [MoondreamClient::Caption]
+      def create!(image_url:, length: "normal", stream: false, client: MoondreamClient.client)
+        image_data_url = MoondreamClient::Image.to_data_url(image_url)
+        payload = {
+          image_url: image_data_url,
+          length: length,
+          stream: stream
+        }
+
+        attributes = client.post("/caption", payload)
+        new(attributes, client: client)
+      end
+
+      # Stream caption chunks and return the final Caption instance.
+      #
+      # @param image_url [String]
+      # @param length [String]
+      # @param client [MoondreamClient::Client]
+      # @yield [chunk] yields each text chunk String as it arrives
+      # @return [MoondreamClient::Caption]
+      def stream!(image_url:, length: "normal", client: MoondreamClient.client, &block)
+        image_data_url = MoondreamClient::Image.to_data_url(image_url)
+        payload = {
+          image_url: image_data_url,
+          length: length,
+          stream: true
+        }
+
+        caption = nil
+
+        client.post_stream("/caption", payload) do |data|
+          if (chunk = data["chunk"]) && !chunk.to_s.empty?
+            block&.call(chunk)
+          end
+
+          caption = data["caption"] if data["caption"]
+        end
+
+        # Build the final Caption from aggregated stream content.
+        new({ "caption" => caption }, client: client)
+      end
+    end
+
+    private
+
+    # Normalize attributes from the /caption response.
+    # @param attributes [Hash]
+    # @return [void]
+    def reset_attributes(attributes)
+      @request_id = attributes["request_id"]
+      @caption = attributes["caption"]
+    end
+  end
+end

data/lib/moondream-client/client.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+module MoondreamClient
+  class Client
+    # The configuration for the client.
+    #
+    # @return [MoondreamClient::Configuration]
+    attr_accessor :configuration
+
+    # Initialize the client.
+    #
+    # @param configuration [MoondreamClient::Configuration] The configuration for the client.
+    #
+    # @return [MoondreamClient::Client]
+    def initialize(configuration = MoondreamClient.configuration)
+      @configuration = configuration
+    end
+
+    # Make a POST request to the API.
+    #
+    # @param path [String] The path to the API endpoint.
+    # @param payload [Hash] The payload to send to the API.
+    # @param headers [Hash] The headers to send to the API.
+    #
+    # @return [Hash] The response from the API.
+    def post(path, payload, headers: {})
+      response = connection.post(build_url(path)) do |request|
+        request.headers["X-Moondream-Auth"] = @configuration.access_token if @configuration.access_token
+        request.headers["Content-Type"] = "application/json"
+        request.headers["Accept"] = "application/json"
+        request.headers.merge!(headers)
+        request.body = payload.compact.to_json
+      end
+
+      handle_error(response) unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    # Make a GET request to the API.
+    #
+    # @param path [String] The path to the API endpoint.
+    #
+    # @return [Hash] The response from the API.
+    def get(path)
+      response = connection.get(build_url(path)) do |request|
+        request.headers["X-Moondream-Auth"] = @configuration.access_token if @configuration.access_token
+        request.headers["Content-Type"] = "application/json"
+      end
+
+      handle_error(response) unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    # Make a streaming POST request to the API using text/event-stream.
+    # Parses SSE lines and yields decoded event data Hashes to the provided block.
+    #
+    # @param path [String]
+    # @param payload [Hash]
+    # @param headers [Hash]
+    # @yield [data] yields parsed JSON from each SSE event's data field
+    # @return [void]
+    def post_stream(path, payload = {}, headers: {}, &block)
+      decoder = SSEDecoder.new
+      buffer = ""
+
+      connection.post(build_url(path)) do |request|
+        request.headers["X-Moondream-Auth"] = @configuration.access_token if @configuration.access_token
+        request.headers["Accept"] = "text/event-stream"
+        request.headers["Cache-Control"] = "no-store"
+        request.headers["Content-Type"] = "application/json"
+        request.headers.merge!(headers)
+        request.body = payload.compact.to_json
+        request.options.on_data = lambda { |chunk, _total_bytes, _env|
+          # Normalize and split into lines, preserving last partial line in buffer
+          buffer = (buffer + chunk.to_s).gsub(/\r\n?/, "\n")
+          lines = buffer.split("\n", -1)
+          buffer = lines.pop || ""
+          lines.each do |line|
+            event = decoder.decode(line)
+            block&.call(event["data"]) if event && event["data"]
+          end
+        }
+      end
+    end
+
+    # Handle errors from the API.
+    #
+    # @param response [Faraday::Response] The response from the API.
+    #
+    # @return [void]
+    def handle_error(response)
+      case response.status
+      when 401
+        raise UnauthorizedError, response.body
+      when 403
+        raise ForbiddenError, response.body
+      when 404
+        raise NotFoundError, response.body
+      else
+        raise ServerError, response.body
+      end
+    end
+
+    private
+
+    # Minimal SSE decoder for parsing standard server-sent event lines.
+    class SSEDecoder
+      def initialize
+        @event = ""
+        @data = ""
+        @id = nil
+        @retry = nil
+      end
+
+      # @param line [String]
+      # @return [Hash, nil]
+      def decode(line)
+        return flush_event if line.empty?
+        return if line.start_with?(":")
+
+        field, _, value = line.partition(":")
+        value = value.lstrip
+
+        case field
+        when "event"
+          @event = value
+        when "data"
+          @data += "#{value}\n"
+        when "id"
+          @id = value
+        when "retry"
+          @retry = value.to_i
+        end
+
+        nil
+      end
+
+      private
+
+      def flush_event
+        return if @data.empty?
+
+        data = @data.chomp
+        parsed = JSON.parse(data)
+
+        event = { "data" => parsed }
+        event["event"] = @event unless @event.empty?
+        event["id"] = @id if @id
+        event["retry"] = @retry if @retry
+
+        @event = ""
+        @data = ""
+        @id = nil
+        @retry = nil
+
+        event
+      end
+    end
+
+    # Build the URL for the API.
+    #
+    # @param path [String] The path to the API endpoint.
+    def build_url(path)
+      "#{@configuration.uri_base}#{path}"
+    end
+
+    # Create a connection to the API.
+    #
+    # @return [Faraday::Connection]
+    def connection
+      Faraday.new do |faraday|
+        faraday.request :url_encoded
+        faraday.options.timeout = @configuration.request_timeout
+        faraday.options.open_timeout = @configuration.request_timeout
+      end
+    end
+  end
+end

data/lib/moondream-client/detect.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module MoondreamClient
+  class Detect
+    class BoundingBox
+      # @return [Float] Normalized minimum x coordinate (0.0..1.0)
+      attr_reader :x_min
+      # @return [Float] Normalized minimum y coordinate (0.0..1.0)
+      attr_reader :y_min
+      # @return [Float] Normalized maximum x coordinate (0.0..1.0)
+      attr_reader :x_max
+      # @return [Float] Normalized maximum y coordinate (0.0..1.0)
+      attr_reader :y_max
+
+      def initialize(x_min:, y_min:, x_max:, y_max:)
+        @x_min = x_min
+        @y_min = y_min
+        @x_max = x_max
+        @y_max = y_max
+      end
+    end
+
+    # @return [String] The server-generated request identifier.
+    attr_reader :request_id
+
+    # @return [Array<BoundingBox>] The list of detected object bounding boxes.
+    attr_reader :objects
+
+    # Initialize a new Detect result object.
+    #
+    # @param attributes [Hash] Raw attributes from the /detect endpoint response.
+    # @param client [MoondreamClient::Client]
+    def initialize(attributes, client: MoondreamClient.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Detect objects described by `object` within an image.
+      # Corresponds to POST /detect
+      #
+      # @param image_url [String]
+      # @param object [String] Object description, e.g. "person".
+      # @param client [MoondreamClient::Client]
+      #
+      # @return [MoondreamClient::Detect]
+      def create!(image_url:, object:, client: MoondreamClient.client)
+        image_data_url = MoondreamClient::Image.to_data_url(image_url)
+        payload = {
+          image_url: image_data_url,
+          object: object
+        }
+
+        attributes = client.post("/detect", payload)
+        new(attributes, client: client)
+      end
+    end
+
+    private
+
+    # Normalize attributes from the /detect response.
+    # @param attributes [Hash]
+    # @return [void]
+    def reset_attributes(attributes)
+      @request_id = attributes["request_id"]
+      @objects = Array(attributes["objects"]).map do |o|
+        BoundingBox.new(x_min: o["x_min"], y_min: o["y_min"], x_max: o["x_max"], y_max: o["y_max"])
+      end
+    end
+  end
+end

data/lib/moondream-client/image.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module MoondreamClient
+  module Image
+    class << self
+      # Convert an input reference into a data URL.
+      # If it is already a data URL, return as-is.
+      # If it is an HTTP(S) URL, download and convert to base64 data URL.
+      # Otherwise, return as-is.
+      #
+      # @param reference [String]
+      # @return [String]
+      def to_data_url(reference)
+        return reference if data_url?(reference)
+
+        return http_to_data_url(reference) if http_url?(reference)
+
+        reference
+      end
+
+      private
+
+      def data_url?(value)
+        value.is_a?(String) && value.start_with?("data:")
+      end
+
+      def http_url?(value)
+        value.is_a?(String) && (value.start_with?("http://") || value.start_with?("https://"))
+      end
+
+      def http_to_data_url(url)
+        connection = Faraday.new do |faraday|
+          faraday.request :url_encoded
+          faraday.options.timeout = MoondreamClient.configuration.request_timeout
+          faraday.options.open_timeout = MoondreamClient.configuration.request_timeout
+        end
+
+        response = connection.get(url)
+        raise MoondreamClient::ServerError, "Failed to download image: #{response.status}" unless response.success?
+
+        content_type = response.headers["content-type"] || "image/jpeg"
+        base64 = Base64.strict_encode64(response.body)
+        "data:#{content_type};base64,#{base64}"
+      end
+    end
+  end
+end

data/lib/moondream-client/point.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module MoondreamClient
+  class Point
+    class Coordinate
+      # @return [Float] Normalized x coordinate (0.0..1.0)
+      attr_reader :x
+      # @return [Float] Normalized y coordinate (0.0..1.0)
+      attr_reader :y
+
+      def initialize(x:, y:) # rubocop:disable Naming/MethodParameterName
+        @x = x
+        @y = y
+      end
+    end
+
+    # @return [String] The server-generated request identifier.
+    attr_reader :request_id
+
+    # @return [Array<Coordinate>] The list of point coordinates.
+    attr_reader :points
+
+    # Initialize a new Point result object.
+    #
+    # @param attributes [Hash] Raw attributes from the /point endpoint response.
+    # @param client [MoondreamClient::Client]
+    def initialize(attributes, client: MoondreamClient.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Locate the center points for objects described by `object` in an image.
+      # Corresponds to POST /point
+      #
+      # @param image_url [String]
+      # @param object [String] Object description, e.g. "face".
+      # @param client [MoondreamClient::Client]
+      #
+      # @return [MoondreamClient::Point]
+      def create!(image_url:, object:, client: MoondreamClient.client)
+        image_data_url = MoondreamClient::Image.to_data_url(image_url)
+        payload = {
+          image_url: image_data_url,
+          object: object
+        }
+
+        attributes = client.post("/point", payload)
+        new(attributes, client: client)
+      end
+    end
+
+    private
+
+    # Normalize attributes from the /point response.
+    # @param attributes [Hash]
+    # @return [void]
+    def reset_attributes(attributes)
+      @request_id = attributes["request_id"]
+      @points = Array(attributes["points"]).map do |p|
+        Coordinate.new(x: p["x"], y: p["y"])
+      end
+    end
+  end
+end

data/lib/moondream-client/query.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module MoondreamClient
+  class Query
+    # @return [String] The server-generated request identifier.
+    attr_reader :request_id
+
+    # @return [String] The model's answer text.
+    attr_reader :answer
+
+    # Initialize a new Query result object.
+    #
+    # @param attributes [Hash] Raw attributes from the /query endpoint response.
+    # @param client [MoondreamClient::Client]
+    def initialize(attributes, client: MoondreamClient.client)
+      @client = client
+      reset_attributes(attributes)
+    end
+
+    class << self
+      # Ask a question about an image.
+      # Corresponds to POST /query
+      #
+      # @param image_url [String]
+      # @param question [String]
+      # @param client [MoondreamClient::Client]
+      #
+      # @return [MoondreamClient::Query]
+      def create!(image_url:, question:, client: MoondreamClient.client)
+        image_data_url = MoondreamClient::Image.to_data_url(image_url)
+        payload = {
+          image_url: image_data_url,
+          question: question
+        }
+
+        attributes = client.post("/query", payload)
+        new(attributes, client: client)
+      end
+    end
+
+    private
+
+    # Normalize attributes from the /query response.
+    # @param attributes [Hash]
+    # @return [void]
+    def reset_attributes(attributes)
+      @request_id = attributes["request_id"]
+      @answer = attributes["answer"]
+    end
+  end
+end

data/lib/moondream-client/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MoondreamClient
+  VERSION = "0.0.1"
+end

data/lib/moondream-client.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "time"
+
+require_relative "moondream-client/version"
+require_relative "moondream-client/client"
+require_relative "moondream-client/image"
+require_relative "moondream-client/caption"
+require_relative "moondream-client/detect"
+require_relative "moondream-client/point"
+require_relative "moondream-client/query"
+
+module MoondreamClient
+  class Error < StandardError; end
+  class UnauthorizedError < Error; end
+  class NotFoundError < Error; end
+  class ServerError < Error; end
+  class ConfigurationError < Error; end
+  class ForbiddenError < Error; end
+
+  class Configuration
+    DEFAULT_URI_BASE = "https://api.moondream.ai/v1"
+    DEFAULT_REQUEST_TIMEOUT = 120
+
+    # The access token for the API.
+    #
+    # @return [String]
+    attr_accessor :access_token
+
+    # The base URI for the API.
+    #
+    # @return [String]
+    attr_accessor :uri_base
+
+    # The request timeout in seconds.
+    #
+    # @return [Integer]
+    attr_accessor :request_timeout
+
+    def initialize
+      @access_token = ENV.fetch("MOONDREAM_ACCESS_TOKEN", nil)
+      @uri_base = DEFAULT_URI_BASE
+      @request_timeout = DEFAULT_REQUEST_TIMEOUT
+    end
+  end
+
+  class << self
+    # The configuration for the client.
+    #
+    # @return [MoondreamClient::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Allows replacing the configuration object.
+    attr_writer :configuration
+
+    # Configure the client.
+    #
+    # @yield [MoondreamClient::Configuration] The configuration for the client.
+    def configure
+      yield(configuration)
+    end
+
+    # The client for the API.
+    #
+    # @return [MoondreamClient::Client]
+    def client
+      @client ||= Client.new(configuration)
+    end
+  end
+end

data/moondream-client.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/moondream-client/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "moondream-client"
+  spec.version = MoondreamClient::VERSION
+  spec.authors = ["Dylan Player"]
+  spec.email = ["dylan@851.sh"]
+
+  spec.summary = "Ruby client for MoonDream API."
+  spec.homepage = "https://github.com/851-labs/moondream-client"
+  spec.required_ruby_version = ">= 3.3.0"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.license = "MIT"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (f == __FILE__) || f.match(%r{\A(?:(?:bin|test|spec|features)/|\.(?:git|travis|circleci)|appveyor)})
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("faraday", ">= 1")
+  # Base64 becomes a non-default gem in Ruby >= 3.4
+  spec.add_dependency("base64", ">= 0")
+  spec.metadata["rubygems_mfa_required"] = "true"
+end

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification
+name: moondream-client
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Dylan Player
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-10-07 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description:
+email:
+- dylan@851.sh
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".env.example"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- Rakefile
+- lib/moondream-client.rb
+- lib/moondream-client/caption.rb
+- lib/moondream-client/client.rb
+- lib/moondream-client/detect.rb
+- lib/moondream-client/image.rb
+- lib/moondream-client/point.rb
+- lib/moondream-client/query.rb
+- lib/moondream-client/version.rb
+- moondream-client.gemspec
+homepage: https://github.com/851-labs/moondream-client
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/851-labs/moondream-client
+  source_code_uri: https://github.com/851-labs/moondream-client
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.3
+signing_key:
+specification_version: 4
+summary: Ruby client for MoonDream API.
+test_files: []