smith-agents 0.4.0

data/lib/smith.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require "dry-configurable"
+
+require_relative "smith/version"
+
+module Smith
+  class Error < StandardError; end
+
+  extend Dry::Configurable
+
+  # Artifact store (§4.7)
+  setting :artifact_store
+  setting :artifact_retention
+  setting :artifact_encryption, default: :none
+  setting :artifact_tenant_isolation, default: false
+
+  # Trace adapters (§4.8)
+  setting :trace_adapter
+  setting :trace_transitions, default: true
+  setting :trace_tool_calls, default: true
+  setting :trace_token_usage, default: true
+  setting :trace_cost, default: true
+  setting :trace_fields
+  setting :trace_content, default: false
+  setting :trace_retention
+  setting :trace_tenant_isolation, default: false
+
+  # Pricing (§4.5 — model-call cost computation)
+  setting :pricing, default: nil
+
+  # Persistence adapter for host durability verification (§doctor)
+  setting :persistence_adapter, default: nil
+  setting :persistence_options, default: {}.freeze
+
+  # Persistence TTL in Integer seconds. nil (default) means workflows
+  # persist indefinitely. Adapters that natively support TTL (Redis,
+  # CacheStore, Memory) pass this through; ActiveRecordStore TTL is
+  # deferred (would need an `expires_at` column + sweeper).
+  # Per-workflow `Workflow.persistence_ttl 1.day.to_i` DSL overrides this.
+  setting :persistence_ttl, default: nil
+
+  # Retry policy for transient persistence I/O failures.
+  #   attempts:    total attempts (including the first)
+  #   base_delay:  initial sleep between attempts, doubled each retry
+  #   max_delay:   cap on per-retry sleep
+  setting :persistence_retry_policy, default: { attempts: 3, base_delay: 0.1, max_delay: 1.0 }
+
+  # Test isolation: when true AND persistence_adapter is nil, Smith
+  # auto-selects the in-process Memory adapter. Lets specs avoid wiring
+  # Redis/Rails.cache in spec_helper.rb.
+  setting :test_mode, default: false
+
+  # RubyLLM model registry mode: nil/:bundled (default) or :database (§doctor)
+  setting :ruby_llm_model_registry, default: nil
+
+  # OpenAI API mode controls Smith's vendored /v1/responses routing
+  # for gpt-5 family + tools + reasoning_effort. :auto routes
+  # automatically when the combo is detected; :off disables routing
+  # (Smith's normalizer falls back to dropping incompatible tools).
+  #
+  # Default :auto reflects the "use both when possible" design intent.
+  # Smith ships the Responses adapter vendored from crmne/ruby_llm PR #770
+  # at a pinned SHA, so the routing path is operational for sync
+  # completions. Streaming over /v1/responses is not yet supported and
+  # raises NotImplementedError; hosts who need streaming with the
+  # (gpt-5 + tools + thinking) combo should set openai_api_mode = :off
+  # for graceful tool-dropping via chat-completions.
+  setting :openai_api_mode, default: :auto, constructor: lambda { |value|
+    unless %i[off auto].include?(value)
+      raise ArgumentError, "Smith.config.openai_api_mode must be :off or :auto, got #{value.inspect}"
+    end
+    value
+  }
+
+  # Trace gating for normalizer decision events. Hosts can opt out
+  # of the per-mutation event stream (the normalizer can emit several
+  # events per chat construction if multiple capabilities translate).
+  setting :trace_normalizer, default: true
+
+  # Logger (§7 — Ruby Logger, not Rails.logger)
+  setting :logger, default: nil
+
+  def self.artifacts
+    scoped_artifacts || config.artifact_store || (@_default_artifacts ||= Artifacts::Memory.new)
+  end
+
+  def self.artifacts=(store)
+    config.artifact_store = store
+  end
+
+  def self.scoped_artifacts
+    Thread.current[:smith_scoped_artifacts]
+  end
+
+  def self.scoped_artifacts=(store)
+    Thread.current[:smith_scoped_artifacts] = store
+  end
+
+  def self.persistence_adapter
+    raw_adapter = config.persistence_adapter
+    raw_options = config.persistence_options || {}
+    signature = persistence_signature(raw_adapter, raw_options, config.test_mode)
+
+    if defined?(@_persistence_adapter_signature) && @_persistence_adapter_signature == signature
+      return @_persistence_adapter
+    end
+
+    @_persistence_adapter_signature = signature
+    @_persistence_adapter = resolve_persistence_adapter(raw_adapter, raw_options)
+  end
+
+  # Test isolation auto-detect: when no adapter is configured AND
+  # test_mode is on, fall back to the in-process Memory adapter so spec
+  # suites don't need to wire Redis/Rails.cache in spec_helper.rb.
+  # Explicit adapter config always wins over this auto-detect.
+  def self.resolve_persistence_adapter(raw_adapter, raw_options)
+    return PersistenceAdapters.resolve(raw_adapter, **raw_options) if raw_adapter
+    return PersistenceAdapters::Memory.new if config.test_mode
+
+    nil
+  end
+  private_class_method :resolve_persistence_adapter
+
+  def self.persistence_signature(adapter, options, test_mode)
+    [snapshot_value(adapter), snapshot_value(options), test_mode]
+  end
+  private_class_method :persistence_signature
+
+  def self.snapshot_value(value)
+    case value
+    when Hash
+      value.each_with_object({}) do |(key, nested), copy|
+        copy[snapshot_value(key)] = snapshot_value(nested)
+      end.freeze
+    when Array
+      value.map { |nested| snapshot_value(nested) }.freeze
+    when String
+      value.dup.freeze
+    else
+      value
+    end
+  end
+  private_class_method :snapshot_value
+end
+
+# Leaf modules (no internal dependencies)
+require_relative "smith/types"
+require_relative "smith/errors"
+
+# Event system (depends on Types)
+require_relative "smith/event"
+require_relative "smith/events"
+require_relative "smith/events/subscription"
+require_relative "smith/events/bus"
+require_relative "smith/events/step_completed"
+
+# Budget (depends on Errors)
+require_relative "smith/budget"
+require_relative "smith/budget/ledger"
+
+# Pricing (depends on Smith config)
+require_relative "smith/pricing"
+
+# Model capability registry + pattern-based inference (depends on Errors).
+# Smith ships NO specific model_id declarations. Inference rules describe
+# PROVIDER FAMILIES (Anthropic Opus 4.7+ adaptive, gpt-5 family
+# responses-route, Gemini 2.5+ budget_tokens). Applications register
+# Smith::Models.register(Profile.new(...)) overrides only for custom
+# models. Loaded BEFORE Tool so Tools that declare `compatible_with` can
+# resolve capability semantics, AND before Agent so the chat override
+# can call Smith::Models.find_or_infer on first construction.
+require_relative "smith/models/profile"
+require_relative "smith/models"
+require_relative "smith/models/inference"
+require_relative "smith/models/normalizer"
+
+# OpenAI /v1/responses routing prepend. Dormant until
+# Smith.config.openai_api_mode = :auto (default :off). Full
+# payload assembly (Smith::Providers::OpenAI::Responses) and tool
+# format helpers (Smith::Providers::OpenAI::ToolsExtensions) are
+# vendored from crmne/ruby_llm PR #770 at pinned SHA. They retire when
+# the PR merges upstream (Smith bumps the ruby_llm dep + deletes the
+# vendored files). The require order must keep the helpers (ToolsExtensions)
+# loaded BEFORE Responses since Responses calls into ToolsExtensions,
+# and BOTH must load before Routing since Routing dispatches to
+# Responses.complete via `defined?(...)` guard.
+require_relative "smith/providers/openai/tools_extensions"
+require_relative "smith/providers/openai/responses"
+require_relative "smith/providers/openai/routing"
+
+# Trace adapters (no internal deps)
+require_relative "smith/trace"
+require_relative "smith/trace/memory"
+require_relative "smith/trace/logger"
+require_relative "smith/trace/open_telemetry"
+
+# Artifact store (no internal deps)
+require_relative "smith/artifacts"
+require_relative "smith/artifacts/memory"
+require_relative "smith/artifacts/file"
+require_relative "smith/artifacts/scoped_store"
+
+# Host persistence adapters (no internal deps)
+require_relative "smith/persistence_adapters"
+
+# Tool (depends on RubyLLM::Tool)
+require_relative "smith/tool"
+require_relative "smith/tools"
+require_relative "smith/tools/web_search"
+require_relative "smith/tools/url_fetcher"
+require_relative "smith/tools/think"
+
+# Guardrails and Context (no internal deps)
+require_relative "smith/guardrails"
+require_relative "smith/guardrails/runner"
+require_relative "smith/guardrails/url_verifier"
+require_relative "smith/context"
+require_relative "smith/context/observation_masking"
+require_relative "smith/context/state_injection"
+require_relative "smith/context/session"
+
+# Agent (depends on RubyLLM::Agent)
+require_relative "smith/agent"
+require_relative "smith/agent/lifecycle"
+require_relative "smith/agent/registry"
+
+# Workflow (Transition, DSL, Persistence, and Execution must load before Workflow)
+require_relative "smith/workflow/transition"
+require_relative "smith/workflow/dsl"
+require_relative "smith/workflow/persistence"
+require_relative "smith/workflow/durability"
+require_relative "smith/workflow/guardrail_integration"
+require_relative "smith/workflow/budget_integration"
+require_relative "smith/workflow/event_integration"
+require_relative "smith/workflow/artifact_integration"
+require_relative "smith/workflow/data_volume_policy"
+require_relative "smith/workflow/deadline_enforcement"
+require_relative "smith/workflow/nested_execution"
+require_relative "smith/workflow/evaluator_optimizer"
+require_relative "smith/workflow/orchestrator_worker"
+require_relative "smith/workflow/parallel_execution"
+require_relative "smith/workflow/deterministic_step"
+require_relative "smith/workflow/deterministic_execution"
+require_relative "smith/workflow/execution"
+require_relative "smith/workflow"
+require_relative "smith/workflow/claim"
+require_relative "smith/workflow/execution_frame"
+require_relative "smith/workflow/pipeline"
+require_relative "smith/workflow/router"
+require_relative "smith/workflow/parallel"
+
+# Conditional Rails integration
+require_relative "smith/railtie" if defined?(Rails::Railtie)

