nunki 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 017ee258c9b1ee3339e0f394431890fc96069100ca3aaee503b4da00ff293ab6
+  data.tar.gz: 67fa32687f3fdb13e5c9c153ec3e6db77509aac900bfcf5b4c0ff9a7c55aa1e0
+SHA512:
+  metadata.gz: c232b4ea39676c16571b92cfbe8cc01374f4eb2d822c2d70ec44696e8c2ac9b13d8922f5bb7b8892fe1c02e3a26dde04d6e3b7d518d9b10b9d504525bb8e739d
+  data.tar.gz: 2b125428bf1c14490169d76a8e05e456e5384b82d1cadcb0b2d18f6c956a979562f8e6e08f51c4a9511326ef04d61f9e0894c07a9279c6c0323af744d0258ff7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - 2026-09-16
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,117 @@
+# Nunki
+
+Nunki is a pure Ruby, provider-neutral client for streaming LLM APIs and the
+Model Context Protocol (MCP). It supplies protocol and transport behavior while
+leaving prompts, UI, context selection, and edits to the host application.
+
+## Installation
+
+```bash
+bundle add nunki
+```
+
+## LLM providers
+
+The endpoint is always explicit. Pass the full completion/messages URL supplied
+by your service configuration.
+
+```ruby
+require "nunki"
+
+provider = Nunki::Provider.build(
+  :openai,
+  endpoint: ENV.fetch("LLM_ENDPOINT"),
+  api_key: ENV.fetch("LLM_API_KEY"),
+  model: "configured-model"
+)
+
+text = Nunki::Part.new(
+  type: :text, text: "Explain this method",
+  tool_name: nil, tool_input: nil, tool_use_id: nil
+)
+message = Nunki::Message.new(role: :user, content: [text])
+
+response = provider.complete([message]) do |part|
+  print part.text if part.type == :text
+end
+```
+
+Supported kinds are `:openai`, `:openai_compatible`, `:local`, and
+`:anthropic`. The OpenAI-compatible local kind does not add an authorization
+header unless an API key is supplied. A completion returns `Nunki::Response`;
+tool requests appear as `:tool_use` parts containing `tool_name`, `tool_input`,
+and `tool_use_id`. Send results back as `:tool_result` parts.
+
+`provider.cancel` interrupts streaming or a retry wait. HTTP 429 and 5xx
+responses are retried with exponential backoff. `dispatch:` may move blocking
+work onto an application-owned worker:
+
+```ruby
+provider = Nunki::Provider.build(
+  :local,
+  endpoint: settings.fetch("endpoint"),
+  model: settings.fetch("model"),
+  dispatch: ->(&work) { Thread.new(&work) }
+)
+```
+
+`Nunki.estimate_tokens(value)` provides a byte-based estimate.
+`Nunki.truncate(messages, max_tokens:)` drops the oldest messages while always
+retaining the newest one, or raises if that message alone exceeds the budget.
+
+## MCP
+
+Nunki implements MCP 2025-11-25 over newline-delimited stdio and Streamable
+HTTP. Both transports support tools, resources, prompts, pagination, request
+timeouts, and protocol errors.
+
+```ruby
+client = Nunki::MCP::Client.stdio(command: ["my-mcp-server"])
+# Or: Nunki::MCP::Client.http(url: settings.fetch("mcp_url"), headers: {...})
+
+client.start
+client.tools
+client.call_tool("lookup", {"query" => "Ruby"})
+client.resources
+client.read_resource("file:///project/README.md")
+client.prompts
+client.get_prompt("review", {"language" => "ruby"})
+client.close
+```
+
+`close` closes a stdio server's input, waits briefly, then uses TERM and KILL if
+needed. HTTP sessions are ended with DELETE when the server issued a session ID.
+
+## Limits and security
+
+Default limits are 1 MiB per HTTP request, 8 MiB per HTTP response/SSE event,
+and 4 MiB per stdio MCP message. Provider HTTP defaults are a 10-second connect
+timeout and 60-second read timeout; MCP requests default to 30 seconds. All are
+configurable at construction.
+
+Nunki deliberately accepts local and remote HTTP(S) endpoints because every
+endpoint is configuration-derived. This means an untrusted endpoint setting is
+an SSRF capability: hosts must validate it against their own trust policy.
+Nunki has no default endpoints and never persists credentials; supplied keys
+exist only in the client instance and request headers.
+
+Nunki does not choose prompts or context, render UI, save credentials, execute
+tool requests without a caller decision, or apply model-produced diffs.
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+bundle exec rbs -I sig validate
+BUDGET=1 bundle exec rake bench
+gem build --strict nunki.gemspec
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/noxdea/nunki.
+
+## License
+
+The gem is available under the [MIT License](LICENSE.txt).

