simforge 0.5.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 662f1ce8942083e856907a38568a40b252c4d6360f043fc25da58900a46e36e7
+  data.tar.gz: 9d74cf518171472d22b49c6b8fb3544e258607e5284acebe0f6b46e71213e0cd
+SHA512:
+  metadata.gz: 556e17aa0f010ecb394f7a5937c3c02a43ef0d76bffe00082899074a19f26c555bec5c4d47dfe1afa98c34f7093beae5dd4b4a4d2d9d00a68d0155aadd979aea
+  data.tar.gz: 14cd3fbc8c4ea4096036ce312e6eac67ab7b57a634c10faba0962fa3dd10368928ebc3c25c1236b5ff6019a8db36094b0a4e4a8eeb737da2c76fc42e5525cd62

data/lib/simforge/client.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+require_relative "constants"
+require_relative "http_client"
+require_relative "span_context"
+require_relative "serialize"
+
+module Simforge
+  class Client
+    SPAN_TYPES = %w[llm agent function guardrail handoff custom].freeze
+
+    attr_reader :api_key, :service_url
+
+    def initialize(api_key:, service_url: nil)
+      @api_key = api_key
+      @service_url = service_url || DEFAULT_SERVICE_URL
+      @http_client = HttpClient.new(api_key:, service_url: @service_url)
+    end
+
+    # Execute a block inside a span context, sending trace data on completion.
+    # Called by Traceable — not intended for direct use.
+    def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:)
+      validate_span_type!(span_type)
+
+      parent = SpanContext.current
+      trace_id = parent ? parent[:trace_id] : SecureRandom.uuid
+      span_id = SecureRandom.uuid
+      parent_span_id = parent&.dig(:span_id)
+      started_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+
+      result = nil
+      error = nil
+
+      begin
+        result = SpanContext.with_span(trace_id:, span_id:) { yield }
+      rescue => e
+        error = e.message
+        raise
+      ensure
+        ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+
+        send_span(
+          trace_function_key:,
+          trace_id:,
+          span_id:,
+          parent_span_id:,
+          span_name:,
+          span_type:,
+          function_name:,
+          args:,
+          kwargs:,
+          result:,
+          error:,
+          started_at:,
+          ended_at:
+        )
+      end
+
+      result
+    end
+
+    private
+
+    def validate_span_type!(type)
+      return if SPAN_TYPES.include?(type.to_s)
+
+      raise ArgumentError, "Invalid span type '#{type}'. Must be one of: #{SPAN_TYPES.join(", ")}"
+    end
+
+    def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
+      span_name:, span_type:, function_name:, args:, kwargs:, result:, error:,
+      started_at:, ended_at:)
+      # Human-readable JSON (input/output fields)
+      human_inputs = Serialize.serialize_inputs(args, kwargs)
+      human_output = Serialize.serialize_value(result)
+
+      # Marshal + Base64 for full Ruby-to-Ruby object reconstruction
+      raw_input = (args.length == 1 && kwargs.empty?) ? args[0] : {args:, kwargs:}
+      marshalled_input = Serialize.marshal_value(raw_input)
+      marshalled_output = Serialize.marshal_value(result)
+
+      span_data = {
+        "name" => span_name,
+        "type" => span_type,
+        "input" => human_inputs,
+        "output" => human_output,
+        "function_name" => function_name
+      }
+      span_data["input_serialized"] = marshalled_input if marshalled_input
+      span_data["output_serialized"] = marshalled_output if marshalled_output
+      span_data["error"] = error if error
+
+      raw_span = {
+        "id" => span_id,
+        "trace_id" => trace_id,
+        "started_at" => started_at,
+        "ended_at" => ended_at,
+        "span_data" => span_data
+      }
+      raw_span["parent_id"] = parent_span_id if parent_span_id
+
+      @http_client.send_external_span(
+        "type" => "sdk-function",
+        "source" => "ruby-sdk-function",
+        "sourceTraceId" => trace_id,
+        "traceFunctionKey" => trace_function_key,
+        "rawSpan" => raw_span
+      )
+    end
+  end
+end

data/lib/simforge/constants.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Simforge
+  DEFAULT_SERVICE_URL = "https://simforge.goharvest.ai"
+end