data/script/profile_tool_results.rb

@@ -0,0 +1,94 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Usage: bundle exec ruby script/profile_tool_results.rb
+#
+# Profiles tool_results handling at various scales:
+# - snapshot cost (build_run_result deep copy)
+# - JSON persistence round-trip (serialize + restore)
+# - parallel collector contention
+
+require "smith"
+require "json"
+
+def measure
+  start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  yield
+  Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+end
+
+def build_workflow_with_entries(count, payload_size: 100)
+  klass = Class.new(Smith::Workflow) do
+    initial_state :idle
+    state :done
+    transition :finish, from: :idle, to: :done
+  end
+
+  workflow = klass.new
+  payload = { "data" => "x" * payload_size, "urls" => Array.new(5) { "https://example.com/#{_1}" } }
+  count.times { |i| workflow.instance_variable_get(:@tool_results) << { tool: "tool_#{i}", captured: payload.dup } }
+  [klass, workflow]
+end
+
+puts "=" * 70
+puts "Smith tool_results Performance Profile"
+puts "=" * 70
+
+# 1. Snapshot cost
+puts "\n--- Snapshot Cost (build_run_result deep copy) ---"
+[100, 1_000, 5_000].each do |count|
+  _klass, workflow = build_workflow_with_entries(count)
+
+  before_gc = GC.stat[:total_allocated_objects]
+  time = measure { workflow.run! }
+  after_gc = GC.stat[:total_allocated_objects]
+
+  printf "  %5d entries: %.4fs, ~%d allocations\n", count, time, (after_gc - before_gc)
+end
+
+# 2. JSON persistence round-trip
+puts "\n--- JSON Persistence Round-Trip ---"
+json = nil
+[100, 1_000, 5_000].each do |count|
+  klass, workflow = build_workflow_with_entries(count)
+
+  serialize_time = measure { json = JSON.generate(workflow.to_state) }
+  restore_time = measure { klass.from_state(JSON.parse(json)) }
+
+  printf "  %5d entries: serialize=%.4fs restore=%.4fs json_bytes=%d\n",
+         count, serialize_time, restore_time, json.bytesize
+end
+
+# 3. Parallel collector contention
+puts "\n--- Parallel Collector Contention ---"
+[10, 50, 100].each do |branch_count|
+  klass = Class.new(Smith::Workflow) do
+    initial_state :idle
+    state :done
+    transition :finish, from: :idle, to: :done
+  end
+
+  workflow = klass.new
+  collector = workflow.send(:tool_result_collector)
+  threads = []
+
+  time = measure do
+    branch_count.times do |i|
+      threads << Thread.new do
+        5.times do |j|
+          collector.call({ tool: "branch_#{i}_call_#{j}", captured: { index: i, call: j } })
+        end
+      end
+    end
+    threads.each(&:join)
+  end
+
+  total = workflow.instance_variable_get(:@tool_results).length
+  expected = branch_count * 5
+
+  status = total == expected ? "OK" : "LOSS (#{expected - total} missing)"
+  printf "  %3d branches x 5 calls: %.4fs, %d/%d entries [%s]\n",
+         branch_count, time, total, expected, status
+end
+
+puts "\n#{"=" * 70}\nDone."

