octoryn-sdk 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d0390d88d9de20ba64377d0fe29464256cb295be1a77355f76b6876fb079b81f
+  data.tar.gz: c08fccf84d26274fdf0210e1a367b457d5893c1a243d9cabbb05640a001d15bb
+SHA512:
+  metadata.gz: 8ec09df1938b63886f0fd1200930a7447110686bcf082953f1bf856afa0489fb6bf54b7e12e60f3c106c8939028f9379a07e9081a7a10acd6172e63762fd9881
+  data.tar.gz: 4e735f9f27fa42ade37dea4763445ad3b1f309c136d99a5cb4a1442d1d1d3545440a0685d38e4ae9b7de329e09a649b80ea29f7b7d57741c0e6cb4047416e1b1

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2026 Octopus Core Pty Ltd
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+https://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,26 @@
+# Octoryn Ruby SDK
+
+Governed model access for Ruby 3.2 and later.
+
+Until `octoryn-sdk` is available from RubyGems.org, install the public release
+artifact directly:
+
+```bash
+curl -fLO \
+  https://github.com/octopusos/octoryn-ruby/releases/download/v0.1.1/octoryn-sdk-0.1.1.gem
+gem install ./octoryn-sdk-0.1.1.gem
+```
+
+```ruby
+client = Octoryn::Client.new(api_key: ENV.fetch("OCTORYN_API_KEY"))
+result = client.generate_text(
+  model: "policy/au-enterprise",
+  prompt: "Explain this routing decision."
+)
+
+puts result.octoryn.evidence_hash
+```
+
+The SDK supports synchronous and asynchronous text generation, replayable SSE
+streams, split tool calls, JSON Schema-validated Structured Outputs, normalized
+errors, cancellation, replaceable transports and Octoryn governance metadata.

