moondream 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e6517c2a26933df4d90f35faf461db043b59967911564754bc21b88231907d9
+  data.tar.gz: 42957d853162200c52f676a932699db827c9394ad9ab6d006ab4e8c0f108b8cc
+SHA512:
+  metadata.gz: a7650ea40cce0c8212b696c667c65abecfa09e7d8ebad249086bcfd28326e7e6d246d996bd6e4b0d12c08ff6371b75e97a9715f9acfbb299843625caf96bebb5
+  data.tar.gz: cae3f7c18aa6f40bfff2adbd151f7d2df1a33f5c38412dfa171bc588114a601bbbc1700e3441f1f9cc789874cebc4e054b89bda979f69f5be4336a34bcbd014f

data/.gitignore

@@ -0,0 +1,53 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+# Used by dotenv library to load environment variables.
+.env
+
+# Ignore Byebug command history file.
+.byebug_history
+
+## Specific to RubyMotion:
+.dat*
+.repl_history
+build/
+*.bridgesupport
+build-iPhoneOS/
+build-iPhoneSimulator/
+
+## Specific to RubyMotion (use of CocoaPods):
+Pods/
+vendor/bundle/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc
+
+# Used by RuboCop. Remote config files pulled in from inherit_from directive.
+.rubocop-https?--*
+

data/.rspec

@@ -0,0 +1,4 @@
+--require spec_helper
+--color
+--format documentation
+

data/.rspec_status

@@ -0,0 +1,21 @@
+example_id                               | status | run_time        |
+---------------------------------------- | ------ | --------------- |
+./spec/moondream/client_spec.rb[1:1:1]   | passed | 0.00045 seconds |
+./spec/moondream/client_spec.rb[1:1:2]   | passed | 0.00076 seconds |
+./spec/moondream/client_spec.rb[1:2:1]   | passed | 0.0159 seconds  |
+./spec/moondream/client_spec.rb[1:2:2]   | passed | 0.00032 seconds |
+./spec/moondream/client_spec.rb[1:2:3]   | passed | 0.00032 seconds |
+./spec/moondream/client_spec.rb[1:3:1]   | passed | 0.00052 seconds |
+./spec/moondream/client_spec.rb[1:3:2]   | passed | 0.00023 seconds |
+./spec/moondream/client_spec.rb[1:3:3]   | passed | 0.00032 seconds |
+./spec/moondream/client_spec.rb[1:4:1]   | passed | 0.00039 seconds |
+./spec/moondream/client_spec.rb[1:4:2]   | passed | 0.00027 seconds |
+./spec/moondream/client_spec.rb[1:4:3]   | passed | 0.00029 seconds |
+./spec/moondream/client_spec.rb[1:5:1:1] | passed | 0.00016 seconds |
+./spec/moondream/client_spec.rb[1:5:1:2] | passed | 0.00042 seconds |
+./spec/moondream/client_spec.rb[1:5:1:3] | passed | 0.00025 seconds |
+./spec/moondream/client_spec.rb[1:5:1:4] | passed | 0.00032 seconds |
+./spec/moondream/client_spec.rb[1:5:2:1] | passed | 0.00207 seconds |
+./spec/moondream/client_spec.rb[1:5:2:2] | passed | 0.00066 seconds |
+./spec/moondream/client_spec.rb[1:6:1:1] | passed | 0.00468 seconds |
+./spec/moondream/client_spec.rb[1:6:2:1] | passed | 0.00169 seconds |

data/.rubocop.yml

@@ -0,0 +1,45 @@
+AllCops:
+  TargetRubyVersion: 2.7
+  NewCops: enable
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+
+# Disable style cops for spec files
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+    - '*.gemspec'
+
+# Allow empty blocks in specs for testing purposes
+Lint/EmptyBlock:
+  Exclude:
+    - 'spec/**/*.rb'
+
+# Disable development dependency warnings in gemspec
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# Allow missing documentation in specs
+Style/Documentation:
+  Enabled: false
+
+# Allow optional boolean parameters
+Style/OptionalBooleanParameter:
+  Enabled: false
+
+# Allow slightly longer methods for API clients
+Metrics/MethodLength:
+  Max: 15
+
+Metrics/AbcSize:
+  Max: 18
+

