simforge 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 662f1ce8942083e856907a38568a40b252c4d6360f043fc25da58900a46e36e7
-  data.tar.gz: 9d74cf518171472d22b49c6b8fb3544e258607e5284acebe0f6b46e71213e0cd
+  metadata.gz: b9f2c1b27222c1a19c1ee819c021349f8f7cd479432e38a8b8ed5d218b13b026
+  data.tar.gz: '059c030ed76519b30a5fd187392af8af0d29ba6a0704132359792ef4381fed9c'
 SHA512:
-  metadata.gz: 556e17aa0f010ecb394f7a5937c3c02a43ef0d76bffe00082899074a19f26c555bec5c4d47dfe1afa98c34f7093beae5dd4b4a4d2d9d00a68d0155aadd979aea
-  data.tar.gz: 14cd3fbc8c4ea4096036ce312e6eac67ab7b57a634c10faba0962fa3dd10368928ebc3c25c1236b5ff6019a8db36094b0a4e4a8eeb737da2c76fc42e5525cd62
+  metadata.gz: 7057e4d20182d99a6c71b0a5fe4f52f7d661230a111967a805421f5459463371ecc8849a7bbfcb7f313e16a3bf9623b50002393eeed91ef7e311cbfe43fd6e3a
+  data.tar.gz: a76648e123b02fc6a00124910c42624c9da7819df4b8437d8fb1b8aed64498d72871749da56e20a8ba94bc86d2ba0dd013da70ca843900138e33b65ac5e00e12

data/README.md

