rubyn-code 0.7.0 → 0.9.0

data/lib/rubyn_code/index/codebase_index.rb

@@ -14,6 +14,9 @@ module RubynCode
       INDEX_DIR = '.rubyn-code'
       INDEX_FILE = 'codebase_index.json'
       CHARS_PER_TOKEN = 4
+      # Bump when the stored shape changes so stale indexes rebuild instead
+      # of silently serving degraded data. 2 = Prism spans + call edges.
+      FORMAT_VERSION = 2
 
       attr_reader :nodes, :edges, :index_path
 
@@ -33,6 +36,7 @@ module RubynCode
 
         ruby_files.each { |file| index_file(file) }
         extract_rails_edges
+        prune_call_edges!
         save!
         self
       end
@@ -42,6 +46,8 @@ module RubynCode
         return nil unless File.exist?(@index_path)
 
         data = JSON.parse(File.read(@index_path))
+        return nil unless data['format_version'] == FORMAT_VERSION
+
         @nodes = data['nodes'] || []
         # uniq drops duplicate edges accumulated by older versions, which
         # appended tests edges on every update! without dedup.
@@ -68,6 +74,7 @@ module RubynCode
         end
 
         extract_rails_edges
+        prune_call_edges!
         save!
         self
       end
@@ -81,6 +88,7 @@ module RubynCode
         remove_nodes_for(absolute)
         index_file(absolute) if File.exist?(absolute)
         extract_rails_edges
+        prune_call_edges!
         save!
         self
       end
@@ -237,14 +245,66 @@ module RubynCode
         content = File.read(file)
         @file_mtimes[relative] = File.mtime(file).to_i
 
-        extract_classes(content, relative)
-        extract_methods(content, relative)
+        extract_symbols(content, relative)
         extract_associations(content, relative)
         extract_rails_patterns(content, relative)
       rescue StandardError => e
         RubynCode::Debug.warn("Index: failed to parse #{file}: #{e.message}")
       end
 
+      # Prism gives real line spans (needed for verbatim source in code_graph)
+      # and call edges. Files that don't parse fall back to the regex pass,
+      # which produces the same node shapes minus end_line/owner/calls.
+      def extract_symbols(content, file)
+        extracted = PrismExtractor.extract(content)
+        unless extracted
+          extract_classes(content, file)
+          extract_methods(content, file)
+          return
+        end
+
+        add_class_nodes(extracted.classes, file)
+        add_method_nodes(extracted.defs, file)
+        add_call_edges(extracted.calls, file)
+      end
+
+      def add_class_nodes(classes, file)
+        classes.each do |c|
+          @nodes << {
+            'type' => classify_node(file, c[:kind]), 'name' => c[:name],
+            'file' => file, 'line' => c[:line], 'end_line' => c[:end_line]
+          }
+        end
+      end
+
+      def add_method_nodes(methods, file)
+        methods.each do |m|
+          @nodes << {
+            'type' => 'method', 'name' => m[:name], 'file' => file,
+            'line' => m[:line], 'end_line' => m[:end_line],
+            'owner' => m[:owner], 'params' => m[:params], 'visibility' => 'public'
+          }
+        end
+      end
+
+      # `from` stays the file path so remove_nodes_for's from-based cleanup
+      # applies to call edges too; the calling method rides in from_method.
+      def add_call_edges(calls, file)
+        calls.each do |c|
+          @edges << {
+            'from' => file, 'from_method' => c[:from], 'to' => c[:to],
+            'relationship' => 'calls', 'line' => c[:line]
+          }
+        end
+      end
+
+      # Drop call edges whose target isn't defined in the project — filters
+      # out stdlib/gem calls (puts, map, ...) that would swamp the graph.
+      def prune_call_edges!
+        defined_methods = @nodes.filter_map { |n| n['name'] if n['type'] == 'method' }.to_set
+        @edges.reject! { |e| e['relationship'] == 'calls' && !defined_methods.include?(e['to']) }
+      end
+
       def extract_classes(content, file)
         content.scan(/^\s*(class|module)\s+(\S+)/).each do |type, name|
           node_type = classify_node(file, type)
@@ -342,7 +402,8 @@ module RubynCode
 
       def save!
         FileUtils.mkdir_p(File.dirname(@index_path))
-        data = { 'nodes' => @nodes, 'edges' => @edges, 'file_mtimes' => @file_mtimes }
+        data = { 'format_version' => FORMAT_VERSION, 'nodes' => @nodes, 'edges' => @edges,
+                 'file_mtimes' => @file_mtimes }
         File.write(@index_path, JSON.generate(data))
       end
     end

