ruby_llm-providers-qiniu 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b5e7836bffa849ff6b9fd54403b700a8dbaeab2a67a74f3c6cf3b6e1a970ec48
+  data.tar.gz: 2410a9a181ca32639c239935827a41fff116c115e01ba4904b6d4b785a1ae9a9
+SHA512:
+  metadata.gz: 852caaac2b39890efe96174c3597c559649e333a4c942ef2bcfa583e6eb9435950b87d4ec8959062f4b0e6104e634c5777a2d4ed3951e68f56d058943cd29ad7
+  data.tar.gz: 6e7b0361b660c2d92321d947f2e40e845a1d8622b63950f599d9f71f5fa1b43c2848de7cb63615a6cbabe6b0677552d35f214452081a6dc94615929970b61ea3

data/.flayignore

@@ -0,0 +1 @@
+spec/support/streaming_error_helpers.rb

data/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Ruby ${{ matrix.ruby-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby-version: ["4.0"]
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - run: bundle exec rake

data/.github/workflows/gitleaks.yml

@@ -0,0 +1,23 @@
+name: Gitleaks
+
+on:
+  pull_request:
+    branches: ["main"]
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: gitleaks/gitleaks-action@v3
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GITLEAKS_LICENSE: ${{ secrets.GITLEAKS_LICENSE }}

data/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.4"
+          bundler-cache: true
+
+      - run: bundle exec rake
+
+      - name: Build gem
+        run: gem build ruby_llm-providers-qiniu.gemspec
+
+      - name: Publish to RubyGems
+        run: |
+          mkdir -p "$HOME/.gem"
+          touch "$HOME/.gem/credentials"
+          chmod 0600 "$HOME/.gem/credentials"
+          printf -- "---\n:rubygems_api_key: ${GEM_HOST_API_KEY}\n" > "$HOME/.gem/credentials"
+          gem push ruby_llm-providers-qiniu-*.gem
+        env:
+          GEM_HOST_API_KEY: ${{ secrets.RUBYGEMS_AUTH_TOKEN }}

data/.overcommit.yml

@@ -0,0 +1,31 @@
+PreCommit:
+  RuboCop:
+    enabled: true
+    auto_correct: true
+    on_warn: fail
+
+  Flay:
+    enabled: true
+    include:
+      - lib/**/*.rb
+      - spec/**/*.rb
+    mass_threshold: 70
+
+  ArchSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'archspec', 'check']
+    on_warn: fail
+
+  RSpec:
+    enabled: true
+    command: ['bundle', 'exec', 'rspec']
+    on_warn: fail
+
+  TrailingWhitespace:
+    enabled: true
+    auto_correct: true
+
+  Gitleaks:
+    enabled: true
+    required_executable: gitleaks
+    command: ['gitleaks', 'protect', '--staged', '--redact', '--verbose']

data/.rspec

@@ -0,0 +1,2 @@
+--require spec_helper
+--format progress

data/.rubocop.yml

@@ -0,0 +1,29 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rake
+  - rubocop-rspec
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 4.0
+  Exclude:
+    - Archspec.rb
+    - vendor/**/*
+    - gemfiles/**/*
+  SuggestExtensions: false
+
+Metrics/AbcSize:
+  Max: 80
+Metrics/MethodLength:
+  Max: 40
+  CountAsOne:
+    - array
+    - hash
+    - heredoc
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false

data/Archspec.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+source 'lib/**/*.rb'
+
+component :provider,
+          in: %w[
+            lib/ruby_llm/providers/qiniu.rb
+            lib/ruby_llm/providers/qiniu/**/*.rb
+          ],
+          namespace: 'RubyLLM::Providers::Qiniu'
+
+provider.cannot_reference_constants 'RSpec', 'WebMock', 'VCR'
+
+preset :ruby_conventions

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mihuashi
+
+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,114 @@
+# ruby_llm-providers-qiniu (modelink)
+
+RubyLLM provider gem for Qiniu's model gateway (documented at
+[docs.modelink.ai](https://docs.modelink.ai) — Modelink is the overseas
+brand of the same service).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ruby_llm-providers-qiniu', require: 'ruby_llm/providers/qiniu'
+```
+
+Then configure the provider:
+
+```ruby
+require 'ruby_llm/providers/qiniu'
+
+RubyLLM.configure do |config|
+  config.qiniu_api_key = ENV['QINIU_API_KEY']
+  config.qiniu_api_base = ENV.fetch('QINIU_BASE_URL', 'https://api.qnaigc.com')
+end
+```
+
+## Endpoints
+
+Pick one regional entry point per deployment; all of them serve the same
+protocols:
+
+| Region | Base URL | Use when |
+| ------ | -------- | -------- |
+| Mainland China | `https://api.qnaigc.com` | default; lowest latency for China deployments |
+| Overseas | `https://api.modelink.ai` | overseas deployment or cross-border access |
+| Hybrid | `https://xapi.qnaigc.com` | sharing one entry across protocol-different clients |
+
+`qiniu_api_base` is used verbatim — pass the bare host, since each protocol
+path already carries its own version segment (`/v1`, `/bypass/…/v1`, …).
+
+## Protocols
+
+One provider, several wire formats. For chat, RubyLLM prefers each vendor's
+native bypass channel — Claude models use Anthropic Messages, Gemini models
+use GenerateContent, GPT models use Responses — while every other model and
+all auxiliary operations use the OpenAI-compatible endpoint. Override
+globally with `config.qiniu_protocol = :anthropic` or per call:
+
+```ruby
+RubyLLM.chat(model: 'deepseek-v3', provider: :qiniu, protocol: :chat_completions)
+```
+
+| Protocol | Path | Notes |
+| -------- | ---- | ----- |
+| `:chat_completions` (default) | `POST /v1/chat/completions` | All models; also serves model listing at `GET /v1/models` |
+| `:anthropic` | `POST /v1/messages` | Anthropic Messages compat; accepts every model, gateway adapts per channel |
+| `:anthropic_bypass` | `POST /bypass/anthropic/v1/messages` | Claude only; vendor-native Messages semantics |
+| `:gemini_bypass` | `POST /bypass/vertex/v1/models/{model}:{func}` | Gemini only; native GenerateContent (generateContent / streamGenerateContent) |
+| `:responses` | `POST /bypass/openai/v1/responses` | GPT family; OpenAI Responses API |
+
+Only chat is wired up for now — embeddings, images, audio, video, rerank
+and other capabilities raise `RubyLLM::Error` until the corresponding
+endpoints are added.
+
+Prefer the compatible dialects for unified multi-model access. Reach for a
+bypass protocol when you depend on vendor-native fields, streaming events,
+or extended capabilities (Extended Thinking, Prompt Caching, Gemini-native
+tools, Responses). Bypass requests still pass through the gateway's auth,
+routing, rate limiting, and billing — "bypass" only skips the unified
+protocol conversion.
+
+Authentication is `Authorization: Bearer <api_key>` everywhere (the
+Anthropic paths also accept `X-Api-Key`; Bearer alone is sufficient).
+
+## Usage
+
+```ruby
+model = RubyLLM.models.by_provider(:qiniu).chat_models.first
+chat = RubyLLM.chat(model: model.id)
+response = chat.ask('Hello')
+puts response.content
+```
+
+## Notes
+
+- `GET /v1/models` may be called anonymously; the provider still sends
+  credentials when configured. The listing is only a partial catalog — it
+  omits whole vendors such as Claude, Gemini and GPT and exposes no
+  capabilities or pricing — which is why `models.json` is maintained by
+  hand from the official docs.
+- Batch inference (`/v1/batchjob/inference`), FAL-format async media
+  (`/queue/...`), AK/SK management endpoints, and Volcengine asset signing
+  are service-specific APIs this provider does not wrap.
+- The hybrid endpoint converts between protocols but may not preserve every
+  vendor-native field or streaming event; verify tool calls, thinking,
+  caching, structured output, and multimodal inputs with real requests
+  before production use.
+
+## Development
+
+The generator installs the bundle and creates an ignored `.env`. Edit the generated `op read` reference so it points to your 1Password credential. If you do not use the 1Password CLI, replace the expression with the provider key.
+
+```sh
+bundle exec rake
+```
+
+The packaged `models.json` at the gem root is maintained by hand from the official catalog at [modelink.ai/models](https://modelink.ai/models) — `GET /v1/models` is too thin to generate it, since the listing omits whole vendors (no Claude, Gemini or GPT entries) and carries no context windows, capabilities or pricing. RubyLLM loads that catalog as a fallback when this provider is registered, so applications do not need to combine registry files. The main RubyLLM registry always wins when both catalogs carry the same model. If the API grows a richer listing path, update `models_url` in `lib/ruby_llm/providers/qiniu.rb`.
+
+Edit `models.json` directly when you want to update the packaged catalog. `RubyLLM.models.refresh` updates the application's main registry and does not refresh provider gem catalogs.
+
+If the packaged catalog is ever dropped, uncomment `assume_models_exist?` in the provider so chats can start against unlisted models.
+
+The suite always runs the provider integration specs. The first local run calls the API and records VCR cassettes; CI only replays committed cassettes. A failing example deletes its cassette so the next local run tests the live API again.
+
+After updating the catalog, add real model IDs to `spec/support/models.rb`. Keep only the operation matrices the provider supports. The portable contract specs are adapted from [RubyLLM's live specs](https://github.com/crmne/ruby_llm/tree/main/spec/ruby_llm); use those as the reference when your provider needs coverage for another feature or dialect.

data/lib/ruby_llm/providers/qiniu.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+module RubyLLM
+  module Providers
+    # Qiniu API integration (documented at https://docs.modelink.ai —
+    # Modelink is the overseas brand of the same gateway).
+    #
+    # The gateway serves several access styles on the same regional host:
+    #
+    # - OpenAI Chat Completions compatible API under /v1 (chat and model
+    #   listing)
+    # - Anthropic Messages compatible API at /v1/messages, which accepts
+    #   every chat model and lets the gateway adapt per-channel
+    # - Native protocol bypass endpoints that keep vendor-native wire
+    #   formats: /bypass/anthropic (Claude only), /bypass/vertex (Gemini),
+    #   /bypass/openai (Responses and Images)
+    #
+    # All regional endpoints speak the same protocols; pick one with
+    # qiniu_api_base:
+    #
+    # - https://api.qnaigc.com   — mainland China (default)
+    # - https://api.modelink.ai  — overseas
+    # - https://xapi.qnaigc.com  — hybrid multi-protocol entry
+    class Qiniu < Provider
+      # OpenAI Chat Completions-compatible dialect under /v1. This is the
+      # default protocol and the only one used for model listing.
+      class ChatCompletions < Protocols::ChatCompletions
+        private
+
+        def completion_url
+          'v1/chat/completions'
+        end
+
+        def models_url
+          'v1/models'
+        end
+      end
+
+      # OpenAI Responses native bypass at /bypass/openai/v1/responses for
+      # GPT-family models. count_tokens_url and compaction_url derive from
+      # completion_url.
+      class ResponsesBypass < Protocols::Responses
+        private
+
+        def completion_url
+          'bypass/openai/v1/responses'
+        end
+      end
+
+      # Anthropic native bypass at /bypass/anthropic/v1/messages. Claude
+      # models only; request and streaming events stay vendor-native.
+      class AnthropicBypass < Protocols::Anthropic
+        private
+
+        def completion_url
+          'bypass/anthropic/v1/messages'
+        end
+
+        def count_tokens_url
+          'bypass/anthropic/v1/messages/count_tokens'
+        end
+      end
+
+      # Vertex/Gemini native bypass at /bypass/vertex/v1/models/{m}:{func}.
+      # Gemini models only; keeps the GenerateContent wire format.
+      class GeminiBypass < Protocols::Gemini
+        private
+
+        def completion_url
+          vertex_url(super)
+        end
+
+        def stream_url
+          vertex_url(super)
+        end
+
+        def count_tokens_url
+          vertex_url(super)
+        end
+
+        def vertex_url(path)
+          "bypass/vertex/v1/#{path}"
+        end
+      end
+
+      protocol :chat_completions, ChatCompletions
+      protocol :anthropic, Protocols::Anthropic
+      protocol :responses, ResponsesBypass
+      protocol :anthropic_bypass, AnthropicBypass
+      protocol :gemini_bypass, GeminiBypass
+
+      def api_base
+        @config.qiniu_api_base || 'https://api.qnaigc.com'
+      end
+
+      def headers
+        { 'Authorization' => "Bearer #{@config.qiniu_api_key}" }
+      end
+
+      # Chat prefers each vendor's native bypass channel — Claude via
+      # Anthropic Messages, Gemini via GenerateContent, GPT via Responses —
+      # and everything else uses the OpenAI-compatible endpoint. Auxiliary
+      # operations (embeddings, images, audio, …) only exist on the
+      # compatible layout. Override globally with config.qiniu_protocol or
+      # per call with protocol: (e.g. :anthropic for the Messages compat
+      # layer, :chat_completions to force the compatible dialect).
+      def protocol_for(model, operation: nil, **)
+        return super if operation
+
+        case model_id_for(model).to_s
+        when /claude/i then protocols[:anthropic_bypass]
+        when /gemini/i then protocols[:gemini_bypass]
+        when %r{(?:\A|/)(?:gpt|o\d)}i then protocols[:responses]
+        else super
+        end
+      end
+
+      class << self
+        def configuration_options
+          %i[qiniu_api_key qiniu_api_base]
+        end
+
+        def configuration_requirements
+          %i[qiniu_api_key]
+        end
+      end
+    end
+  end
+end
+
+RubyLLM::Provider.register :qiniu, RubyLLM::Providers::Qiniu,
+                           models: File.expand_path('../../../models.json', __dir__)