data/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in moondream.gemspec
+gemspec
+
+gem "httparty", "~> 0.21.0"
+gem "rake", "~> 13.0"
+gem "rspec", "~> 3.0"
+gem "rubocop", "~> 1.21"
+gem "webmock", "~> 3.18"

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Your Name
+
+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,185 @@
+# Moondream Ruby Client
+
+A Ruby gem for interacting with the [Moondream API](https://moondream.ai), a powerful vision-language model for image understanding. This gem provides a simple interface for querying images, detecting objects, pointing to objects, and generating captions.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'moondream'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself with:
+
+```bash
+$ gem install moondream
+```
+
+## Configuration
+
+First, obtain an API key from [Moondream](https://moondream.ai). Then initialize the client:
+
+```ruby
+require 'moondream'
+
+client = Moondream::Client.new(api_key: "your_api_key_here")
+```
+
+## Usage
+
+### Query an Image
+
+Ask questions about an image using natural language:
+
+```ruby
+response = client.query(
+  "https://example.com/image.jpg",
+  "What is in this image?"
+)
+puts response
+```
+
+### Detect Objects
+
+Detect specific objects in an image and get their locations:
+
+```ruby
+response = client.detect(
+  "https://example.com/image.jpg",
+  "person"
+)
+puts response
+```
+
+### Point to Objects
+
+Get the coordinates of specific objects in an image:
+
+```ruby
+response = client.point(
+  "https://example.com/image.jpg",
+  "the red car"
+)
+puts response
+```
+
+### Generate Captions
+
+Generate descriptive captions for images:
+
+```ruby
+# Normal length caption
+response = client.caption(
+  image_url: "https://example.com/image.jpg",
+  length: "normal"
+)
+puts response
+
+# Short caption
+response = client.caption(
+  image_url: "https://example.com/image.jpg",
+  length: "short"
+)
+puts response
+```
+
+### Streaming Captions
+
+For real-time caption generation, you can use streaming mode:
+
+```ruby
+client.caption(
+  image_url: "https://example.com/image.jpg",
+  length: "normal",
+  stream: true
+) do |response|
+  response.read_body do |chunk|
+    print chunk
+  end
+end
+```
+
+## API Methods
+
+### `initialize(api_key:)`
+
+Creates a new Moondream client instance.
+
+**Parameters:**
+- `api_key` (String, required): Your Moondream API key
+
+### `query(image_url, prompt)`
+
+Query an image with a natural language prompt.
+
+**Parameters:**
+- `image_url` (String): URL of the image to analyze
+- `prompt` (String): The question or prompt about the image
+
+**Returns:** String response from the API
+
+### `detect(image_url, object)`
+
+Detect objects in an image.
+
+**Parameters:**
+- `image_url` (String): URL of the image to analyze
+- `object` (String): The object to detect
+
+**Returns:** String response from the API with detection results
+
+### `point(image_url, object)`
+
+Get coordinates pointing to specific objects in an image.
+
+**Parameters:**
+- `image_url` (String): URL of the image to analyze
+- `object` (String): The object to point to
+
+**Returns:** String response from the API with coordinate information
+
+### `caption(image_url:, length:, stream:)`
+
+Generate a caption for an image.
+
+**Parameters:**
+- `image_url` (String, required): URL of the image to caption
+- `length` (String, optional): Caption length - "normal" or "short" (default: "normal")
+- `stream` (Boolean, optional): Enable streaming mode (default: false)
+
+**Returns:** String response from the API, or yields response chunks if streaming with a block
+
+## Error Handling
+
+The gem raises `Moondream::Error` for API-related errors. Wrap your calls in error handling:
+
+```ruby
+begin
+  response = client.query(image_url, prompt)
+  puts response
+rescue Moondream::Error => e
+  puts "Error: #{e.message}"
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` 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](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/moondream-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "moondream"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here
+

data/lib/moondream/client.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require_relative "version"
+require "httparty"
+require "net/http"
+require "json"
+
+# This module contains the Moondream client to use the Moondream API
+# to run inference on image querying, detection, pointing, and captioning.
+module Moondream
+  class Error < StandardError; end
+
+  class Client
+    attr_reader :api_key
+
+    BASE_URL = "https://api.moondream.ai/v1"
+
+    # @param api_key [String] The API key to use for the client
+    # @return [Moondream::Client] The client instance
+    def initialize(api_key:)
+      @api_key = api_key
+    end
+
+    # @param image_url [String] The URL of the image to query
+    # @param prompt [String] The prompt to query the image with
+    # @return [String] The response from the API
+    def query(image_url, prompt)
+      response = HTTParty.post(
+        "#{BASE_URL}/query",
+        body: { image_url: image_url, prompt: prompt },
+        headers: { "Authorization" => "Bearer #{api_key}" }
+      )
+
+      response.body
+    end
+
+    # @param image_url [String] The URL of the image to detect objects in
+    # @param object [String] The object to detect in the image
+    # @return [String] The response from the API
+    def detect(image_url, object)
+      response = HTTParty.post(
+        "#{BASE_URL}/detect",
+        body: { image_url: image_url, object: object },
+        headers: { "Authorization" => "Bearer #{api_key}" }
+      )
+
+      response.body
+    end
+
+    # @param image_url [String] The URL of the image to point to
+    # @param object [String] The object to point to in the image
+    # @return [String] The response from the API
+    def point(image_url, object)
+      response = HTTParty.post(
+        "#{BASE_URL}/point",
+        body: { image_url: image_url, object: object },
+        headers: { "Authorization" => "Bearer #{api_key}" }
+      )
+
+      response.body
+    end
+
+    # In this method, we're using the native Net::HTTP so that the stream support can be supported.
+    # The usage of this function if stream=true is:
+    # client = Moondream::Client.new(api_key: "your_api_key")
+    # client.caption("https://example.com/image.jpg", "normal", true) do |response|
+    #   response.read_body do |chunk|
+    #     puts chunk # or do something else with the chunk
+    #   end
+    # end
+    #
+    # @param image_url [String] The URL of the image to caption
+    # @param length [String] The length of the caption, "normal" or "short"
+    # @param stream [Boolean] Whether to stream the response, default is false
+    # @return [String] The response from the API
+    def caption(image_url: nil, length: "normal", stream: false)
+      if image_url.nil?
+        raise ArgumentError, "image_url is required"
+      end
+
+      uri = URI("#{BASE_URL}/caption")
+
+      result = nil
+      Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https") do |http|
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = { image_url: image_url, length: length, stream: stream }.to_json
+
+        http.request(request) do |response|
+          yield response if stream && block_given?
+          result = response.body
+        end
+      end
+      result
+    end
+  end
+end

data/lib/moondream/version.rb

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

data/moondream.gemspec

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "lib/moondream/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "moondream"
+  spec.version       = Moondream::VERSION
+  spec.authors       = ["Yasu Flores"]
+  spec.email         = ["consulting@yasuflores.me"]
+
+  spec.summary       = "Ruby client for Moondream"
+  spec.description   = "A Ruby gem for interacting with Moondream"
+  spec.homepage      = "https://github.com/yasuf/moondream-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 2.7.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/yasuf/moondream-ruby"
+  spec.metadata["changelog_uri"] = "https://github.com/yasuf/moondream-ruby/blob/master/README.md"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+
+  spec.require_paths = ["lib"]
+
+  # Runtime dependencies
+  spec.add_dependency "httparty", "~> 0.21.0"
+
+  # Development dependencies
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

metadata

@@ -0,0 +1,130 @@
+--- !ruby/object:Gem::Specification
+name: moondream
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yasu Flores
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-10-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.21'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A Ruby gem for interacting with Moondream
+email:
+- consulting@yasuflores.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rspec_status"
+- ".rubocop.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/moondream/client.rb
+- lib/moondream/version.rb
+- moondream.gemspec
+homepage: https://github.com/yasuf/moondream-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/yasuf/moondream-ruby
+  source_code_uri: https://github.com/yasuf/moondream-ruby
+  changelog_uri: https://github.com/yasuf/moondream-ruby/blob/master/README.md
+  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: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Ruby client for Moondream
+test_files: []