data/lib/octoryn/client.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'json_schemer'
+
+module Octoryn
+  # High-level governed client for text, tools, streaming, and JSON Schema output.
+  class Client
+    def initialize(api_key:, base_url: 'https://api.octoryn.dev/v1/',
+                   transport: nil)
+      raise ArgumentError, 'Octoryn API key is required' if api_key.to_s.strip.empty?
+
+      @transport = transport || NetHTTPTransport.new(
+        base_url: base_url,
+        api_key: api_key
+      )
+    end
+
+    def generate_text(**options)
+      response = request(build_request(options, stream: false))
+      normalize(JSON.parse(response.body), governance(response))
+    end
+
+    def generate_text_async(**options)
+      Thread.new { generate_text(**options) }
+    end
+
+    def generate_object(schema:, schema_name: 'response',
+                        schema_description: nil, **options)
+      payload = build_request(options, stream: false)
+      payload['response_format'] = {
+        'type' => 'json_schema',
+        'json_schema' => {
+          'name' => schema_name,
+          'description' => schema_description,
+          'strict' => true,
+          'schema' => schema
+        }
+      }
+      response = request(payload)
+      result = normalize(JSON.parse(response.body), governance(response))
+      object = parse_structured(result.text)
+      errors = JSONSchemer.schema(schema).validate(object).to_a
+      unless errors.empty?
+        raise StructuredOutputError.new(
+          'Octoryn structured output does not match the JSON Schema',
+          raw_output: result.text,
+          validation_errors: errors
+        )
+      end
+      ObjectResult.new(object, result)
+    end
+
+    def stream_text(**options)
+      payload = build_request(options, stream: true)
+      producer = proc do |&on_chunk|
+        response = @transport.post('chat/completions', payload, stream: true) do |head, chunk|
+          if chunk.nil?
+            ensure_success!(head)
+            on_chunk.call(nil, governance(head))
+          else
+            on_chunk.call(chunk, nil)
+          end
+        end
+        ensure_success!(response)
+      end
+      TextStream.new(&producer)
+    end
+
+    private
+
+    def build_request(options, stream:)
+      model = options[:model]
+      raise ArgumentError, 'model is required' if model.to_s.strip.empty?
+
+      has_prompt = options.key?(:prompt)
+      has_messages = options.key?(:messages)
+      raise ArgumentError, 'pass exactly one of prompt or messages' if has_prompt == has_messages
+
+      messages = []
+      messages << { 'role' => 'system', 'content' => options[:system] } if options[:system]
+      if has_prompt
+        messages << { 'role' => 'user', 'content' => options[:prompt] }
+      else
+        messages.concat(Array(options[:messages]))
+      end
+      payload = { 'model' => model, 'messages' => messages, 'stream' => stream }
+      {
+        temperature: 'temperature',
+        top_p: 'top_p',
+        max_output_tokens: 'max_tokens',
+        tools: 'tools',
+        tool_choice: 'tool_choice',
+        metadata: 'metadata'
+      }.each do |input, output|
+        payload[output] = options[input] if options.key?(input)
+      end
+      payload
+    end
+
+    def request(payload)
+      response = @transport.post('chat/completions', payload, stream: false)
+      ensure_success!(response)
+      response
+    end
+
+    def normalize(response, metadata)
+      choice = Array(response['choices']).first
+      raise Error, 'Octoryn response contained no choices' unless choice
+
+      message = choice.fetch('message', {})
+      TextResult.new(
+        text_content(message['content']),
+        Array(message['tool_calls']).filter_map { |call| normalize_tool(call) },
+        choice['finish_reason'],
+        response['usage'],
+        metadata,
+        response
+      )
+    end
+
+    def normalize_tool(call)
+      function = call['function']
+      return unless function.is_a?(Hash)
+
+      ToolCall.new(
+        call.fetch('id', ''),
+        function.fetch('name', ''),
+        function.fetch('arguments', '{}'),
+        call.fetch('type', 'function')
+      )
+    end
+
+    def text_content(content)
+      return content if content.is_a?(String)
+      return '' unless content.is_a?(Array)
+
+      content.filter_map do |part|
+        part['text'] if part.is_a?(Hash) && part['type'] == 'text'
+      end.join
+    end
+
+    def governance(response)
+      header = ->(name) { response.headers[name.downcase] || response.headers[name] }
+      cost = header.call('x-octoryn-estimated-cost')
+      GovernanceMetadata.new(
+        header.call('x-octoryn-run-id'),
+        header.call('x-octoryn-upstream'),
+        header.call('x-octoryn-byok'),
+        header.call('x-octoryn-region'),
+        header.call('x-octoryn-route'),
+        header.call('x-octoryn-policy-decision'),
+        header.call('x-octoryn-evidence-hash'),
+        cost&.to_f
+      )
+    end
+
+    def ensure_success!(response)
+      return if response.status.between?(200, 299)
+
+      body = response.body ? JSON.parse(response.body) : {}
+      error = body.fetch('error', {})
+      raise APIError.new(
+        status: response.status,
+        message: error.fetch('message', 'Octoryn request failed'),
+        code: error['code'],
+        error_type: error['type'],
+        request_id: response.headers['x-request-id'],
+        retry_after: response.headers['retry-after']&.to_i
+      )
+    rescue JSON::ParserError
+      raise APIError.new(status: response.status, message: 'Octoryn request failed')
+    end
+
+    def parse_structured(raw)
+      JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise StructuredOutputError.new(
+        'Octoryn structured output is not valid JSON',
+        raw_output: raw,
+        validation_errors: []
+      ), cause: e
+    end
+  end
+end

data/lib/octoryn/errors.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Octoryn
+  class Error < StandardError; end
+
+  # A normalized non-success response from the Octoryn API.
+  class APIError < Error
+    attr_reader :status, :code, :error_type, :request_id, :retry_after
+
+    def initialize(status:, message:, code: nil, error_type: nil,
+                   request_id: nil, retry_after: nil)
+      super(message)
+      @status = status
+      @code = code
+      @error_type = error_type
+      @request_id = request_id
+      @retry_after = retry_after
+    end
+  end
+
+  # Raised when structured output is invalid JSON or violates its schema.
+  class StructuredOutputError < Error
+    attr_reader :raw_output, :validation_errors
+
+    def initialize(message, raw_output:, validation_errors: [])
+      super(message)
+      @raw_output = raw_output
+      @validation_errors = validation_errors
+    end
+  end
+end

