nunki 0.1.0

data/lib/nunki/providers/anthropic.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Nunki
+  module Providers
+    class Anthropic < Provider
+      def self.headers(api_key)
+        api_key ? {"x-api-key" => Protocol.string(api_key, "api_key", empty: false, max: 8192)} : {}
+      end
+
+      def initialize(client:, model:, api_version: "2023-06-01", **options)
+        super(client: client, model: model, **options)
+        @api_version = Protocol.string(api_version, "api_version", empty: false, max: 64)
+      end
+
+      private
+
+      def perform_complete(prepared)
+        messages, tools, system, max_tokens = prepared
+        payload = {model: @model, messages: messages.map { |message| encode_message(message) }, max_tokens: max_tokens, stream: true}
+        payload[:system] = system if system
+        payload[:tools] = tools.map { |tool| encode_tool(tool) } unless tools.empty?
+        state = {parts: [], active: {}, usage: [0, 0], finish: nil}
+
+        result = @client.post_json(payload, headers: {
+          "Accept" => "text/event-stream, application/json",
+          "anthropic-version" => @api_version
+        }) do |event|
+          next if event.data.empty?
+          consume_stream(parse_event(event), state) { |part| yield part if block_given? }
+        end
+        return consume_response(result.body, messages) unless result.body.empty?
+
+        usage = state[:usage]
+        usage[0] = Nunki.estimate_tokens(messages) if usage[0].zero?
+        usage[1] = Nunki.estimate_tokens(state[:parts]) if usage[1].zero?
+        response(state[:parts], usage, state[:finish])
+      end
+
+      def consume_stream(message, state)
+        case message["type"]
+        when "message_start"
+          usage = Protocol.object(Protocol.object(message["message"], "message")["usage"], "usage")
+          state[:usage][0] = Protocol.uint(usage.fetch("input_tokens", 0), "input tokens")
+        when "content_block_start"
+          start_block(message, state) { |part| yield part }
+        when "content_block_delta"
+          consume_delta(message, state) { |part| yield part }
+        when "content_block_stop"
+          finish_block(message, state) { |part| yield part }
+        when "message_delta"
+          delta = Protocol.object(message["delta"], "message delta")
+          state[:finish] = Protocol.string(delta["stop_reason"], "stop reason") if delta["stop_reason"]
+          usage = Protocol.object(message.fetch("usage", {}), "usage")
+          state[:usage][1] = Protocol.uint(usage["output_tokens"], "output tokens") if usage["output_tokens"]
+        when "error"
+          error = Protocol.object(message["error"], "error")
+          raise Error, Protocol.string(error["message"], "error message")
+        end
+      end
+
+      def start_block(message, state)
+        index = Protocol.uint(message["index"], "content index")
+        block = Protocol.object(message["content_block"], "content block")
+        case block["type"]
+        when "text"
+          text = Protocol.string(block.fetch("text", ""), "text")
+          state[:active][index] = {type: :text, text: +text}
+          yield text_part(text) unless text.empty?
+        when "tool_use"
+          state[:active][index] = {
+            type: :tool_use,
+            id: Protocol.string(block["id"], "tool id", empty: false),
+            name: Protocol.string(block["name"], "tool name", empty: false),
+            input: block["input"], json: +""
+          }
+        end
+      end
+
+      def consume_delta(message, state)
+        index = Protocol.uint(message["index"], "content index")
+        block = state[:active][index]
+        return unless block
+        delta = Protocol.object(message["delta"], "content delta")
+        if delta["type"] == "text_delta"
+          text = Protocol.string(delta["text"], "text delta")
+          block[:text] << text
+          yield text_part(text)
+        elsif delta["type"] == "input_json_delta"
+          block[:json] << Protocol.string(delta["partial_json"], "tool input delta")
+        end
+      end
+
+      def finish_block(message, state)
+        block = state[:active].delete(Protocol.uint(message["index"], "content index"))
+        return unless block
+        if block[:type] == :text
+          state[:parts] << text_part(block[:text]) unless block[:text].empty?
+        else
+          input = block[:json].empty? ? Protocol.object(block[:input], "tool input") :
+            Protocol.object(Protocol.parse(block[:json], "tool input"), "tool input")
+          part = tool_part(block[:name], input, block[:id])
+          state[:parts] << part
+          yield part
+        end
+      end
+
+      def consume_response(body, messages)
+        value = Protocol.object(Protocol.parse(body), "response")
+        parts = Protocol.collection(value["content"], "content").map { |part| decode_part(part) }
+        usage = Protocol.object(value.fetch("usage", {}), "usage")
+        counts = [
+          usage["input_tokens"] ? Protocol.uint(usage["input_tokens"], "input tokens") : Nunki.estimate_tokens(messages),
+          usage["output_tokens"] ? Protocol.uint(usage["output_tokens"], "output tokens") : Nunki.estimate_tokens(parts)
+        ]
+        response(parts, counts, value["stop_reason"])
+      end
+
+      def decode_part(value)
+        value = Protocol.object(value, "content part")
+        return text_part(Protocol.string(value["text"], "text")) if value["type"] == "text"
+        raise ProtocolError, "unsupported content type" unless value["type"] == "tool_use"
+        tool_part(
+          Protocol.string(value["name"], "tool name", empty: false),
+          Protocol.object(value["input"], "tool input"),
+          Protocol.string(value["id"], "tool id", empty: false)
+        )
+      end
+
+      def encode_message(message)
+        {role: message.role.to_s, content: message.content.map { |part| encode_part(part) }}
+      end
+
+      def encode_part(part)
+        case part.type.to_s.to_sym
+        when :text then {type: "text", text: part.text}
+        when :tool_use then {type: "tool_use", id: part.tool_use_id, name: part.tool_name, input: part.tool_input}
+        when :tool_result then {type: "tool_result", tool_use_id: part.tool_use_id, content: part.text}
+        else raise ProtocolError, "unsupported part type: #{part.type}"
+        end
+      end
+
+      def encode_tool(tool)
+        {name: tool.name, description: tool.description, input_schema: tool.input_schema}
+      end
+    end
+  end
+end

