dexter_llm 0.1.2

data/lib/dexter_llm/token_estimator.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  module TokenEstimator
+    module_function
+
+    # Heuristic fallback (provider-independent):
+    # - English-ish text averages ~4 bytes/token in many BPE tokenizers.
+    def estimate_text_tokens(text)
+      str = text.to_s
+      return 0 if str.empty?
+
+      (str.bytesize / 4.0).ceil
+    end
+
+    def estimate_tokens(messages)
+      Array(messages).sum { |m| estimate_message_tokens(m) }
+    end
+
+    def estimate_message_tokens(message)
+      case message
+      when String
+        estimate_text_tokens(message)
+      when Hash
+        estimate_content_tokens(message["content"] || message[:content])
+      else
+        if message.respond_to?(:content)
+          estimate_content_tokens(message.content)
+        else
+          estimate_text_tokens(message.to_s)
+        end
+      end
+    end
+
+    def estimate_content_tokens(content)
+      case content
+      when nil
+        0
+      when String
+        estimate_text_tokens(content)
+      when Array
+        content.sum do |part|
+          if part.is_a?(String)
+            estimate_text_tokens(part)
+          elsif part.respond_to?(:text)
+            estimate_text_tokens(part.text)
+          elsif part.respond_to?(:thinking)
+            estimate_text_tokens(part.thinking)
+          else
+            estimate_text_tokens(part.to_s)
+          end
+        end
+      else
+        estimate_text_tokens(content.to_s)
+      end
+    end
+  end
+end