data/lib/octoryn/text_stream.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+module Octoryn
+  # A lazy, cancellable, replayable stream of normalized Octoryn events.
+  class TextStream
+    include Enumerable
+
+    def initialize(governance: nil, &producer)
+      @governance = governance
+      @producer = producer
+      @events = []
+      @source = nil
+      @complete = false
+      @result = nil
+      @error = nil
+      @cancelled = false
+    end
+
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      @events.each(&)
+      return finish_replay if @complete
+
+      consume_events(&)
+      raise @error if @error
+    end
+
+    def result
+      each { nil } unless @complete
+      raise @error if @error
+
+      @result || raise(Error, 'Octoryn stream has no final result')
+    end
+
+    def cancel
+      @cancelled = true
+      @error = Error.new('Octoryn stream cancelled')
+      @complete = true
+    end
+
+    private
+
+    def finish_replay
+      raise @error if @error
+    end
+
+    def consume_events
+      @source ||= consume
+      loop do
+        streamed = @source.next
+        @events << streamed
+        yield streamed
+      end
+    rescue StopIteration
+      nil
+    end
+
+    def consume
+      Enumerator.new do |events|
+        state = stream_state
+        started = false
+        @producer.call do |chunk, metadata = nil|
+          raise Error, 'Octoryn stream cancelled' if @cancelled
+
+          if metadata
+            @governance = metadata
+            events << event('start', octoryn: @governance)
+            started = true
+            next
+          end
+          unless started
+            events << event('start', octoryn: @governance)
+            started = true
+          end
+          state[:buffer] << chunk
+          parse_lines(state, events)
+        end
+        finalize_stream(state, events)
+      rescue StandardError => e
+        @error = e
+        @complete = true
+        events << event('error', octoryn: @governance, error: e)
+      end
+    end
+
+    def stream_state
+      {
+        buffer: +'',
+        data: [],
+        text: +'',
+        tools: {},
+        usage: nil,
+        finish_reason: nil,
+        done: false
+      }
+    end
+
+    def parse_lines(state, events)
+      while (newline = state[:buffer].index("\n"))
+        line = state[:buffer].slice!(0..newline).sub(/\r?\n\z/, '')
+        if line.empty?
+          process_event(state, events)
+        elsif line.start_with?('data:')
+          state[:data] << line.delete_prefix('data:').lstrip
+        end
+      end
+    end
+
+    def process_event(state, events)
+      return if state[:data].empty?
+
+      payload = state[:data].join("\n")
+      state[:data].clear
+      if payload == '[DONE]'
+        state[:done] = true
+        return
+      end
+
+      apply(JSON.parse(payload), state, events)
+    end
+
+    def apply(chunk, state, events)
+      recognized = false
+      if chunk['usage']
+        state[:usage] = chunk['usage']
+        events << event('usage', usage: state[:usage])
+        recognized = true
+      end
+      Array(chunk['choices']).each do |choice|
+        recognized = apply_delta(choice, state, events) || recognized
+        state[:finish_reason] = choice['finish_reason'] if choice['finish_reason']
+      end
+      events << event('provider-event', provider_event: chunk) unless recognized
+    end
+
+    def apply_delta(choice, state, events)
+      delta = choice.fetch('delta', {})
+      content = delta['content']
+      recognized = content.is_a?(String)
+      append_text(content, state, events) if recognized
+      reasoning = delta['reasoning'] || delta['reasoning_content']
+      if reasoning.is_a?(String)
+        events << event('reasoning-delta', text: reasoning)
+        recognized = true
+      end
+      Array(delta['tool_calls']).each do |part|
+        append_tool(part, state, events)
+        recognized = true
+      end
+      recognized
+    end
+
+    def append_text(content, state, events)
+      state[:text] << content
+      events << event('text-delta', text: content)
+    end
+
+    def append_tool(part, state, events)
+      index = part.fetch('index', 0)
+      starting = !state[:tools].key?(index)
+      tool = state[:tools][index] ||= {
+        'id' => '',
+        'type' => 'function',
+        'name' => +'',
+        'arguments' => +''
+      }
+      tool['id'] = part['id'] if part['id']
+      tool['type'] = part['type'] if part['type']
+      function = part.fetch('function', {})
+      tool['name'] << function.fetch('name', '')
+      tool['arguments'] << function.fetch('arguments', '')
+      events << event('tool-call-start', provider_event: part) if starting
+      events << event('tool-call-delta', provider_event: part)
+    end
+
+    def finalize_stream(state, events)
+      process_trailing_data(state, events)
+      raise Error, 'Octoryn stream ended before [DONE]' unless state[:done]
+
+      calls = state[:tools].sort.map do |_index, tool|
+        call = ToolCall.new(tool['id'], tool['name'], tool['arguments'], tool['type'])
+        events << event('tool-call', tool_call: call)
+        call
+      end
+      events << event(
+        'finish',
+        finish_reason: state[:finish_reason],
+        octoryn: @governance
+      )
+      @result = TextResult.new(
+        state[:text],
+        calls,
+        state[:finish_reason],
+        state[:usage],
+        @governance,
+        nil
+      )
+      @complete = true
+    end
+
+    def process_trailing_data(state, events)
+      unless state[:buffer].empty?
+        line = state[:buffer].sub(/\r?\n\z/, '')
+        state[:data] << line.delete_prefix('data:').lstrip if line.start_with?('data:')
+      end
+      process_event(state, events)
+    end
+
+    def event(type, **attributes)
+      StreamEvent.new(
+        type,
+        attributes[:text],
+        attributes[:tool_call],
+        attributes[:usage],
+        attributes[:finish_reason],
+        attributes[:octoryn],
+        attributes[:provider_event],
+        attributes[:error]
+      )
+    end
+  end
+end