data/lib/nunki/providers/open_ai.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Nunki
+  module Providers
+    class OpenAI < Provider
+      def self.headers(api_key)
+        api_key ? {"Authorization" => "Bearer #{Protocol.string(api_key, "api_key", empty: false, max: 8192)}"} : {}
+      end
+
+      private
+
+      def perform_complete(prepared)
+        messages, tools, system, max_tokens = prepared
+        messages = [Message.new(role: :system, content: [text_part(system)])] + messages if system
+        payload = {
+          model: @model,
+          messages: messages.map { |message| encode_message(message) },
+          max_tokens: max_tokens,
+          stream: true
+        }
+        payload[:tools] = tools.map { |tool| encode_tool(tool) } unless tools.empty?
+
+        state = {text: +"", tools: {}, finish: nil, usage: nil}
+        result = @client.post_json(payload, headers: {"Accept" => "text/event-stream, application/json"}) do |event|
+          next if event.data.empty? || event.data == "[DONE]"
+          consume_stream(parse_event(event), state) { |part| yield part if block_given? }
+        end
+        return consume_response(result.body, messages) unless result.body.empty?
+
+        parts = []
+        parts << text_part(state[:text]) unless state[:text].empty?
+        state[:tools].sort.each do |_index, tool|
+          part = tool_part(tool[:name], parse_tool_input(tool[:arguments]), tool[:id])
+          parts << part
+          yield part if block_given?
+        end
+        usage = state[:usage] || [Nunki.estimate_tokens(messages), Nunki.estimate_tokens(parts)]
+        response(parts, usage, state[:finish])
+      end
+
+      def consume_stream(message, state)
+        usage = message["usage"]
+        usage = Protocol.object(usage, "usage") if usage
+        state[:usage] = [usage["prompt_tokens"], usage["completion_tokens"]].map { |v| Protocol.uint(v, "usage") } if usage
+
+        Protocol.collection(message.fetch("choices", []), "choices").each do |choice|
+          choice = Protocol.object(choice, "choice")
+          state[:finish] = Protocol.string(choice["finish_reason"], "finish reason") if choice["finish_reason"]
+          delta = Protocol.object(choice.fetch("delta", {}), "delta")
+          if delta["content"]
+            text = Protocol.string(delta["content"], "content delta")
+            state[:text] << text
+            yield text_part(text)
+          end
+          consume_tool_deltas(delta["tool_calls"], state) if delta["tool_calls"]
+        end
+      end
+
+      def consume_tool_deltas(calls, state)
+        Protocol.collection(calls, "tool calls").each do |call|
+          call = Protocol.object(call, "tool call")
+          index = Protocol.uint(call["index"], "tool call index")
+          tool = state[:tools][index] ||= {id: nil, name: +"", arguments: +""}
+          tool[:id] = Protocol.string(call["id"], "tool call id") if call["id"]
+          function = Protocol.object(call.fetch("function", {}), "tool function")
+          tool[:name] << Protocol.string(function["name"], "tool name") if function["name"]
+          tool[:arguments] << Protocol.string(function["arguments"], "tool arguments") if function["arguments"]
+        end
+      end
+
+      def consume_response(body, messages)
+        message = Protocol.object(Protocol.parse(body), "response")
+        choice = Protocol.object(Protocol.collection(message["choices"], "choices").first, "choice")
+        value = Protocol.object(choice["message"], "message")
+        parts = []
+        parts << text_part(Protocol.string(value["content"], "content")) if value["content"]
+        consume_nonstream_tools(value["tool_calls"], parts) if value["tool_calls"]
+        usage = message["usage"]
+        usage = Protocol.object(usage, "usage") if usage
+        counts = usage ? [usage["prompt_tokens"], usage["completion_tokens"]].map { |v| Protocol.uint(v, "usage") } :
+          [Nunki.estimate_tokens(messages), Nunki.estimate_tokens(parts)]
+        finish = choice["finish_reason"] && Protocol.string(choice["finish_reason"], "finish reason")
+        response(parts, counts, finish)
+      end
+
+      def consume_nonstream_tools(calls, parts)
+        Protocol.collection(calls, "tool calls").each do |call|
+          call = Protocol.object(call, "tool call")
+          function = Protocol.object(call["function"], "tool function")
+          parts << tool_part(
+            Protocol.string(function["name"], "tool name", empty: false),
+            parse_tool_input(Protocol.string(function["arguments"], "tool arguments")),
+            Protocol.string(call["id"], "tool id", empty: false)
+          )
+        end
+      end
+
+      def encode_message(message)
+        role = message.role.to_s
+        text = message.content.select { |part| part.type.to_s.to_sym == :text }.map(&:text).join
+        results = message.content.select { |part| part.type.to_s.to_sym == :tool_result }
+        if results.any?
+          raise ProtocolError, "OpenAI tool result messages must contain exactly one result" unless results.one? && text.empty?
+          return {role: "tool", tool_call_id: results.first.tool_use_id, content: results.first.text}
+        end
+
+        encoded = {role: role, content: text.empty? ? nil : text}
+        calls = message.content.select { |part| part.type.to_s.to_sym == :tool_use }
+        encoded[:tool_calls] = calls.map do |part|
+          {id: part.tool_use_id, type: "function", function: {name: part.tool_name, arguments: JSON.generate(part.tool_input)}}
+        end unless calls.empty?
+        encoded
+      end
+
+      def encode_tool(tool)
+        {type: "function", function: {name: tool.name, description: tool.description, parameters: tool.input_schema}}
+      end
+
+      def parse_tool_input(json)
+        Protocol.object(Protocol.parse(json, "tool input"), "tool input")
+      end
+    end
+  end
+end

