spurline-docs 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d01e41a525f02722170194e4cbe75d41ffa59143cc22b04c6530f8e44bfddfab
+  data.tar.gz: 6421a4919f0727e7527beadae4ef1867adaca01657b97c91522c42999f401031
+SHA512:
+  metadata.gz: 5c063bca9b9cd710dbf1497505d4db261ee03fba423d98f24817d064eec2e696aae0c319f22a8e4f4982ebe2f64b10f4559873c5bb58d180081c062a61731746
+  data.tar.gz: 290f4d0784c2d8e1bdb12e2cdcf77b5a6e50a1c3afe83e14e5d770d5a6697e1607974b528714c9636760d6207e9cc2755c7c367ed52b33e4ef432a2219b4bd90

data/lib/spurline/adapters/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    # Abstract base class for LLM adapters. Adapters translate between
+    # Spurline's internal representation and a specific LLM API.
+    #
+    # The primary interface is #stream (ADR-001). The scheduler parameter
+    # is the async seam (ADR-002).
+    class Base
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system:, tools:, config:, scheduler: Scheduler::Sync.new, &chunk_handler)
+        raise NotImplementedError, "#{self.class.name} must implement #stream"
+      end
+    end
+  end
+end

data/lib/spurline/adapters/claude.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+require "json"
+
+module Spurline
+  module Adapters
+    # Claude adapter using the official anthropic gem.
+    # Translates between Spurline's internal representation and the Claude API.
+    #
+    # This adapter streams responses and converts API events into
+    # Spurline::Streaming::Chunk objects.
+    class Claude < Base
+      DEFAULT_MODEL = "claude-sonnet-4-20250514"
+      DEFAULT_MAX_TOKENS = 4096
+
+      def initialize(api_key: nil, model: nil, max_tokens: nil)
+        @api_key = resolve_api_key(api_key)
+        @model = model || DEFAULT_MODEL
+        @max_tokens = max_tokens || DEFAULT_MAX_TOKENS
+      end
+
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system: nil, tools: [], config: {}, scheduler: Scheduler::Sync.new, &chunk_handler)
+        model = config[:model] || @model
+        max_tokens = config[:max_tokens] || @max_tokens
+        turn = config[:turn] || 1
+        pending_tool_input_snapshots = []
+
+        scheduler.run do
+          client = build_client
+
+          params = {
+            model: model,
+            max_tokens: max_tokens,
+            messages: format_messages(messages),
+          }
+
+          params[:system] = system if system && !system.empty?
+          params[:tools] = format_tools(tools) if tools && !tools.empty?
+          params[:tool_choice] = config[:tool_choice] if config[:tool_choice]
+
+          client.messages.stream(**params).each do |event|
+            handle_stream_event(
+              event,
+              turn: turn,
+              pending_tool_input_snapshots: pending_tool_input_snapshots,
+              &chunk_handler
+            )
+          end
+        end
+      end
+
+      private
+
+      def resolve_api_key(explicit_key)
+        candidates = [
+          explicit_key,
+          ENV.fetch("ANTHROPIC_API_KEY", nil),
+          Spurline.credentials["anthropic_api_key"],
+        ]
+        key = candidates.find { |value| present_string?(value) }
+        return key if key
+
+        raise Spurline::ConfigurationError,
+          "Missing Anthropic API key for adapter :claude. " \
+          "Set ANTHROPIC_API_KEY, add anthropic_api_key to Spurline.credentials, " \
+          "or pass api_key:."
+      end
+
+      def present_string?(value)
+        return false if value.nil?
+        return !value.strip.empty? if value.respond_to?(:strip)
+
+        true
+      end
+
+      def build_client
+        require "anthropic"
+        Anthropic::Client.new(api_key: @api_key)
+      rescue LoadError
+        raise Spurline::ConfigurationError,
+          "The 'anthropic' gem is required for adapter :claude. " \
+          "Add `gem \"anthropic\"` to your Gemfile."
+      end
+
+      def format_messages(messages)
+        messages.map do |msg|
+          content = msg[:content]
+
+          # Content blocks (tool_use, tool_result) pass through as-is
+          formatted_content = if content.is_a?(Array)
+            content
+          else
+            content.to_s
+          end
+
+          {
+            role: msg[:role] || "user",
+            content: formatted_content,
+          }
+        end
+      end
+
+      def format_tools(tools)
+        tools.map do |tool|
+          {
+            name: tool[:name].to_s,
+            description: tool[:description].to_s,
+            input_schema: tool[:input_schema] || {},
+          }
+        end
+      end
+
+      def handle_stream_event(event, turn:, pending_tool_input_snapshots:, &chunk_handler)
+        case event
+        when Anthropic::Streaming::TextEvent
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :text,
+              text: event.text,
+              turn: turn,
+            )
+          )
+        when Anthropic::Streaming::InputJsonEvent
+          snapshot = event.respond_to?(:snapshot) ? event.snapshot : nil
+          normalized = normalize_tool_arguments(snapshot)
+          pending_tool_input_snapshots << normalized unless normalized.empty?
+        when Anthropic::Streaming::ContentBlockStopEvent
+          content_block = event.content_block
+          return unless content_block && content_block.type.to_s == "tool_use"
+
+          tool_name = content_block.name.to_s
+          arguments = normalize_tool_arguments(content_block.input)
+          if arguments.empty? && pending_tool_input_snapshots.any?
+            arguments = pending_tool_input_snapshots.last
+          end
+          pending_tool_input_snapshots.clear
+
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :tool_start,
+              turn: turn,
+              metadata: {
+                tool_name: tool_name,
+                tool_use_id: content_block.id,
+                tool_call: {
+                  name: tool_name,
+                  arguments: arguments,
+                },
+              }
+            )
+          )
+        when Anthropic::Streaming::MessageStopEvent
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :done,
+              turn: turn,
+              metadata: { stop_reason: event.message.stop_reason.to_s }
+            )
+          )
+        end
+      end
+
+      def normalize_tool_arguments(raw_input)
+        case raw_input
+        when nil
+          {}
+        when Hash
+          raw_input
+        when String
+          parse_json_object(raw_input)
+        else
+          from_hash_like = extract_hash_like(raw_input)
+          return from_hash_like unless from_hash_like.empty?
+
+          json_candidate = raw_input.respond_to?(:to_json) ? raw_input.to_json : nil
+          parse_json_object(json_candidate)
+        end
+      rescue StandardError
+        {}
+      end
+
+      def extract_hash_like(value)
+        if value.respond_to?(:to_h)
+          converted = value.to_h
+          return converted if converted.is_a?(Hash)
+        end
+
+        if value.respond_to?(:to_hash)
+          converted = value.to_hash
+          return converted if converted.is_a?(Hash)
+        end
+
+        {}
+      rescue StandardError
+        {}
+      end
+
+      def parse_json_object(raw_json)
+        return {} unless raw_json.is_a?(String) && !raw_json.strip.empty?
+
+        parsed = JSON.parse(raw_json)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/spurline/adapters/open_ai.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Spurline
+  module Adapters
+    # OpenAI adapter using the ruby-openai gem.
+    # Translates between Spurline's internal representation and the OpenAI API.
+    class OpenAI < Base
+      DEFAULT_MODEL = "gpt-4o"
+      DEFAULT_MAX_TOKENS = 4096
+
+      STOP_REASON_MAP = {
+        "stop" => "end_turn",
+        "tool_calls" => "tool_use",
+        "length" => "max_tokens",
+        "content_filter" => "content_filter",
+      }.freeze
+
+      def initialize(api_key: nil, model: nil, max_tokens: nil)
+        @api_key = resolve_api_key(api_key)
+        @model = model || DEFAULT_MODEL
+        @max_tokens = max_tokens || DEFAULT_MAX_TOKENS
+      end
+
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system: nil, tools: [], config: {}, scheduler: Scheduler::Sync.new, &chunk_handler)
+        model = config[:model] || @model
+        max_tokens = config[:max_tokens] || @max_tokens
+        turn = config[:turn] || 1
+        pending_tool_calls = {}
+
+        scheduler.run do
+          client = build_client
+
+          params = {
+            model: model,
+            max_tokens: max_tokens,
+            messages: format_messages(messages, system: system),
+            stream: proc do |chunk|
+              handle_stream_chunk(
+                chunk,
+                turn: turn,
+                pending_tool_calls: pending_tool_calls,
+                &chunk_handler
+              )
+            end,
+          }
+
+          params[:tools] = format_tools(tools) if tools && !tools.empty?
+
+          client.chat(parameters: params)
+          flush_pending_tool_calls!(pending_tool_calls, turn: turn, &chunk_handler)
+        end
+      end
+
+      private
+
+      def resolve_api_key(explicit_key)
+        candidates = [
+          explicit_key,
+          ENV.fetch("OPENAI_API_KEY", nil),
+          Spurline.credentials["openai_api_key"],
+        ]
+        key = candidates.find { |value| present_string?(value) }
+        return key if key
+
+        raise Spurline::ConfigurationError,
+          "Missing OpenAI API key for adapter :openai. " \
+          "Set OPENAI_API_KEY, add openai_api_key to Spurline.credentials, " \
+          "or pass api_key:."
+      end
+
+      def present_string?(value)
+        return false if value.nil?
+        return !value.strip.empty? if value.respond_to?(:strip)
+
+        true
+      end
+
+      def build_client
+        require "openai"
+        ::OpenAI::Client.new(access_token: @api_key)
+      rescue LoadError
+        raise Spurline::ConfigurationError,
+          "The 'ruby-openai' gem is required for adapter :openai. " \
+          "Add `gem \"ruby-openai\"` to your Gemfile."
+      end
+
+      # OpenAI expects the system prompt as a message in the message array.
+      def format_messages(messages, system: nil)
+        formatted = []
+        formatted << { role: "system", content: system } if present_string?(system)
+
+        messages.each do |message|
+          formatted << {
+            role: message[:role] || "user",
+            content: message[:content].to_s,
+          }
+        end
+
+        formatted
+      end
+
+      # OpenAI wraps tools in { type: "function", function: { ... } }.
+      def format_tools(tools)
+        tools.map do |tool|
+          {
+            type: "function",
+            function: {
+              name: tool[:name].to_s,
+              description: tool[:description].to_s,
+              parameters: tool[:input_schema] || {},
+            },
+          }
+        end
+      end
+
+      def handle_stream_chunk(chunk, turn:, pending_tool_calls:, &chunk_handler)
+        choice = first_choice(chunk)
+        return unless choice
+
+        delta = read_key(choice, "delta") || {}
+        finish_reason = read_key(choice, "finish_reason")
+
+        content = read_key(delta, "content")
+        if content
+          chunk_handler.call(
+            Streaming::Chunk.new(type: :text, text: content, turn: turn)
+          )
+        end
+
+        tool_calls = read_key(delta, "tool_calls")
+        accumulate_tool_call_deltas!(tool_calls, pending_tool_calls) if tool_calls
+
+        return unless finish_reason
+
+        chunk_handler.call(
+          Streaming::Chunk.new(
+            type: :done,
+            turn: turn,
+            metadata: { stop_reason: STOP_REASON_MAP[finish_reason] || finish_reason }
+          )
+        )
+      end
+
+      def first_choice(chunk)
+        choices = read_key(chunk, "choices")
+        return nil unless choices.is_a?(Array)
+
+        choices.first
+      end
+
+      def read_key(hash, key)
+        return nil unless hash.respond_to?(:[])
+
+        hash[key] || hash[key.to_sym]
+      end
+
+      def accumulate_tool_call_deltas!(tool_call_deltas, pending_tool_calls)
+        return unless tool_call_deltas.is_a?(Array)
+
+        tool_call_deltas.each do |tool_call_delta|
+          index = read_key(tool_call_delta, "index") || 0
+          pending_tool_calls[index] ||= { id: nil, name: "", arguments: "" }
+          tool_call = pending_tool_calls[index]
+
+          tool_call[:id] = read_key(tool_call_delta, "id") || tool_call[:id]
+          function_data = read_key(tool_call_delta, "function") || {}
+
+          name = read_key(function_data, "name")
+          tool_call[:name] = name if name
+
+          arguments_delta = read_key(function_data, "arguments")
+          tool_call[:arguments] += arguments_delta.to_s if arguments_delta
+        end
+      end
+
+      def flush_pending_tool_calls!(pending_tool_calls, turn:, &chunk_handler)
+        pending_tool_calls.keys.sort.each do |index|
+          tool_call = pending_tool_calls[index]
+          next if tool_call[:name].empty?
+
+          chunk_handler.call(
+            Streaming::Chunk.new(
+              type: :tool_start,
+              turn: turn,
+              metadata: {
+                tool_name: tool_call[:name],
+                tool_use_id: tool_call[:id],
+                tool_call: {
+                  name: tool_call[:name],
+                  arguments: parse_tool_arguments(tool_call[:arguments]),
+                },
+              }
+            )
+          )
+        end
+
+        pending_tool_calls.clear
+      end
+
+      def parse_tool_arguments(raw_json)
+        return {} unless raw_json.is_a?(String) && !raw_json.strip.empty?
+
+        parsed = JSON.parse(raw_json)
+        parsed.is_a?(Hash) ? parsed : {}
+      rescue JSON::ParserError
+        {}
+      end
+    end
+  end
+end

