smith-agents 0.4.0

data/UPSTREAM_PROPOSAL.md

@@ -0,0 +1,141 @@
+# Upstream proposal: Capability profiles + before_complete hook for RubyLLM
+
+## Motivation
+
+Smith (a workflow-first multi-agent orchestration library built on RubyLLM) currently maintains a "shadow registry" of model capabilities — pattern-based provider rules describing how each provider shapes its API payload (Anthropic Opus 4.7+ uses adaptive thinking; OpenAI gpt-5 family needs `/v1/responses` for tools+thinking; Gemini 2.5+ accepts `thinking_budget`; etc.). When the underlying RubyLLM client doesn't know these distinctions, Smith's normalizer rewrites the chat object's `@temperature`, `@thinking`, and `@params` ivars before the request leaves.
+
+This works but requires Smith to:
+
+1. Maintain a parallel capability registry (`Smith::Models::Inference`)
+2. Mutate RubyLLM-owned chat ivars directly (`@temperature`, `@thinking`) because RubyLLM 1.15 has no `Chat#without_thinking` / `#without_temperature` public API
+3. Vendor PR #770's `/v1/responses` adapter ahead of upstream merge so gpt-5 family can use tools + reasoning_effort together
+
+A cleaner design lives upstream in RubyLLM. This proposal describes three additive changes that would let Smith retire ~400 lines of vendored code and ~6 monkey-patches.
+
+## Proposed RubyLLM API
+
+### 1. `RubyLLM::Chat#without_thinking` and `#without_temperature`
+
+Smith currently does `chat.instance_variable_set(:@thinking, nil)` and `chat.instance_variable_set(:@temperature, nil)` because there's no public way to clear these. `with_thinking` requires at least one of `effort:` or `budget:`. Add the no-arg clearers:
+
+```ruby
+module RubyLLM
+  class Chat
+    def without_thinking
+      @thinking = nil
+      self
+    end
+
+    def without_temperature
+      @temperature = nil
+      self
+    end
+  end
+end
+```
+
+Small additive change. Smith retires its only remaining `instance_variable_set` calls.
+
+### 2. `RubyLLM::Capabilities::Profile` + `Model::Info#capabilities`
+
+Add a structured capability profile to model info:
+
+```ruby
+module RubyLLM
+  module Capabilities
+    Profile = Data.define(
+      :thinking_shape,            # :budget_tokens | :reasoning_effort | :adaptive | nil
+      :accepts_temperature,
+      :tools_with_thinking_native,
+      :tools_with_thinking_route  # :responses | nil for OpenAI
+    )
+
+    # Public registration API. Idempotent.
+    def self.register(model_id, profile)
+      registry[model_id.to_s] = profile
+    end
+
+    def self.find(model_id)
+      registry[model_id.to_s]
+    end
+
+    def self.registry
+      @registry ||= {}
+    end
+  end
+
+  class Model::Info
+    attr_reader :capabilities  # RubyLLM::Capabilities::Profile?
+  end
+end
+```
+
+RubyLLM's `models.json` could ship default capability profiles for the models it bundles. Smith would migrate its `Smith::Models::Inference` defaults upstream as a `Capabilities.default_rules` table.
+
+### 3. `RubyLLM::Provider.before_complete` hook
+
+Add an extension point for per-request shaping:
+
+```ruby
+module RubyLLM
+  class Provider
+    # Hosts register normalizers that run AFTER chat construction but
+    # BEFORE render_payload. The hook receives the chat and the
+    # capabilities profile of the resolved model.
+    def self.before_complete(&block)
+      normalizers << block
+    end
+
+    def self.normalizers
+      @normalizers ||= []
+    end
+
+    # Existing complete(...) signature unchanged. Internally invokes
+    # the registered normalizers before render_payload.
+  end
+end
+```
+
+## What Smith looks like after upstream lands
+
+```ruby
+# lib/smith.rb (post-upstream)
+# Register Smith's library-shipped pattern rules into RubyLLM's catalog
+Smith::Models::Inference.rules.each do |rule|
+  RubyLLM::Capabilities.register_rule(
+    provider: rule.provider,
+    matcher:  rule.matcher,
+    profile:  rule.to_profile("anyone").to_h.except(:model_id)
+  )
+end
+
+# Register Smith's normalizer as a public RubyLLM hook
+RubyLLM::Provider.before_complete do |chat, profile|
+  Smith::Models::Normalizer.apply!(chat, profile: profile) if profile
+end
+```
+
+Smith's `Models` registry, the `Smith::Agent.chat()` override, and the `lib/smith/providers/openai/routing.rb` vendor patch all retire. What remains in Smith: the capability defaults table and the normalizer's translation logic — still Smith-owned (orchestration concerns), just consumed through a public RubyLLM hook.
+
+## Retirement checklist
+
+Once the upstream API ships and Smith adopts it, the following files retire:
+
+- `lib/smith/models.rb` — becomes a thin wrapper around `RubyLLM::Capabilities`
+- `lib/smith/models/profile.rb` — replaced by `RubyLLM::Capabilities::Profile`
+- `lib/smith/agent.rb#chat` override — replaced by `RubyLLM::Provider.before_complete` hook
+- `lib/smith/providers/openai/routing.rb` — replaced when PR #770 merges (independent track)
+- `lib/smith/providers/openai/responses.rb` — same
+- `lib/smith/providers/openai/tools_extensions.rb` — same
+
+What stays Smith-owned (orchestration concerns, not provider-API concerns):
+
+- `lib/smith/models/inference.rb` — pattern rules table; registers itself into RubyLLM via `Capabilities.register_rule`
+- `lib/smith/models/normalizer.rb` — translation logic; registered via `Provider.before_complete`
+- `lib/smith/tool/compatibility.rb` — tool-side compatibility checks
+- The agent / workflow / tool DSLs
+
+## Tracking
+
+- RubyLLM PR #770 (OpenAI `/v1/responses` support) is the related upstream track. Smith's vendored `Smith::Providers::OpenAI::Responses` retires when #770 merges.
+- This proposal (capability profiles + before_complete) is a separate, additive RubyLLM RFC. Once accepted, Smith files a migration PR to consume it.