data/lib/dexter_llm/tool.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  # Error raised when tool execution fails.
+  # @see Tool#execute
+  class ToolExecutionError < DexterLlm::Error; end
+
+  # Base class for defining tools that can be called by the LLM.
+  #
+  # Tools allow the LLM to perform actions and retrieve information.
+  # Define a tool by subclassing and providing a name, description,
+  # parameter schema, and execute method.
+  #
+  # @example Basic tool
+  #   class WeatherTool < DexterLlm::Tool
+  #     name "get_weather"
+  #     description "Get current weather for a location"
+  #
+  #     params do
+  #       string :location, required: true, description: "City name"
+  #       string :units, enum: %w[metric imperial]
+  #     end
+  #
+  #     def execute(location:, units: "metric")
+  #       # Implementation here
+  #       "Temperature: 72F"
+  #     end
+  #   end
+  #
+  # @example Using with an agent
+  #   weather = WeatherTool.new
+  #   agent = Agent::Agent.new(model: model, tools: [weather])
+  #   agent.prompt("What's the weather in Tokyo?")
+  #
+  # @see Schema::Builder for parameter schema DSL
+  #
+  class Tool
+    class << self
+      # Set or get the tool name.
+      #
+      # If no name is set, it's derived from the class name by converting
+      # CamelCase to snake_case and removing "Tool" suffix.
+      #
+      # @param value [String, nil] The tool name to set
+      # @return [String] The tool name
+      #
+      # @example
+      #   class MyCustomTool < DexterLlm::Tool
+      #     name "custom_tool"  # Set explicitly
+      #   end
+      #
+      #   class AnotherTool < DexterLlm::Tool
+      #     # Name is automatically "another"
+      #   end
+      #
+      def name(value = nil)
+        if value
+          @tool_name = value.to_s
+        else
+          @tool_name || self.to_s.split("::").last.gsub(/Tool$/, "").gsub(/([a-z])([A-Z])/, '\1_\2').downcase
+        end
+      end
+
+      # Set or get the tool description.
+      #
+      # The description is sent to the LLM to help it understand
+      # when and how to use the tool.
+      #
+      # @param value [String, nil] The description to set
+      # @return [String] The tool description
+      #
+      # @example
+      #   class WeatherTool < DexterLlm::Tool
+      #     description "Get current weather conditions for a location"
+      #   end
+      #
+      def description(value = nil)
+        if value
+          @description = value
+        else
+          @description || ""
+        end
+      end
+
+      # Define the tool's parameter schema.
+      #
+      # The block is evaluated using the {Schema::Builder} DSL
+      # and generates a JSON Schema for parameter validation.
+      #
+      # @yield Block defining parameters using Schema::Builder DSL
+      #
+      # @example
+      #   params do
+      #     string :query, required: true, description: "Search query"
+      #     integer :limit, minimum: 1, maximum: 100
+      #     boolean :include_metadata
+      #   end
+      #
+      # @see Schema::Builder
+      #
+      def params(&block)
+        @params_block = block if block_given?
+        @params_block
+      end
+
+      # @private
+      def inherited(subclass)
+        super
+        # Don't copy params block - each subclass should define its own
+      end
+    end
+
+    # @return [String] The tool name
+    def name
+      self.class.name
+    end
+
+    # @return [String] The tool description
+    def description
+      self.class.description
+    end
+
+    # Generate the JSON Schema for the tool's parameters.
+    #
+    # @return [Hash] JSON Schema object
+    def parameters_schema
+      block = self.class.params
+      return empty_schema unless block
+
+      # Evaluate block in tool's context so @instance_vars work,
+      # with builder methods available via singleton methods
+      builder = Schema::Builder.new
+      add_builder_methods(builder)
+
+      begin
+        instance_exec(&block)
+      ensure
+        remove_builder_methods
+      end
+
+      builder.to_json_schema
+    end
+
+    # Call the tool with the given arguments.
+    #
+    # This method validates and coerces the arguments according to
+    # the parameter schema, then calls {#execute}.
+    #
+    # @param arguments [Hash] The arguments to pass to the tool
+    # @return [Object] The result from execute
+    # @raise [ToolExecutionError] If validation fails or execution errors
+    #
+    # @example
+    #   tool = WeatherTool.new
+    #   result = tool.call({ location: "Paris", units: "metric" })
+    #
+    def call(arguments)
+      schema = parameters_schema
+      coerced = Schema::Coercer.new(schema).coerce(arguments)
+      Schema::Validator.new(schema).validate!(coerced)
+
+      execute(**coerced)
+    rescue Schema::ValidationError => e
+      raise ToolExecutionError, "Invalid arguments for #{name}: #{e.message}"
+    rescue StandardError => e
+      raise ToolExecutionError, "Error executing #{name}: #{e.message}"
+    end
+
+    # Execute the tool with validated arguments.
+    #
+    # Subclasses must override this method to implement the tool's logic.
+    # The return value is sent back to the LLM as the tool result.
+    #
+    # @abstract
+    # @param args [Hash] Validated and coerced arguments
+    # @return [String, Object] The tool result (converted to string if needed)
+    # @raise [ToolExecutionError] If execution fails
+    #
+    def execute(**_args)
+      raise NotImplementedError, "#{self.class}#execute must be implemented"
+    end
+
+    private
+
+    BUILDER_METHODS = %i[string number integer boolean null object array any_of].freeze
+
+    def add_builder_methods(builder)
+      @__schema_builder__ = builder
+
+      BUILDER_METHODS.each do |method|
+        define_singleton_method(method) do |*args, **kwargs, &blk|
+          @__schema_builder__.send(method, *args, **kwargs, &blk)
+        end
+      end
+    end
+
+    def remove_builder_methods
+      BUILDER_METHODS.each do |method|
+        singleton_class.remove_method(method) if respond_to?(method)
+      end
+      @__schema_builder__ = nil
+    end
+
+    def empty_schema
+      { "type" => "object", "properties" => {} }
+    end
+  end
+end

data/lib/dexter_llm/tool_result_message.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  class ToolResultMessage
+    include Message::Serializable
+
+    def initialize(tool_call_id:, tool_name:, content:, is_error: false, details: nil, timestamp: Time.now)
+      @tool_call_id = tool_call_id
+      @tool_name = tool_name
+      @content = normalize_content(content)
+      @is_error = is_error
+      @details = details
+      @timestamp = timestamp
+    end
+
+    attr_reader :tool_call_id, :tool_name, :content, :is_error, :details, :timestamp
+    def role = :tool_result
+
+    def to_h
+      h = {
+        "role" => "tool_result",
+        "tool_call_id" => tool_call_id,
+        "tool_name" => tool_name,
+        "is_error" => is_error,
+        "content" => content_to_h(content),
+        "timestamp" => timestamp.utc.iso8601(3)
+      }
+      h["details"] = details if details
+      h
+    end
+  end
+end

