ruby_llm-gitlab 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ba3f9f64c038b7c3242e43d2b9788bd45d3b962cca9f371088a4522e802cceef
+  data.tar.gz: a7e6e3a8a144b9a0ff59693b7b319c7beefb73d3ae670d720f238a44eb8df27b
+SHA512:
+  metadata.gz: 11d9a84ea5e990121e3d1873352840fe703b3131e8b826e76eee60cc3ccdc36a4c7792d101a14e46e6a9899f805f95f4191e3249eca0493788ce53166a5ce65e
+  data.tar.gz: a42a3537f0bb9e305cb4b207053e127db0a61dd6e91904ee8fa773fed8afe675c36a10fff6517a4f0cf05257e752cfc2dab45dba88a260f65212208e72927b80

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 RubyLLM Contributors
+
+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,154 @@
+# RubyLLM::GitLab
+
+Access Claude and GPT models through **GitLab Duo** via the [RubyLLM](https://rubyllm.com) interface. One provider, automatic routing.
+
+## Requirements
+
+- Ruby >= 3.1
+- [RubyLLM](https://github.com/crmne/ruby_llm) >= 1.0
+- GitLab Premium/Ultimate with Duo Enterprise
+- Personal Access Token with `ai_features` scope
+
+## Installation
+
+```ruby
+gem 'ruby_llm-gitlab'
+```
+
+## Configuration
+
+### gitlab.com
+
+```ruby
+RubyLLM.configure do |config|
+  config.gitlab_api_key = ENV['GITLAB_TOKEN']
+end
+```
+
+### Self-managed
+
+```ruby
+RubyLLM.configure do |config|
+  config.gitlab_api_key = ENV['GITLAB_TOKEN']
+  config.gitlab_instance_url = 'https://gitlab.example.com'
+  config.gitlab_gateway_url = 'https://cloud.gitlab.com'  # default
+end
+```
+
+## Usage
+
+### Chat
+
+```ruby
+chat = RubyLLM.chat(model: 'duo-chat-opus-4-6', provider: :gitlab)
+chat.ask "What's the best way to learn Ruby?"
+```
+
+### Streaming
+
+```ruby
+chat = RubyLLM.chat(model: 'duo-chat-sonnet-4-6', provider: :gitlab)
+chat.ask "Tell me a story" do |chunk|
+  print chunk.content
+end
+```
+
+### Tools
+
+```ruby
+class Weather < RubyLLM::Tool
+  description "Get current weather"
+  param :city, type: :string
+
+  def execute(city:)
+    { temperature: 22, condition: "sunny" }
+  end
+end
+
+chat = RubyLLM.chat(model: 'duo-chat-opus-4-6', provider: :gitlab)
+chat.with_tool(Weather).ask "What's the weather in Berlin?"
+```
+
+### Agents
+
+```ruby
+class CodeReviewer < RubyLLM::Agent
+  model 'duo-chat-opus-4-6'
+  provider :gitlab
+  instructions "You are a senior Ruby developer. Review code for bugs and style."
+end
+
+CodeReviewer.new.ask "Review this: def foo(x) x+1 end"
+```
+
+### Rails
+
+```ruby
+class Chat < ApplicationRecord
+  acts_as_chat model: 'duo-chat-sonnet-4-6', provider: :gitlab
+end
+
+chat = Chat.create!
+chat.ask "Explain Active Record callbacks"
+```
+
+## Models
+
+| GitLab Model ID | Routes To | Backend |
+|---|---|---|
+| `duo-chat-opus-4-6` | `claude-opus-4-6` | Anthropic |
+| `duo-chat-sonnet-4-6` | `claude-sonnet-4-6` | Anthropic |
+| `duo-chat-opus-4-5` | `claude-opus-4-5-20251101` | Anthropic |
+| `duo-chat-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Anthropic |
+| `duo-chat-haiku-4-5` | `claude-haiku-4-5-20251001` | Anthropic |
+| `duo-chat-gpt-5-1` | `gpt-5.1-2025-11-13` | OpenAI |
+| `duo-chat-gpt-5-2` | `gpt-5.2-2025-12-11` | OpenAI |
+| `duo-chat-gpt-5-mini` | `gpt-5-mini-2025-08-07` | OpenAI |
+
+## How It Works
+
+```
+User → RubyLLM.chat(provider: :gitlab)
+         ↓
+       GitLab Provider (router)
+         ├── Claude model? → AnthropicDelegate → GitLab AI Gateway → Anthropic API
+         └── GPT model?    → OpenAIDelegate   → GitLab AI Gateway → OpenAI API
+```
+
+1. **Token exchange** — Your PAT is exchanged for a short-lived gateway token via GitLab's Direct Access API
+2. **Routing** — The provider inspects the model ID and delegates to the correct sub-provider
+3. **Proxy** — Requests go through GitLab's AI Gateway (`cloud.gitlab.com`) which proxies to the upstream API
+4. **Model mapping** — GitLab model IDs (e.g. `duo-chat-opus-4-6`) are transparently mapped to upstream IDs (e.g. `claude-opus-4-6`)
+
+## Limitations
+
+- Chat completions only (no embeddings, images, audio, moderation)
+- No Codex/Responses API models
+- Token cached for 25 minutes; auto-refreshes on expiry
+- Requires GitLab Duo Enterprise license
+
+## Troubleshooting
+
+### `ConfigurationError: Missing configuration for GitLab: gitlab_api_key`
+
+Set your token:
+
+```ruby
+RubyLLM.configure { |c| c.gitlab_api_key = ENV['GITLAB_TOKEN'] }
+```
+
+### `ConfigurationError: Failed to obtain GitLab direct access token`
+
+- Verify your PAT has `ai_features` scope
+- Check your GitLab instance URL is correct
+- Ensure Duo Enterprise is enabled for your group/project
+
+### 401 errors during chat
+
+The gem automatically retries once with a fresh token. If it persists:
+- Your PAT may have expired
+- The Duo license may have been revoked
+
+## License
+
+MIT

data/lib/ruby_llm/providers/gitlab/anthropic_delegate.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class GitLab
+      class AnthropicDelegate < RubyLLM::Providers::Anthropic
+        include RubyLLM::Providers::GitLab::Chat
+
+        def api_base
+          token_manager.anthropic_base_url
+        end
+
+        def headers
+          {
+            'Authorization' => "Bearer #{token_manager.token}",
+            'anthropic-version' => '2023-06-01'
+          }.merge(token_manager.gateway_headers)
+        end
+
+        def complete(...)
+          super
+        rescue RubyLLM::UnauthorizedError
+          token_manager.invalidate!
+          super
+        end
+
+        class << self
+          def configuration_requirements
+            %i[gitlab_api_key]
+          end
+
+          def configuration_options
+            %i[gitlab_api_key gitlab_instance_url gitlab_gateway_url]
+          end
+        end
+
+        private
+
+        def token_manager
+          @token_manager ||= TokenManager.new(@config)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/gitlab/capabilities.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class GitLab
+      module Capabilities
+        MODEL_MAPPINGS = {
+          'duo-chat-opus-4-6' => 'claude-opus-4-6',
+          'duo-chat-sonnet-4-6' => 'claude-sonnet-4-6',
+          'duo-chat-opus-4-5' => 'claude-opus-4-5-20251101',
+          'duo-chat-sonnet-4-5' => 'claude-sonnet-4-5-20250929',
+          'duo-chat-haiku-4-5' => 'claude-haiku-4-5-20251001',
+          'duo-chat-gpt-5-1' => 'gpt-5.1-2025-11-13',
+          'duo-chat-gpt-5-2' => 'gpt-5.2-2025-12-11',
+          'duo-chat-gpt-5-mini' => 'gpt-5-mini-2025-08-07'
+        }.freeze
+
+        ANTHROPIC_MODELS = MODEL_MAPPINGS.select { |_, v| v.start_with?('claude-') }.keys.freeze
+        OPENAI_MODELS = MODEL_MAPPINGS.reject { |_, v| v.start_with?('claude-') }.keys.freeze
+
+        module_function
+
+        def actual_model(id)
+          MODEL_MAPPINGS[id]
+        end
+
+        def anthropic_model?(id)
+          ANTHROPIC_MODELS.include?(id)
+        end
+
+        def openai_model?(id)
+          OPENAI_MODELS.include?(id)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/gitlab/chat.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'delegate'
+
+module RubyLLM
+  module Providers
+    class GitLab
+      module Chat
+        def render_payload(messages, tools:, temperature:, model:, stream: false, schema: nil,
+                           thinking: nil, tool_prefs: nil)
+          super(messages, tools: tools, temperature: temperature, model: ModelIdProxy.new(model),
+                stream: stream, schema: schema, thinking: thinking, tool_prefs: tool_prefs)
+        end
+      end
+
+      class ModelIdProxy < SimpleDelegator
+        def id
+          Capabilities.actual_model(__getobj__.id) || __getobj__.id
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/gitlab/openai_delegate.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class GitLab
+      class OpenAIDelegate < RubyLLM::Providers::OpenAI
+        include RubyLLM::Providers::GitLab::Chat
+
+        def api_base
+          token_manager.openai_base_url
+        end
+
+        def headers
+          {
+            'Authorization' => "Bearer #{token_manager.token}"
+          }.merge(token_manager.gateway_headers)
+        end
+
+        def complete(...)
+          super
+        rescue RubyLLM::UnauthorizedError
+          token_manager.invalidate!
+          super
+        end
+
+        class << self
+          def configuration_requirements
+            %i[gitlab_api_key]
+          end
+
+          def configuration_options
+            %i[gitlab_api_key gitlab_instance_url gitlab_gateway_url]
+          end
+        end
+
+        private
+
+        def token_manager
+          @token_manager ||= TokenManager.new(@config)
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/gitlab/token_manager.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class GitLab
+      class TokenManager
+        CACHE_DURATION = 25 * 60 # 25 minutes
+        DEFAULT_INSTANCE_URL = 'https://gitlab.com'
+        DEFAULT_GATEWAY_URL = 'https://cloud.gitlab.com'
+        TOKEN_PATH = '/api/v4/ai/third_party_agents/direct_access'
+
+        def initialize(config)
+          @config = config
+          @mutex = Mutex.new
+          @cached_token = nil
+          @cached_headers = nil
+          @cached_at = nil
+        end
+
+        def token
+          refresh_if_needed
+          @cached_token
+        end
+
+        def gateway_headers
+          refresh_if_needed
+          @cached_headers
+        end
+
+        def invalidate!
+          @mutex.synchronize do
+            @cached_token = nil
+            @cached_headers = nil
+            @cached_at = nil
+          end
+        end
+
+        def anthropic_base_url
+          "#{gateway_url}/ai/v1/proxy/anthropic"
+        end
+
+        def openai_base_url
+          "#{gateway_url}/ai/v1/proxy/openai/v1"
+        end
+
+        private
+
+        def refresh_if_needed
+          @mutex.synchronize do
+            fetch_token if stale?
+          end
+        end
+
+        def stale?
+          @cached_at.nil? || (Time.now - @cached_at) > CACHE_DURATION
+        end
+
+        def fetch_token
+          response = request_direct_access
+          body = response.body
+
+          @cached_token = body['token']
+          # SECURITY: Filter out x-api-key — gateway auth uses Bearer token only
+          raw_headers = body.fetch('headers', {})
+          @cached_headers = raw_headers.reject { |k, _| k.downcase == 'x-api-key' }
+          @cached_at = Time.now
+        rescue Faraday::Error => e
+          raise RubyLLM::ConfigurationError,
+                "Failed to obtain GitLab direct access token: #{e.message}"
+        end
+
+        def request_direct_access
+          connection.post(TOKEN_PATH) do |req|
+            req.headers['Authorization'] = "Bearer #{pat}"
+            req.headers['Content-Type'] = 'application/json'
+            req.body = JSON.generate(feature_flags: { DuoAgentPlatformNext: true })
+          end
+        end
+
+        def connection
+          @connection ||= RubyLLM::Connection.basic do |f|
+            f.url_prefix = instance_url
+            f.request :json
+            f.response :json
+            f.adapter :net_http
+          end
+        end
+
+        def pat
+          @config.gitlab_api_key
+        end
+
+        def instance_url
+          @config.respond_to?(:gitlab_instance_url) && @config.gitlab_instance_url || DEFAULT_INSTANCE_URL
+        end
+
+        def gateway_url
+          @config.respond_to?(:gitlab_gateway_url) && @config.gitlab_gateway_url || DEFAULT_GATEWAY_URL
+        end
+      end
+    end
+  end
+end

data/lib/ruby_llm/providers/gitlab.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Providers
+    class GitLab < Provider
+      require_relative 'gitlab/capabilities'
+      require_relative 'gitlab/token_manager'
+      require_relative 'gitlab/chat'
+      require_relative 'gitlab/anthropic_delegate'
+      require_relative 'gitlab/openai_delegate'
+
+      include GitLab::Chat
+
+      def initialize(config)
+        @config = config
+        ensure_configured!
+      end
+
+      def complete(messages, tools:, temperature:, model:, **kwargs, &block)
+        delegate_for(model).complete(messages, tools: tools, temperature: temperature, model: model, **kwargs, &block)
+      end
+
+      def list_models
+        GitLab::Capabilities::MODEL_MAPPINGS.map do |gitlab_id, _actual_id|
+          RubyLLM::Model::Info.new(
+            id: gitlab_id,
+            name: gitlab_id.tr('-', ' ').capitalize,
+            provider: 'gitlab',
+            capabilities: %w[function_calling streaming vision structured_output],
+            modalities: { input: %w[text image], output: %w[text] }
+          )
+        end
+      end
+
+      def test_connection
+        token_manager.token
+        true
+      rescue StandardError
+        false
+      end
+
+      class << self
+        def configuration_options = %i[gitlab_api_key gitlab_instance_url gitlab_gateway_url]
+        def configuration_requirements = %i[gitlab_api_key]
+        def assume_models_exist? = true
+      end
+
+      private
+
+      def delegate_for(model)
+        model_id = model.is_a?(String) ? model : model.id
+        if GitLab::Capabilities.anthropic_model?(model_id)
+          anthropic_delegate
+        else
+          openai_delegate
+        end
+      end
+
+      def anthropic_delegate
+        @anthropic_delegate ||= GitLab::AnthropicDelegate.new(@config)
+      end
+
+      def openai_delegate
+        @openai_delegate ||= GitLab::OpenAIDelegate.new(@config)
+      end
+
+      def token_manager
+        @token_manager ||= GitLab::TokenManager.new(@config)
+      end
+    end
+  end
+end

data/lib/ruby_llm-gitlab.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+require_relative 'ruby_llm/providers/gitlab'
+
+RubyLLM::Provider.register :gitlab, RubyLLM::Providers::GitLab

metadata

@@ -0,0 +1,118 @@
+--- !ruby/object:Gem::Specification
+name: ruby_llm-gitlab
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Compasify
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.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.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  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'
+description: Access Claude and GPT models through GitLab Duo via the RubyLLM interface.
+  One provider, automatic routing to Anthropic or OpenAI backends.
+email:
+- timdapan.com@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/ruby_llm-gitlab.rb
+- lib/ruby_llm/providers/gitlab.rb
+- lib/ruby_llm/providers/gitlab/anthropic_delegate.rb
+- lib/ruby_llm/providers/gitlab/capabilities.rb
+- lib/ruby_llm/providers/gitlab/chat.rb
+- lib/ruby_llm/providers/gitlab/openai_delegate.rb
+- lib/ruby_llm/providers/gitlab/token_manager.rb
+homepage: https://github.com/compasify/ruby_llm-gitlab
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/compasify/ruby_llm-gitlab
+  source_code_uri: https://github.com/compasify/ruby_llm-gitlab
+  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.1'
+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: GitLab AI Gateway provider for RubyLLM
+test_files: []