@@ -0,0 +1,342 @@
+# Simforge Ruby SDK
+
+Ruby client library for [Simforge](https://simforge.goharvest.ai) - trace and monitor your Ruby application's function execution with nested span support.
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'simforge'
+```
+
+Or install directly:
+
+```bash
+gem install simforge
+```
+
+## Requirements
+
+- Ruby >= 3.1
+- No external runtime dependencies (uses stdlib only)
+
+## Quick Start
+
+```ruby
+require 'simforge'
+
+# Configure once at application startup
+Simforge.configure(
+  api_key: ENV.fetch('SIMFORGE_API_KEY')
+)
+
+# Add tracing to your classes
+class OrderService
+  include Simforge::Traceable
+  simforge_function "order-processing"
+
+  simforge_span :process_order, type: "function"
+  def process_order(order_id)
+    # Your code here
+    { status: "completed" }
+  end
+end
+
+# Use your code normally - spans are sent automatically
+service = OrderService.new
+service.process_order("order-123")
+
+# Flush traces before exit (automatic via at_exit hook)
+Simforge.flush_traces
+```
+
+## Configuration
+
+### Basic Configuration
+
+```ruby
+Simforge.configure(
+  api_key: "your-api-key"
+)
+```
+
+### Custom Service URL
+
+```ruby
+Simforge.configure(
+  api_key: "your-api-key",
+  service_url: "https://custom.example.com"
+)
+```
+
+### Disabling Span Sending
+
+The `enabled` option controls whether spans are sent to Simforge. When disabled, your code executes normally but no spans are created or sent.
+
+```ruby
+# Disable tracing (useful for development/test environments)
+Simforge.configure(
+  api_key: ENV.fetch('SIMFORGE_API_KEY', 'dummy-key'),
+  enabled: false
+)
+```
+
+**Common patterns:**
+
+```ruby
+# Rails: Enable only in production
+Simforge.configure(
+  api_key: ENV.fetch('SIMFORGE_API_KEY', 'dummy-key'),
+  enabled: Rails.env.production?
+)
+
+# Environment variable control
+Simforge.configure(
+  api_key: ENV.fetch('SIMFORGE_API_KEY', 'dummy-key'),
+  enabled: ENV.fetch('SIMFORGE_ENABLED', 'false') == 'true'
+)
+
+# Multi-environment control
+Simforge.configure(
+  api_key: ENV.fetch('SIMFORGE_API_KEY', 'dummy-key'),
+  enabled: ['production', 'staging'].include?(ENV['RACK_ENV'])
+)
+```
+
+When `enabled: false`:
+- ✅ Code executes normally with no performance impact
+- ✅ Return values and errors work as expected
+- ✅ Nested spans are properly skipped
+- ❌ No HTTP requests are made
+- ❌ No span data is collected or sent
+
+## Usage
+
+### Class-Level Trace Function Key
+
+All spans in the class share the same trace function key:
+
+```ruby
+class PaymentService
+  include Simforge::Traceable
+  simforge_function "payment-processing"
+
+  simforge_span :charge_card, type: "function"
+  def charge_card(amount)
+    # Traced automatically
+  end
+
+  simforge_span :refund, type: "function"
+  def refund(transaction_id)
+    # Also uses "payment-processing" key
+  end
+end
+```
+
+### Per-Span Trace Function Key
+
+Each span can declare its own key:
+
+```ruby
+class NotificationService
+  include Simforge::Traceable
+
+  simforge_span :send_email, trace_function_key: "email-notifications", type: "function"
+  def send_email(to, subject)
+    # Uses "email-notifications" key
+  end
+
+  simforge_span :send_sms, trace_function_key: "sms-notifications", type: "function"
+  def send_sms(to, message)
+    # Uses "sms-notifications" key
+  end
+end
+```
+
+### Span Types
+
+Simforge supports the following span types:
+
+- `"llm"` - LLM API calls
+- `"agent"` - Agent decision loops
+- `"function"` - Business logic functions
+- `"guardrail"` - Validation and safety checks
+- `"handoff"` - Human-in-the-loop interactions
+- `"custom"` - Custom span types (default)
+
+```ruby
+simforge_span :validate_input, type: "guardrail"
+simforge_span :call_openai, type: "llm"
+simforge_span :agent_loop, type: "agent"
+```
+
+### Custom Span Names
+
+By default, the method name is used as the span name. Override it:
+
+```ruby
+simforge_span :process_order, name: "ProcessOrderV2", type: "function"
+def process_order(order_id)
+  # Span will be named "ProcessOrderV2"
+end
+```
+
+### Nested Spans
+
+Spans automatically track parent-child relationships:
+
+```ruby
+class OrderPipeline
+  include Simforge::Traceable
+  simforge_function "order-pipeline"
+
+  simforge_span :process, type: "function"
+  def process(order_id)
+    validate(order_id)
+    # More processing
+  end
+
+  simforge_span :validate, type: "guardrail"
+  def validate(order_id)
+    check_fraud(order_id)
+    # More validation
+  end
+
+  simforge_span :check_fraud, type: "guardrail"
+  def check_fraud(order_id)
+    # Fraud checking logic
+  end
+end
+
+# Creates 3 nested spans:
+# process (parent)
+#   └─ validate (child)
+#       └─ check_fraud (grandchild)
+```
+
+### Input/Output Capture
+
+Positional and keyword arguments are automatically captured:
+
+```ruby
+simforge_span :process_order, type: "function"
+def process_order(order_id, priority: :normal)
+  # Input captured: { "order_id" => "123", "priority" => "normal" }
+  { status: "completed" }
+  # Output captured: { "status" => "completed" }
+end
+```
+
+### Metadata
+
+Add custom metadata to spans:
+
+```ruby
+# Definition-time metadata
+simforge_span :process_order,
+  type: "function",
+  metadata: { "region" => "us-east", "version" => "v2" }
+def process_order(order_id)
+  # ...
+end
+
+# Runtime metadata (inside a span)
+simforge_span :process_order, type: "function"
+def process_order(order_id)
+  Simforge.current_span.set_metadata(
+    "user_id" => current_user.id,
+    "request_id" => request.id
+  )
+  # Runtime metadata merges with definition-time metadata
+end
+```
+
+### Wrapping External Code
+
+Wrap third-party library methods without modifying them:
+
+```ruby
+class ExternalHttpClient
+  def get(url)
+    # Third-party code
+  end
+end
+
+# Add tracing via wrap
+Simforge::Traceable.wrap(
+  ExternalHttpClient,
+  :get,
+  trace_function_key: "http-client",
+  type: "function"
+)
+
+# Now traced automatically
+client = ExternalHttpClient.new
+client.get("https://api.example.com")
+```
+
+### Error Handling
+
+Errors are automatically captured and re-raised:
+
+```ruby
+simforge_span :risky_operation, type: "function"
+def risky_operation
+  raise StandardError, "Something went wrong"
+end
+
+begin
+  service.risky_operation
+rescue StandardError => e
+  # Error is captured in span and re-raised
+  puts "Caught: #{e.message}"
+end
+```
+
+## Lifecycle
+
+### Automatic Flush
+
+Spans are sent in background threads and automatically flushed on exit via `at_exit` hook.
+
+### Manual Flush
+
+Wait for all pending spans to be sent:
+
+```ruby
+Simforge.flush_traces
+# Blocks until all background threads complete
+```
+
+### Reset Client
+
+Clear the global client (useful for testing):
+
+```ruby
+Simforge.reset!
+```
+
+## Thread Safety
+
+- Each thread has its own span context stack (using `Thread.current`)
+- Nested spans only work within the same thread
+- Background span sending is thread-safe
+
+## Examples
+
+See [simforge-ruby-example/](../simforge-ruby-example/) for complete working examples:
+
+- [test_span.rb](../simforge-ruby-example/scripts/test_span.rb) - Basic span creation
+- [test_nested_spans.rb](../simforge-ruby-example/scripts/test_nested_spans.rb) - Nested span hierarchies
+- [test_wrap.rb](../simforge-ruby-example/scripts/test_wrap.rb) - Wrapping external code
+- [test_enabled.rb](../simforge-ruby-example/scripts/test_enabled.rb) - Using the enabled flag
+- [test_metadata.rb](../simforge-ruby-example/scripts/test_metadata.rb) - Custom metadata
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup, testing, and publishing instructions.
+
+## License
+
+MIT

data/lib/simforge/client.rb

@@ -12,18 +12,23 @@ module Simforge
   class Client
     SPAN_TYPES = %w[llm agent function guardrail handoff custom].freeze
 
-    attr_reader :api_key, :service_url
+    attr_reader :api_key, :service_url, :enabled
 
-    def initialize(api_key:, service_url: nil)
+    def initialize(api_key:, service_url: nil, enabled: true)
       @api_key = api_key
       @service_url = service_url || DEFAULT_SERVICE_URL
+      @enabled = enabled
+      if @enabled && (@api_key.nil? || @api_key.to_s.strip.empty?)
+        warn "Simforge: api_key is empty — tracing is disabled. Provide a valid API key to enable tracing."
+        @enabled = false
+      end
       @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)
+    def execute_span(trace_function_key:, span_name:, span_type:, function_name:, args:, kwargs:, metadata: nil)
+      return yield unless @enabled
 
       parent = SpanContext.current
       trace_id = parent ? parent[:trace_id] : SecureRandom.uuid
@@ -33,30 +38,51 @@ module Simforge
 
       result = nil
       error = nil
+      runtime_metadata = nil
 
       begin
-        result = SpanContext.with_span(trace_id:, span_id:) { yield }
+        SpanContext.with_span(trace_id:, span_id:) do
+          result = yield
+        ensure
+          # Capture runtime metadata before the span context is popped
+          runtime_metadata = SpanContext.current&.dig(:metadata)
+        end
       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:
-        )
+        # Never crash the host app due to span building/sending
+        begin
+          ended_at = Time.now.utc.strftime("%Y-%m-%dT%H:%M:%S.%3NZ")
+
+          # Merge runtime metadata with definition-time metadata (runtime wins)
+          merged_metadata = if runtime_metadata
+            (metadata || {}).merge(runtime_metadata)
+          else
+            metadata
+          end
+
+          send_span(
+            trace_function_key:,
+            trace_id:,
+            span_id:,
+            parent_span_id:,
+            span_name:,
+            span_type:,
+            function_name:,
+            metadata: merged_metadata,
+            args:,
+            kwargs:,
+            result:,
+            error:,
+            started_at:,
+            ended_at:
+          )
+        rescue Exception # rubocop:disable Lint/RescueException
+          # Silently ignore — user's result/exception takes priority
+          # Catches Exception (not just StandardError) to handle SystemStackError
+          # from deeply nested serialization
+        end
       end
 
       result
@@ -71,7 +97,7 @@ module Simforge
     end
 
     def send_span(trace_function_key:, trace_id:, span_id:, parent_span_id:,
-      span_name:, span_type:, function_name:, args:, kwargs:, result:, error:,
+      span_name:, span_type:, function_name:, metadata:, args:, kwargs:, result:, error:,
       started_at:, ended_at:)
       # Human-readable JSON (input/output fields)
       human_inputs = Serialize.serialize_inputs(args, kwargs)
@@ -92,6 +118,7 @@ module Simforge
       span_data["input_serialized"] = marshalled_input if marshalled_input
       span_data["output_serialized"] = marshalled_output if marshalled_output
       span_data["error"] = error if error
+      span_data["metadata"] = metadata if metadata
 
       raw_span = {
         "id" => span_id,

data/lib/simforge/span_context.rb

@@ -1,6 +1,22 @@
 # frozen_string_literal: true
 
 module Simforge
+  # Handle to the current active span, allowing runtime metadata to be set.
+  class CurrentSpan
+    def initialize(context)
+      @context = context
+    end
+
+    # Set custom metadata on this span. Merges with any existing metadata
+    # (both definition-time and previous runtime calls), with later values
+    # taking precedence on conflict.
+    def set_metadata(metadata)
+      return unless metadata.is_a?(Hash)
+
+      @context[:metadata] = (@context[:metadata] || {}).merge(metadata)
+    end
+  end
+
   # Thread-local span stack for tracking nested spans.
   # Each entry is a Hash with :trace_id and :span_id keys.
   module SpanContext

data/lib/simforge/traceable.rb

@@ -26,6 +26,41 @@ module Simforge
       base.extend(ClassMethods)
     end
 
+    # Wrap an existing method on an external class with span tracing.
+    # Use this to trace third-party library calls without modifying their source.
+    #
+    # @example
+    #   Simforge::Traceable.wrap(OpenAI::Client, :chat,
+    #     trace_function_key: "openai", name: "Chat", type: "llm")
+    #
+    # @param klass [Class, Module] the class to wrap
+    # @param method_name [Symbol] the method to wrap
+    # @param trace_function_key [String] the trace function key
+    # @param name [String, nil] explicit span name (defaults to method name)
+    # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+    def self.wrap(klass, method_name, trace_function_key:, name: nil, type: "custom", metadata: nil)
+      span_name = name || method_name.to_s
+      method_name_str = method_name.to_s
+      span_metadata = metadata
+
+      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,
+            metadata: span_metadata,
+            args:,
+            kwargs:) do
+            super(*args, **kwargs, &block)
+          end
+        end
+      end
+
+      klass.prepend(wrapper)
+    end
+
     module ClassMethods
       # Set the trace function key for this class.
       # All spans declared in this class will be grouped under this key.
@@ -52,7 +87,7 @@ module Simforge
       # @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")
+      def simforge_span(method_name, trace_function_key: nil, name: nil, type: "custom", metadata: nil)
         trace_function_key ||= @simforge_function_key
         unless trace_function_key
           raise "No trace function key provided. Pass `trace_function_key:` to `simforge_span` " \
@@ -61,14 +96,15 @@ module Simforge
 
         # 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:)
+          _simforge_wrap_method(method_name, trace_function_key:, name:, type:, metadata:)
         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:
+            type:,
+            metadata:
           }
         end
       end
@@ -83,9 +119,10 @@ module Simforge
         _simforge_wrap_method(method_name, **config)
       end
 
-      def _simforge_wrap_method(method_name, trace_function_key:, name: nil, type: "custom")
+      def _simforge_wrap_method(method_name, trace_function_key:, name: nil, type: "custom", metadata: nil)
         span_name = name || method_name.to_s
         method_name_str = method_name.to_s
+        span_metadata = metadata
 
         wrapper = Module.new do
           define_method(method_name) do |*args, **kwargs, &block|
@@ -94,6 +131,7 @@ module Simforge
               span_name:,
               span_type: type,
               function_name: method_name_str,
+              metadata: span_metadata,
               args:,
               kwargs:) do
               super(*args, **kwargs, &block)

data/lib/simforge/version.rb

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

data/lib/simforge.rb

@@ -18,8 +18,8 @@ module Simforge
     # @example
     #   Simforge.configure(api_key: ENV["SIMFORGE_API_KEY"])
     #
-    def configure(api_key:, service_url: nil)
-      @client = Client.new(api_key:, service_url:)
+    def configure(api_key:, service_url: nil, enabled: true)
+      @client = Client.new(api_key:, service_url:, enabled:)
     end
 
     # Returns the global client, raising if not configured.
@@ -31,5 +31,18 @@ module Simforge
     def reset!
       @client = nil
     end
+
+    # Get a handle to the current active span.
+    #
+    # Call this from inside a traced method to get a span handle that allows
+    # setting metadata at runtime.
+    #
+    # @return [CurrentSpan, nil] the current span, or nil if outside a span context
+    def current_span
+      entry = SpanContext.current
+      return nil unless entry
+
+      CurrentSpan.new(entry)
+    end
   end
 end

metadata

@@ -1,13 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simforge
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Harvest Team
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-29 00:00:00.000000000 Z
+date: 2026-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -29,40 +30,68 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.13'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  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: rubocop-standard
+  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.
@@ -73,6 +102,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - lib/simforge.rb
 - lib/simforge/client.rb
 - lib/simforge/constants.rb
@@ -88,6 +118,7 @@ metadata:
   homepage_uri: https://simforge.goharvest.ai
   source_code_uri: https://simforge.goharvest.ai
   rubygems_mfa_required: 'true'
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -102,7 +133,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.6
+rubygems_version: 3.3.26
+signing_key:
 specification_version: 4
 summary: Simforge Ruby SDK for function tracing and span management
 test_files: []