data/lib/rubyn_code/index/prism_extractor.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module RubynCode
+  module Index
+    # Prism-based symbol and call extractor for a single Ruby file.
+    # Returns classes/modules and methods with real line spans, plus
+    # method-to-method call sites the regex pass can't see. Used by
+    # CodebaseIndex, with the regex extractors as a parse-error fallback.
+    class PrismExtractor < Prism::Visitor
+      Result = Struct.new(:classes, :defs, :calls)
+
+      # @return [Result, nil] nil when the file doesn't parse
+      def self.extract(content)
+        parsed = Prism.parse(content)
+        return nil unless parsed.success?
+
+        visitor = new
+        visitor.visit(parsed.value)
+        Result.new(visitor.classes, visitor.defs, visitor.calls)
+      rescue StandardError
+        nil
+      end
+
+      attr_reader :classes, :defs, :calls
+
+      def initialize
+        super
+        @namespace = []
+        @current_def = nil
+        @classes = [] # { name:, kind:, line:, end_line: }
+        @defs    = [] # { name:, owner:, line:, end_line:, params: }
+        @calls   = [] # { from:, to:, line: }
+      end
+
+      def visit_class_node(node)
+        record_namespace(node, 'class') { super }
+      end
+
+      def visit_module_node(node)
+        record_namespace(node, 'module') { super }
+      end
+
+      def visit_def_node(node)
+        @defs << {
+          name: node.name.to_s,
+          owner: @namespace.join('::'),
+          line: node.location.start_line,
+          end_line: node.location.end_line,
+          params: node.parameters ? "(#{node.parameters.slice})" : nil
+        }
+        previous = @current_def
+        @current_def = node.name.to_s
+        super
+        @current_def = previous
+      end
+
+      # ponytail: resolution is by method name, not receiver type — a call to
+      # `user.save` links to any `save` defined in the project. Real receiver
+      # inference needs type analysis; name matching covers the common case.
+      def visit_call_node(node)
+        @calls << { from: @current_def, to: node.name.to_s, line: node.location.start_line } if @current_def
+        super
+      end
+
+      private
+
+      # The block continues the walk into child nodes (the caller's `super`).
+      def record_namespace(node, kind)
+        name = node.constant_path.slice
+        @classes << {
+          name: name, kind: kind,
+          line: node.location.start_line, end_line: node.location.end_line
+        }
+        @namespace.push(name)
+        yield
+        @namespace.pop
+      end
+    end
+  end
+end

data/lib/rubyn_code/learning/injector.rb

@@ -112,8 +112,7 @@ module RubynCode
           tag_set = tags.to_set(&:downcase)
 
           instincts.select do |inst|
-            inst_tags = inst.context_tags.map(&:downcase)
-            inst_tags.any? { |t| tag_set.include?(t) }
+            inst.context_tags.any? { |t| tag_set.include?(t.downcase) }
           end
         end
 

data/lib/rubyn_code/llm/adapters/anthropic.rb

@@ -11,20 +11,39 @@ module RubynCode
       class Anthropic < Base
         include JsonParsing
         include PromptCaching
-        include TokenCaching
 
         API_URL = 'https://api.anthropic.com/v1/messages'
         ANTHROPIC_VERSION = '2023-06-01'
         MAX_RETRIES = 3
         RETRY_DELAYS = [2, 5, 10].freeze
 
+        # Fable/Mythos/Opus 5 models opt into a server-side Opus 4.8 fallback
+        # by default: a declined request (safety-classifier refusal) is
+        # transparently re-served by the fallback model in the same call.
+        # No config toggle — hardcoded for these model families only.
+        FALLBACK_ELIGIBLE_MODELS = /\Aclaude-(fable|mythos|opus-5)/
+        FALLBACK_BETA = 'server-side-fallback-2026-06-01'
+
+        TASK_BUDGET_BETA = 'task-budgets-2026-03-13'
+        TASK_BUDGET_MIN_TOKENS = 20_000 # API minimum; below this, task_budget is omitted entirely
+        TASK_BUDGET_MODELS = /\Aclaude-(fable|mythos|sonnet-5|opus-5|opus-4-[78])/
+
         AVAILABLE_MODELS = %w[
           claude-fable-5
+          claude-opus-5
           claude-opus-4-8
-          claude-sonnet-4-20250514
-          claude-haiku-4-20250506
+          claude-opus-4-7
+          claude-opus-4-6
+          claude-sonnet-5
+          claude-sonnet-4-6
+          claude-haiku-4-5
         ].freeze
 
