llm_logs 0.1.6 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e59977f8fa67dd219ec626f20f5320c325b0eab9349c7b7b69ba75c200353513
-  data.tar.gz: cc78c8b7ed85a03e2b2b85ebee10107c51089dc1fe012de14e2fdd3de93cb126
+  metadata.gz: 5eb2c037f1c19d83e843722bd9ca664324311e7fb6b75de47a96569919cae05b
+  data.tar.gz: 0db8f27945ce97dd74f9e4fedb5c337b68af537a83ab17dfc3f6bcd9ad18d360
 SHA512:
-  metadata.gz: f97806146008910196d8072f6c7c051fc67362705c6a28ed6486afe465bc0d58865e0f590efee24b41be57ef2fc853eac942741b64b940d705212a096ac5577e
-  data.tar.gz: 166a50f08ab90b2568a2cd8bc6b0942ab1bcd75e97839e82d9ceb8f6b91e3a8e5aec7f23cc318af444b96f3b2eafea31f2c8ea10f4f1059678761bd356b34b27
+  metadata.gz: fa82e4b390f8528a1d89c386ffb92b3c51f7e2f496ecec4061d4357dac679eb880dec648f6ca2d8885c256b3f175c8821a96143e318ac4e875dfa39aea4fe578
+  data.tar.gz: 8f3c2ae33e33667c3b4d1afa60a3afbe3154e6f5f6c9982892e772d4c8d7c60f5b5fa7c437ab5c597f79f9eefe9a0ecafea1642f6280e0508143d91ee20d50b2

data/README.md

@@ -180,6 +180,72 @@ messages:
 
 Running the task creates missing prompts, updates metadata, and creates a new prompt version only when messages, model, or model parameters changed.
 
