buble 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a7f0b94c29ce6c1dac4973776d3963d6c5089930b6401a6a4dfd770bb204860
+  data.tar.gz: d5235b3f9911f2f731f9d09902e198887464e7cecd8e1743bd3b2b5df5f3289b
+SHA512:
+  metadata.gz: 54f916c30d5162bd18582f01cfd1c33f902d2ea64517e6727dc756621146c8d67a0ff6fe5fd153843df9c84acef6ccc82782ca133ef64965cb26d2f38d91215b
+  data.tar.gz: befb6e7610c07676ed1ced3ee4ac6a8e2bc366dd044629536d49a6acf45bb27235e3c37ba8e771ed1ccf85c11985d472b04346af219ea2ef581e72da51258520

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Buble
+
+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,273 @@
+# Buble SDK for Ruby
+
+Official Ruby SDK for [Buble](https://buble.ai/), built for the [Buble public API](https://buble.ai/docs).
+
+Use this SDK from server-side Ruby applications to discover media models, upload source media, create asynchronous image and video generation tasks, run preconfigured Buble app workflows, and call chat models through OpenAI, Anthropic Messages, and Gemini-compatible API formats.
+
+Keep API keys on the server. Do not expose `BUBLE_API_KEY` in browser, mobile, or other client-side code.
+
+## Installation
+
+After publication to RubyGems:
+
+```bash
+gem install buble
+```
+
+Bundler:
+
+```ruby
+gem "buble"
+```
+
+The gem requires Ruby 3.3+ and has no runtime dependencies outside the Ruby standard library.
+
+## Quick Start
+
+Set your API key:
+
+```bash
+export BUBLE_API_KEY="sk_..."
+```
+
+The generation examples below create real Buble generation tasks and may consume credits.
+
+```ruby
+require "buble"
+
+client = Buble::Client.new
+
+task = client.generations.create(
+  model: "google/nano-banana",
+  mode: "text_to_image",
+  prompt: "A cinematic product photo of a matte black espresso cup",
+  aspect_ratio: "1:1",
+  output_format: "png"
+)
+
+result = client.generations.wait(task.dig("data", "id"))
+puts result.dig("data", "result", "images", 0, "url")
+```
+
+The client reads `BUBLE_API_KEY` and `BUBLE_BASE_URL` from the environment when omitted.
+
+## Configuration
+
+```ruby
+client = Buble::Client.new(
+  api_key: "sk_...",
+  base_url: "https://buble.ai",
+  timeout: 60,
+  headers: {
+    "X-Request-Id" => "request-id"
+  }
+)
+```
+
+## Discover Media Models
+
+```ruby
+models = client.media_models.list(media_type: "video")
+
+models.fetch("data", []).each do |model|
+  puts model["model"]
+end
+```
+
+Use media model discovery as the source of truth for model keys, modes, required inputs, and public parameters. New Buble models can become available without an SDK release.
+
+## Upload Files
+
+```ruby
+upload = Buble::FileUpload.from_path("reference.png", content_type: "image/png")
+
+uploaded = client.files.upload(
+  upload,
+  file_type: "image",
+  model: "google/nano-banana",
+  mode: "image_to_image"
+)
+
+task = client.generations.create(
+  model: "google/nano-banana",
+  mode: "image_to_image",
+  prompt: "Turn this reference into a polished ecommerce hero image.",
+  image_urls: [uploaded.dig("data", "url")]
+)
+```
+
+Uploads support local paths, IO objects, and `Buble::FileUpload`. Path uploads are streamed from disk.
+
+## Video Generation
+
+```ruby
+task = client.generations.create(
+  model: "gork/grok-imagine-video",
+  mode: "text_to_video",
+  prompt: "A slow cinematic shot of a futuristic train station at sunrise.",
+  duration: "5s",
+  resolution: "480p",
+  aspect_ratio: "16:9"
+)
+
+result = client.generations.wait(
+  task.dig("data", "id"),
+  interval: 2,
+  timeout: 900
+)
+
+puts result.dig("data", "result", "videos", 0, "url")
+```
+
+Generation request bodies use Buble's flat public API shape. Put model-specific controls in keyword arguments; the SDK serializes those controls at the JSON request root.
+
+Do not send internal Buble fields such as `input`, `options`, `scene`, `sub_mode_id`, `provider`, `mediaType`, or `media_type`.
+
+## Apps
+
+```ruby
+app = client.apps.retrieve("video-background-remover")
+puts app.dig("data", "input_parameters")
+
+task = client.apps.generations.create("video-background-remover", {
+  "source_video" => ["https://example.com/source.mp4"],
+  "refine_foreground_edges" => true,
+  "subject_is_person" => true
+})
+
+result = client.apps.generations.wait("video-background-remover", task.dig("data", "id"))
+```
+
+Apps are preconfigured workflows. Only send parameter names returned by `client.apps.list` or `client.apps.retrieve(...)`.
+
+## Chat
+
+### OpenAI-Compatible
+
+```ruby
+completion = client.chat.completions.create(
+  model: "openai/gpt-5.4",
+  messages: [
+    { role: "user", content: "Write a short launch summary." }
+  ],
+  max_completion_tokens: 800
+)
+
+puts completion.dig("choices", 0, "message", "content")
+```
+
+### Streaming
+
+```ruby
+client.chat.completions.stream_text(
+  model: "openai/gpt-5.4",
+  messages: [
+    { role: "user", content: "Write one sentence at a time." }
+  ]
+).each do |text|
+  print text
+end
+```
+
+### Anthropic-Compatible
+
+```ruby
+message = client.chat.messages.create(
+  model: "openai/gpt-5.4",
+  system: "You are concise.",
+  messages: [
+    { role: "user", content: "Summarize this release." }
+  ],
+  max_tokens: 800
+)
+```
+
+### Gemini-Compatible
+
+```ruby
+response = client.chat.gemini.generate_content("openai/gpt-5.4", {
+  contents: [
+    {
+      role: "user",
+      parts: [
+        { text: "Write a short launch summary." }
+      ]
+    }
+  ]
+})
+```
+
+Gemini streaming uses `stream_generate_content`, not `stream: true` on `generate_content`.
+
+Chat methods preserve protocol-native response shapes as Ruby Hashes with string keys.
+
+## Error Handling
+
+```ruby
+begin
+  client.generations.retrieve("task_id")
+rescue Buble::APIError => error
+  warn error.status
+  warn error.code
+  warn error.message
+  warn error.details
+end
+
+begin
+  client.generations.wait("task_id")
+rescue Buble::GenerationFailedError => error
+  warn error.task["error"]
+end
+```
+
+## Development
+
+```bash
+cd ruby
+bundle install
+bundle exec rake test
+bundle exec rubocop
+gem build buble.gemspec
+```
+
+Live smoke test:
+
+```bash
+BUBLE_API_KEY=sk_... ruby -Ilib tools/live_smoke.rb
+```
+
+The live smoke test calls discovery and chat endpoints only and does not create billable generation tasks.
+
+## Publishing Checklist
+
+RubyGems package identity:
+
+- Gem name: `buble`
+- Namespace: `Buble`
+- License: MIT
+- Homepage: `https://buble.ai/`
+
+Build and publish:
+
+```bash
+cd ruby
+bundle exec rake test
+bundle exec rubocop
+gem build buble.gemspec
+```
+
+Publication is handled by the monorepo `Release Ruby SDK` GitHub Actions workflow. Configure RubyGems Trusted Publishing for:
+
+- Repository owner: `bublehq`
+- Repository name: `sdks`
+- Workflow filename: `release-ruby-sdk.yml`
+- Environment: `release`
+
+Then publish from the monorepo with:
+
+```bash
+git tag ruby-v0.1.0
+git push origin ruby-v0.1.0
+```
+
+RubyGems versions are immutable. After `0.1.0` is published, fixes must use a new version such as `0.1.1`.

data/docs/technical-design.md

@@ -0,0 +1,145 @@
+# Buble Ruby SDK Technical Design
+
+## Goals
+
+The Ruby SDK mirrors the public Buble API in the same style as the existing JavaScript, Python, Go, Java, .NET, and PHP SDKs.
+
+The SDK should:
+
+- Keep the public API shape close to Buble's HTTP API.
+- Preserve protocol-native chat response shapes.
+- Use flat generation request bodies.
+- Reject internal Buble workflow fields before sending requests.
+- Avoid runtime dependencies outside the Ruby standard library.
+- Be safe for server-side use and never encourage client-side API key exposure.
+
+## Package Shape
+
+The gem is named `buble` and exposes the `Buble` namespace.
+
+Primary entry point:
+
+```ruby
+require "buble"
+
+client = Buble::Client.new
+```
+
+The package root contains the gemspec and build metadata. Runtime source lives under `lib/`.
+
+## HTTP Layer
+
+`Buble::HTTP` is a small wrapper around `Net::HTTP`.
+
+Responsibilities:
+
+- Resolve base URL and paths.
+- Add bearer token authentication.
+- Encode query strings.
+- Encode JSON request bodies.
+- Decode JSON responses.
+- Raise `Buble::APIError` for non-2xx responses.
+- Send multipart file uploads.
+- Stream SSE response lines.
+
+The SDK intentionally avoids Faraday or other HTTP dependencies. This keeps installation lightweight and reduces dependency surface for Rails and non-Rails server applications.
+
+## Resources
+
+Resources map directly to API areas:
+
+- `Buble::MediaModelsResource`
+- `Buble::FilesResource`
+- `Buble::GenerationsResource`
+- `Buble::AppsResource`
+- `Buble::AppGenerationsResource`
+- `Buble::ChatResource`
+- `Buble::ChatModelsResource`
+- `Buble::ChatCompletionsResource`
+- `Buble::MessagesResource`
+- `Buble::GeminiResource`
+
+Responses are Ruby Hashes with string keys. This preserves Buble API response shapes and avoids symbolizing arbitrary server-provided keys.
+
+## Generation Requests
+
+Generation requests use keyword arguments for stable fields and `**params` for model-specific controls:
+
+```ruby
+client.generations.create(
+  model: "google/nano-banana",
+  mode: "text_to_image",
+  prompt: "A product photo",
+  aspect_ratio: "1:1",
+  output_format: "png"
+)
+```
+
+The resulting HTTP body is flat:
+
+```json
+{
+  "model": "google/nano-banana",
+  "mode": "text_to_image",
+  "prompt": "A product photo",
+  "aspect_ratio": "1:1",
+  "output_format": "png"
+}
+```
+
+The SDK rejects internal fields:
+
+- `input`
+- `options`
+- `scene`
+- `sub_mode_id`
+- `subModeId`
+- `provider`
+- `mediaType`
+- `media_type`
+- `images`
+- `image_input`
+- `video_input`
+- `audio_input`
+
+## Streaming
+
+`Buble::Streaming::SSEParser` parses server-sent event lines into `Buble::Streaming::Event` objects.
+
+Text helpers extract deltas for:
+
+- OpenAI-compatible chat: `choices[0].delta.content`
+- Anthropic-compatible messages: `delta.text`
+- Gemini-compatible chat: `candidates[0].content.parts[0].text`
+
+The lower-level `stream` APIs expose parsed SSE events for callers that need protocol details.
+
+## Errors
+
+The error hierarchy is:
+
+- `Buble::Error`
+- `Buble::APIError`
+- `Buble::TimeoutError`
+- `Buble::GenerationFailedError`
+- `Buble::GenerationCanceledError`
+- `Buble::UnsupportedGenerationFieldError`
+
+`APIError` carries HTTP status, API error code, details, and raw response body.
+
+## Testing
+
+Unit tests use Minitest and `FakeTransport`.
+
+Coverage focuses on:
+
+- Request paths and bodies.
+- Flat generation request serialization.
+- Forbidden generation field rejection.
+- Wait polling behavior.
+- Multipart upload shape.
+- App generation paths.
+- Chat response preservation.
+- SSE parsing and text extraction.
+
+Live smoke tests are intentionally limited to low-cost discovery and chat checks.

data/examples/anthropic_messages.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'buble'
+
+client = Buble::Client.new
+
+message = client.chat.messages.create(
+  model: 'openai/gpt-5.4',
+  system: 'You are concise.',
+  messages: [
+    { role: 'user', content: 'Summarize this release.' }
+  ],
+  max_tokens: 800
+)
+
+puts message

data/examples/app_generation.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require 'buble'
+
+client = Buble::Client.new
+
+task = client.apps.generations.create('video-background-remover', {
+                                        'source_video' => ['https://example.com/source.mp4'],
+                                        'refine_foreground_edges' => true,
+                                        'subject_is_person' => true
+                                      })
+
+result = client.apps.generations.wait('video-background-remover', task.dig('data', 'id'))
+puts result.dig('data', 'result', 'videos', 0, 'url')

data/examples/gemini_generate.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'buble'
+
+client = Buble::Client.new
+
+response = client.chat.gemini.generate_content('openai/gpt-5.4', {
+                                                 contents: [
+                                                   {
+                                                     role: 'user',
+                                                     parts: [
+                                                       { text: 'Write a short launch summary.' }
+                                                     ]
+                                                   }
+                                                 ]
+                                               })
+
+puts response

data/examples/image_to_image.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'buble'
+
+client = Buble::Client.new
+
+uploaded = client.files.upload(
+  Buble::FileUpload.from_path('reference.png', content_type: 'image/png'),
+  file_type: 'image',
+  model: 'google/nano-banana',
+  mode: 'image_to_image'
+)
+
+task = client.generations.create(
+  model: 'google/nano-banana',
+  mode: 'image_to_image',
+  prompt: 'Turn this reference into a polished ecommerce hero image.',
+  image_urls: [uploaded.dig('data', 'url')]
+)
+
+result = client.generations.wait(task.dig('data', 'id'))
+puts result.dig('data', 'result', 'images', 0, 'url')

data/examples/openai_chat.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'buble'
+
+client = Buble::Client.new
+
+completion = client.chat.completions.create(
+  model: 'openai/gpt-5.4',
+  messages: [
+    { role: 'user', content: 'Write a short launch summary.' }
+  ],
+  max_completion_tokens: 800
+)
+
+puts completion.dig('choices', 0, 'message', 'content')

data/examples/text_to_image.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'buble'
+
+client = Buble::Client.new
+
+task = client.generations.create(
+  model: 'google/nano-banana',
+  mode: 'text_to_image',
+  prompt: 'A cinematic product photo of a matte black espresso cup',
+  aspect_ratio: '1:1',
+  output_format: 'png'
+)
+
+result = client.generations.wait(task.dig('data', 'id'))
+puts result.dig('data', 'result', 'images', 0, 'url')

data/examples/text_to_video.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'buble'
+
+client = Buble::Client.new
+
+task = client.generations.create(
+  model: 'gork/grok-imagine-video',
+  mode: 'text_to_video',
+  prompt: 'A slow cinematic shot of a futuristic train station at sunrise.',
+  duration: '5s',
+  resolution: '480p',
+  aspect_ratio: '16:9'
+)
+
+result = client.generations.wait(task.dig('data', 'id'), interval: 2, timeout: 900)
+puts result.dig('data', 'result', 'videos', 0, 'url')

data/lib/buble/apps.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Buble
+  class AppGenerationsResource
+    TERMINAL_STATUSES = GenerationsResource::TERMINAL_STATUSES
+
+    def initialize(http)
+      @http = http
+    end
+
+    def create(app_id, params = {})
+      @http.request('POST', "/api/v1/apps/#{HTTP.encode_segment(app_id)}/generations", body: params)
+    end
+
+    def retrieve(app_id, id)
+      @http.request('GET', "/api/v1/apps/#{HTTP.encode_segment(app_id)}/generations/#{HTTP.encode_segment(id)}")
+    end
+
+    def wait(app_id, id, interval: 2, timeout: 600, throw_on_failed: true, throw_on_canceled: true)
+      deadline = Time.now + timeout
+
+      loop do
+        envelope = retrieve(app_id, id)
+        task = envelope['data'] || {}
+        status = task['status']
+        if TERMINAL_STATUSES.include?(status)
+          raise_if_terminal_error!(id, task, status, throw_on_failed, throw_on_canceled)
+          return envelope
+        end
+
+        if Time.now >= deadline
+          raise TimeoutError.new(
+            "App generation #{id} did not finish within #{timeout} seconds.",
+            timeout: timeout
+          )
+        end
+
+        sleep interval
+      end
+    end
+
+    private
+
+    def raise_if_terminal_error!(id, task, status, throw_on_failed, throw_on_canceled)
+      if status == 'failed' && throw_on_failed
+        error = task['error'] || {}
+        raise GenerationFailedError.new(error['message'] || 'Generation failed.', task: task)
+      end
+
+      return unless status == 'canceled' && throw_on_canceled
+
+      raise GenerationCanceledError.new("App generation #{id} was canceled.", task: task)
+    end
+  end
+
+  class AppsResource
+    attr_reader :generations
+
+    def initialize(http)
+      @http = http
+      @generations = AppGenerationsResource.new(http)
+    end
+
+    def list
+      @http.request('GET', '/api/v1/apps')
+    end
+
+    def retrieve(app_id)
+      @http.request('GET', "/api/v1/apps/#{HTTP.encode_segment(app_id)}")
+    end
+  end
+end