data/lib/simforge/http_client.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+require_relative "constants"
+require_relative "version"
+
+module Simforge
+  class HttpClient
+    attr_reader :service_url
+
+    def initialize(api_key:, service_url: nil, timeout: 120)
+      @api_key = api_key
+      @service_url = (service_url || DEFAULT_SERVICE_URL).chomp("/")
+      @timeout = timeout
+    end
+
+    # Make a POST request to the Simforge API.
+    # Returns parsed JSON response hash.
+    def request(endpoint, payload, timeout: nil, max_retries: 1, retry_delay: 0.1)
+      uri = URI("#{@service_url}#{endpoint}")
+      request_timeout = timeout || @timeout
+
+      last_error = nil
+
+      max_retries.times do |attempt|
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = request_timeout
+        http.read_timeout = request_timeout
+
+        req = Net::HTTP::Post.new(uri.path, headers)
+        req.body = JSON.generate(payload)
+
+        response = http.request(req)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Net::HTTPError.new("HTTP #{response.code}: #{response.body}", response)
+        end
+
+        result = JSON.parse(response.body)
+
+        if result["error"]
+          msg = result["error"]
+          msg = "#{msg} Configure it at: #{@service_url}#{result["url"]}" if result["url"]
+          raise StandardError, msg
+        end
+
+        return result
+      rescue => e
+        last_error = e
+        sleep(retry_delay) if attempt < max_retries - 1
+      end
+
+      raise last_error
+    end
+
+    # Send an external span (fire-and-forget in background thread).
+    def send_external_span(payload)
+      merged = payload.merge("sdkVersion" => VERSION)
+
+      Simforge._run_in_background do
+        request("/api/sdk/externalSpans", merged, timeout: 30)
+      end
+    end
+
+    private
+
+    def headers
+      {
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{@api_key}"
+      }
+    end
+  end
+
+  # --- Background thread management ---
+
+  @pending_threads_mutex = Mutex.new
+  @pending_threads = []
+
+  class << self
+    # Run a block in a background thread with tracking.
+    def _run_in_background(&block)
+      thread = Thread.new do
+        block.call
+      rescue
+        # Silently ignore failures in background spans
+      ensure
+        @pending_threads_mutex.synchronize { @pending_threads.delete(Thread.current) }
+      end
+
+      @pending_threads_mutex.synchronize { @pending_threads << thread }
+    end
+
+    # Wait for all pending background threads to complete.
+    def flush_traces(timeout: 30)
+      threads = @pending_threads_mutex.synchronize { @pending_threads.dup }
+      threads.each { |t| t.join(timeout) }
+    end
+  end
+
+  at_exit do
+    Simforge.flush_traces(timeout: 2)
+  end
+end

data/lib/simforge/serialize.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+require "time"
+
+module Simforge
+  module Serialize
+    module_function
+
+    # Serialize a value for JSON storage (human-readable).
+    # Handles primitives, hashes, arrays, and objects with common conversion methods.
+    # Note: We intentionally avoid as_json here because it requires ActiveSupport,
+    # and we want to keep the SDK dependency-free (stdlib only).
+    def serialize_value(value)
+      case value
+      when nil, true, false, Integer, Float, String
+        value
+      when Hash
+        value.transform_keys(&:to_s).transform_values { |v| serialize_value(v) }
+      when Array
+        value.map { |v| serialize_value(v) }
+      when Set
+        value.map { |v| serialize_value(v) }
+      when Time, DateTime
+        value.iso8601(3)
+      when Date
+        value.to_s
+      when Symbol
+        value.to_s
+      else
+        if value.respond_to?(:to_h)
+          serialize_value(value.to_h)
+        elsif value.respond_to?(:to_a)
+          serialize_value(value.to_a)
+        else
+          value.to_s
+        end
+      end
+    end
+
+    # Serialize function inputs (args + kwargs) for span data (human-readable).
+    def serialize_inputs(args, kwargs = {})
+      serialized = args.map { |arg| serialize_value(arg) }
+      serialized << kwargs.transform_keys(&:to_s).transform_values { |v| serialize_value(v) } unless kwargs.empty?
+      serialized
+    end
+
+    # Marshal a value to a Base64-encoded string for Ruby-to-Ruby reconstruction.
+    # Handles arbitrary Ruby objects including custom classes.
+    #
+    # @param value [Object] any Ruby value
+    # @return [String, nil] Base64-encoded Marshal dump, or nil if marshalling fails
+    def marshal_value(value)
+      Base64.strict_encode64(Marshal.dump(value))
+    rescue TypeError, ArgumentError
+      # Some objects (Proc, IO, etc.) can't be marshalled
+      nil
+    end
+
+    # Unmarshal a Base64-encoded string back into a Ruby object.
+    #
+    # @param encoded [String] Base64-encoded Marshal dump
+    # @return [Object] the reconstructed Ruby object
+    def unmarshal_value(encoded)
+      Marshal.load(Base64.strict_decode64(encoded)) # rubocop:disable Security/MarshalLoad
+    end
+  end
+end

data/lib/simforge/span_context.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Simforge
+  # Thread-local span stack for tracking nested spans.
+  # Each entry is a Hash with :trace_id and :span_id keys.
+  module SpanContext
+    STACK_KEY = :simforge_span_stack
+
+    module_function
+
+    def stack
+      Thread.current[STACK_KEY] ||= []
+    end
+
+    def current
+      stack.last
+    end
+
+    # Execute a block with a new span pushed onto the stack.
+    # The span is automatically popped when the block completes.
+    def with_span(trace_id:, span_id:)
+      entry = {trace_id:, span_id:}
+      stack.push(entry)
+      yield
+    ensure
+      stack.pop
+    end
+  end
+end

