aihub2api 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5c217a92bc821e354fc53232edfc94dce1648768f4c4b74df6deebde8d8d457a
+  data.tar.gz: 2453613e660708d21d575b732ba942272e5ef90d94f175fd3e2c95923734e738
+SHA512:
+  metadata.gz: cd0a82f063d233e77f77cf3538700e0b49b152d17dccada3cac650fb750d17c5fc3b6e1e1cc1124afe87c8f75c7a13b0ac5e2b01a468c7ee5a56f737de96230f
+  data.tar.gz: d86e7798444be0d2231346e55dd8160398a07cd78a597df0ccccc25ce628dfc11a32f4fd2886f7b475c443ac2ac965a7f962f7eeb7abee753d510d8a464427ca

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AIHub
+
+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,78 @@
+# AIHub2API for Ruby
+
+`aihub2api` is a small, dependency-free Ruby client and command-line preflight
+checker for the [AIHub OpenAI-compatible API](https://aihub2api.cloud/?utm_source=rubygems&utm_medium=readme&utm_campaign=westdev).
+It can check the public health endpoint, list models with your own API key, and
+send Chat Completions or Responses requests. API keys are read from the
+environment and are never printed by the client.
+
+AIHub is an independent third-party gateway. It is not affiliated with or
+endorsed by OpenAI. The service is intended only for users outside mainland
+China.
+
+## Install
+
+```bash
+gem install aihub2api
+```
+
+## Preflight check
+
+The health check does not need a key:
+
+```bash
+aihub2api check
+```
+
+To query the authenticated model list:
+
+```bash
+export AIHUB_API_KEY='your-key'
+aihub2api models
+aihub2api check --model gpt-5.6-sol
+```
+
+The AIHub operator reports availability of `gpt-5.6-sol`. Treat the output of
+the authenticated `/v1/models` endpoint as authoritative for your account at
+the time of use.
+
+## Ruby usage
+
+```ruby
+require "aihub2api"
+
+client = AIHub2API::Client.new(api_key: ENV.fetch("AIHUB_API_KEY"))
+
+puts client.model_ids
+
+result = client.chat_completions(
+  model: "gpt-5.6-sol",
+  messages: [{ role: "user", content: "Reply with exactly: connection ok" }],
+)
+
+puts result.dig("choices", 0, "message", "content")
+```
+
+You can test another OpenAI-compatible endpoint without changing code:
+
+```bash
+AIHUB_BASE_URL='https://your-gateway.example' aihub2api check
+```
+
+## Billing terminology
+
+On AIHub, `0.2x` is an internal balance-conversion convention: CNY 0.20 covers
+USD 1.00 of official-list-price-equivalent usage, so CNY 2 covers USD 10 of
+that usage. It is not a foreign-exchange rate and not an OpenAI discount.
+Actual charges and model availability must be checked in the AIHub dashboard.
+
+## Security notes
+
+- Use environment variables or a secret manager for API keys.
+- Do not commit keys to a repository or pass them as command-line arguments.
+- The client requires HTTPS, except for explicit loopback testing.
+- Pin the gem version in production and review changes before upgrading.
+
+The initial implementation was drafted with AI assistance and validated with
+the included automated tests. Bug reports should include Ruby version and a
+redacted response status, never an API key.

data/exe/aihub2api

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+
+require "optparse"
+require "aihub2api"
+
+command = ARGV.shift || "help"
+options = { base_url: ENV.fetch("AIHUB_BASE_URL", AIHub2API::Client::DEFAULT_BASE_URL) }
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: aihub2api COMMAND [options]"
+  opts.on("--base-url URL", "OpenAI-compatible base URL") { |value| options[:base_url] = value }
+  opts.on("--model MODEL", "Model ID to verify or use") { |value| options[:model] = value }
+  opts.on("--prompt TEXT", "Prompt for the chat command") { |value| options[:prompt] = value }
+  opts.on("-h", "--help", "Show help") do
+    puts opts
+    puts "Commands: check, models, chat"
+    exit 0
+  end
+end
+
+parser.parse!(ARGV)
+
+begin
+  client = AIHub2API::Client.new(base_url: options[:base_url])
+  case command
+  when "check"
+    health = client.health
+    puts "health: #{health["status"] || (health["ok"] ? "ok" : "reachable")}" 
+    if ENV["AIHUB_API_KEY"].to_s.empty?
+      puts "models: skipped (set AIHUB_API_KEY to run the authenticated check)"
+    else
+      ids = client.model_ids
+      puts "models: #{ids.length} returned"
+      puts "requested_model: #{ids.include?(options[:model]) ? "available" : "not returned"}" if options[:model]
+    end
+  when "models"
+    puts client.model_ids
+  when "chat"
+    abort "--model is required" unless options[:model]
+    abort "--prompt is required" unless options[:prompt]
+    result = client.chat_completions(
+      model: options[:model],
+      messages: [{ role: "user", content: options[:prompt] }],
+    )
+    puts result.dig("choices", 0, "message", "content") || JSON.pretty_generate(result)
+  else
+    puts parser
+    puts "Commands: check, models, chat"
+    exit(command == "help" ? 0 : 1)
+  end
+rescue AIHub2API::Error => e
+  warn "error: #{e.message}"
+  exit 1
+end

data/lib/aihub2api/client.rb

@@ -0,0 +1,127 @@
+require "json"
+require "net/http"
+require "uri"
+
+module AIHub2API
+  class Client
+    DEFAULT_BASE_URL = "https://aihub2api.cloud".freeze
+    USER_AGENT = "aihub2api-ruby/#{AIHub2API::VERSION}".freeze
+
+    attr_reader :api_key, :base_url
+
+    def initialize(api_key: ENV["AIHUB_API_KEY"], base_url: ENV.fetch("AIHUB_BASE_URL", DEFAULT_BASE_URL),
+                   open_timeout: 10, read_timeout: 60, http_factory: nil)
+      @api_key = api_key.to_s.strip
+      @base_url = base_url.to_s.sub(%r{/+\z}, "")
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+      @http_factory = http_factory
+      validate_base_url!
+    end
+
+    def health
+      request(:get, "/health", authenticated: false)
+    end
+
+    def models
+      request(:get, "/v1/models")
+    end
+
+    def model_ids
+      Array(models["data"]).filter_map { |model| model["id"] if model.is_a?(Hash) }
+    end
+
+    def chat_completions(model:, messages:, **options)
+      payload = options.merge(model: model, messages: messages)
+      request(:post, "/v1/chat/completions", body: payload)
+    end
+
+    def responses(model:, input:, **options)
+      payload = options.merge(model: model, input: input)
+      request(:post, "/v1/responses", body: payload)
+    end
+
+    def request(method, path, body: nil, authenticated: true)
+      ensure_api_key! if authenticated
+      uri = endpoint_uri(path)
+      request = build_request(method, uri, body, authenticated)
+      response = perform_request(uri, request)
+      parsed_body = parse_body(response.body)
+
+      if response.code.to_i.between?(200, 299)
+        parsed_body
+      else
+        raise APIError.new(
+          "AIHub API returned HTTP #{response.code}",
+          status: response.code.to_i,
+          response_body: parsed_body,
+        )
+      end
+    rescue Timeout::Error, SocketError, SystemCallError, IOError => e
+      raise TransportError, "AIHub API request failed: #{e.class}"
+    end
+
+    private
+
+    def validate_base_url!
+      uri = URI.parse(base_url)
+      valid_https = uri.is_a?(URI::HTTPS) && uri.host
+      valid_loopback = uri.is_a?(URI::HTTP) && ["127.0.0.1", "localhost", "::1"].include?(uri.host)
+      return if valid_https || valid_loopback
+
+      raise ConfigurationError, "base_url must use HTTPS (plain HTTP is allowed only for loopback tests)"
+    rescue URI::InvalidURIError
+      raise ConfigurationError, "base_url is not a valid URL"
+    end
+
+    def ensure_api_key!
+      return unless api_key.empty?
+
+      raise ConfigurationError, "AIHUB_API_KEY is required for authenticated endpoints"
+    end
+
+    def endpoint_uri(path)
+      base = URI.parse(base_url)
+      target = base.dup
+      suffix = path.to_s.start_with?("/") ? path.to_s : "/#{path}"
+      prefix = base.path.to_s.sub(%r{/+\z}, "")
+      target.path = "#{prefix}#{suffix}"
+      target.query = nil
+      target.fragment = nil
+      target
+    end
+
+    def build_request(method, uri, body, authenticated)
+      klass = case method.to_s.downcase
+              when "get" then Net::HTTP::Get
+              when "post" then Net::HTTP::Post
+              else raise ConfigurationError, "unsupported HTTP method: #{method}"
+              end
+      request = klass.new(uri.request_uri)
+      request["Accept"] = "application/json"
+      request["User-Agent"] = USER_AGENT
+      request["Authorization"] = "Bearer #{api_key}" if authenticated
+      if body
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+      request
+    end
+
+    def perform_request(uri, request)
+      http = @http_factory ? @http_factory.call(uri) : Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https" if http.respond_to?(:use_ssl=)
+      http.open_timeout = @open_timeout if http.respond_to?(:open_timeout=)
+      http.read_timeout = @read_timeout if http.respond_to?(:read_timeout=)
+      http.request(request)
+    end
+
+    def parse_body(body)
+      return {} if body.to_s.empty?
+
+      JSON.parse(body)
+    rescue JSON::ParserError
+      { "raw" => body.to_s }
+    end
+  end
+end

data/lib/aihub2api/errors.rb

@@ -0,0 +1,17 @@
+module AIHub2API
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+
+  class APIError < Error
+    attr_reader :status, :response_body
+
+    def initialize(message, status:, response_body: nil)
+      super(message)
+      @status = status
+      @response_body = response_body
+    end
+  end
+
+  class TransportError < Error; end
+end

data/lib/aihub2api/version.rb

@@ -0,0 +1,3 @@
+module AIHub2API
+  VERSION = "0.1.0"
+end

data/lib/aihub2api.rb

@@ -0,0 +1,6 @@
+require_relative "aihub2api/version"
+require_relative "aihub2api/errors"
+require_relative "aihub2api/client"
+
+module AIHub2API
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: aihub2api
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- AIHub
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2026-08-17 00:00:00.000000000 Z
+dependencies: []
+description: |-
+  A small Ruby client and command-line preflight checker for AIHub's
+  OpenAI-compatible API. It checks health, lists authenticated models,
+  and sends Chat Completions or Responses requests without logging API keys.
+email:
+- aihub2api@mail.ljmai.online
+executables:
+- aihub2api
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- exe/aihub2api
+- lib/aihub2api.rb
+- lib/aihub2api/client.rb
+- lib/aihub2api/errors.rb
+- lib/aihub2api/version.rb
+homepage: https://aihub2api.cloud/?utm_source=rubygems&utm_medium=package&utm_campaign=westdev
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://aihub2api.cloud/?utm_source=rubygems&utm_medium=package&utm_campaign=westdev
+  documentation_uri: https://aihub2api.cloud/?utm_source=rubygems&utm_medium=documentation&utm_campaign=westdev
+  rubygems_mfa_required: 'false'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Dependency-free Ruby client and preflight checker for the AIHub OpenAI-compatible
+  API
+test_files: []