+        # Models on the adaptive-thinking API surface (Claude 4.6+).
+        # budget_tokens is removed there and returns a 400; older models
+        # (Haiku 4.5, Sonnet/Opus 4.5 and earlier) still take enabled + budget.
+        ADAPTIVE_THINKING_MODELS = /\Aclaude-(fable|mythos|opus-5|opus-4-[678]|sonnet-5|sonnet-4-6)/
+
         def provider_name
           'anthropic'
         end
@@ -33,14 +52,16 @@ module RubynCode
           AVAILABLE_MODELS
         end
 
-        def chat(messages:, model:, max_tokens:, tools: nil, system: nil, on_text: nil, task_budget: nil) # rubocop:disable Metrics/ParameterLists -- mirrors LLM adapter interface
+        def chat(messages:, model:, max_tokens:, tools: nil, system: nil, on_text: nil, # rubocop:disable Metrics/ParameterLists -- mirrors LLM adapter interface
+                 task_budget: nil, thinking: nil, effort: nil)
           ensure_valid_token!
           use_streaming = on_text && oauth_token?
 
           body = build_request_body(
             messages: messages, tools: tools, system: system,
             model: model, max_tokens: max_tokens,
-            stream: use_streaming, task_budget: task_budget
+            stream: use_streaming, task_budget: task_budget,
+            thinking: thinking, effort: effort
           )
 
           return stream_request(body, on_text) if use_streaming
@@ -138,7 +159,7 @@ module RubynCode
 
         def post_request(body)
           connection.post(api_url) do |req|
-            apply_headers(req)
+            apply_headers(req, body)
             req.body = JSON.generate(body)
           end
         end
@@ -163,7 +184,7 @@ module RubynCode
           error_chunks = []
 
           response = streaming_connection.post(api_url) do |req|
-            apply_headers(req)
+            apply_headers(req, body)
             req.body = JSON.generate(body)
             req.options.on_data = on_data_proc(streamer, error_chunks)
           end
@@ -189,7 +210,6 @@ module RubynCode
 
           error_msg = extract_error_message(error_chunks.join)
 
-          invalidate_token_cache! if response.status == 401
           raise Client::AuthExpiredError, "Authentication expired: #{error_msg}" if response.status == 401
           raise Client::PromptTooLongError, "Prompt too long: #{error_msg}" if response.status == 413
 
@@ -223,23 +243,35 @@ module RubynCode
 
         # -- Headers ------------------------------------------------------
 
-        def apply_headers(req)
+        def apply_headers(req, body = {})
           req.headers['Content-Type'] = 'application/json'
           req.headers['anthropic-version'] = ANTHROPIC_VERSION
-          oauth_token? ? apply_oauth_headers(req) : apply_api_key_headers(req)
+          oauth_token? ? apply_oauth_headers(req, body) : apply_api_key_headers(req, body)
         end
 
-        def apply_oauth_headers(req)
+        def apply_oauth_headers(req, body)
           req.headers['Authorization'] = "Bearer #{access_token}"
-          req.headers['anthropic-beta'] = 'oauth-2025-04-20'
+          # The subscription-auth beta must stay present, so feature betas append rather than replace.
+          betas = ['oauth-2025-04-20']
+          betas << TASK_BUDGET_BETA if task_budget_on_wire?(body)
+          betas << FALLBACK_BETA if body[:fallbacks]
+          req.headers['anthropic-beta'] = betas.join(',')
           req.headers['x-app'] = 'cli'
           req.headers['User-Agent'] = 'claude-code/2.1.79'
           req.headers['X-Claude-Code-Session-Id'] = session_id
           req.headers['anthropic-dangerous-direct-browser-access'] = 'true'
         end
 
-        def apply_api_key_headers(req)
+        def apply_api_key_headers(req, body)
           req.headers['x-api-key'] = access_token
+          betas = []
+          betas << TASK_BUDGET_BETA if task_budget_on_wire?(body)
+          betas << FALLBACK_BETA if body[:fallbacks]
+          req.headers['anthropic-beta'] = betas.join(',') unless betas.empty?
+        end
+
+        def task_budget_on_wire?(body)
+          !!body&.dig(:output_config, :task_budget)
         end
 
         def session_id