data/docs/adr/000-template.md

@@ -0,0 +1,16 @@
+# ADR NNN: Implementation decision title
+
+- Status: Proposed
+- Date: YYYY-MM-DD
+
+## Context
+
+Describe the concrete implementation question and its constraints.
+
+## Decision
+
+Describe the durable boundary or architecture choice.
+
+## Consequences
+
+Describe the important trade-offs and when to revisit the decision.

data/docs/adr/001-explicit-network-boundary.md

@@ -0,0 +1,23 @@
+# ADR 001: Keep network destinations explicit
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+LLM vendors and local servers expose compatible APIs at different URLs. A
+library-selected default would couple provider protocol support to product
+policy and could silently send data to an unintended service.
+
+## Decision
+
+Require a complete HTTP(S) endpoint for every provider and MCP HTTP client.
+Adapters add protocol headers and request shapes but never select a host. API
+keys remain in memory and are not persisted. The host application owns endpoint
+trust and authorization policy.
+
+## Consequences
+
+Nunki supports hosted and local services without product-specific settings.
+Callers must treat endpoint configuration as an SSRF-capable input and validate
+it before constructing a client.

data/docs/adr/002-mcp-transports.md

@@ -0,0 +1,23 @@
+# ADR 002: Implement the stable MCP transports directly
+
+- Status: Accepted
+- Date: 2026-09-15
+
+## Context
+
+Nunki needs only the MCP client lifecycle plus tools, resources, and prompts.
+Adding a full protocol framework would expand dependencies and expose unrelated
+host features.
+
+## Decision
+
+Implement MCP 2025-11-25 JSON-RPC over its stable newline-delimited stdio and
+Streamable HTTP transports. Validate and bound every message. Serialize client
+requests, enforce timeouts, negotiate the exact supported version, and cleanly
+terminate stdio children and HTTP sessions.
+
+## Consequences
+
+The core has no runtime dependencies. Legacy HTTP+SSE, server-side features,
+sampling, elicitation, tasks, and subscriptions remain outside 0.1.0 and can be
+added only when a host needs them.

data/docs/adr/README.md

@@ -0,0 +1,3 @@
+# Architecture decision records
+
+These records document Nunki's durable boundaries.

data/lib/nunki/context.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Nunki
+  module Context
+    module_function
+
+    def estimate_tokens(value)
+      case value
+      when Message
+        estimate_string(value.role.to_s) + estimate_tokens(value.content)
+      when Part
+        estimate_string([value.type, value.text, value.tool_name, value.tool_input, value.tool_use_id].compact.join)
+      when Array
+        value.sum { |item| estimate_tokens(item) }
+      else
+        estimate_string(value.to_s)
+      end
+    end
+
+    def truncate(messages, max_tokens:)
+      Protocol.uint(max_tokens, "max_tokens", positive: true)
+      messages = Protocol.collection(messages, "messages")
+      validate_messages(messages)
+
+      kept = messages.dup
+      kept.shift while kept.length > 1 && estimate_tokens(kept) > max_tokens
+      raise ProtocolError, "latest message exceeds token budget" if estimate_tokens(kept) > max_tokens
+
+      kept.freeze
+    end
+
+    def validate_messages(messages)
+      messages.each do |message|
+        raise ProtocolError, "message must be a Nunki::Message" unless message.is_a?(Message)
+        role = Protocol.string(message.role.to_s, "message role", empty: false, max: 32)
+        raise ProtocolError, "unsupported message role: #{role}" unless %w[system user assistant tool].include?(role)
+        Protocol.collection(message.content, "message content").each do |part|
+          raise ProtocolError, "message content must contain Nunki::Part values" unless part.is_a?(Part)
+          validate_part(part)
+        end
+      end
+    end
+
+    def validate_part(part)
+      case part.type.to_s.to_sym
+      when :text
+        Protocol.string(part.text, "text part")
+      when :tool_use
+        Protocol.string(part.tool_name, "tool name", empty: false, max: 256)
+        Protocol.string(part.tool_use_id, "tool use id", empty: false, max: 1024)
+        Protocol.json(Protocol.object(part.tool_input, "tool input"))
+      when :tool_result
+        Protocol.string(part.tool_use_id, "tool use id", empty: false, max: 1024)
+        Protocol.string(part.text, "tool result")
+      else
+        raise ProtocolError, "unsupported part type: #{part.type}"
+      end
+    end
+
+    def estimate_string(text) = [(text.bytesize + 3) / 4, 1].max
+  end
+
+  def self.estimate_tokens(value) = Context.estimate_tokens(value)
+  def self.truncate(messages, max_tokens:) = Context.truncate(messages, max_tokens: max_tokens)
+end

