bitfab 0.9.0

data/lib/bitfab/traceable.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Bitfab
+  # Mixin for declarative span tracing on instance methods.
+  #
+  # @example
+  #   Bitfab.configure(api_key: "...")
+  #
+  #   class OrderService
+  #     include Bitfab::Traceable
+  #     bitfab_function "order-processing"
+  #
+  #     bitfab_span :process_order, type: "function"
+  #     def process_order(order_id)
+  #       { total: 100 }
+  #     end
+  #
+  #     bitfab_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
+
+    # Wrap an existing method on an external class with span tracing.
+    # Use this to trace third-party library calls without modifying their source.
+    #
+    # @example
+    #   Bitfab::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")
+      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|
+          Bitfab.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
+
+      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.
+      #
+      # @param key [String] the trace function key
+      def bitfab_function(key)
+        @bitfab_function_key = key
+      end
+
+      # Declare that a method should be wrapped with span tracing.
+      #
+      # Supports three styles:
+      #   bitfab_span :foo, type: "function"   # before def foo (uses method_added hook)
+      #   def foo; end
+      #
+      #   bitfab_span def foo                   # inline (def returns :foo, method already exists)
+      #     ...
+      #   end, type: "function"
+      #
+      #   def foo; end                            # after def foo (method already exists)
+      #   bitfab_span :foo, type: "function"
+      #
+      # @param method_name [Symbol] the method to wrap
+      # @param trace_function_key [String, nil] trace function key (overrides class-level bitfab_function)
+      # @param name [String, nil] explicit span name (defaults to method name)
+      # @param type [String] span type: llm, agent, function, guardrail, handoff, custom
+      def bitfab_span(method_name, trace_function_key: nil, name: nil, type: "custom")
+        trace_function_key ||= @bitfab_function_key
+        unless trace_function_key
+          raise "No trace function key provided. Pass `trace_function_key:` to `bitfab_span` " \
+                "or call `bitfab_function 'my-key'` before using `bitfab_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)
+          _bitfab_wrap_method(method_name, trace_function_key:, name:, type:)
+        else
+          # Method doesn't exist yet (before-method style) — register for method_added hook
+          @_bitfab_pending_spans ||= {}
+          @_bitfab_pending_spans[method_name] = {
+            trace_function_key:,
+            name:,
+            type:
+          }
+        end
+      end
+
+      private
+
+      def method_added(method_name)
+        super
+        return unless defined?(@_bitfab_pending_spans) && @_bitfab_pending_spans&.key?(method_name)
+
+        config = @_bitfab_pending_spans.delete(method_name)
+        _bitfab_wrap_method(method_name, **config)
+      end
+
+      def _bitfab_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|
+            Bitfab.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/bitfab/version.rb

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

data/lib/bitfab.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require_relative "bitfab/version"
+require_relative "bitfab/constants"
+require_relative "bitfab/serialize"
+require_relative "bitfab/span_context"
+require_relative "bitfab/http_client"
+require_relative "bitfab/replay"
+require_relative "bitfab/client"
+require_relative "bitfab/traceable"
+
+module Bitfab
+  # No-op span handle returned when outside a span context.
+  # All methods do nothing, preventing crashes when called outside traced code.
+  class NoOpCurrentSpan
+    def trace_id
+      ""
+    end
+
+    def add_context(_context)
+      # No-op
+    end
+
+    def set_prompt(_prompt)
+      # No-op
+    end
+  end
+
+  # No-op trace handle returned when outside a span context.
+  # All methods do nothing, preventing crashes when called outside traced code.
+  class NoOpCurrentTrace
+    def set_session_id(_session_id)
+      # No-op
+    end
+
+    def set_metadata(_metadata)
+      # No-op
+    end
+
+    def add_context(_context)
+      # No-op
+    end
+  end
+
+  NO_OP_SPAN = NoOpCurrentSpan.new.freeze
+  NO_OP_TRACE = NoOpCurrentTrace.new.freeze
+
+  class << self
+    # Configure the global Bitfab client.
+    #
+    # @param api_key [String] API key for authentication
+    # @param service_url [String, nil] base URL (default: https://bitfab.ai)
+    #
+    # @example
+    #   Bitfab.configure(api_key: ENV["BITFAB_API_KEY"])
+    #
+    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.
+    def client
+      @client or raise "Bitfab not configured. Call Bitfab.configure(api_key: '...') first."
+    end
+
+    # Reset the global client (primarily for testing).
+    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, NoOpCurrentSpan] the current span, or a no-op if outside a span context
+    def current_span
+      entry = SpanContext.current
+      return NO_OP_SPAN unless entry
+
+      CurrentSpan.new(entry)
+    end
+
+    # Get a handle to the current active trace.
+    #
+    # Call this from inside a traced method to get a trace handle that allows
+    # setting trace-level context at runtime.
+    #
+    # @return [CurrentTrace, NoOpCurrentTrace] the current trace, or a no-op if outside a span context
+    def current_trace
+      entry = SpanContext.current
+      return NO_OP_TRACE unless entry
+
+      CurrentTrace.new(entry[:trace_id])
+    end
+  end
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: bitfab
+version: !ruby/object:Gem::Version
+  version: 0.9.0
+platform: ruby
+authors:
+- Harvest Team
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !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.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 Bitfab API.
+  Provides automatic tracing with nested span support.
+email:
+- team@goharvest.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/bitfab.rb
+- lib/bitfab/client.rb
+- lib/bitfab/constants.rb
+- lib/bitfab/http_client.rb
+- lib/bitfab/replay.rb
+- lib/bitfab/serialize.rb
+- lib/bitfab/span_context.rb
+- lib/bitfab/traceable.rb
+- lib/bitfab/version.rb
+homepage: https://bitfab.ai
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://bitfab.ai
+  source_code_uri: https://bitfab.ai
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Bitfab Ruby SDK for function tracing and span management
+test_files: []