@@ -248,15 +280,70 @@ module RubynCode
 
         # -- Request body -------------------------------------------------
 
-        def build_request_body(messages:, tools:, system:, model:, max_tokens:, stream:, **_opts) # rubocop:disable Metrics/ParameterLists -- API request builder mirrors Claude API params
-          body = { model: model, max_tokens: max_tokens }
+        def build_request_body(messages:, tools:, system:, model:, max_tokens:, stream:, # rubocop:disable Metrics/ParameterLists -- API request builder mirrors Claude API params
+                               thinking: nil, effort: nil, task_budget: nil, **_opts)
+          body = { model: model, max_tokens: ensure_max_tokens_for_thinking(max_tokens, thinking) }
+          apply_thinking(body, thinking)
+          apply_effort(body, effort)
+          apply_task_budget(body, task_budget, model)
           apply_system_blocks(body, system)
           apply_tool_cache(body, tools)
+          apply_fallbacks(body, model)
           body[:messages] = add_message_cache_breakpoint(messages)
           body[:stream] = true if stream
           body
         end
 
+        def apply_fallbacks(body, model)
+          return unless model.to_s.match?(FALLBACK_ELIGIBLE_MODELS)
+
+          body[:fallbacks] = [{ model: 'claude-opus-4-8' }]
+        end
+
+        # Advisory pacing signal only — Claude sees a running countdown and paces
+        # itself, but max_tokens remains the enforced hard cap per response.
+        def apply_task_budget(body, task_budget, model)
+          return unless task_budget.is_a?(Hash)
+          return unless model.to_s.match?(TASK_BUDGET_MODELS)
+
+          # `remaining` is what's left for the task, matching what the model should pace against.
+          total = task_budget[:remaining].to_i
+          return if total < TASK_BUDGET_MIN_TOKENS
+
+          (body[:output_config] ||= {})[:task_budget] = { type: 'tokens', total: total }
+        end
+
+        def apply_thinking(body, thinking)
+          return unless thinking.is_a?(Hash) && thinking[:budget_tokens].to_i.positive?
+
+          body[:thinking] =
+            if body[:model].to_s.match?(ADAPTIVE_THINKING_MODELS)
+              { type: 'adaptive' }
+            else
+              { type: 'enabled', budget_tokens: thinking[:budget_tokens].to_i }
+            end
+        end
+
+        # Merges into `output_config` (rather than assigning a whole hash) so
+        # this composes with other output_config keys, e.g. task_budget.
+        def apply_effort(body, effort)
+          return unless effort
+
+          (body[:output_config] ||= {})[:effort] = effort
+        end
+
+        # Anthropic requires max_tokens > budget_tokens. When thinking is on,
+        # raise max_tokens to budget + 1024 if not already large enough.
+        def ensure_max_tokens_for_thinking(max_tokens, thinking)
+          return max_tokens unless thinking.is_a?(Hash)
+
+          budget = thinking[:budget_tokens].to_i
+          return max_tokens if budget.zero?
+          return max_tokens if max_tokens >= budget + 1024
+
+          budget + 1024
+        end
+
         # -- Response parsing ---------------------------------------------
 
         def handle_api_response(response)
@@ -274,7 +361,6 @@ module RubynCode
           error_type = body&.dig('error', 'type') || 'api_error'
 
           log_api_error(response)
-          invalidate_token_cache! if response.status == 401
           raise Client::AuthExpiredError, "Authentication expired: #{error_msg}" if response.status == 401
           raise Client::PromptTooLongError, "Prompt too long: #{error_msg}" if response.status == 413
 
@@ -293,13 +379,17 @@ module RubynCode
         def build_api_response(body)
           content = parse_content_blocks(body['content'])
           usage = parse_usage(body['usage'])
-          Response.new(id: body['id'], content: content, stop_reason: body['stop_reason'], usage: usage)
+          Response.new(
+            id: body['id'], content: content, stop_reason: body['stop_reason'],
+            stop_details: body['stop_details'], usage: usage
+          )
         end
 
         def parse_content_blocks(blocks)
           (blocks || []).filter_map do |block|
             case block['type']
             when 'text' then TextBlock.new(text: block['text'])
+            when 'thinking' then ThinkingBlock.new(text: block['thinking'] || block['text'])
             when 'tool_use'
               ToolUseBlock.new(id: block['id'], name: block['name'], input: block['input'])
             end