data/lib/nunki/sse.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Nunki
+  module SSE
+    Event = Value.define(:event, :data, :id, :retry)
+
+    class Parser
+      DEFAULT_MAX_EVENT_BYTES = 1_048_576
+
+      def initialize(max_event_bytes: DEFAULT_MAX_EVENT_BYTES)
+        @max_event_bytes = Protocol.uint(max_event_bytes, "max_event_bytes", positive: true)
+        @buffer = +""
+        reset_event
+      end
+
+      def feed(chunk)
+        raise ProtocolError, "SSE chunk must be a string" unless chunk.is_a?(String)
+        @buffer << chunk
+        events = []
+        while (newline = @buffer.index("\n"))
+          line = @buffer.slice!(0, newline + 1).delete_suffix("\n").delete_suffix("\r")
+          consume(line, events)
+        end
+        raise ProtocolError, "SSE event exceeds #{@max_event_bytes} bytes" if event_bytes > @max_event_bytes
+        events
+      end
+
+      def finish
+        events = []
+        consume(@buffer.delete_suffix("\r"), events) unless @buffer.empty?
+        dispatch(events) if @seen
+        @buffer.clear
+        events
+      end
+
+      private
+
+      def consume(line, events)
+        if line.empty?
+          dispatch(events)
+          return
+        end
+        return if line.start_with?(":")
+
+        field, value = line.split(":", 2)
+        value = value&.delete_prefix(" ") || ""
+        @seen = true
+        case field
+        when "event" then @event = value
+        when "data" then @data << value
+        when "id" then @id = value unless value.include?("\0")
+        when "retry" then @retry = Integer(value, exception: false) if value.match?(/\A\d+\z/)
+        end
+      end
+
+      def dispatch(events)
+        return reset_event unless @seen
+
+        events << Event.new(event: @event, data: @data.join("\n"), id: @id, retry: @retry)
+        reset_event
+      end
+
+      def reset_event
+        @event = nil
+        @data = []
+        @id = nil
+        @retry = nil
+        @seen = false
+      end
+
+      def event_bytes = @buffer.bytesize + @data.sum(&:bytesize)
+    end
+  end
+end