data/lib/spurline/adapters/registry.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    # Registry of available LLM adapters. Maps symbolic names to adapter classes.
+    class Registry
+      def initialize
+        @adapters = {}
+      end
+
+      def register(name, adapter_class)
+        @adapters[name.to_sym] = adapter_class
+      end
+
+      def resolve(name)
+        name = name.to_sym
+        @adapters.fetch(name) do
+          raise Spurline::AdapterNotFoundError,
+            "Adapter '#{name}' is not registered. Available adapters: " \
+            "#{@adapters.keys.map(&:inspect).join(", ")}."
+        end
+      end
+
+      def registered?(name)
+        @adapters.key?(name.to_sym)
+      end
+
+      def names
+        @adapters.keys
+      end
+    end
+  end
+end

data/lib/spurline/adapters/scheduler/base.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    module Scheduler
+      # Abstract scheduler interface. The scheduler parameter is the async seam (ADR-002).
+      # v1 ships only Sync. A future async scheduler will implement the same interface.
+      class Base
+        def run(&block)
+          raise NotImplementedError, "#{self.class.name} must implement #run"
+        end
+      end
+    end
+  end
+end

data/lib/spurline/adapters/scheduler/sync.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    module Scheduler
+      # Synchronous no-op scheduler. Simply yields the block.
+      # This is the v1 default — the async seam (ADR-002).
+      class Sync < Base
+        def run(&block)
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/spurline/adapters/stub_adapter.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Spurline
+  module Adapters
+    # Test adapter that plays back canned streaming responses.
+    # Ships with the framework — available in production code for testing and demos.
+    #
+    # Usage:
+    #   adapter = StubAdapter.new(responses: [
+    #     stub_text("Here is what I found..."),
+    #     stub_tool_call(:web_search, query: "test"),
+    #     stub_text("Based on my research...")
+    #   ])
+    class StubAdapter < Base
+      attr_reader :calls
+
+      def initialize(responses: [])
+        @responses = responses
+        @response_index = 0
+        @calls = []
+      end
+
+      # ASYNC-READY: scheduler param is the async entry point
+      def stream(messages:, system: nil, tools: [], config: {}, scheduler: Scheduler::Sync.new, &chunk_handler)
+        @calls << { messages: messages, system: system, tools: tools, config: config }
+
+        response = next_response!
+
+        response[:chunks].each do |chunk|
+          chunk_handler.call(chunk)
+        end
+
+        response
+      end
+
+      def call_count
+        @calls.length
+      end
+
+      private
+
+      def next_response!
+        if @response_index >= @responses.length
+          raise "StubAdapter exhausted: #{@responses.length} responses configured, " \
+                "but call ##{@response_index + 1} was made."
+        end
+
+        response = @responses[@response_index]
+        @response_index += 1
+        response
+      end
+    end
+  end
+end