coolhand 0.7.0 → 0.9.0

data/lib/coolhand/workload_service.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "api_service"
+require_relative "pagination"
+require_relative "read_query"
+require_relative "write_requests"
+
+module Coolhand
+  # Rows stay plain Symbol-keyed Hashes so a field the server adds later is not dropped in transit.
+  WorkloadSearchResult = Struct.new(:workloads, :pagination, keyword_init: true)
+
+  # Lists workloads and upserts them by key. Requires the client's **private** key. There is no per-id
+  # endpoint. See docs/workload-search.md and docs/declared_workloads.md.
+  class WorkloadService < ApiService
+    include ReadQuery
+    include WriteRequests
+
+    ERROR_NOUN = "Workload"
+
+    def initialize
+      super("v2/workloads")
+    end
+
+    # Filters, windows, error semantics and server behaviour: docs/workload-search.md.
+    def search_workloads(search: nil, include_archived: nil, include_system: nil, include_templates: nil,
+      include_metrics: nil, days_back: nil, since: nil, until: nil, page: nil, per: nil)
+      query = {
+        search: search,
+        include_archived: include_archived,
+        include_system: include_system,
+        include_templates: include_templates,
+        include_metrics: include_metrics,
+        days_back: days_back,
+        **window_params(since, binding.local_variable_get(:until)),
+        page: page,
+        per: per
+      }.compact
+
+      fetch_list(query, WorkloadSearchResult, :workloads, page: page, per: per)
+    end
+
+    # Creates the workload with this `key`, or updates the existing one. The key is immutable; a new
+    # `name` renames the display name. Returns the workload Hash (the server answers 201 on create,
+    # 200 on update). Raises {Coolhand::HttpError} on a non-2xx response. See docs/declared_workloads.md.
+    def upsert(key:, name: nil, description: nil, reporter: nil)
+      body = { name: name, description: description, reporter: reporter }.compact
+      request_json(:put, by_key_url("upsert", key), ERROR_NOUN, body: body)
+    end
+  end
+end

data/lib/coolhand/write_requests.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require_relative "errors"
+require_relative "read_requests"
+
+module Coolhand
+  # POST/DELETE counterpart of {ReadRequests} for callers that act on the response: raises on any
+  # failure where {ApiService#send_request} logs and returns nil. Timeouts are the read ones, for
+  # the same server-side statement-bound reason. Mix into an {ApiService} subclass: it relies on
+  # `api_key`, `apply_headers` and `format_error_body` from there and the shared HTTP helpers from
+  # {ReadRequests}.
+  module WriteRequests
+    DOT_SEGMENTS = [".", ".."].freeze
+
+    protected
+
+    # Returns the parsed body, or nil for an empty one (204).
+    def request_json(verb, url, noun, body: nil)
+      raise Error, "#{noun} request failed: an API key is required" unless Coolhand.required_field?(api_key)
+
+      response = perform_write(verb, url, noun, body)
+
+      raise_http_error(response, noun) unless response.is_a?(Net::HTTPSuccess)
+
+      response.body.to_s.strip.empty? ? nil : parse_json_body(response.body, noun)
+    end
+
+    # `<endpoint>/by_key/<key>` for the upsert routes, which are globs: a key like "Parser#call/squish:L2"
+    # keeps its slashes and each segment is escaped, so `#` or `?` in a key cannot retarget the request.
+    def by_key_url(method_name, key)
+      trimmed = key.is_a?(String) ? key.strip : ""
+      segments = trimmed.split("/", -1)
+      if trimmed.empty? || segments.any? { |segment| segment.empty? || DOT_SEGMENTS.include?(segment) }
+        raise Error, "#{method_name}: key must be a non-empty string without empty or dot path segments"
+      end
+
+      URI.parse("#{api_endpoint}/by_key/#{segments.map { |segment| escape_path_segment(segment) }.join('/')}")
+    end
+
+    private
+
+    def perform_write(verb, url, noun, body)
+      uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+      http = build_http(uri)
+
+      request = Net::HTTP.const_get(verb.to_s.capitalize).new(uri.request_uri)
+      apply_headers(request, "Accept" => "application/json", "X-API-Key" => api_key)
+      unless body.nil?
+        apply_headers(request, "Content-Type" => "application/json")
+        request.body = JSON.generate(body).force_encoding("UTF-8")
+      end
+
+      Coolhand.without_capture { http.request(request) }
+    rescue StandardError => e
+      raise Error, "#{noun} request failed: #{e.message}"
+    end
+  end
+end

data/lib/coolhand.rb

@@ -10,13 +10,22 @@ require_relative "coolhand/errors"
 require_relative "coolhand/version"
 require_relative "coolhand/configuration"
 require_relative "coolhand/collector"
+require_relative "coolhand/declared_context"
+require_relative "coolhand/declarable"
+require_relative "coolhand/rails_auto_declare"
+require_relative "coolhand/log_queue"
 require_relative "coolhand/base_interceptor"
 require_relative "coolhand/net_http_interceptor"
 require_relative "coolhand/api_service"
 require_relative "coolhand/logger_service"
 require_relative "coolhand/feedback_service"
 require_relative "coolhand/template_service"
+require_relative "coolhand/optimization_feedback_link_service"
+require_relative "coolhand/workload_service"
+require_relative "coolhand/log_service"
 require_relative "coolhand/webhook_interceptor"
+# Only when Rails is already loaded; the gem has no Rails dependency.
+require_relative "coolhand/railtie" if defined?(Rails::Railtie)
 
 # The main module for the Coolhand gem.
 # It provides the configuration interface and initializes the patching.