data/lib/nunki/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Nunki
+  VERSION = "0.1.0"
+end

data/lib/nunki.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require_relative "nunki/version"
+
+module Nunki
+  class Error < StandardError; end
+  class ProtocolError < Error; end
+  class Timeout < Error; end
+  class Cancelled < Error; end
+
+  class HTTPError < Error
+    attr_reader :status, :body
+
+    def initialize(status, body = nil)
+      @status = status
+      @body = body
+      super("HTTP request failed with status #{status}")
+    end
+  end
+
+  class RateLimited < HTTPError
+    attr_reader :retry_after
+
+    def initialize(body = nil, retry_after: nil)
+      @retry_after = retry_after
+      super(429, body)
+    end
+  end
+
+  module Value
+    module_function
+
+    def define(*members)
+      return Data.define(*members) if defined?(Data) && Data.respond_to?(:define)
+
+      Struct.new(*members) do
+        members.each { |member| undef_method("#{member}=") }
+
+        define_method(:initialize) do |*values, **keywords|
+          if keywords.empty?
+            raise ArgumentError, "wrong number of arguments" unless values.length == self.class.members.length
+            super(*values)
+          else
+            raise ArgumentError, "cannot mix positional and keyword arguments" unless values.empty?
+
+            missing = self.class.members - keywords.keys
+            unknown = keywords.keys - self.class.members
+            raise ArgumentError, "missing keyword: #{missing.first.inspect}" unless missing.empty?
+            raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+
+            super(*self.class.members.map { |member| keywords.fetch(member) })
+          end
+          freeze
+        end
+
+        define_method(:with) do |**changes|
+          return self if changes.empty?
+          unknown = changes.keys - self.class.members
+          raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?
+          self.class.new(**to_h.merge(changes))
+        end
+      end
+    end
+  end
+
+  Message = Value.define(:role, :content)
+  Part = Value.define(:type, :text, :tool_name, :tool_input, :tool_use_id)
+  Tool = Value.define(:name, :description, :input_schema)
+  Usage = Value.define(:input_tokens, :output_tokens)
+  Response = Value.define(:message, :usage, :finish_reason)
+  private_constant :Value
+end
+
+require_relative "nunki/protocol"
+require_relative "nunki/context"
+require_relative "nunki/sse"
+require_relative "nunki/http"
+require_relative "nunki/provider"
+require_relative "nunki/providers/open_ai"
+require_relative "nunki/providers/anthropic"
+require_relative "nunki/mcp"