data/lib/dexter_llm/unsupported_content_error.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  class UnsupportedContentError < Error; end
+end

data/lib/dexter_llm/usage.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  class Usage
+    def initialize(
+      input_tokens: 0,
+      output_tokens: 0,
+      cached_input_tokens: 0,
+      cache_read_input_tokens: 0,
+      cache_write_input_tokens: 0,
+      input_audio_tokens: 0,
+      input_image_tokens: 0,
+      input_video_tokens: 0,
+      input_document_tokens: 0,
+      output_audio_tokens: 0,
+      reasoning_tokens: 0,
+      thoughts_tokens: 0,
+      tool_use_prompt_tokens: 0,
+      meta: {},
+      raw: nil
+    )
+      @input_tokens = input_tokens.to_i
+      @output_tokens = output_tokens.to_i
+
+      @cached_input_tokens = cached_input_tokens.to_i
+      @cache_read_input_tokens = cache_read_input_tokens.to_i
+      @cache_write_input_tokens = cache_write_input_tokens.to_i
+
+      @input_audio_tokens = input_audio_tokens.to_i
+      @input_image_tokens = input_image_tokens.to_i
+      @input_video_tokens = input_video_tokens.to_i
+      @input_document_tokens = input_document_tokens.to_i
+
+      @output_audio_tokens = output_audio_tokens.to_i
+
+      @reasoning_tokens = reasoning_tokens.to_i
+      @thoughts_tokens = thoughts_tokens.to_i
+      @tool_use_prompt_tokens = tool_use_prompt_tokens.to_i
+
+      @meta = meta
+      @raw = raw
+    end
+
+    attr_accessor :input_tokens, :output_tokens,
+      :cached_input_tokens, :cache_read_input_tokens, :cache_write_input_tokens,
+      :input_audio_tokens, :input_image_tokens, :input_video_tokens, :input_document_tokens,
+      :output_audio_tokens, :reasoning_tokens, :thoughts_tokens, :tool_use_prompt_tokens
+
+    attr_reader :meta, :raw
+
+    def prompt_tokens
+      input_tokens
+    end
+
+    def total_tokens
+      input_tokens + output_tokens
+    end
+
+    def billable_meters
+      cached_text = cached_input_tokens + cache_read_input_tokens
+      uncached_input = [ input_tokens - cached_text - cache_write_input_tokens, 0 ].max
+
+      input_text = [
+        uncached_input - input_audio_tokens - input_image_tokens - input_video_tokens - input_document_tokens,
+        0
+      ].max
+
+      output_text = [ output_tokens - output_audio_tokens, 0 ].max
+
+      {
+        input_text_tokens: input_text,
+        input_text_tokens_cached: cached_text,
+        input_text_tokens_cache_write: cache_write_input_tokens,
+        input_audio_tokens: input_audio_tokens,
+        input_image_tokens: input_image_tokens,
+        input_video_tokens: input_video_tokens,
+        input_document_tokens: input_document_tokens,
+        output_text_tokens: output_text,
+        output_audio_tokens: output_audio_tokens
+      }
+    end
+
+    def calculate_cost(model)
+      billable_meters.sum do |meter, units|
+        model.pricing.cost_for(meter, units, usage: self)
+      end
+    end
+
+    def to_h
+      {
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        cached_input_tokens: cached_input_tokens,
+        cache_read_input_tokens: cache_read_input_tokens,
+        cache_write_input_tokens: cache_write_input_tokens,
+        input_audio_tokens: input_audio_tokens,
+        input_image_tokens: input_image_tokens,
+        input_video_tokens: input_video_tokens,
+        input_document_tokens: input_document_tokens,
+        output_audio_tokens: output_audio_tokens,
+        reasoning_tokens: reasoning_tokens,
+        thoughts_tokens: thoughts_tokens,
+        tool_use_prompt_tokens: tool_use_prompt_tokens
+      }
+    end
+  end
+end

data/lib/dexter_llm/user_message.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module DexterLlm
+  class UserMessage
+    include Message::Serializable
+
+    def initialize(content, timestamp: Time.now)
+      @content = normalize_content(content)
+      @timestamp = timestamp
+    end
+
+    attr_reader :content, :timestamp
+    def role = :user
+
+    def to_h
+      {
+        "role" => "user",
+        "content" => content_to_h(content),
+        "timestamp" => timestamp.utc.iso8601(3)
+      }
+    end
+  end
+end

data/lib/dexter_llm/version.rb

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

data/lib/dexter_llm.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module DexterLlm
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+
+  module Agent
+  end
+
+  module Session
+  end
+end
+
+require_relative "dexter_llm/version"
+
+# Core LLM types
+%w[
+  dexter_llm/error
+  dexter_llm/api_error
+  dexter_llm/authentication_error
+  dexter_llm/invalid_request_error
+  dexter_llm/context_overflow_error
+  dexter_llm/rate_limit_error
+  dexter_llm/cancelled_error
+  dexter_llm/unsupported_content_error
+  dexter_llm/cancellation_signal
+  dexter_llm/instrumentation
+  dexter_llm/stop_reason
+  dexter_llm/thinking_level
+  dexter_llm/api
+  dexter_llm/provider
+  dexter_llm/message
+  dexter_llm/content
+  dexter_llm/user_message
+  dexter_llm/assistant_message
+  dexter_llm/tool_result_message
+  dexter_llm/summary_message
+  dexter_llm/token_estimator
+  dexter_llm/usage
+  dexter_llm/pricing
+  dexter_llm/model
+  dexter_llm/models
+  dexter_llm/configuration
+  dexter_llm/retry_policy
+  dexter_llm/stream_event
+  dexter_llm/streaming/sse_parser
+  dexter_llm/streaming/events
+  dexter_llm/schema
+  dexter_llm/schema/builder
+  dexter_llm/schema/coercer
+  dexter_llm/schema/validator
+  dexter_llm/tool
+  dexter_llm/built_in_tool
+  dexter_llm/built_in_tools/web_search
+  dexter_llm/built_in_tools/web_fetch
+  dexter_llm/documents/store
+  dexter_llm/documents/stored_document
+  dexter_llm/documents/ingestor
+  dexter_llm/documents/stores/file_system
+  dexter_llm/prompt/materializer
+  dexter_llm/message_transformer
+  dexter_llm/client
+  dexter_llm/adapters/base
+  dexter_llm/adapters/anthropic
+  dexter_llm/adapters/openai
+  dexter_llm/adapters/google
+].each { |path| require_relative path }
+
+# Agent
+%w[
+  dexter_llm/agent/error
+  dexter_llm/agent/agent_busy_error
+  dexter_llm/agent/max_iterations_error
+  dexter_llm/agent/event
+  dexter_llm/agent/state
+  dexter_llm/agent/loop
+  dexter_llm/agent/agent
+  dexter_llm/agent/console
+  dexter_llm/agent/session
+].each { |path| require_relative path }
+
+# Session persistence
+%w[
+  dexter_llm/session/error
+  dexter_llm/session/store
+  dexter_llm/session/entry
+  dexter_llm/session/loaded_session
+  dexter_llm/session/compaction_settings
+  dexter_llm/session/compaction
+  dexter_llm/session/manager
+  dexter_llm/session/stores/jsonl_file
+].each { |path| require_relative path }

metadata

