terret-openrouter 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7d65c1ea74581205c219735230596ea49ae2a70d2e091f0be3350cbb642b88b0
+  data.tar.gz: c547f2ba2ad7f207f0fb84cd1eb5b05eaefd894fc0ceaa567bc24d27dcc82469
+SHA512:
+  metadata.gz: 24d3c8eee134e36363a3434724c22b9683de36800f76fb13aac18da01b7f0a40a0dcf042f9123b380fc33e445744ff6c04883adc80a2e992c39bb4ec8e9299fd
+  data.tar.gz: 6bfd78533bbcdb6c6fe9caae98718f58065ef166209d67cd0812fc1549020deb9386d49a9af92782914cbc48505e37e5362db3acf91660e0fa8e7a3db3da56cc

data/lib/terret/openrouter/accumulator.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Terret
+  module OpenRouter
+    # Accumulates parsed streaming chunks into vocabulary StreamEvents and the
+    # final assistant Message. Tool-call argument fragments are gathered per
+    # index; the calls close on finalize. Pure, no I/O.
+    class Accumulator
+      STOP_REASONS = {
+        "stop" => :end_turn, "tool_calls" => :tool_use,
+        "length" => :length, "error" => :error
+      }.freeze
+
+      attr_reader :error
+
+      def initialize
+        @text = +""
+        @calls = {} # index => { id:, name:, args: +"" }
+        @stop = nil
+        @error = nil
+      end
+
+      def feed(chunk)
+        if (err = chunk[:error])
+          @error = LLM::StreamError.new(message: err[:message], code: err[:code])
+          yield @error
+        end
+        if (usage = chunk[:usage])
+          yield LLM::Usage.new(prompt_tokens: usage[:prompt_tokens],
+                               completion_tokens: usage[:completion_tokens],
+                               cost: usage[:cost])
+        end
+        choice = chunk[:choices]&.first or return
+        @stop = choice[:finish_reason] if choice[:finish_reason]
+        delta = choice[:delta] or return
+        if (text = delta[:content]) && !text.empty?
+          @text << text
+          yield LLM::TextDelta.new(text: text)
+        end
+        Array(delta[:tool_calls]).each { |tc| accumulate_call(tc) }
+        nil
+      end
+
+      def finalize
+        parts = []
+        parts << LLM::Text.new(text: @text) unless @text.empty?
+        @calls.keys.sort.each do |index|
+          slot = @calls[index]
+          args = slot[:args].empty? ? {} : JSON.parse(slot[:args], symbolize_names: true)
+          call = LLM::ToolCall.new(id: slot[:id], name: slot[:name], args: args)
+          yield LLM::ToolCallEnd.new(tool_call: call)
+          parts << call
+        end
+        yield LLM::MessageStop.new(stop_reason: STOP_REASONS.fetch(@stop, :end_turn))
+        LLM::Message.new(role: :assistant, parts: parts)
+      end
+
+      private
+
+      def accumulate_call(tc)
+        slot = @calls[tc[:index]] ||= { id: nil, name: nil, args: +"" }
+        slot[:id] = tc[:id] if tc[:id]
+        if (fn = tc[:function])
+          slot[:name] = fn[:name] if fn[:name]
+          slot[:args] << fn[:arguments] if fn[:arguments]
+        end
+      end
+    end
+  end
+end

data/lib/terret/openrouter/adapter.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Terret
+  module OpenRouter
+    # The ctx.llm adapter. Transport is injectable: tests drive it with canned
+    # SSE bodies; the default (lazily required) streams over async-http.
+    # Retries apply only before any bytes have streamed — once the consumer
+    # has seen deltas, a failure surfaces as StreamError and raises.
+    class Adapter < LLM::AdapterBase
+      DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+
+      def initialize(api_key: nil, base_url: DEFAULT_BASE_URL, referer: nil,
+                     title: nil, transport: nil, credentials: nil, **retry_opts)
+        super(**retry_opts)
+        @api_key = api_key
+        @base_url = base_url.chomp("/")
+        @referer = referer
+        @title = title
+        @transport = transport
+        # An optional resolver callable (the row wires it to ctx[:credentials]),
+        # consulted lazily at request time so mount order never matters.
+        @credentials = credentials
+      end
+
+      def stream(request, &on_event)
+        body = JSON.generate(Translate.request_body(request))
+        headers = request_headers
+        with_retries do
+          transport.call(url: "#{@base_url}/chat/completions",
+                         headers: headers, body: body) do |status, chunks|
+            check_status!(status, chunks)
+            consume(chunks, &on_event)
+          end
+        end
+      end
+
+      private
+
+      def consume(chunks, &on_event)
+        parser = SSE::Parser.new
+        acc = Accumulator.new
+        chunks.each do |chunk|
+          parser.feed(chunk) do |data|
+            next if data == "[DONE]"
+
+            acc.feed(JSON.parse(data, symbolize_names: true), &on_event)
+          end
+        end
+        if (err = acc.error)
+          raise LLM::AdapterError.new("mid-stream error: #{err.message}", status: err.code)
+        end
+
+        acc.finalize(&on_event)
+      end
+
+      def check_status!(status, chunks)
+        return if status == 200
+
+        body = chunks.to_a.join
+        message = begin
+          JSON.parse(body).dig("error", "message") || body
+        rescue JSON::ParserError
+          body
+        end
+        klass = status == 429 || status >= 500 ? LLM::RetryableError : LLM::AdapterError
+        raise klass.new("OpenRouter #{status}: #{message}", status: status, body: body)
+      end
+
+      def request_headers
+        # Precedence: an explicit config key, then the credentials resolver
+        # (itself ENV-first, then an encrypted store), then the adapter's own
+        # last-resort ENV read so the gem stays usable with no credentials
+        # service mounted.
+        key = @api_key
+        key ||= @credentials.call if @credentials
+        key ||= ENV["OPENROUTER_API_KEY"]
+        unless key
+          raise LLM::AdapterError, "no OpenRouter API key (set OPENROUTER_API_KEY or pass api_key:)"
+        end
+
+        headers = { "Authorization" => "Bearer #{key}", "Content-Type" => "application/json" }
+        headers["HTTP-Referer"] = @referer if @referer
+        headers["X-OpenRouter-Title"] = @title if @title # renamed upstream from X-Title
+        headers
+      end
+
+      def transport
+        @transport ||= begin
+          require_relative "async_transport"
+          AsyncTransport.new
+        end
+      end
+    end
+  end
+end

data/lib/terret/openrouter/async_transport.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/http/client"
+require "async/http/endpoint"
+
+module Terret
+  module OpenRouter
+    # Default transport: streams over async-http on the Fiber scheduler.
+    # Sync reuses a running reactor when called from inside one and spins a
+    # temporary reactor otherwise, so the adapter blocks correctly in both
+    # plain Ruby and Async callers. The connection stays open only for the
+    # duration of the block, which is why the contract yields rather than
+    # returns: an SSE body must be consumed before the response closes.
+    class AsyncTransport
+      CONNECT_ERRORS = [SystemCallError, SocketError, IOError, Async::TimeoutError].freeze
+
+      def initialize(timeout: 120)
+        @timeout = timeout
+      end
+
+      def call(url:, headers:, body:)
+        Sync do
+          endpoint = Async::HTTP::Endpoint.parse(url, timeout: @timeout)
+          client = Async::HTTP::Client.new(endpoint)
+          begin
+            response = begin
+              client.post(endpoint.path, headers, body)
+            rescue *CONNECT_ERRORS => e
+              raise LLM::RetryableError, "connection failed: #{e.class}: #{e.message}"
+            end
+            begin
+              chunks = Enumerator.new { |y| response.body&.each { |c| y << c } }
+              yield response.status, chunks
+            ensure
+              response.close
+            end
+          ensure
+            client.close
+          end
+        end
+      end
+    end
+  end
+end

data/lib/terret/openrouter/sse.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Terret
+  module OpenRouter
+    module SSE
+      # Incremental server-sent-events parser. Fed raw transport chunks with
+      # boundaries wherever the network put them; yields one data payload per
+      # event (multi-line data joined per the SSE spec). Comment lines and
+      # non-data fields are ignored — OpenRouter uses comments as keep-alives.
+      class Parser
+        def initialize
+          @buffer = +""
+          @data = []
+        end
+
+        def feed(chunk)
+          @buffer << chunk
+          while (line, rest = @buffer.split("\n", 2)) && rest
+            @buffer = rest
+            line.chomp!("\r")
+            if line.empty?
+              yield @data.join("\n") unless @data.empty?
+              @data.clear
+            elsif line.start_with?("data:")
+              @data << line.delete_prefix("data:").sub(/\A /, "")
+            end
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/terret/openrouter/translate.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Terret
+  module OpenRouter
+    # Pure translation between the provider-neutral vocabulary and
+    # OpenRouter's OpenAI-compatible wire format. No I/O.
+    module Translate
+      module_function
+
+      def request_body(request)
+        body = { model: request.model, messages: wire_messages(request), stream: true }
+        tools = Array(request.tools)
+        body[:tools] = tools.map { |s| { type: "function", function: s } } unless tools.empty?
+        body
+      end
+
+      def wire_messages(request)
+        out = []
+        system = request.system.to_s
+        out << { role: "system", content: system } unless system.empty?
+        request.messages.each { |m| out.concat(wire_message(m)) }
+        out
+      end
+
+      def wire_message(message)
+        case message.role
+        when :user
+          [{ role: "user", content: message.text }]
+        when :assistant
+          msg = { role: "assistant", content: message.text.empty? ? nil : message.text }
+          calls = message.tool_calls
+          unless calls.empty?
+            msg[:tool_calls] = calls.map do |tc|
+              { id: tc.id, type: "function",
+                function: { name: tc.name, arguments: JSON.generate(tc.args) } }
+            end
+          end
+          [msg]
+        when :tool
+          message.parts.grep(LLM::ToolResult).map do |tr|
+            content = tr.error ? "Error: #{tr.error}" : tr.content.to_s
+            { role: "tool", tool_call_id: tr.id, content: content }
+          end
+        else
+          raise ArgumentError, "cannot translate message role #{message.role.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/terret/openrouter.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+begin
+  require "terret"
+rescue LoadError
+  require_relative "../../../terret-core/lib/terret" # monorepo path source
+end
+
+module Terret
+  # The one v1 adapter (plan §6.5): OpenRouter is OpenAI-compatible, so a
+  # single implementation reaches the whole model space behind ctx.llm.
+  module OpenRouter
+  end
+end
+
+require_relative "openrouter/sse"
+require_relative "openrouter/translate"
+require_relative "openrouter/accumulator"
+require_relative "openrouter/adapter"
+
+module Terret
+  module OpenRouter
+    # Config-row form: mounts the adapter into ctx.llm under the "openrouter"
+    # provider name. Roles then point at it: { main: "openrouter/<model>" }.
+    class Plugin < Hames::Service
+      inject :llm
+      # transport: and sleeper: are injectable seams (tests pass callables), not
+      # YAML config, so they are deliberately absent from the schema.
+      config_schema api_key:      { type: String,
+                                    doc: "OpenRouter key; falls back to ENV OPENROUTER_API_KEY when unset" },
+                    base_url:     { type: String, default: "https://openrouter.ai/api/v1",
+                                    doc: "OpenAI-compatible API base URL" },
+                    referer:      { type: String, doc: "HTTP-Referer header sent with each request" },
+                    title:        { type: String, doc: "X-Title header sent with each request" },
+                    max_attempts: { type: Integer, default: 4, doc: "retry attempts on a retryable error" },
+                    base_delay:   { type: Numeric, default: 0.5, doc: "seconds of the first retry backoff" }
+
+      def start(ctx)
+        # A resolver evaluated at REQUEST time, not now: it checks for the
+        # credentials service at call time, so the row need not inject it (the
+        # gem stays usable without terret-core's credentials mounted) and mount
+        # order between the two rows never matters. resolve(:openrouter) is
+        # ENV-first, so ENV-direct keeps working; when it resolves anything, the
+        # value is registered as a scrub pattern (plan §6.9).
+        credentials = -> { ctx[:credentials].resolve(:openrouter) if ctx.service?(:credentials) }
+        adapter = Adapter.new(**config, credentials: credentials)
+        ctx.effect { ctx[:llm].register_adapter("openrouter", adapter) }
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: terret-openrouter
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Obie Fernandez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: terret-core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.94'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.94'
+description: 'The one v1 model adapter for Terret: OpenRouter is OpenAI-compatible,
+  so a single streaming implementation reaches the whole model space behind the provider-neutral
+  ctx.llm seam. SSE streaming with tool calling, usage accounting, and retry with
+  jittered backoff.'
+email:
+- obiefernandez@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/terret/openrouter.rb
+- lib/terret/openrouter/accumulator.rb
+- lib/terret/openrouter/adapter.rb
+- lib/terret/openrouter/async_transport.rb
+- lib/terret/openrouter/sse.rb
+- lib/terret/openrouter/translate.rb
+homepage: https://terret.org
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://terret.org
+  source_code_uri: https://github.com/terret-org/terret
+  bug_tracker_uri: https://github.com/terret-org/terret/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: OpenRouter adapter for the Terret agent harness
+test_files: []