data/lib/nunki/http.rb

@@ -0,0 +1,198 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "timeout"
+require "uri"
+
+module Nunki
+  module HTTP
+    Result = Value.define(:status, :headers, :body, :events)
+
+    class Client
+      DEFAULT_MAX_REQUEST_BYTES = 1_048_576
+      DEFAULT_MAX_RESPONSE_BYTES = 8_388_608
+      RETRY_STATUSES = [429, *(500..599)].freeze
+
+      attr_reader :endpoint
+
+      def initialize(endpoint:, headers: {}, open_timeout: 10, read_timeout: 60, retries: 2,
+        retry_base: 0.25, max_request_bytes: DEFAULT_MAX_REQUEST_BYTES,
+        max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
+        @endpoint = parse_endpoint(endpoint)
+        @headers = validate_headers(headers)
+        @open_timeout = positive_number(open_timeout, "open_timeout")
+        @read_timeout = positive_number(read_timeout, "read_timeout")
+        @retries = Protocol.uint(retries, "retries")
+        @retry_base = nonnegative_number(retry_base, "retry_base")
+        @max_request_bytes = Protocol.uint(max_request_bytes, "max_request_bytes", positive: true)
+        @max_response_bytes = Protocol.uint(max_response_bytes, "max_response_bytes", positive: true)
+        @state_lock = Mutex.new
+        @state_changed = ConditionVariable.new
+        @cancel_epoch = 0
+        @active = []
+      end
+
+      def post_json(payload, headers: {}, &event_handler)
+        body = JSON.generate(Protocol.json(payload))
+        raise ProtocolError, "request exceeds #{@max_request_bytes} bytes" if body.bytesize > @max_request_bytes
+
+        request(Net::HTTP::Post, body, headers, &event_handler)
+      end
+
+      def delete(headers: {}) = request(Net::HTTP::Delete, nil, headers)
+
+      def cancel
+        connections = @state_lock.synchronize do
+          @cancel_epoch += 1
+          @state_changed.broadcast
+          @active.dup
+        end
+        connections.each do |http|
+          http.finish if http.active?
+        rescue IOError, SystemCallError
+          nil
+        end
+        nil
+      end
+
+      private
+
+      def request(request_class, body, headers)
+        epoch = @state_lock.synchronize { @cancel_epoch }
+        attempts = 0
+        loop do
+          response = perform(request_class, body, validate_headers(headers), epoch) do |event, response_headers|
+            yield event, response_headers if block_given?
+          end
+          if RETRY_STATUSES.include?(response.status) && attempts < @retries
+            attempts += 1
+            wait_retry(@retry_base * (2**(attempts - 1)), epoch)
+            next
+          end
+
+          raise_http_error(response) unless (200..299).cover?(response.status)
+          return response
+        end
+      rescue ::Timeout::Error => error
+        raise Cancelled, "request cancelled" if cancelled?(epoch)
+        raise Timeout, error.message
+      rescue IOError, EOFError, SocketError, SystemCallError => error
+        raise Cancelled, "request cancelled" if cancelled?(epoch)
+        raise Error, error.message
+      end
+
+      def perform(request_class, body, extra_headers, epoch)
+        raise Cancelled, "request cancelled" if cancelled?(epoch)
+
+        http = Net::HTTP.new(@endpoint.host, @endpoint.port)
+        http.use_ssl = @endpoint.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+        @state_lock.synchronize do
+          raise Cancelled, "request cancelled" unless @cancel_epoch == epoch
+          @active << http
+        end
+
+        request = request_class.new(request_target)
+        @headers.merge(extra_headers).each { |key, value| request[key] = value }
+        if body
+          request["Content-Type"] ||= "application/json"
+          request.body = body
+        end
+
+        result = nil
+        http.start do
+          raise Cancelled, "request cancelled" if cancelled?(epoch)
+          http.request(request) do |response|
+            result = read_response(response, epoch) do |event, response_headers|
+              yield event, response_headers if block_given?
+            end
+          end
+        end
+        result
+      ensure
+        @state_lock.synchronize { @active.delete(http) } if http
+      end
+
+      def read_response(response, epoch)
+        headers = response.each_header.to_h.freeze
+        parser = SSE::Parser.new(max_event_bytes: @max_response_bytes) if sse?(headers)
+        bytes = 0
+        body = +""
+        events = []
+
+        response.read_body do |chunk|
+          raise Cancelled, "request cancelled" if cancelled?(epoch)
+          bytes += chunk.bytesize
+          raise ProtocolError, "response exceeds #{@max_response_bytes} bytes" if bytes > @max_response_bytes
+          if parser
+            parser.feed(chunk).each do |event|
+              events << event
+              yield event, headers if block_given? && response.is_a?(Net::HTTPSuccess)
+            end
+          else
+            body << chunk
+          end
+        end
+        parser&.finish&.each do |event|
+          events << event
+          yield event, headers if block_given? && response.is_a?(Net::HTTPSuccess)
+        end
+        Result.new(status: response.code.to_i, headers: headers, body: body.freeze, events: events.freeze)
+      end
+
+      def raise_http_error(result)
+        retry_after = Float(result.headers["retry-after"], exception: false)
+        raise RateLimited.new(result.body, retry_after: retry_after) if result.status == 429
+        raise HTTPError.new(result.status, result.body)
+      end
+
+      def wait_retry(seconds, epoch)
+        @state_lock.synchronize do
+          @state_changed.wait(@state_lock, seconds) if @cancel_epoch == epoch && !seconds.zero?
+          raise Cancelled, "request cancelled" unless @cancel_epoch == epoch
+        end
+      end
+
+      def cancelled?(epoch) = @state_lock.synchronize { @cancel_epoch != epoch }
+
+      def sse?(headers)
+        headers.fetch("content-type", "").downcase.start_with?("text/event-stream")
+      end
+
+      def request_target
+        path = @endpoint.path.empty? ? "/" : @endpoint.path
+        @endpoint.query ? "#{path}?#{@endpoint.query}" : path
+      end
+
+      def parse_endpoint(endpoint)
+        uri = URI.parse(Protocol.string(endpoint, "endpoint", empty: false, max: 4096))
+        valid = %w[http https].include?(uri.scheme) && uri.host && !uri.userinfo && !uri.fragment
+        raise ProtocolError, "endpoint must be an HTTP(S) URL without credentials or fragment" unless valid
+        uri
+      rescue URI::InvalidURIError => error
+        raise ProtocolError, "invalid endpoint: #{error.message}"
+      end
+
+      def validate_headers(headers)
+        raise ProtocolError, "headers must be an object" unless headers.is_a?(Hash)
+        headers.to_h do |key, value|
+          key = Protocol.string(key.to_s, "header name", empty: false, max: 256)
+          value = Protocol.string(value, "header value", max: 8192)
+          raise ProtocolError, "headers must not contain newlines" if key.match?(/[\r\n]/) || value.match?(/[\r\n]/)
+          [key, value]
+        end.freeze
+      end
+
+      def positive_number(value, name)
+        raise ProtocolError, "#{name} must be positive" unless value.is_a?(Numeric) && value.positive?
+        value
+      end
+
+      def nonnegative_number(value, name)
+        raise ProtocolError, "#{name} must not be negative" unless value.is_a?(Numeric) && value >= 0
+        value
+      end
+    end
+  end
+end