data/docs/CONFIGURATION.md

@@ -0,0 +1,123 @@
+# Configuration
+
+There are three different configuration scopes.
+
+### 1. Global runtime configuration: `Smith.configure`
+
+Use this for shared runtime services:
+
+- artifact backend
+- tracing
+- pricing catalog
+- logger
+
+### 2. Agent configuration: `Smith::Agent`
+
+Use agent classes for invocation behavior:
+
+- `model`
+- `tools`
+- `instructions`
+- `temperature`
+- `thinking`
+- `budget`
+- `guardrails`
+- `output_schema`
+- `data_volume`
+- `fallback_models`
+- `register_as`
+
+### 3. Workflow configuration: `Smith::Workflow`
+
+Use workflow classes for orchestration behavior:
+
+- `initial_state`
+- `state`
+- `transition`
+- `pipeline`
+- `budget`
+- `max_transitions`
+- `guardrails`
+- `context_manager`
+
+### If You Are Unsure Where Something Goes
+
+- "Which model should this agent use?" -> agent class
+- "How do I store artifacts or emit traces?" -> `Smith.configure`
+- "What happens after this step succeeds or fails?" -> workflow class
+- "How many tokens/cost/tool calls can this one invocation use?" -> agent budget
+- "How much total budget can the whole workflow consume?" -> workflow budget
+- "Which provider credentials should the app use?" -> RubyLLM, not Smith
+
+### Full `Smith.configure` Example
+
+```ruby
+Smith.configure do |config|
+  config.artifact_store = Smith::Artifacts::Memory.new
+  config.artifact_retention = 3600
+  config.artifact_encryption = :none
+  config.artifact_tenant_isolation = false
+
+  config.trace_adapter = Smith::Trace::Logger
+  config.trace_transitions = true
+  config.trace_tool_calls = true
+  config.trace_token_usage = true
+  config.trace_cost = true
+  config.trace_fields = {
+    transition: %i[transition from to],
+    tool_call: %i[tool duration]
+  }
+  config.trace_content = false
+  config.trace_retention = 86_400
+  config.trace_tenant_isolation = false
+
+  config.pricing = {
+    "gpt-4.1-nano" => {
+      input_cost_per_token: 0.0000001,
+      output_cost_per_token: 0.0000004
+    }
+  }
+
+  config.logger = Logger.new($stdout)
+end
+```
+
+### What Each `Smith.configure` Setting Is For
+
+| Setting | What it controls | Typical first use |
+| --- | --- | --- |
+| `artifact_store` | Where large handoff payloads are stored | Start with `Smith::Artifacts::Memory.new` |
+| `artifact_retention` | Default retention window for artifact expiry checks | Set once you have a cleanup policy |
+| `artifact_encryption` | Metadata-level encryption policy flag | Leave at default until you wire a real backend |
+| `artifact_tenant_isolation` | Require namespaced artifact writes | Enable in multi-tenant systems |
+| `trace_adapter` | Where structural traces go | Use `Smith::Trace::Memory` or `Smith::Trace::Logger` first |
+| `trace_transitions` | Emit transition traces | Usually leave on |
+| `trace_tool_calls` | Emit tool call traces | Usually leave on |
+| `trace_token_usage` | Emit usage traces | Useful for budget visibility |
+| `trace_cost` | Emit cost traces | Useful once pricing is configured |
+| `trace_fields` | Allowlist structural trace fields | Use when you want tighter trace output |
+| `trace_content` | Whether content appears in traces | Leave `false` first |
+| `trace_retention` | Trace retention policy hook | Useful when traces leave memory |
+| `trace_tenant_isolation` | Trace multi-tenant isolation flag | Enable in multi-tenant systems |
+| `pricing` | Best-known model-call cost catalog | Add once you care about `total_cost` |
+| `logger` | Smith's runtime logger | Usually the first setting to add |
+| `persistence_adapter` | Adapter for durable workflow state | `:redis`, `:rails_cache`, `:active_record`, `:memory`, or a custom object |
+| `persistence_options` | Per-adapter options (client, namespace, model, columns) | See "Built-In Persistence Adapters" |
+| `persistence_ttl` | Global TTL for persisted state (Integer/Float seconds; nil = no expiry) | Set when long-tail abandoned workflows accumulate in storage |
+| `persistence_retry_policy` | Exponential-backoff policy for transient adapter I/O failures | Defaults to `{ attempts: 3, base_delay: 0.1, max_delay: 1.0 }` |
+| `test_mode` | Auto-select `:memory` adapter when `persistence_adapter` is nil | Enable in `spec_helper.rb` to skip Redis/cache wiring in tests |
+| `openai_api_mode` | `:auto` routes (gpt-5 family + tools + thinking) via `/v1/responses` using Smith's vendored Responses adapter (sync only; streaming over `/v1/responses` is not yet supported); `:off` drops incompatible tools instead | Leave `:auto` (default) unless you need streaming with the (gpt-5 + tools + thinking) combo, in which case set `:off` for graceful tool-dropping |
+| `trace_normalizer` | Emit `:normalizer_decision` trace events from `Smith::Models::Normalizer` | Useful when debugging cross-provider request shaping |
+| `ruby_llm_model_registry` | `:database` to require an AR-backed RubyLLM model registry; `:bundled` for the JSON fallback | Leave at default unless you've migrated to DB-backed |
+
+### Recommended First Additions
+
+Add settings in this order:
+
+1. `config.logger`
+2. `config.trace_adapter`
+3. `config.artifact_store`
+4. `config.pricing`
+
+Do not start by configuring every advanced switch at once.
+