data/lib/simforge/traceable.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Simforge
+  # Mixin for declarative span tracing on instance methods.
+  #
+  # @example
+  #   Simforge.configure(api_key: "...")
+  #
+  #   class OrderService
+  #     include Simforge::Traceable
+  #     simforge_function "order-processing"
+  #
+  #     simforge_span :process_order, type: "function"
+  #     def process_order(order_id)
+  #       { total: 100 }
+  #     end
+  #
+  #     simforge_span :validate_order, name: "Validate", type: "guardrail"
+  #     def validate_order(order_id)
+  #       { valid: true }
+  #     end
+  #   end
+  #
+  module Traceable
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      # Set the trace function key for this class.
+      # All spans declared in this class will be grouped under this key.
+      #
+      # @param key [String] the trace function key
+      def simforge_function(key)
+        @simforge_function_key = key
+      end
+
+      # Declare that a method should be wrapped with span tracing.
+      #
+      # Supports three styles:
+      #   simforge_span :foo, type: "function"   # before def foo (uses method_added hook)
+      #   def foo; end
+      #
+      #   simforge_span def foo                   # inline (def returns :foo, method already exists)
+      #     ...
+      #   end, type: "function"
+      #
+      #   def foo; end                            # after def foo (method already exists)
+      #   simforge_span :foo, type: "function"
+      #
+      # @param method_name [Symbol] the method to wrap
+      # @param trace_function_key [String, nil] trace function key (overrides class-level simforge_function)
+      # @param name [String, nil] explicit span name (defaults to method name)
+      # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+      def simforge_span(method_name, trace_function_key: nil, name: nil, type: "custom")
+        trace_function_key ||= @simforge_function_key
+        unless trace_function_key
+          raise "No trace function key provided. Pass `trace_function_key:` to `simforge_span` " \
+                "or call `simforge_function 'my-key'` before using `simforge_span`."
+        end
+
+        # If the method already exists (inline or after-method style), wrap it immediately
+        if method_defined?(method_name) || private_method_defined?(method_name)
+          _simforge_wrap_method(method_name, trace_function_key:, name:, type:)
+        else
+          # Method doesn't exist yet (before-method style) — register for method_added hook
+          @_simforge_pending_spans ||= {}
+          @_simforge_pending_spans[method_name] = {
+            trace_function_key:,
+            name:,
+            type:
+          }
+        end
+      end
+
+      private
+
+      def method_added(method_name)
+        super
+        return unless defined?(@_simforge_pending_spans) && @_simforge_pending_spans&.key?(method_name)
+
+        config = @_simforge_pending_spans.delete(method_name)
+        _simforge_wrap_method(method_name, **config)
+      end
+
+      def _simforge_wrap_method(method_name, trace_function_key:, name: nil, type: "custom")
+        span_name = name || method_name.to_s
+        method_name_str = method_name.to_s
+
+        wrapper = Module.new do
+          define_method(method_name) do |*args, **kwargs, &block|
+            Simforge.client.send(:execute_span,
+              trace_function_key:,
+              span_name:,
+              span_type: type,
+              function_name: method_name_str,
+              args:,
+              kwargs:) do
+              super(*args, **kwargs, &block)
+            end
+          end
+        end
+
+        prepend(wrapper)
+      end
+    end
+  end
+end

data/lib/simforge/version.rb

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

data/lib/simforge.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "simforge/version"
+require_relative "simforge/constants"
+require_relative "simforge/serialize"
+require_relative "simforge/span_context"
+require_relative "simforge/http_client"
+require_relative "simforge/client"
+require_relative "simforge/traceable"
+
+module Simforge
+  class << self
+    # Configure the global Simforge client.
+    #
+    # @param api_key [String] API key for authentication
+    # @param service_url [String, nil] base URL (default: https://simforge.goharvest.ai)
+    #
+    # @example
+    #   Simforge.configure(api_key: ENV["SIMFORGE_API_KEY"])
+    #
+    def configure(api_key:, service_url: nil)
+      @client = Client.new(api_key:, service_url:)
+    end
+
+    # Returns the global client, raising if not configured.
+    def client
+      @client or raise "Simforge not configured. Call Simforge.configure(api_key: '...') first."
+    end
+
+    # Reset the global client (primarily for testing).
+    def reset!
+      @client = nil
+    end
+  end
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: simforge
+version: !ruby/object:Gem::Version
+  version: 0.5.0
+platform: ruby
+authors:
+- Harvest Team
+bindir: bin
+cert_chain: []
+date: 2026-01-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !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: Client library for sending function execution spans to the Simforge API.
+  Provides automatic tracing with nested span support.
+email:
+- team@goharvest.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/simforge.rb
+- lib/simforge/client.rb
+- lib/simforge/constants.rb
+- lib/simforge/http_client.rb
+- lib/simforge/serialize.rb
+- lib/simforge/span_context.rb
+- lib/simforge/traceable.rb
+- lib/simforge/version.rb
+homepage: https://simforge.goharvest.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://simforge.goharvest.ai
+  source_code_uri: https://simforge.goharvest.ai
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.6
+specification_version: 4
+summary: Simforge Ruby SDK for function tracing and span management
+test_files: []