data/lib/octoryn/transport.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Octoryn
+  Response = Data.define(:status, :headers, :body)
+
+  # Standard-library HTTP transport with incremental response-body streaming.
+  class NetHTTPTransport
+    def initialize(base_url:, api_key:, open_timeout: 30, read_timeout: 600)
+      @base_url = base_url.end_with?('/') ? base_url : "#{base_url}/"
+      @api_key = api_key
+      @open_timeout = open_timeout
+      @read_timeout = read_timeout
+    end
+
+    def post(path, payload, stream: false, &block)
+      uri = URI.join(@base_url, path)
+      request = Net::HTTP::Post.new(uri)
+      request['Authorization'] = "Bearer #{@api_key}"
+      request['Content-Type'] = 'application/json'
+      request['Accept'] = stream ? 'text/event-stream' : 'application/json'
+      request['User-Agent'] = 'octoryn-ruby/0.1.1'
+      request['X-Octoryn-Sdk'] = 'ruby/0.1.1'
+      request.body = JSON.generate(payload)
+
+      Net::HTTP.start(
+        uri.hostname,
+        uri.port,
+        use_ssl: uri.scheme == 'https',
+        open_timeout: @open_timeout,
+        read_timeout: @read_timeout
+      ) do |http|
+        if stream
+          stream_response(http, request, &block)
+        else
+          response = http.request(request)
+          Response.new(response.code.to_i, headers(response), response.body)
+        end
+      end
+    end
+
+    private
+
+    def stream_response(http, request)
+      final = nil
+      http.request(request) do |response|
+        final = Response.new(response.code.to_i, headers(response), nil)
+        yield final, nil
+        response.read_body { |chunk| yield final, chunk }
+      end
+      final
+    end
+
+    def headers(response)
+      response.each_header.to_h
+    end
+  end
+end

data/lib/octoryn/types.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Octoryn
+  GovernanceMetadata = Data.define(
+    :run_id,
+    :upstream,
+    :byok,
+    :region,
+    :route,
+    :policy_decision,
+    :evidence_hash,
+    :estimated_cost
+  )
+
+  ToolCall = Data.define(:id, :name, :arguments, :type) do
+    def decode_input
+      value = JSON.parse(arguments)
+      raise JSON::ParserError, 'tool arguments must be an object' unless value.is_a?(Hash)
+
+      value
+    end
+  end
+
+  TextResult = Data.define(
+    :text,
+    :tool_calls,
+    :finish_reason,
+    :usage,
+    :octoryn,
+    :response
+  )
+
+  ObjectResult = Data.define(:object, :result)
+
+  StreamEvent = Data.define(
+    :type,
+    :text,
+    :tool_call,
+    :usage,
+    :finish_reason,
+    :octoryn,
+    :provider_event,
+    :error
+  )
+end

data/lib/octoryn/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Octoryn
+  VERSION = '0.1.1'
+end

data/lib/octoryn.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative 'octoryn/version'
+require_relative 'octoryn/errors'
+require_relative 'octoryn/types'
+require_relative 'octoryn/transport'
+require_relative 'octoryn/text_stream'
+require_relative 'octoryn/client'

metadata

@@ -0,0 +1,65 @@
+--- !ruby/object:Gem::Specification
+name: octoryn-sdk
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Octopus Core Pty Ltd
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: json_schemer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.4'
+email:
+- support@octoryn.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/octoryn.rb
+- lib/octoryn/client.rb
+- lib/octoryn/errors.rb
+- lib/octoryn/text_stream.rb
+- lib/octoryn/transport.rb
+- lib/octoryn/types.rb
+- lib/octoryn/version.rb
+homepage: https://octoryn.dev
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/octopusos/octoryn-ruby
+  documentation_uri: https://octoryn.dev/docs
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Governed AI SDK for Octoryn Router
+test_files: []