+## Batches
+
+Send requests through the [OpenAI Responses Batch API](https://platform.openai.com/docs/guides/batch) for roughly half the cost when latency doesn't matter. LlmLogs persists each request, groups pending requests into a provider batch, reconciles results, and records a trace per request — so batched work shows up in the dashboard alongside synchronous calls.
+
+Batch support uses the [`ruby_llm-responses_api`](https://rubygems.org/gems/ruby_llm-responses_api) provider. Add it to your app's Gemfile:
+
+```ruby
+gem "ruby_llm-responses_api"
+```
+
+### Enqueue a Request
+
+Requests are persisted immediately and grouped by `purpose` + `model` when submitted:
+
+```ruby
+LlmLogs::Batch.enqueue(
+  purpose: "chat_summary",
+  model: "gpt-4.1-mini",
+  instructions: "Summarize the conversation in two sentences.",
+  input: conversation_text,
+  schema: SummarySchema,          # optional RubyLLM::Schema for structured output
+  routing: { conversation_id: 42 }, # your keys, echoed into the trace metadata
+  temperature: 0.2                  # optional
+)
+```
+
+`routing` is arbitrary metadata you control. It rides along with the request and is copied onto the recorded trace, so you can trace a result back to your own records.
+
+### Handle Results
+
+Register one handler per `purpose`. The gem owns the batch lifecycle; your app owns what happens with each result:
+
+```ruby
+# config/initializers/llm_logs.rb
+LlmLogs.register_batch_handler("chat_summary", ChatSummaryHandler.new)
+
+class ChatSummaryHandler
+  # Called once a request succeeds. `message` is the RubyLLM::Message.
+  def call(request, message)
+    Conversation.find(request.routing["conversation_id"])
+      .update!(summary: message.content)
+  end
+
+  # Called when a request fails or its batch expires.
+  def on_failure(request, error)
+    Rails.logger.warn("[chat_summary] #{request.custom_id} failed: #{error}")
+  end
+end
+```
+
+A request is marked `succeeded` only after its handler completes; a handler that raises leaves the request `failed` with the error visible in the dashboard, so a result is never silently lost.
+
+### Submit and Reconcile
+
+Two background jobs drive the lifecycle — schedule them on your own cadence (e.g. via cron, `solid_queue` recurring tasks, or `sidekiq-cron`):
+
+```ruby
+# Group this purpose's pending requests into provider batches and submit them.
+LlmLogs::Batch::FlushJob.perform_later("chat_summary")
+
+# Reconcile every in-flight batch: fetch results, run handlers, recover stale claims.
+LlmLogs::Batch::PollJob.perform_later
+```
+
+`FlushJob` claims pending rows with `FOR UPDATE SKIP LOCKED`, so concurrent runs never double-submit. `PollJob` reconciles all unfinished batches and recovers requests stranded by an interrupted submission. Both are idempotent at the request level — already-resolved requests are skipped on re-run.
+
 ## Web UI
 
 Browse traces and manage prompts at `/llm_logs`.
@@ -188,6 +254,8 @@ Browse traces and manage prompts at `/llm_logs`.
 
 **Prompts** — CRUD with Mustache template editor, model configuration, and version history.
 
+**Batches** — list batches with status and request counts, drill into per-request results, tokens, routing metadata, and linked traces.
+
 ## Configuration
 
 ```ruby
@@ -197,6 +265,8 @@ LlmLogs.setup do |config|
   config.retention_days = 30                                 # for future cleanup job
   config.prompts_source_path = Rails.root.join("db/data/prompts")
   config.prompt_subfolders = %w[skills fragments templates]
+  config.batch_enabled = true                                # enable the batch API integration
+  config.batch_provider = :openai_responses                  # batch backend
 end
 ```
 

data/app/controllers/llm_logs/batches_controller.rb

@@ -0,0 +1,15 @@
+module LlmLogs
+  class BatchesController < ApplicationController
+    def index
+      @batches = Batch.recent
+      @batches = @batches.where(purpose: params[:purpose]) if params[:purpose].present?
+      @batches = @batches.where(status: params[:status]) if params[:status].present?
+      @batches = @batches.page(params[:page]).per(50)
+    end
+
+    def show
+      @batch = Batch.find(params[:id])
+      @requests = @batch.requests.order(:created_at).page(params[:page]).per(100)
+    end
+  end
+end

data/app/controllers/llm_logs/traces_controller.rb

@@ -13,6 +13,7 @@ module LlmLogs
     def show
       @trace = Trace.includes(prompt_version: :prompt).find(params[:id])
       @root_spans = @trace.root_spans
+      @models = @trace.spans.where(span_type: "llm").distinct.pluck(:model).compact
     end
 
   end

data/app/helpers/llm_logs/batches_helper.rb

@@ -0,0 +1,23 @@
+module LlmLogs
+  module BatchesHelper
+    ROUTING_VALUE_LENGTH = 80
+
+    def routing_display_value(value)
+      full_value = routing_full_value(value)
+      return full_value if full_value.length <= ROUTING_VALUE_LENGTH
+
+      "#{full_value.first(ROUTING_VALUE_LENGTH - 3)}..."
+    end
+
+    def routing_full_value(value)
+      case value
+      when Hash, Array
+        JSON.generate(value)
+      when nil
+        "null"
+      else
+        value.to_s
+      end
+    end
+  end
+end

data/app/jobs/llm_logs/batch/flush_job.rb

@@ -0,0 +1,12 @@
+module LlmLogs
+  class Batch
+    class FlushJob < ::ActiveJob::Base
+      queue_as :default
+
+      def perform(purpose)
+        models = LlmLogs::BatchRequest.pending.where(purpose: purpose).distinct.pluck(:model)
+        models.each { |model| LlmLogs::Batch.submit_pending(purpose: purpose, model: model) }
+      end
+    end
+  end
+end

data/app/jobs/llm_logs/batch/poll_job.rb

@@ -0,0 +1,35 @@
+module LlmLogs
+  class Batch
+    class PollJob < ::ActiveJob::Base
+      queue_as :default
+
+      # A placeholder claim (status "pending", no openai_batch_id) is only meant to exist
+      # for the sub-second window of Submitter#submit. Anything older died mid-submit
+      # (e.g. the worker was killed), so its requests are stranded. Recover them.
+      STALE_CLAIM_AFTER = 15.minutes
+
+      def perform
+        recover_stale_claims
+        LlmLogs::Batch.unreconciled.where.not(openai_batch_id: nil).find_each do |batch|
+          batch.reconcile!
+        rescue StandardError => e
+          Rails.logger.error("[llm_logs] batch #{batch.id} reconcile failed: #{e.class}: #{e.message}")
+        end
+      end
+
+      private
+
+      def recover_stale_claims
+        LlmLogs::Batch
+          .where(status: :pending, openai_batch_id: nil)
+          .where("created_at < ?", STALE_CLAIM_AFTER.ago)
+          .find_each do |batch|
+            batch.requests.update_all(batch_id: nil, status: :pending)
+            batch.destroy
+          rescue StandardError => e
+            Rails.logger.error("[llm_logs] batch #{batch.id} stale-claim recovery failed: #{e.class}: #{e.message}")
+          end
+      end
+    end
+  end
+end

data/app/models/llm_logs/batch/handler_registry.rb

@@ -0,0 +1,24 @@
+module LlmLogs
+  class Batch
+    # Maps a batch purpose (e.g. "chat_summary") to a handler object. Handlers respond
+    # to `call(request, message)` for successful results and `on_failure(request, error)`
+    # for failed/expired requests. The gem owns the lifecycle; the host app owns handlers.
+    module HandlerRegistry
+      @handlers = {}
+
+      module_function
+
+      def register(purpose, handler)
+        @handlers[purpose.to_s] = handler
+      end
+
+      def resolve(purpose)
+        @handlers[purpose.to_s]
+      end
+
+      def clear!
+        @handlers = {}
+      end
+    end
+  end
+end

data/app/models/llm_logs/batch/reconciler.rb

@@ -0,0 +1,96 @@
+module LlmLogs
+  class Batch
+    # Resumes a submitted batch by id, and once terminal, records a trace per request,
+    # routes each result to its registered handler, and updates statuses. Idempotent at
+    # the request level (succeeded/failed/fell_back requests are skipped on re-run).
+    class Reconciler
+      def initialize(batch)
+        @batch = batch
+      end
+
+      def call
+        rubyllm_batch = RubyLLM.batch(id: @batch.openai_batch_id, provider: LlmLogs.batch_provider)
+        status = rubyllm_batch.status
+
+        case status
+        when "completed"
+          reconcile_completed(rubyllm_batch)
+        when "failed", "expired", "cancelled"
+          fail_all(status)
+        end
+        @batch
+      end
+
+      private
+
+      def reconcile_completed(rubyllm_batch)
+        results = rubyllm_batch.results
+        error_ids = rubyllm_batch.errors.filter_map { |e| e["custom_id"] }
+
+        @batch.update!(status: :completed, completed_at: Time.current)
+
+        @batch.requests.where.not(status: %i[succeeded failed fell_back]).find_each do |request|
+          message = results[request.custom_id]
+          if message
+            reconcile_success(request, message)
+          else
+            reconcile_failure(request, "no result for custom_id (in error file: #{error_ids.include?(request.custom_id)})")
+          end
+        end
+
+        @batch.update!(status: :reconciled, reconciled_at: Time.current)
+      end
+
+      def reconcile_success(request, message)
+        trace = TraceRecorder.record(request: request, message: message)
+        request.assign_attributes(
+          result_content: result_content_for(message.content),
+          input_tokens: message.input_tokens,
+          output_tokens: message.output_tokens,
+          cost: trace.total_cost,
+          trace_id: trace.id
+        )
+        handler = LlmLogs.batch_handler(request.purpose)
+        handler&.call(request, message)
+        request.succeeded!
+      rescue StandardError => e
+        # The LLM result was produced, but the handler (or persistence) failed. Mark the
+        # request failed-with-error rather than a misleading "succeeded" so the dropped
+        # result is visible in the dashboard instead of silently lost. The trace/tokens
+        # are still recorded (the spend happened); only delivery failed.
+        request.update!(status: :failed, error: "handler error: #{e.class}: #{e.message}")
+      end
+
+      # `result_content` is a text column. Structured (schema) results arrive as a Hash;
+      # store them as JSON so the snapshot stays machine-readable instead of Ruby inspect
+      # syntax ("key" => "value").
+      def result_content_for(content)
+        content.is_a?(Hash) || content.is_a?(Array) ? content.to_json : content.to_s
+      end
+
+      def reconcile_failure(request, error)
+        request.update!(status: :failed, error: error.to_s)
+        invoke_handler(request) { |handler| handler.on_failure(request, error) }
+      end
+
+      def fail_all(status)
+        # STATUSES does not include "cancelled"; treat a cancelled batch as failed so the
+        # batch record stays valid, while preserving the real status in the request error.
+        batch_status = status == "cancelled" ? :failed : status.to_sym
+        @batch.update!(status: batch_status, completed_at: Time.current)
+        @batch.requests.where.not(status: %i[succeeded failed fell_back]).find_each do |request|
+          reconcile_failure(request, "batch #{status}")
+        end
+      end
+
+      def invoke_handler(request)
+        handler = LlmLogs.batch_handler(request.purpose)
+        return unless handler
+
+        yield handler
+      rescue StandardError => e
+        request.update!(error: "handler error: #{e.class}: #{e.message}")
+      end
+    end
+  end
+end

data/app/models/llm_logs/batch/schema_format.rb

@@ -0,0 +1,25 @@
+module LlmLogs
+  class Batch
+    # Translates a {name:, schema:, strict:} schema (the shape RubyLLM::Chat#with_schema
+    # produces) into the OpenAI Responses API `text.format` block. The batch path builds
+    # request bodies directly via RubyLLM.batch#add(**extra), bypassing with_schema, so
+    # we must hand the json_schema block in ourselves.
+    module SchemaFormat
+      module_function
+
+      def call(schema)
+        return nil if schema.nil?
+
+        schema = schema.symbolize_keys if schema.respond_to?(:symbolize_keys)
+        {
+          format: {
+            type: "json_schema",
+            name: schema[:name] || "response",
+            schema: schema[:schema] || schema,
+            strict: schema.key?(:strict) ? schema[:strict] : true
+          }
+        }
+      end
+    end
+  end
+end

data/app/models/llm_logs/batch/submitter.rb

@@ -0,0 +1,76 @@
+module LlmLogs
+  class Batch
+    # Groups pending BatchRequests of one purpose+model into a single OpenAI batch via
+    # ruby_llm-responses_api. To prevent two concurrent FlushJobs from double-submitting
+    # the same requests, it first CLAIMS the pending rows in a `FOR UPDATE SKIP LOCKED`
+    # transaction (assigning them to a placeholder Batch with no openai_batch_id, which
+    # flips them out of the `pending` scope and which PollJob ignores). It then submits to
+    # OpenAI and records the batch id. If submission fails, the claim is released (requests
+    # return to `pending`) and the placeholder batch is dropped, so the work retries next flush.
+    class Submitter
+      def initialize(purpose:, model:, metadata: {})
+        @purpose = purpose
+        @model = model
+        @metadata = metadata
+      end
+
+      def call
+        batch = claim_batch
+        return nil if batch.nil?
+
+        submit(batch)
+        batch
+      end
+
+      private
+
+      def claim_batch
+        BatchRequest.transaction do
+          requests = BatchRequest.pending
+            .where(purpose: @purpose, model: @model)
+            .lock("FOR UPDATE SKIP LOCKED")
+            .to_a
+          next nil if requests.empty?
+
+          batch = LlmLogs::Batch.create!(
+            purpose: @purpose,
+            provider: LlmLogs.batch_provider.to_s,
+            model: @model,
+            status: :pending,
+            request_count: requests.size,
+            metadata: @metadata
+          )
+          BatchRequest.where(id: requests.map(&:id)).update_all(batch_id: batch.id, status: :submitted)
+          batch
+        end
+      end
+
+      def submit(batch)
+        rubyllm_batch = RubyLLM.batch(model: @model, provider: LlmLogs.batch_provider)
+        batch.requests.each do |request|
+          payload = request.payload
+          rubyllm_batch.add(
+            payload["input"],
+            id: request.custom_id,
+            instructions: payload["instructions"],
+            temperature: payload["temperature"],
+            **schema_extra(payload["schema"])
+          )
+        end
+        rubyllm_batch.create!
+        batch.update!(openai_batch_id: rubyllm_batch.id, status: :submitted, submitted_at: Time.current)
+      rescue StandardError
+        # Release the claim so the requests retry on the next flush, and drop the
+        # placeholder batch so it isn't polled. Re-raise so the caller/job sees the error.
+        batch.requests.update_all(batch_id: nil, status: :pending)
+        batch.destroy
+        raise
+      end
+
+      def schema_extra(schema)
+        format = SchemaFormat.call(schema)
+        format ? { text: format } : {}
+      end
+    end
+  end
+end

data/app/models/llm_logs/batch/trace_recorder.rb

@@ -0,0 +1,49 @@
+module LlmLogs
+  class Batch
+    # Records a completed trace + llm span for a reconciled batch request, mirroring
+    # what the synchronous chat.complete auto-instrumentation captures (model, provider,
+    # tokens, cost). Cost applies the 50% Batch API discount.
+    module TraceRecorder
+      BATCH_COST_MULTIPLIER = 0.5
+
+      module_function
+
+      def record(request:, message:)
+        trace = nil
+        metadata = request.routing.merge("execution_mode" => "batch")
+        LlmLogs.trace(request.purpose, metadata: metadata) do |t|
+          trace = t
+          prompt_version_id = request.routing["prompt_version_id"]
+          t.update_column(:prompt_version_id, prompt_version_id) if prompt_version_id
+
+          span = LlmLogs::Tracer.start_span(
+            name: "batch.complete",
+            span_type: "llm",
+            model: message.model_id || request.model,
+            provider: LlmLogs.batch_provider.to_s,
+            input: request.payload["input"]
+          )
+          span.update!(
+            output: { "content" => span.serialize_content(message.content) },
+            input_tokens: message.input_tokens,
+            output_tokens: message.output_tokens,
+            cost: compute_cost(message)
+          )
+          span.finish
+        end
+        trace
+      end
+
+      def compute_cost(message)
+        model_info = RubyLLM.models.find(message.model_id)
+        return nil unless model_info&.input_price_per_million && model_info&.output_price_per_million
+
+        raw = (message.input_tokens.to_f * model_info.input_price_per_million +
+               message.output_tokens.to_f * model_info.output_price_per_million) / 1_000_000
+        (raw * BATCH_COST_MULTIPLIER).round(6)
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/app/models/llm_logs/batch.rb

@@ -0,0 +1,51 @@
+module LlmLogs
+  class Batch < ApplicationRecord
+    self.table_name = "llm_logs_batches"
+
+    has_many :requests, class_name: "LlmLogs::BatchRequest", dependent: :destroy
+
+    enum :status, {
+      pending: "pending",
+      submitted: "submitted",
+      completed: "completed",
+      failed: "failed",
+      expired: "expired",
+      reconciled: "reconciled"
+    }, default: :pending
+
+    validates :purpose, :model, presence: true
+
+    scope :recent, -> { order(created_at: :desc) }
+    scope :unreconciled, -> { where.not(status: %i[reconciled failed expired]) }
+
+    def self.enqueue(purpose:, model:, input:, instructions:, schema:, routing:, temperature: nil)
+      BatchRequest.create!(
+        purpose: purpose,
+        model: model,
+        status: :pending,
+        custom_id: "req_#{SecureRandom.hex(8)}",
+        routing: routing,
+        payload: {
+          "input" => input,
+          "instructions" => instructions,
+          "schema" => schema,
+          "temperature" => temperature
+        }.compact
+      )
+    end
+
+    def self.submit_pending(purpose:, model:, metadata: {})
+      Submitter.new(purpose: purpose, model: model, metadata: metadata).call
+    end
+
+    def reconcile!
+      Reconciler.new(self).call
+    end
+
+    def self.batchable?(model)
+      return false unless LlmLogs.batch_enabled?
+
+      !defined?(RubyLLM::Providers::OpenAIResponses).nil?
+    end
+  end
+end

data/app/models/llm_logs/batch_request.rb

@@ -0,0 +1,18 @@
+module LlmLogs
+  class BatchRequest < ApplicationRecord
+    self.table_name = "llm_logs_batch_requests"
+
+    belongs_to :batch, class_name: "LlmLogs::Batch", optional: true
+
+    enum :status, {
+      pending: "pending",
+      submitted: "submitted",
+      succeeded: "succeeded",
+      failed: "failed",
+      fell_back: "fell_back"
+    }, default: :pending
+
+    validates :custom_id, presence: true, uniqueness: true
+    validates :purpose, :model, presence: true
+  end
+end

data/app/models/llm_logs/span.rb

@@ -20,12 +20,20 @@ module LlmLogs
     end
 
     def record_response(message)
-      self.output = { content: message.content.to_s }
+      self.output = { content: serialize_content(message.content) }
       self.input_tokens = message.input_tokens
       self.output_tokens = message.output_tokens
       self.cached_tokens = message.cached_tokens
     end
 
+    # Structured (schema) responses arrive as a Hash/Array; keep them as-is so the
+    # JSON `output` column stores real JSON and the UI renders nested fields. Calling
+    # `.to_s` here would serialize a Hash with Ruby inspect syntax ("key" => "value"),
+    # which is not valid JSON and shows up as an escaped blob in the dashboard.
+    def serialize_content(content)
+      content.is_a?(Hash) || content.is_a?(Array) ? content : content.to_s
+    end
+
     def record_error(exception)
       self.status = "error"
       self.error_message = "#{exception.class}: #{exception.message}"

data/app/views/layouts/llm_logs/application.html.erb

@@ -114,6 +114,8 @@
           <div class="flex space-x-1">
             <%= link_to "Traces", llm_logs.traces_path,
               class: "px-3 py-2 rounded-md text-sm font-medium #{request.path.start_with?(llm_logs.traces_path) || request.path == llm_logs.root_path ? 'bg-gray-800 text-white' : 'text-gray-300 hover:bg-gray-700 hover:text-white'}" %>
+            <%= link_to "Batches", llm_logs.batches_path,
+              class: "px-3 py-2 rounded-md text-sm font-medium #{request.path.start_with?(llm_logs.batches_path) ? 'bg-gray-800 text-white' : 'text-gray-300 hover:bg-gray-700 hover:text-white'}" %>
             <%= link_to "Prompts", llm_logs.prompts_path,
               class: "px-3 py-2 rounded-md text-sm font-medium #{request.path.start_with?(llm_logs.prompts_path) ? 'bg-gray-800 text-white' : 'text-gray-300 hover:bg-gray-700 hover:text-white'}" %>
           </div>

data/app/views/llm_logs/batches/index.html.erb

@@ -0,0 +1,47 @@
+<div class="flex items-center justify-between mb-6">
+  <h1 class="text-2xl font-bold text-gray-900">Batches</h1>
+  <%= form_tag batches_path, method: :get, class: "flex items-center space-x-2" do %>
+    <select name="status" class="rounded-md border-gray-300 text-sm py-1.5 px-3 bg-white border shadow-sm">
+      <option value="">All statuses</option>
+      <% LlmLogs::Batch.statuses.keys.each do |status| %>
+        <option value="<%= status %>" <%= 'selected' if params[:status] == status %>><%= status %></option>
+      <% end %>
+    </select>
+    <button type="submit" class="bg-gray-900 text-white px-3 py-1.5 rounded-md text-sm hover:bg-gray-700">Filter</button>
+  <% end %>
+</div>
+
+<div class="bg-white shadow-sm ring-1 ring-gray-900/5 rounded-lg overflow-hidden">
+  <table class="min-w-full divide-y divide-gray-200">
+    <thead class="bg-gray-50">
+      <tr>
+        <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Purpose</th>
+        <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Model</th>
+        <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">OpenAI Batch</th>
+        <th class="px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase">Requests</th>
+        <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Status</th>
+        <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Submitted</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-200">
+      <% status_colors = { "pending" => "bg-gray-100 text-gray-800", "submitted" => "bg-yellow-100 text-yellow-800", "completed" => "bg-blue-100 text-blue-800", "reconciled" => "bg-green-100 text-green-800", "failed" => "bg-red-100 text-red-800", "expired" => "bg-red-100 text-red-800" } %>
+      <% @batches.each do |batch| %>
+        <tr class="hover:bg-gray-50">
+          <td class="px-4 py-3 text-sm"><%= link_to batch.purpose, batch_path(batch), class: "text-indigo-600 hover:text-indigo-900 font-medium" %></td>
+          <td class="px-4 py-3 text-sm text-gray-500"><%= batch.model %></td>
+          <td class="px-4 py-3 text-sm text-gray-500 font-mono"><%= batch.openai_batch_id %></td>
+          <td class="px-4 py-3 text-sm text-gray-500 text-right"><%= batch.request_count %></td>
+          <td class="px-4 py-3 text-sm">
+            <span class="inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium <%= status_colors[batch.status] %>"><%= batch.status %></span>
+          </td>
+          <td class="px-4 py-3 text-sm text-gray-500"><%= batch.submitted_at&.strftime('%b %d %H:%M') %></td>
+        </tr>
+      <% end %>
+      <% if @batches.empty? %>
+        <tr><td colspan="6" class="px-4 py-8 text-center text-sm text-gray-500">No batches found.</td></tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+
+<%= paginate @batches, theme: "tailwind" %>

data/app/views/llm_logs/batches/show.html.erb

@@ -0,0 +1,47 @@
+<div class="mb-6">
+  <%= link_to "← Batches", batches_path, class: "text-sm text-indigo-600 hover:text-indigo-900" %>
+  <h1 class="text-2xl font-bold text-gray-900 mt-2"><%= @batch.purpose %> · <%= @batch.model %></h1>
+  <p class="text-sm text-gray-500 mt-1">
+    OpenAI: <span class="font-mono"><%= @batch.openai_batch_id %></span> · status <%= @batch.status %> ·
+    <%= @batch.request_count %> requests
+  </p>
+</div>
+
+<div class="bg-white shadow-sm ring-1 ring-gray-900/5 rounded-lg overflow-hidden">
+  <table class="w-full table-fixed divide-y divide-gray-200">
+    <thead class="bg-gray-50">
+      <tr>
+        <th class="w-56 px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase" data-column="custom-id">Custom ID</th>
+        <th class="w-28 px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Status</th>
+        <th class="w-28 px-4 py-3 text-right text-xs font-medium text-gray-500 uppercase">Tokens</th>
+        <th class="px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Metadata</th>
+        <th class="w-16 px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Trace</th>
+        <th class="w-48 px-4 py-3 text-left text-xs font-medium text-gray-500 uppercase">Error</th>
+      </tr>
+    </thead>
+    <tbody class="divide-y divide-gray-200">
+      <% req_colors = { "pending" => "bg-gray-100 text-gray-800", "submitted" => "bg-yellow-100 text-yellow-800", "succeeded" => "bg-green-100 text-green-800", "failed" => "bg-red-100 text-red-800", "fell_back" => "bg-orange-100 text-orange-800" } %>
+      <% @requests.each do |request| %>
+        <tr class="hover:bg-gray-50 align-top">
+          <td class="px-4 py-3 text-sm font-mono text-gray-700 whitespace-nowrap"><%= request.custom_id %></td>
+          <td class="px-4 py-3 text-sm"><span class="inline-flex items-center rounded-full px-2 py-0.5 text-xs font-medium <%= req_colors[request.status] %>"><%= request.status %></span></td>
+          <td class="px-4 py-3 text-sm text-gray-500 text-right"><%= request.input_tokens %> &rarr; <%= request.output_tokens %></td>
+          <td class="px-4 py-3 text-xs text-gray-500 min-w-0">
+            <dl class="grid grid-cols-[max-content_minmax(0,1fr)] gap-x-3 gap-y-1 min-w-0" data-routing>
+              <% request.routing.each do |key, value| %>
+                <dt class="font-medium text-gray-700"><%= key %></dt>
+                <dd class="min-w-0 truncate" title="<%= routing_full_value(value) %>"><%= routing_display_value(value) %></dd>
+              <% end %>
+            </dl>
+          </td>
+          <td class="px-4 py-3 text-sm">
+            <%= link_to "trace", trace_path(request.trace_id), class: "text-indigo-600 hover:text-indigo-900" if request.trace_id %>
+          </td>
+          <td class="px-4 py-3 text-xs text-red-600"><%= request.error %></td>
+        </tr>
+      <% end %>
+    </tbody>
+  </table>
+</div>
+
+<%= paginate @requests, theme: "tailwind" %>

data/app/views/llm_logs/prompts/show.html.erb

@@ -1,6 +1,7 @@
 <div class="mb-6">
+  <%= link_to "← Prompts", prompts_path, class: "text-sm text-indigo-600 hover:text-indigo-900" %>
   <div class="flex items-center justify-between">
-    <div>
+    <div class="mt-2">
       <h1 class="text-2xl font-bold text-gray-900"><%= @prompt.name %></h1>
       <p class="text-sm text-gray-500 mt-1">
         <span class="font-mono"><%= @prompt.slug %></span>

data/app/views/llm_logs/traces/show.html.erb

@@ -1,6 +1,7 @@
 <div class="mb-6">
+  <%= link_to "← Traces", traces_path, class: "text-sm text-indigo-600 hover:text-indigo-900" %>
   <div class="flex items-center justify-between">
-    <div>
+    <div class="mt-2">
       <div class="flex items-center space-x-3">
         <h1 class="text-2xl font-bold text-gray-900"><%= @trace.name %></h1>
         <% status_colors = { "running" => "bg-blue-100 text-blue-800", "completed" => "bg-green-100 text-green-800", "error" => "bg-red-100 text-red-800" } %>
@@ -19,11 +20,14 @@
         </p>
       <% end %>
     </div>
-    <%= link_to "Back to traces", traces_path, class: "text-sm text-gray-600 hover:text-gray-900" %>
   </div>
 </div>
 
-<div class="grid grid-cols-5 gap-4 mb-6">
+<div class="grid grid-cols-6 gap-4 mb-6">
+  <div class="bg-white rounded-lg p-4 shadow-sm ring-1 ring-gray-900/5">
+    <dt class="text-xs font-medium text-gray-500 uppercase">Model</dt>
+    <dd class="text-lg font-semibold text-gray-900 mt-1 break-words"><%= @models.join(", ").presence || "—" %></dd>
+  </div>
   <div class="bg-white rounded-lg p-4 shadow-sm ring-1 ring-gray-900/5">
     <dt class="text-xs font-medium text-gray-500 uppercase">Spans</dt>
     <dd class="text-2xl font-semibold text-gray-900 mt-1"><%= @trace.spans.count %></dd>

data/config/routes.rb

@@ -5,6 +5,8 @@ LlmLogs::Engine.routes.draw do
     resources :spans, only: [:show]
   end
 
+  resources :batches, only: [:index, :show]
+
   resources :prompts do
     resources :versions, only: [:index, :show, :destroy], controller: "prompt_versions" do
       member do

data/db/migrate/007_create_llm_logs_batches.rb

@@ -0,0 +1,22 @@
+class CreateLlmLogsBatches < ActiveRecord::Migration[8.0]
+  def change
+    create_table :llm_logs_batches do |t|
+      t.string :purpose, null: false
+      t.string :provider, null: false, default: "openai_responses"
+      t.string :model, null: false
+      t.string :openai_batch_id
+      t.string :openai_output_file_id
+      t.string :openai_error_file_id
+      t.string :status, null: false, default: "pending"
+      t.integer :request_count, null: false, default: 0
+      t.jsonb :metadata, null: false, default: {}
+      t.datetime :submitted_at
+      t.datetime :completed_at
+      t.datetime :reconciled_at
+      t.timestamps
+    end
+    add_index :llm_logs_batches, :openai_batch_id, unique: true
+    add_index :llm_logs_batches, :status
+    add_index :llm_logs_batches, :purpose
+  end
+end

data/db/migrate/008_create_llm_logs_batch_requests.rb

@@ -0,0 +1,22 @@
+class CreateLlmLogsBatchRequests < ActiveRecord::Migration[8.0]
+  def change
+    create_table :llm_logs_batch_requests do |t|
+      t.references :batch, foreign_key: { to_table: :llm_logs_batches }
+      t.string :custom_id, null: false
+      t.string :purpose, null: false
+      t.string :status, null: false, default: "pending"
+      t.string :model, null: false
+      t.jsonb :payload, null: false, default: {}
+      t.jsonb :routing, null: false, default: {}
+      t.text :result_content
+      t.integer :input_tokens
+      t.integer :output_tokens
+      t.decimal :cost, precision: 10, scale: 6
+      t.bigint :trace_id
+      t.text :error
+      t.timestamps
+    end
+    add_index :llm_logs_batch_requests, :custom_id, unique: true
+    add_index :llm_logs_batch_requests, [:purpose, :status]
+  end
+end

data/lib/llm_logs/configuration.rb

@@ -1,6 +1,7 @@
 module LlmLogs
   class Configuration
-    attr_accessor :enabled, :auto_instrument, :retention_days, :prompts_source_path, :prompt_subfolders
+    attr_accessor :enabled, :auto_instrument, :retention_days, :prompts_source_path, :prompt_subfolders,
+                  :batch_enabled, :batch_provider
 
     def initialize
       @enabled             = true
@@ -8,6 +9,8 @@ module LlmLogs
       @retention_days      = 30
       @prompts_source_path = nil
       @prompt_subfolders   = %w[skills fragments templates]
+      @batch_enabled       = true
+      @batch_provider      = :openai_responses
     end
   end
 

data/lib/llm_logs/version.rb

@@ -1,3 +1,3 @@
 module LlmLogs
-  VERSION = "0.1.6"
+  VERSION = "0.2.2"
 end

data/lib/llm_logs.rb

@@ -38,6 +38,22 @@ module LlmLogs
     configuration.retention_days = retention_days
   end
 
+  def self.batch_enabled?
+    configuration.batch_enabled
+  end
+
+  def self.batch_provider
+    configuration.batch_provider
+  end
+
+  def self.register_batch_handler(purpose, handler)
+    LlmLogs::Batch::HandlerRegistry.register(purpose, handler)
+  end
+
+  def self.batch_handler(purpose)
+    LlmLogs::Batch::HandlerRegistry.resolve(purpose)
+  end
+
   def self.trace(name, **options, &block)
     LlmLogs::Tracer.start_trace(name, **options, &block)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: llm_logs
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.2.2
 platform: ruby
 authors:
 - Anton
@@ -93,6 +93,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.16'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm-responses_api
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: Mountable Rails engine that provides hierarchical LLM call tracing and
   versioned prompt management with Mustache templates.
 executables: []
@@ -103,13 +145,24 @@ files:
 - README.md
 - Rakefile
 - app/controllers/llm_logs/application_controller.rb
+- app/controllers/llm_logs/batches_controller.rb
 - app/controllers/llm_logs/prompt_versions_controller.rb
 - app/controllers/llm_logs/prompts_controller.rb
 - app/controllers/llm_logs/spans_controller.rb
 - app/controllers/llm_logs/traces_controller.rb
+- app/helpers/llm_logs/batches_helper.rb
 - app/helpers/llm_logs/formatting_helper.rb
 - app/helpers/llm_logs/prompts_helper.rb
+- app/jobs/llm_logs/batch/flush_job.rb
+- app/jobs/llm_logs/batch/poll_job.rb
 - app/models/llm_logs/application_record.rb
+- app/models/llm_logs/batch.rb
+- app/models/llm_logs/batch/handler_registry.rb
+- app/models/llm_logs/batch/reconciler.rb
+- app/models/llm_logs/batch/schema_format.rb
+- app/models/llm_logs/batch/submitter.rb
+- app/models/llm_logs/batch/trace_recorder.rb
+- app/models/llm_logs/batch_request.rb
 - app/models/llm_logs/prompt.rb
 - app/models/llm_logs/prompt_version.rb
 - app/models/llm_logs/span.rb
@@ -123,6 +176,8 @@ files:
 - app/views/kaminari/tailwind/_paginator.html.erb
 - app/views/kaminari/tailwind/_prev_page.html.erb
 - app/views/layouts/llm_logs/application.html.erb
+- app/views/llm_logs/batches/index.html.erb
+- app/views/llm_logs/batches/show.html.erb
 - app/views/llm_logs/prompt_versions/compare.html.erb
 - app/views/llm_logs/prompt_versions/index.html.erb
 - app/views/llm_logs/prompt_versions/show.html.erb
@@ -142,6 +197,8 @@ files:
 - db/migrate/004_create_llm_logs_prompt_versions.rb
 - db/migrate/005_add_prompt_version_to_traces.rb
 - db/migrate/006_add_tags_to_prompts.rb
+- db/migrate/007_create_llm_logs_batches.rb
+- db/migrate/008_create_llm_logs_batch_requests.rb
 - lib/generators/llm_logs/install_generator.rb
 - lib/generators/llm_logs/templates/initializer.rb
 - lib/llm_logs.rb