data/lib/rubyn_code/llm/adapters/anthropic_streaming.rb

@@ -35,8 +35,10 @@ module RubynCode
           @content_blocks = []
           @current_block_index = nil
           @current_text = +''
+          @current_thinking_text = +''
           @current_tool_input_json = +''
           @stop_reason = nil
+          @stop_details = nil
           @usage = nil
         end
 
@@ -51,6 +53,7 @@ module RubynCode
             id: @response_id,
             content: @content_blocks.compact,
             stop_reason: @stop_reason,
+            stop_details: @stop_details,
             usage: @usage
           )
         end
@@ -107,6 +110,8 @@ module RubynCode
           case block['type']
           when 'text'
             @current_text = +(block['text'] || '')
+          when 'thinking'
+            @current_thinking_text = +(block['thinking'] || '')
           when 'tool_use'
             @current_tool_id = block['id']
             @current_tool_name = block['name']
@@ -124,6 +129,10 @@ module RubynCode
             text = delta['text'] || ''
             @current_text << text
             emit(:text_delta, { index: data['index'], text: text })
+          when 'thinking_delta'
+            text = delta['thinking'] || ''
+            @current_thinking_text << text
+            emit(:thinking_delta, { index: data['index'], text: text })
           when 'input_json_delta'
             json_chunk = delta['partial_json'] || ''
             @current_tool_input_json << json_chunk
@@ -141,6 +150,7 @@ module RubynCode
         def handle_message_delta(data)
           delta = data['delta'] || {}
           @stop_reason = delta['stop_reason'] if delta['stop_reason']
+          @stop_details = delta['stop_details'] if delta['stop_details']
           update_output_tokens(data['usage']) if data['usage']
           emit(:message_delta, data)
         end
@@ -167,6 +177,9 @@ module RubynCode
           elsif !@current_text.empty?
             @content_blocks[index] = TextBlock.new(text: @current_text.dup)
             @current_text = +''
+          elsif !@current_thinking_text.empty?
+            @content_blocks[index] = ThinkingBlock.new(text: @current_thinking_text.dup)
+            @current_thinking_text = +''
           end
         end
 

data/lib/rubyn_code/llm/adapters/base.rb

@@ -15,8 +15,9 @@ module RubynCode
         # @param system [String, nil] System prompt text
         # @param on_text [Proc, nil] Streaming text callback
         # @param task_budget [Hash, nil] Optional task budget context
+        # @param thinking [Hash, nil] Optional {budget_tokens: Integer} for extended reasoning
         # @return [LLM::Response]
-        def chat(messages:, model:, max_tokens:, tools: nil, system: nil, on_text: nil, task_budget: nil) # rubocop:disable Metrics/ParameterLists -- LLM adapter interface requires these params
+        def chat(messages:, model:, max_tokens:, tools: nil, system: nil, on_text: nil, task_budget: nil, thinking: nil) # rubocop:disable Metrics/ParameterLists -- LLM adapter interface requires these params
           raise NotImplementedError, "#{self.class}#chat must be implemented"
         end
 

data/lib/rubyn_code/llm/adapters/openai.rb

@@ -30,7 +30,7 @@ module RubynCode
           AVAILABLE_MODELS
         end
 