@@ -0,0 +1,158 @@
+--- !ruby/object:Gem::Specification
+name: dexter_llm
+version: !ruby/object:Gem::Version
+  version: 0.1.2
+platform: ruby
+authors:
+- Dexter Team
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: marcel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pastel
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Ruby-native LLM agent framework with provider adapters (Anthropic, OpenAI,
+  Google), tool calling, streaming, and session persistence.
+email:
+- team@getdexter.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/dexter_llm.rb
+- lib/dexter_llm/adapters/anthropic.rb
+- lib/dexter_llm/adapters/base.rb
+- lib/dexter_llm/adapters/google.rb
+- lib/dexter_llm/adapters/openai.rb
+- lib/dexter_llm/agent/agent.rb
+- lib/dexter_llm/agent/agent_busy_error.rb
+- lib/dexter_llm/agent/console.rb
+- lib/dexter_llm/agent/error.rb
+- lib/dexter_llm/agent/event.rb
+- lib/dexter_llm/agent/loop.rb
+- lib/dexter_llm/agent/max_iterations_error.rb
+- lib/dexter_llm/agent/session.rb
+- lib/dexter_llm/agent/state.rb
+- lib/dexter_llm/api.rb
+- lib/dexter_llm/api_error.rb
+- lib/dexter_llm/assistant_message.rb
+- lib/dexter_llm/authentication_error.rb
+- lib/dexter_llm/built_in_tool.rb
+- lib/dexter_llm/built_in_tools/web_fetch.rb
+- lib/dexter_llm/built_in_tools/web_search.rb
+- lib/dexter_llm/cancellation_signal.rb
+- lib/dexter_llm/cancelled_error.rb
+- lib/dexter_llm/client.rb
+- lib/dexter_llm/configuration.rb
+- lib/dexter_llm/content.rb
+- lib/dexter_llm/context_overflow_error.rb
+- lib/dexter_llm/documents/ingestor.rb
+- lib/dexter_llm/documents/store.rb
+- lib/dexter_llm/documents/stored_document.rb
+- lib/dexter_llm/documents/stores/file_system.rb
+- lib/dexter_llm/error.rb
+- lib/dexter_llm/instrumentation.rb
+- lib/dexter_llm/invalid_request_error.rb
+- lib/dexter_llm/message.rb
+- lib/dexter_llm/message_transformer.rb
+- lib/dexter_llm/model.rb
+- lib/dexter_llm/models.rb
+- lib/dexter_llm/models/catalog.yml
+- lib/dexter_llm/pricing.rb
+- lib/dexter_llm/prompt/materializer.rb
+- lib/dexter_llm/provider.rb
+- lib/dexter_llm/rate_limit_error.rb
+- lib/dexter_llm/retry_policy.rb
+- lib/dexter_llm/schema.rb
+- lib/dexter_llm/schema/builder.rb
+- lib/dexter_llm/schema/coercer.rb
+- lib/dexter_llm/schema/validator.rb
+- lib/dexter_llm/session/compaction.rb
+- lib/dexter_llm/session/compaction_settings.rb
+- lib/dexter_llm/session/entry.rb
+- lib/dexter_llm/session/error.rb
+- lib/dexter_llm/session/loaded_session.rb
+- lib/dexter_llm/session/manager.rb
+- lib/dexter_llm/session/store.rb
+- lib/dexter_llm/session/stores/jsonl_file.rb
+- lib/dexter_llm/stop_reason.rb
+- lib/dexter_llm/stream_event.rb
+- lib/dexter_llm/streaming/events.rb
+- lib/dexter_llm/streaming/sse_parser.rb
+- lib/dexter_llm/summary_message.rb
+- lib/dexter_llm/thinking_level.rb
+- lib/dexter_llm/token_estimator.rb
+- lib/dexter_llm/tool.rb
+- lib/dexter_llm/tool_result_message.rb
+- lib/dexter_llm/unsupported_content_error.rb
+- lib/dexter_llm/usage.rb
+- lib/dexter_llm/user_message.rb
+- lib/dexter_llm/version.rb
+homepage: https://github.com/getdexter/llm
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/getdexter/llm
+  source_code_uri: https://github.com/getdexter/llm
+  changelog_uri: https://github.com/getdexter/llm/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Unified LLM agent core (providers, tools, sessions, compaction)
+test_files: []