data/sig/smith.rbs

@@ -0,0 +1,4 @@
+module Smith
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,258 @@
+--- !ruby/object:Gem::Specification
+name: smith-agents
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Samuel Ralak
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: dry-types
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: dry-struct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !ruby/object:Gem::Dependency
+  name: dry-initializer
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: dry-container
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.11'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+description: Smith is a workflow-first multi-agent orchestration library built on
+  RubyLLM. It provides state machine modeling, typed contracts, budget enforcement,
+  guardrails, and observability for agent workflows.
+email:
+- thesamuelralak@gmail.com
+executables:
+- smith
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE
+- README.md
+- Rakefile
+- UPSTREAM_PROPOSAL.md
+- docs/CONFIGURATION.md
+- docs/PATTERNS.md
+- docs/PERSISTENCE.md
+- docs/TOOLS_AND_GUARDRAILS.md
+- docs/workflow_claim.md
+- exe/smith
+- lib/generators/smith/install/install_generator.rb
+- lib/generators/smith/install/templates/smith.rb.tt
+- lib/smith.rb
+- lib/smith/agent.rb
+- lib/smith/agent/lifecycle.rb
+- lib/smith/agent/registry.rb
+- lib/smith/artifacts.rb
+- lib/smith/artifacts/file.rb
+- lib/smith/artifacts/memory.rb
+- lib/smith/artifacts/scoped_store.rb
+- lib/smith/budget.rb
+- lib/smith/budget/ledger.rb
+- lib/smith/cli.rb
+- lib/smith/context.rb
+- lib/smith/context/observation_masking.rb
+- lib/smith/context/session.rb
+- lib/smith/context/state_injection.rb
+- lib/smith/doctor.rb
+- lib/smith/doctor/check.rb
+- lib/smith/doctor/checks/baseline.rb
+- lib/smith/doctor/checks/configuration.rb
+- lib/smith/doctor/checks/durability.rb
+- lib/smith/doctor/checks/live.rb
+- lib/smith/doctor/checks/models_registry.rb
+- lib/smith/doctor/checks/openai_api_mode.rb
+- lib/smith/doctor/checks/persistence.rb
+- lib/smith/doctor/checks/persistence_capabilities.rb
+- lib/smith/doctor/checks/persistence_registry.rb
+- lib/smith/doctor/checks/rails.rb
+- lib/smith/doctor/checks/serialization.rb
+- lib/smith/doctor/installer.rb
+- lib/smith/doctor/printer.rb
+- lib/smith/doctor/report.rb
+- lib/smith/errors.rb
+- lib/smith/event.rb
+- lib/smith/events.rb
+- lib/smith/events/.keep
+- lib/smith/events/bus.rb
+- lib/smith/events/step_completed.rb
+- lib/smith/events/subscription.rb
+- lib/smith/guardrails.rb
+- lib/smith/guardrails/runner.rb
+- lib/smith/guardrails/url_verifier.rb
+- lib/smith/models.rb
+- lib/smith/models/inference.rb
+- lib/smith/models/normalizer.rb
+- lib/smith/models/profile.rb
+- lib/smith/persistence_adapters.rb
+- lib/smith/persistence_adapters/active_record_store.rb
+- lib/smith/persistence_adapters/cache_store.rb
+- lib/smith/persistence_adapters/memory.rb
+- lib/smith/persistence_adapters/rails_cache.rb
+- lib/smith/persistence_adapters/redis_store.rb
+- lib/smith/persistence_adapters/retry.rb
+- lib/smith/pricing.rb
+- lib/smith/providers/openai/responses.rb
+- lib/smith/providers/openai/routing.rb
+- lib/smith/providers/openai/tools_extensions.rb
+- lib/smith/railtie.rb
+- lib/smith/tasks/doctor.rake
+- lib/smith/tool.rb
+- lib/smith/tool/budget_enforcement.rb
+- lib/smith/tool/capability_builder.rb
+- lib/smith/tool/capture.rb
+- lib/smith/tool/compatibility.rb
+- lib/smith/tool/policy.rb
+- lib/smith/tools.rb
+- lib/smith/tools/think.rb
+- lib/smith/tools/url_fetcher.rb
+- lib/smith/tools/web_search.rb
+- lib/smith/trace.rb
+- lib/smith/trace/logger.rb
+- lib/smith/trace/memory.rb
+- lib/smith/trace/open_telemetry.rb
+- lib/smith/types.rb
+- lib/smith/version.rb
+- lib/smith/workflow.rb
+- lib/smith/workflow/artifact_integration.rb
+- lib/smith/workflow/budget_integration.rb
+- lib/smith/workflow/claim.rb
+- lib/smith/workflow/data_volume_policy.rb
+- lib/smith/workflow/deadline_enforcement.rb
+- lib/smith/workflow/deterministic_execution.rb
+- lib/smith/workflow/deterministic_step.rb
+- lib/smith/workflow/dsl.rb
+- lib/smith/workflow/durability.rb
+- lib/smith/workflow/evaluator_optimizer.rb
+- lib/smith/workflow/event_integration.rb
+- lib/smith/workflow/execution.rb
+- lib/smith/workflow/execution_frame.rb
+- lib/smith/workflow/guardrail_integration.rb
+- lib/smith/workflow/nested_execution.rb
+- lib/smith/workflow/orchestrator_worker.rb
+- lib/smith/workflow/parallel.rb
+- lib/smith/workflow/parallel_execution.rb
+- lib/smith/workflow/persistence.rb
+- lib/smith/workflow/pipeline.rb
+- lib/smith/workflow/router.rb
+- lib/smith/workflow/transition.rb
+- script/profile_tool_results.rb
+- sig/smith.rbs
+homepage: https://github.com/samuelralak/smith
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/samuelralak/smith
+  changelog_uri: https://github.com/samuelralak/smith/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/samuelralak/smith/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Workflow-first multi-agent orchestration for Ruby
+test_files: []