dexter_llm 0.1.2

data/lib/dexter_llm/adapters/openai.rb

@@ -0,0 +1,415 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module DexterLlm
+  module Adapters
+    class OpenAI < Base
+      DEFAULT_BASE_URL = "https://api.openai.com".freeze
+
+      def initialize(api_key:, base_url: nil, open_timeout: nil, read_timeout: nil, write_timeout: nil)
+        super(
+          api_key: api_key,
+          base_url: base_url || DEFAULT_BASE_URL,
+          open_timeout: open_timeout,
+          read_timeout: read_timeout,
+          write_timeout: write_timeout
+        )
+      end
+
+      def stream(model:, messages:, system_prompt: nil, tools: [], max_tokens: nil, thinking_config: nil)
+        Enumerator.new do |yielder|
+          body = build_request_body(
+            model: model,
+            messages: messages,
+            system_prompt: system_prompt,
+            tools: tools,
+            max_tokens: max_tokens,
+            thinking_config: thinking_config
+          )
+
+          state = StreamState.new(model_id: model.id)
+
+          stream_request("/v1/responses", body) do |event_type, data|
+            state.ensure_started!(yielder)
+            state.handle_event!(yielder, event_type, data)
+          end
+        end
+      end
+
+      def complete(model:, messages:, system_prompt: nil, tools: [], max_tokens: nil)
+        final = nil
+
+        stream(model: model, messages: messages, system_prompt: system_prompt, tools: tools, max_tokens: max_tokens).each do |event|
+          case event
+          when StreamEvent::Done
+            final = event.message
+          when StreamEvent::Error
+            raise event.error
+          end
+        end
+
+        final
+      end
+
+      protected
+
+      def build_request_body(model:, messages:, system_prompt:, tools:, max_tokens:, thinking_config: nil)
+        body = {
+          model: model.id,
+          input: convert_messages(messages),
+          stream: true
+        }
+
+        body[:instructions] = system_prompt if system_prompt
+
+        resolved_max = max_tokens || (model.respond_to?(:max_tokens) ? model.max_tokens : nil)
+        body[:max_output_tokens] = resolved_max if resolved_max
+
+        body[:tools] = convert_tools(tools) if tools.any?
+
+        apply_reasoning_config!(body, thinking_config)
+
+        body
+      end
+
+      def apply_reasoning_config!(body, thinking_config)
+        level = thinking_config&.dig(:level)
+        return if level.nil? || level == ThinkingLevel::OFF
+
+        body[:reasoning] = { effort: openai_reasoning_effort(level) }
+      end
+
+      def openai_reasoning_effort(level)
+        case level
+        when ThinkingLevel::MINIMAL then "low"
+        when ThinkingLevel::LOW     then "low"
+        when ThinkingLevel::MEDIUM  then "medium"
+        when ThinkingLevel::HIGH    then "high"
+        else "medium"
+        end
+      end
+
+      def convert_messages(messages)
+        items = []
+
+        Array(messages).each do |msg|
+          case msg
+          when UserMessage
+            items << { role: "user", content: convert_user_content(msg.content) }
+          when AssistantMessage
+            items << { role: "assistant", content: convert_assistant_content(msg.content) }
+
+            msg.content
+              .select { |c| c.is_a?(Content::ToolCall) }
+              .each do |tc|
+                items << {
+                  type: "function_call",
+                  call_id: tc.id,
+                  name: tc.name,
+                  arguments: JSON.generate(tc.arguments)
+                }
+              end
+          when ToolResultMessage
+            items << {
+              type: "function_call_output",
+              call_id: msg.tool_call_id,
+              output: extract_text_content(msg.content)
+            }
+          else
+            items << { role: "user", content: [ { type: "input_text", text: msg.to_s } ] }
+          end
+        end
+
+        items
+      end
+
+      def convert_user_content(content)
+        Array(content).map do |block|
+          case block
+          when Content::Text
+            { type: "input_text", text: block.text }
+          when Content::Image
+            { type: "input_image", image_url: "data:#{block.mime_type};base64,#{block.data}" }
+          when Content::Document
+            convert_document(block)
+          else
+            raise UnsupportedContentError, "Unsupported content block: #{block.class}"
+          end
+        end
+      end
+
+      def convert_document(block)
+        case block.source
+        when Content::DocumentSource::Url
+          { type: "input_file", file_url: block.source.url }
+        when Content::DocumentSource::ProviderFile
+          { type: "input_file", file_id: block.source.file_id }
+        when Content::DocumentSource::Base64
+          { type: "input_file", file_data: block.source.data }
+        else
+          raise UnsupportedContentError, "Unsupported document source: #{block.source.class}"
+        end
+      end
+
+      def convert_assistant_content(content)
+        text = Array(content)
+          .select { |c| c.is_a?(Content::Text) }
+          .map(&:text)
+          .join
+
+        text.empty? ? [] : [ { type: "output_text", text: text } ]
+      end
+
+      def extract_text_content(content)
+        Array(content)
+          .select { |c| c.is_a?(Content::Text) }
+          .map(&:text)
+          .join("\n")
+      end
+
+      def convert_tools(tools)
+        tools.filter_map do |tool|
+          if tool.respond_to?(:built_in?) && tool.built_in?
+            # Built-in tools have provider-specific config
+            # Returns nil for unsupported tools (e.g., web_fetch on OpenAI)
+            tool.provider_config(:openai)
+          else
+            # User-defined tools use standard function format
+            {
+              type: "function",
+              name: tool.name,
+              description: tool.description,
+              parameters: make_all_properties_required(tool.parameters_schema),
+              strict: true
+            }
+          end
+        end
+      end
+
+      # OpenAI requires all properties to be required in strict mode.
+      # For optional properties, we wrap them in anyOf: [original_type, null]
+      def make_all_properties_required(schema)
+        return schema unless schema.is_a?(Hash) && schema["type"] == "object"
+
+        properties = schema["properties"] || {}
+        required = schema["required"] || []
+
+        new_properties = properties.transform_values do |prop_schema|
+          transform_property_schema(prop_schema)
+        end
+
+        # Wrap optional properties in anyOf with null
+        new_properties = new_properties.map do |name, prop_schema|
+          if required.include?(name)
+            [ name, prop_schema ]
+          else
+            [ name, { "anyOf" => [ prop_schema, { "type" => "null" } ] } ]
+          end
+        end.to_h
+
+        {
+          "type" => "object",
+          "properties" => new_properties,
+          "required" => properties.keys,
+          "additionalProperties" => false
+        }
+      end
+
+      def transform_property_schema(prop_schema)
+        return prop_schema unless prop_schema.is_a?(Hash)
+
+        case prop_schema["type"]
+        when "object"
+          make_all_properties_required(prop_schema)
+        when "array"
+          items = prop_schema["items"]
+          if items&.dig("type") == "object"
+            prop_schema.merge("items" => make_all_properties_required(items))
+          else
+            prop_schema
+          end
+        else
+          prop_schema
+        end
+      end
+
+      def stream_request(path, body)
+        uri = build_uri(path)
+
+        post_json(
+          uri,
+          body,
+          headers: {
+            "Authorization" => "Bearer #{api_key}",
+            "Accept" => "text/event-stream"
+          }
+        ) do |response|
+          status = response.code.to_i
+          unless status == 200
+            raise ApiError.for_status(status, "OpenAI HTTP #{status}", body: response.body)
+          end
+
+          parse_sse_response(response) do |event_type, data|
+            yield(event_type, data)
+          end
+        end
+      end
+
+      class StreamState
+        def initialize(model_id:)
+          @model_id = model_id
+          @started = false
+
+          @content_blocks = []
+
+          @text_block_index_by_ref = {} # [output_index, content_index] => content_block_index
+          @tool_call_block_index_by_id = {} # call_id => content_block_index
+          @tool_call_args_json = Hash.new { |h, k| h[k] = "" }
+        end
+
+        def ensure_started!(yielder)
+          return if @started
+
+          @started = true
+          yielder << StreamEvent::Start.new(
+            AssistantMessage.new(content: [], model: @model_id, usage: Usage.new, stop_reason: nil)
+          )
+        end
+
+        def handle_event!(yielder, event_type, data)
+          case event_type
+          when "response.output_text.delta"
+            handle_text_delta!(yielder, data)
+          when "response.output_text.done"
+            handle_text_done!(yielder, data)
+          when "response.output_item.added"
+            handle_output_item_added!(yielder, data)
+          when "response.function_call_arguments.delta"
+            handle_function_call_arguments_delta!(yielder, data)
+          when "response.function_call_arguments.done"
+            handle_function_call_arguments_done!(yielder, data)
+          when "response.completed"
+            handle_completed!(yielder, data)
+          when "response.failed"
+            raise ApiError, (data.dig("error", "message") || "OpenAI response failed")
+          when "error"
+            raise ApiError, (data.dig("error", "message") || "OpenAI stream error")
+          end
+        end
+
+        private
+
+        def handle_text_delta!(yielder, data)
+          output_index = data["output_index"]
+          content_index = data["content_index"]
+          delta = data["delta"] || ""
+
+          ref = [ output_index, content_index ]
+          block_index = @text_block_index_by_ref[ref]
+          if block_index.nil?
+            block_index = @content_blocks.length
+            @content_blocks << Content::Text.new("")
+            @text_block_index_by_ref[ref] = block_index
+            yielder << StreamEvent::TextStart.new(index: block_index)
+          end
+
+          existing = @content_blocks[block_index]
+          @content_blocks[block_index] = Content::Text.new(existing.text + delta)
+          yielder << StreamEvent::TextDelta.new(index: block_index, text: delta)
+        end
+
+        def handle_text_done!(yielder, data)
+          output_index = data["output_index"]
+          content_index = data["content_index"]
+          ref = [ output_index, content_index ]
+          block_index = @text_block_index_by_ref[ref]
+          yielder << StreamEvent::TextEnd.new(index: block_index) if block_index
+        end
+
+        def handle_output_item_added!(yielder, data)
+          item = data["item"] || {}
+          return unless [ "function_call", "tool_call" ].include?(item["type"])
+
+          item_id = item["id"]
+          call_id = item["call_id"] || item_id
+          name = item["name"] || ""
+          return if call_id.nil?
+
+          block_index = @content_blocks.length
+          @content_blocks << Content::ToolCall.new(id: call_id, name: name, arguments: {})
+          @tool_call_block_index_by_id[call_id] = block_index
+          @tool_call_block_index_by_id[item_id] = block_index if item_id
+          yielder << StreamEvent::ToolCallStart.new(index: block_index, id: call_id, name: name)
+        end
+
+        def handle_function_call_arguments_delta!(yielder, data)
+          call_id = data["item_id"] || data["call_id"] || data["id"]
+          delta = data["delta"] || ""
+          return if call_id.nil?
+
+          @tool_call_args_json[call_id] += delta
+          block_index = @tool_call_block_index_by_id[call_id]
+          return if block_index.nil?
+
+          yielder << StreamEvent::ToolCallDelta.new(index: block_index, arguments_json: delta)
+        end
+
+        def handle_function_call_arguments_done!(yielder, data)
+          call_id = data["item_id"] || data["call_id"] || data["id"]
+          return if call_id.nil?
+
+          block_index = @tool_call_block_index_by_id[call_id]
+          return if block_index.nil?
+
+          parsed_args = JSON.parse(@tool_call_args_json[call_id]) rescue {}
+          tc = @content_blocks[block_index]
+          @content_blocks[block_index] = Content::ToolCall.new(id: tc.id, name: tc.name, arguments: parsed_args)
+          yielder << StreamEvent::ToolCallEnd.new(index: block_index)
+        end
+
+        def handle_completed!(yielder, data)
+          response = data["response"] || data
+          usage = parse_usage(response["usage"])
+
+          final_message = AssistantMessage.new(
+            content: @content_blocks.compact,
+            model: @model_id,
+            usage: usage,
+            stop_reason: map_stop_reason(response)
+          )
+
+          yielder << StreamEvent::Done.new(message: final_message, stop_reason: final_message.stop_reason)
+        end
+
+        def map_stop_reason(response)
+          status = response["status"]
+          case status
+          when "incomplete" then StopReason::LENGTH
+          when "failed" then StopReason::ERROR
+          else StopReason::STOP
+          end
+        end
+
+        def parse_usage(usage_data)
+          return Usage.new if usage_data.nil?
+
+          input_details = usage_data["input_tokens_details"] || {}
+          output_details = usage_data["output_tokens_details"] || {}
+
+          Usage.new(
+            input_tokens: usage_data["input_tokens"] || 0,
+            output_tokens: usage_data["output_tokens"] || 0,
+            cached_input_tokens: input_details["cached_tokens"] || 0,
+            input_audio_tokens: input_details["audio_tokens"] || 0,
+            input_image_tokens: input_details["image_tokens"] || 0,
+            output_audio_tokens: output_details["audio_tokens"] || 0,
+            reasoning_tokens: output_details["reasoning_tokens"] || 0,
+            raw: usage_data,
+            meta: { provider: :openai }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/dexter_llm/agent/agent.rb

@@ -0,0 +1,277 @@
+# frozen_string_literal: true
+
+module DexterLlm::Agent
+  # Autonomous LLM agent with multi-turn conversations and tool execution.
+  #
+  # The Agent maintains conversation state, executes tool calls, and emits
+  # events for monitoring. It uses an agent loop that continues until the
+  # model stops calling tools.
+  #
+  # @example Basic usage
+  #   model = DexterLlm::Models.find("claude-sonnet-4-20250514")
+  #   agent = Agent::Agent.new(model: model)
+  #   response = agent.prompt("Hello!")
+  #   puts response.text
+  #
+  # @example With tools
+  #   agent = Agent::Agent.new(
+  #     model: model,
+  #     tools: [WeatherTool.new, CalculatorTool.new],
+  #     system_prompt: "You are a helpful assistant."
+  #   )
+  #   agent.prompt("What's 25 * 4?")  # Will use calculator
+  #
+  # @example Streaming with events
+  #   agent.on_event do |event|
+  #     case event.type
+  #     when "stream_event"
+  #       print event.data["text"] if event.data["type"] == "text_delta"
+  #     when "tool_call_start"
+  #       puts "[Calling #{event.data['name']}]"
+  #     end
+  #   end
+  #   agent.prompt("What's the weather?")
+  #
+  class Agent
+    # @return [State] The current agent state (immutable)
+    attr_reader :state
+
+    # Create a new agent.
+    #
+    # @param model [DexterLlm::Model] The model to use for completions
+    # @param system_prompt [String, nil] System prompt to set model behavior
+    # @param tools [Array<DexterLlm::Tool>] Tools available to the agent
+    # @param messages [Array<Message>] Initial conversation history
+    # @param client [DexterLlm::Client, nil] Client instance (creates default if nil)
+    # @param max_iterations [Integer] Maximum agent loop iterations
+    # @param thinking_config [Hash, nil] Extended thinking configuration
+    #
+    # @example
+    #   agent = Agent::Agent.new(
+    #     model: DexterLlm::Models.find("claude-sonnet-4-20250514"),
+    #     system_prompt: "You are helpful.",
+    #     tools: [my_tool],
+    #     max_iterations: 50
+    #   )
+    #
+    def initialize(model:, system_prompt: nil, tools: [], messages: [], client: nil, max_iterations: State::DEFAULT_MAX_ITERATIONS, thinking_config: nil)
+      @client = client || DexterLlm::Client.new
+      @state = State.new(
+        model: model,
+        messages: messages,
+        system_prompt: system_prompt,
+        tools: tools,
+        max_iterations: max_iterations,
+        thinking_config: thinking_config
+      )
+      @event_handlers = []
+      @signal = nil
+      @running = false
+      @mutex = Mutex.new
+      @session_id = SecureRandom.uuid
+      @steering_queue = Queue.new
+      @follow_up_queue = Queue.new
+    end
+
+    # Send a prompt to the agent and get the final response.
+    #
+    # The agent will continue executing tool calls until the model
+    # stops requesting them. All events are emitted to registered handlers.
+    #
+    # @param text [String] The user message text
+    # @param attachments [Array<Content>] Optional attachments (documents, images)
+    #
+    # @return [DexterLlm::AssistantMessage] The final assistant response
+    #
+    # @raise [AgentBusyError] If another prompt is already running
+    # @raise [MaxIterationsError] If max_iterations is exceeded
+    # @raise [DexterLlm::CancelledError] If the operation is cancelled
+    # @raise [DexterLlm::ApiError] For API errors
+    #
+    # @example
+    #   response = agent.prompt("What is Ruby?")
+    #   puts response.text
+    #
+    # @example With attachments
+    #   doc = DexterLlm::Content::Document.new(source: ..., filename: "doc.pdf", ...)
+    #   response = agent.prompt("Summarize this", attachments: [doc])
+    #
+    def prompt(text, attachments: [])
+      @mutex.synchronize do
+        raise AgentBusyError.new if @running
+        @running = true
+        @signal = DexterLlm::CancellationSignal.new
+      end
+
+      begin
+        final_message = run_prompt(text, attachments:)
+
+        # Process follow-up queue
+        while (follow_up_text = dequeue_follow_up)
+          final_message = run_prompt(follow_up_text)
+        end
+
+        final_message
+      ensure
+        @mutex.synchronize do
+          @running = false
+          @signal = nil
+        end
+      end
+    end
+
+    # Register an event handler for agent events.
+    #
+    # The handler is called for all events during prompt execution,
+    # including streaming events, tool calls, and state changes.
+    #
+    # @yield [Event] Block called for each event
+    #
+    # @example
+    #   agent.on_event do |event|
+    #     case event.type
+    #     when "user_message"
+    #       puts "User: #{event.data['content']}"
+    #     when "stream_event"
+    #       print event.data["text"] if event.data["type"] == "text_delta"
+    #     when "tool_call_start"
+    #       puts "[Calling #{event.data['name']}]"
+    #     when "tool_call_end"
+    #       puts "[Result: #{event.data['result']}]"
+    #     end
+    #   end
+    #
+    def on_event(&handler)
+      @mutex.synchronize { @event_handlers << handler }
+    end
+
+    # Reset the agent's conversation history.
+    #
+    # Clears all messages while preserving the model, system prompt,
+    # tools, and settings.
+    #
+    # @raise [AgentBusyError] If the agent is currently running
+    #
+    def reset
+      @mutex.synchronize do
+        raise AgentBusyError.new if @running
+        @state = State.new(
+          model: @state.model,
+          system_prompt: @state.system_prompt,
+          tools: @state.tools,
+          max_iterations: @state.max_iterations
+        )
+      end
+    end
+
+    # Abort a running prompt operation.
+    #
+    # This cancels the current operation, causing prompt() to raise
+    # DexterLlm::CancelledError. Safe to call from another thread.
+    #
+    # @param reason [String] The cancellation reason
+    #
+    # @example
+    #   # In a signal handler or timeout thread
+    #   agent.abort("User cancelled")
+    #
+    def abort(reason = "User aborted")
+      signal = @mutex.synchronize { @signal }
+      signal&.cancel!(reason)
+    end
+
+    # Check if the agent is currently running a prompt.
+    #
+    # @return [Boolean] True if a prompt is in progress
+    #
+    def running?
+      @mutex.synchronize { @running }
+    end
+
+    # Inject a steering message that will be delivered after the current tool
+    # execution completes, skipping any remaining pending tools in this turn.
+    #
+    # @param text [String] The steering message text
+    # @raise [Agent::Error] If the agent is not running
+    def steer(text)
+      @mutex.synchronize do
+        raise Error, "Cannot steer: agent is not running" unless @running
+      end
+      @steering_queue << text
+    end
+
+    # Queue a follow-up message to be processed after the current run completes.
+    # The agent will automatically process this as a new prompt.
+    #
+    # @param text [String] The follow-up message text
+    def follow_up(text)
+      @follow_up_queue << text
+    end
+
+    # Clear all pending steering messages.
+    def clear_steering_queue
+      @steering_queue.clear
+    end
+
+    # Clear all pending follow-up messages.
+    def clear_follow_up_queue
+      @follow_up_queue.clear
+    end
+
+    # Get the conversation message history.
+    #
+    # @return [Array<Message>] All messages in the conversation
+    #
+    def messages
+      @state.messages
+    end
+
+    # Get the current model.
+    #
+    # @return [DexterLlm::Model] The model being used
+    #
+    def model
+      @state.model
+    end
+
+    # Get the agent's session ID.
+    #
+    # The session ID is constant for the lifetime of this agent instance.
+    #
+    # @return [String] UUID for this agent session
+    #
+    def session_id
+      @session_id
+    end
+
+    private
+
+    def run_prompt(text, attachments: [])
+      run_id = SecureRandom.uuid
+      loop = Loop.new(
+        state: @state,
+        client: @client,
+        session_id: @session_id,
+        run_id: run_id,
+        signal: @signal,
+        steering_queue: @steering_queue,
+        emit_event: ->(event) { notify_handlers(event) }
+      )
+
+      new_state, final_message = loop.run(text, attachments:)
+      @state = new_state
+      final_message
+    end
+
+    def dequeue_follow_up
+      @follow_up_queue.pop(true)
+    rescue ThreadError
+      nil
+    end
+
+    def notify_handlers(event)
+      handlers = @mutex.synchronize { @event_handlers.dup }
+      handlers.each { |handler| handler.call(event) }
+    end
+  end
+end

data/lib/dexter_llm/agent/agent_busy_error.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module DexterLlm::Agent
+  class AgentBusyError < Error
+    def initialize(msg = "Agent is already running")
+      super
+    end
+  end
+end