data/sig/nunki.rbs

@@ -0,0 +1,132 @@
+module Nunki
+  VERSION: String
+
+  type json = nil | bool | Integer | Float | String | Array[json] | Hash[String | Symbol, json]
+  type object = Hash[String | Symbol, json]
+
+  class Error < StandardError
+  end
+  class ProtocolError < Error
+  end
+  class Timeout < Error
+  end
+  class Cancelled < Error
+  end
+  class HTTPError < Error
+    attr_reader status: Integer
+    attr_reader body: String?
+    def initialize: (Integer status, ?String? body) -> void
+  end
+  class RateLimited < HTTPError
+    attr_reader retry_after: Float?
+    def initialize: (?String? body, ?retry_after: Float?) -> void
+  end
+
+  class Message
+    attr_reader role: String | Symbol
+    attr_reader content: Array[Part]
+    def self.new: (String | Symbol, Array[Part]) -> Message
+                | (role: String | Symbol, content: Array[Part]) -> Message
+    def with: (?role: String | Symbol, ?content: Array[Part]) -> Message
+  end
+  class Part
+    attr_reader type: String | Symbol
+    attr_reader text: String?
+    attr_reader tool_name: String?
+    attr_reader tool_input: object?
+    attr_reader tool_use_id: String?
+    def self.new: (String | Symbol, String?, String?, object?, String?) -> Part
+                | (type: String | Symbol, text: String?, tool_name: String?, tool_input: object?, tool_use_id: String?) -> Part
+    def with: (?type: String | Symbol, ?text: String?, ?tool_name: String?, ?tool_input: object?, ?tool_use_id: String?) -> Part
+  end
+  class Tool
+    attr_reader name: String
+    attr_reader description: String
+    attr_reader input_schema: object
+    def self.new: (String, String, object) -> Tool
+                | (name: String, description: String, input_schema: object) -> Tool
+    def with: (?name: String, ?description: String, ?input_schema: object) -> Tool
+  end
+  class Usage
+    attr_reader input_tokens: Integer
+    attr_reader output_tokens: Integer
+    def self.new: (Integer, Integer) -> Usage
+                | (input_tokens: Integer, output_tokens: Integer) -> Usage
+    def with: (?input_tokens: Integer, ?output_tokens: Integer) -> Usage
+  end
+  class Response
+    attr_reader message: Message
+    attr_reader usage: Usage
+    attr_reader finish_reason: String?
+    def self.new: (Message, Usage, String?) -> Response
+                | (message: Message, usage: Usage, finish_reason: String?) -> Response
+    def with: (?message: Message, ?usage: Usage, ?finish_reason: String?) -> Response
+  end
+
+  def self.estimate_tokens: (Message | Part | Array[Message | Part] | String value) -> Integer
+  def self.truncate: (Array[Message] messages, max_tokens: Integer) -> Array[Message]
+
+  class Provider
+    def self.build: (String | Symbol kind, endpoint: String, ?api_key: String?, model: String, **untyped options) -> Provider
+    def complete: (Array[Message] messages, ?tools: Array[Tool], ?system: String?, ?max_tokens: Integer) ?{ (Part) -> untyped } -> untyped
+    def cancel: () -> untyped
+  end
+
+  module SSE
+    class Event
+      attr_reader event: String?
+      attr_reader data: String
+      attr_reader id: String?
+      attr_reader retry: Integer?
+      def self.new: (String?, String, String?, Integer?) -> Event
+                  | (event: String?, data: String, id: String?, retry: Integer?) -> Event
+      def with: (?event: String?, ?data: String, ?id: String?, ?retry: Integer?) -> Event
+    end
+    class Parser
+      def initialize: (?max_event_bytes: Integer) -> void
+      def feed: (String chunk) -> Array[Event]
+      def finish: () -> Array[Event]
+    end
+  end
+
+  module HTTP
+    class Result
+      attr_reader status: Integer
+      attr_reader headers: Hash[String, String]
+      attr_reader body: String
+      attr_reader events: Array[SSE::Event]
+      def self.new: (Integer, Hash[String, String], String, Array[SSE::Event]) -> Result
+                  | (status: Integer, headers: Hash[String, String], body: String, events: Array[SSE::Event]) -> Result
+      def with: (?status: Integer, ?headers: Hash[String, String], ?body: String, ?events: Array[SSE::Event]) -> Result
+    end
+    class Client
+      attr_reader endpoint: untyped
+      def initialize: (endpoint: String, ?headers: Hash[String, String], ?open_timeout: Numeric, ?read_timeout: Numeric, ?retries: Integer, ?retry_base: Numeric, ?max_request_bytes: Integer, ?max_response_bytes: Integer) -> void
+      def post_json: (json payload, ?headers: Hash[String, String]) ?{ (SSE::Event, Hash[String, String]) -> untyped } -> Result
+      def delete: (?headers: Hash[String, String]) -> Result
+      def cancel: () -> untyped
+    end
+  end
+
+  module MCP
+    PROTOCOL_VERSION: String
+    class RemoteError < Error
+      attr_reader code: Integer
+      attr_reader data: json
+    end
+    class Client
+      attr_reader capabilities: object
+      attr_reader server_info: object
+      def self.stdio: (command: Array[String], ?env: Hash[String, String], ?timeout: Numeric, ?dispatch: untyped) -> Client
+      def self.http: (url: String, ?headers: Hash[String, String], ?timeout: Numeric, ?dispatch: untyped, **untyped options) -> Client
+      def start: () -> untyped
+      def tools: () -> untyped
+      def call_tool: (String name, object arguments) -> untyped
+      def resources: () -> untyped
+      def read_resource: (String uri) -> untyped
+      def prompts: () -> untyped
+      def get_prompt: (String name, ?object arguments) -> untyped
+      def close: () -> untyped
+    end
+  end
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification
+name: nunki
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- docs/adr/000-template.md
+- docs/adr/001-explicit-network-boundary.md
+- docs/adr/002-mcp-transports.md
+- docs/adr/README.md
+- lib/nunki.rb
+- lib/nunki/context.rb
+- lib/nunki/http.rb
+- lib/nunki/mcp.rb
+- lib/nunki/mcp/transports.rb
+- lib/nunki/protocol.rb
+- lib/nunki/provider.rb
+- lib/nunki/providers/anthropic.rb
+- lib/nunki/providers/open_ai.rb
+- lib/nunki/sse.rb
+- lib/nunki/version.rb
+- sig/nunki.rbs
+homepage: https://github.com/noxdea/nunki
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/noxdea/nunki
+  changelog_uri: https://github.com/noxdea/nunki/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+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: 4.0.16
+specification_version: 4
+summary: Provider-neutral LLM and MCP clients for Ruby
+test_files: []