-        def chat(messages:, model:, max_tokens:, tools: nil, system: nil, on_text: nil, task_budget: nil) # rubocop:disable Metrics/ParameterLists, Lint/UnusedMethodArgument -- LLM adapter interface requires these params
+        def chat(messages:, model:, max_tokens:, tools: nil, system: nil, on_text: nil, task_budget: nil, thinking: nil) # rubocop:disable Metrics/ParameterLists, Lint/UnusedMethodArgument -- LLM adapter interface requires these params
           body = build_request_body(
             messages: messages, model: model, max_tokens: max_tokens,
             tools: tools, system: system

data/lib/rubyn_code/llm/adapters/openai_message_translator.rb

@@ -27,6 +27,10 @@ module RubynCode
           return translate_tool_results(content) if tool_results?(content)
           return translate_assistant_tool_use(content) if role == 'assistant' && tool_use_blocks?(content)
 
+          if content.is_a?(Array) && content.any? { |b| block_type(b) == 'image' }
+            return { role: role, content: translate_user_content_with_images(content) }
+          end
+
           { role: role, content: stringify_content(content) }
         end
 
@@ -34,6 +38,23 @@ module RubynCode
           content.is_a?(Array) && content.any? { |b| block_type(b) == 'tool_result' }
         end
 
+        # Emit OpenAI multipart content: text blocks stay text, image blocks
+        # become {type: 'image_url', image_url: {url: 'data:<media>;base64,...'}}.
+        def translate_user_content_with_images(content)
+          content.map do |block|
+            case block_type(block)
+            when 'image'
+              source = block[:source] || block['source']
+              media = source[:media_type] || source['media_type']
+              data = source[:data] || source['data']
+              { type: 'image_url', image_url: { url: "data:#{media};base64,#{data}" } }
+            else
+              text = block[:text] || block['text'] || ''
+              { type: 'text', text: text }
+            end
+          end
+        end
+
         def tool_use_blocks?(content)
           content.is_a?(Array) && content.any? { |b| block_type(b) == 'tool_use' }
         end

data/lib/rubyn_code/llm/client.rb

@@ -15,20 +15,22 @@ module RubynCode
       class PromptTooLongError < RequestError; end
 
       attr_reader :adapter
-      attr_accessor :model
+      attr_accessor :model, :thinking_budget_tokens, :effort
 
       def initialize(model: nil, provider: nil, adapter: nil)
         settings = Config::Settings.new
         @model = model || settings.model
         @provider = provider || settings.provider
         @adapter = adapter || resolve_adapter(@provider)
+        @thinking_budget_tokens = 0
       end
 
       def chat(messages:, tools: nil, system: nil, model: nil, **opts)
         effective_model = model || @model
         max_tokens = opts[:max_tokens] || Config::Defaults::CAPPED_MAX_OUTPUT_TOKENS
+        effective_thinking = opts[:thinking] || current_thinking_hash
 
-        @adapter.chat(
+        kwargs = {
           messages: messages,
           tools: tools,
           system: system,
@@ -36,7 +38,18 @@ module RubynCode
           max_tokens: max_tokens,
           on_text: opts[:on_text],
           task_budget: opts[:task_budget]
-        )
+        }
+        kwargs[:thinking] = effective_thinking if effective_thinking
+        kwargs[:effort] = @effort if @effort
+
+        @adapter.chat(**kwargs)
+      end
+
+      def current_thinking_hash
+        budget = @thinking_budget_tokens.to_i
+        return nil unless budget.positive?
+
+        { budget_tokens: budget }
       end
 
       def stream(messages:, tools: nil, system: nil, model: nil,

data/lib/rubyn_code/llm/image_reader.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module RubynCode
+  # Pulls in ImageBlock so the constant is loaded before ImageReader resolves it.
+  module LLM
+    autoload :ImageBlock, 'rubyn_code/llm/message_builder'
+  end
+
+  module LLM
+    # Reads image files from disk and returns image content blocks suitable for
+    # sending to the LLM as part of a user turn. Supports common raster formats
+    # accepted by both Anthropic and OpenAI vision APIs.
+    module ImageReader
+      MAX_BYTES = 8 * 1024 * 1024
+
+      MEDIA_TYPES = {
+        '.png' => 'image/png',
+        '.jpg' => 'image/jpeg',
+        '.jpeg' => 'image/jpeg',
+        '.gif' => 'image/gif',
+        '.webp' => 'image/webp'
+      }.freeze
+
+      EXTENSIONS_REGEX = /\.(png|jpe?g|gif|webp)\z/i
+
+      module_function
+
+      # Build a base64 data URI of the form:
+      #   "data:image/png;base64,iVBORw0KG..."
+      # Returns nil for non-image paths or unreadable/oversized files.
+      def data_uri(path)
+        block = for_path(path)
+        return nil unless block
+
+        "data:#{block.media_type};base64,#{block.data}"
+      end
+
+      # @return [LLM::ImageBlock, nil] nil for non-image / unreadable paths
+      def for_path(path)
+        ext = File.extname(path)
+        media = MEDIA_TYPES[ext.downcase] || MEDIA_TYPES[".#{ext.sub(/^\./, '').downcase}"]
+        return nil unless media
+        return nil unless File.file?(path)
+
+        bytes = File.binread(path)
+        return nil if bytes.bytesize > MAX_BYTES
+
+        ImageBlock.new(media_type: media, data: Base64.strict_encode64(bytes))
+      rescue Errno::ENOENT, Errno::EACCES, ArgumentError
+        nil
+      end
+
+      def image_extension?(path)
+        path.to_s.match?(EXTENSIONS_REGEX)
+      end
+    end
+  end
+end