@@ -31,6 +40,7 @@ module Coolhand
     def reset_configuration!
       @configuration = Configuration.new
       Thread.current[:coolhand_capture_override] = nil
+      DeclaredContext.clear!
     end
 
     # Provides a block to configure the gem.
@@ -70,20 +80,32 @@ module Coolhand
       end
     end
 
-    def without_capture
-      previous = Thread.current[:coolhand_capture_override]
-      Thread.current[:coolhand_capture_override] = false
-      yield
-    ensure
-      Thread.current[:coolhand_capture_override] = previous
+    def without_capture(&block)
+      override_capture(false, &block)
     end
 
-    def with_capture
-      previous = Thread.current[:coolhand_capture_override]
-      Thread.current[:coolhand_capture_override] = true
-      yield
-    ensure
-      Thread.current[:coolhand_capture_override] = previous
+    def with_capture(&block)
+      override_capture(true, &block)
+    end
+
+    # Declares the workload/template that LLM calls captured inside the block belong to. Nested
+    # blocks override per field (`reporter`, `workload`, `template`), innermost wins. `workload` and
+    # `template` are Hashes with `id:` (an existing record) or `key:` (find-or-created), plus optional
+    # `name:` (and `description:` on a workload). See docs/declared_workloads.md.
+    #
+    # Example:
+    #   Coolhand.with_context(reporter: "squishling", workload: { key: "Parser#call" }) { client.chat(...) }
+    def with_context(reporter: nil, workload: nil, template: nil, &block)
+      raise ArgumentError, "Coolhand.with_context requires a block" unless block
+
+      DeclaredContext.with(reporter: reporter, workload: workload, template: template, &block)
+    end
+
+    # Blocks until log requests queued by async logging have been sent, or the timeout (in
+    # seconds) elapses. Returns true if everything was sent. Pending logs are also flushed
+    # automatically at process exit.
+    def flush(timeout: LogQueue::DEFAULT_FLUSH_TIMEOUT)
+      LogQueue.flush(timeout)
     end
 
     # A simple logger that respects the 'silent' configuration option.
@@ -113,6 +135,24 @@ module Coolhand
       TemplateService.new
     end
 
+    # Creates a new WorkloadService instance, for listing workloads (with optional cost and
+    # performance metrics). Needs the private API key.
+    def workload_service
+      WorkloadService.new
+    end
+
+    # Creates a new LogService instance, for reading logs back out of Coolhand. Distinct from
+    # {logger_service}, which writes them. Needs the private API key.
+    def log_service
+      LogService.new
+    end
+
+    # Creates a new OptimizationFeedbackLinkService instance, for linking feedback to an
+    # optimization as evidence. Needs the private API key.
+    def optimization_feedback_link_service
+      OptimizationFeedbackLinkService.new
+    end
+
     def required_field?(value)
       return false if value.nil?
       return false if value.respond_to?(:empty?) && value.empty?
@@ -120,5 +160,16 @@ module Coolhand
 
       true
     end
+
+    private
+
+    # Forces capture on or off for the block on this thread, restoring the previous override after.
+    def override_capture(enabled)
+      previous = Thread.current[:coolhand_capture_override]
+      Thread.current[:coolhand_capture_override] = enabled
+      yield
+    ensure
+      Thread.current[:coolhand_capture_override] = previous
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: coolhand
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Michael Carroll
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-20 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -47,32 +47,47 @@ files:
 - SECURITY.md
 - docs/anthropic.md
 - docs/configuration.md
+- docs/declared_workloads.md
 - docs/elevenlabs.md
+- docs/feedback-links.md
 - docs/feedback.md
+- docs/log-search.md
 - docs/openai.md
 - docs/template-search.md
 - docs/vertex.md
+- docs/workload-search.md
 - lib/coolhand.rb
 - lib/coolhand/api_service.rb
 - lib/coolhand/base_interceptor.rb
 - lib/coolhand/collector.rb
 - lib/coolhand/configuration.rb
+- lib/coolhand/declarable.rb
+- lib/coolhand/declared_context.rb
 - lib/coolhand/default_exclude_api_patterns.yml
 - lib/coolhand/default_intercept_addresses.yml
 - lib/coolhand/default_intercept_path_patterns.yml
 - lib/coolhand/errors.rb
 - lib/coolhand/feedback_service.rb
+- lib/coolhand/log_queue.rb
+- lib/coolhand/log_service.rb
 - lib/coolhand/logger_service.rb
 - lib/coolhand/net_http_interceptor.rb
 - lib/coolhand/open_ai/batch_result_processor.rb
 - lib/coolhand/open_ai/webhook_id_store.rb
 - lib/coolhand/open_ai/webhook_validator.rb
+- lib/coolhand/optimization_feedback_link_service.rb
 - lib/coolhand/pagination.rb
+- lib/coolhand/rails_auto_declare.rb
+- lib/coolhand/railtie.rb
+- lib/coolhand/read_query.rb
 - lib/coolhand/read_requests.rb
+- lib/coolhand/response_warnings.rb
 - lib/coolhand/template_service.rb
 - lib/coolhand/version.rb
 - lib/coolhand/vertex/batch_result_processor.rb
 - lib/coolhand/webhook_interceptor.rb
+- lib/coolhand/workload_service.rb
+- lib/coolhand/write_requests.rb
 - sig/coolhand/ruby.rbs
 homepage: https://coolhandlabs.com/
 licenses: