riffer 0.48.0 → 0.49.0

data/sig/generated/riffer/agent.rbs

@@ -1,15 +1,5 @@
 # Generated from lib/riffer/agent.rb with RBS::Inline
 
-# Base class for all agents in the Riffer framework. Subclass it to define an
-# agent's model, instructions, tools, and guardrails.
-#
-#   class MyAgent < Riffer::Agent
-#     model 'openai/gpt-4o'
-#     instructions 'You are a helpful assistant.'
-#   end
-#
-#   agent = MyAgent.new
-#   agent.generate('Hello!')
 class Riffer::Agent
   extend Riffer::Registrable
 
@@ -17,237 +7,131 @@ class Riffer::Agent
 
   INTERRUPT_MAX_STEPS: Symbol
 
-  # Returns the per-class Riffer::Agent::Config holding every DSL setting.
   # --
   # : () -> Riffer::Agent::Config
   def self.config: () -> Riffer::Agent::Config
 
-  # +identifier+ is cleared because it is configuration here but identity on the
-  # subclass; two classes claiming one raise Riffer::DuplicateIdentifierError at
-  # the next registry lookup.
   # --
   # : (Class) -> void
   def self.inherited: (Class) -> void
 
-  # Gets or sets the agent identifier.
-  #
   # --
   # : (?String?) -> String
   def self.identifier: (?String?) -> String
 
-  # Gets or sets the model string (e.g., "openai/gpt-4o").
-  #
   # --
   # : (?(String | Proc)?) -> (String | Proc)?
   def self.model: (?(String | Proc)?) -> (String | Proc)?
 
-  # Gets or sets the agent instructions. A Proc is called at generate time with
-  # the +context+ hash (which may be +nil+).
-  #
-  #   instructions "You are a helpful assistant."
-  #
-  #   instructions -> (context) {
-  #     "You are assisting #{context[:name]}"
-  #   }
-  #
   # --
   # : (?(String | Proc)?) -> (String | Proc)?
   def self.instructions: (?(String | Proc)?) -> (String | Proc)?
 
-  # Gets or sets model options passed to generate_text/stream_text.
-  #
   # --
   # : (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
   def self.model_options: (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
 
-  # Gets or sets the structured output schema for this agent.
   # --
   # : (?Riffer::Params?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def self.structured_output: (?Riffer::Params?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
 
-  # Gets or sets the maximum number of LLM call steps in the tool-use loop.
-  # The splat distinguishes a getter (no argument) from setting the limit to
-  # +nil+ (unlimited); it defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS.
-  #
-  #   max_steps        # reads the current limit
-  #   max_steps 8      # cap the loop at 8 steps
-  #   max_steps nil    # unlimited
-  #
   # --
   # : (*Numeric?) -> Numeric?
   def self.max_steps: (*Numeric?) -> Numeric?
 
-  # Gets or sets the tools used by this agent.
-  #
   # --
   # : (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
   def self.uses_tools: (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
 
-  # Opts this agent into MCP tools from registrations matching the given tag.
-  # Progressive registrations expose +mcp_search+ instead of every schema up front.
-  #
+  # +progressive+ exposes +mcp_search+ instead of every tool schema up front.
+  # --
   # : (String | Symbol, ?progressive: bool) -> void
   def self.use_mcp: (String | Symbol, ?progressive: bool) -> void
 
-  # Returns the accumulated +use_mcp+ configurations for this agent class.
-  #
   # : () -> Array[Hash[Symbol, untyped]]
   def self.mcp_configs: () -> Array[Hash[Symbol, untyped]]
 
-  # Gets or sets the tool runtime for this agent; defaults to
-  # <tt>Riffer.config.tool_runtime</tt> when unset.
   # --
   # : (?(singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def self.tool_runtime: (?(singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
 
-  # Configures skills for this agent via a block DSL, or returns the current
-  # Riffer::Skills::Config when called without a block.
-  #
-  #   skills do
-  #     backend Riffer::Skills::FilesystemBackend.new(".skills")
-  #     adapter Riffer::Skills::XmlAdapter
-  #     activate ["code-review"]
-  #   end
-  #
   # --
   # : () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
   def self.skills: () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
 
-  # Generates a response using a new agent instance.
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def self.generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
-  # Streams a response using a new agent instance.
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def self.stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?context: Hash[Symbol, untyped]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
-  # Reconstructs a runnable agent from a wire hash produced by +#to_h+.
   # --
   # : (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
   def self.from_h: (Hash[Symbol, untyped], ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
 
-  # Reconstructs a runnable agent from a JSON string produced by +#to_json+.
   # --
   # : (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
   def self.from_json: (String, ?context: Hash[Symbol, untyped]?, ?session: Riffer::Agent::Session?, ?tool_resolver: ^(Hash[Symbol, untyped]) -> singleton(Riffer::Tool), ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> Riffer::Agent
 
-  # Registers a guardrail for input, output, or both phases. Raises
-  # Riffer::ArgumentError unless +phase+ is :before, :after, or :around.
   # --
   # : (Symbol, with: singleton(Riffer::Guardrail), **untyped) -> void
   def self.guardrail: (Symbol, with: singleton(Riffer::Guardrail), **untyped) -> void
 
-  # Returns the registered guardrail configs for a given phase.
   # --
   # : (Symbol) -> Array[Hash[Symbol, untyped]]
   def self.guardrails_for: (Symbol) -> Array[Hash[Symbol, untyped]]
 
-  # The conversation handle.
   attr_reader session: Riffer::Agent::Session
 
-  # The per-instance Riffer::Agent::Config.
   attr_reader config: Riffer::Agent::Config
 
-  # The system message built from the configured +instructions+, or +nil+ when
-  # none are configured.
   attr_reader instruction_message: Riffer::Messages::System?
 
-  # The system message describing the configured skills catalog, or +nil+ when
-  # skills are unconfigured or the catalog is empty.
   attr_reader skills_message: Riffer::Messages::System?
 
-  # The mutable runtime context shared with every +Riffer::Agent::Run+ this
-  # agent executes and threaded through all Proc-based settings.
   attr_reader context: Riffer::Agent::Context
 
-  # The resolved provider name (the part before "/" in the model string),
-  # e.g. +"openai"+.
   attr_reader provider_name: String
 
-  # The resolved model name (the part after "/" in the model string), used as
-  # the model argument on every LLM call.
   attr_reader model_name: String
 
-  # The provider client. Public so tests can pre-queue responses on
-  # +Riffer::Providers::Mock+ before calling +#generate+.
+  # Public so tests can pre-queue responses on Riffer::Providers::Mock.
   attr_reader provider: Riffer::Providers::Base
 
-  # The +Riffer::Agent::StructuredOutput+ wrapping the configured schema, or
-  # +nil+ when not configured.
   attr_reader structured_output: Riffer::Agent::StructuredOutput?
 
-  # The tool classes the LLM sees on every call this agent makes.
   attr_reader tools: Array[singleton(Riffer::Tool)]
 
-  # The tool runtime instance used to execute tool calls.
   attr_reader tool_runtime: Riffer::Tools::Runtime
 
-  # Initializes a new agent.
-  #
-  # A provided +session:+ is used as-is — the caller owns its contents (e.g.
-  # cross-process resume from persisted history); an omitted one is seeded with
-  # the instruction and skills messages.
-  #
-  # Raises Riffer::ArgumentError unless the configured model string is
-  # "provider/model" format.
-  #
   # --
   # : (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
   def initialize: (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
 
-  # The identifier for this agent: the instance config's identifier when set
-  # (e.g. an agent restored with +Riffer::Agent.from_h+), otherwise the class
-  # identifier.
-  #
   # --
   # : () -> String
   def identifier: () -> String
 
-  # Generates a response from the agent.
-  #
-  # With +prompt+, a new user message is appended (silently — +on_message+ does
-  # not fire for user inputs) before the loop runs. Without it, the loop runs
-  # against the current session, resuming a persisted conversation or pending
-  # tool calls. +files:+ requires +prompt+.
-  #
-  # +tags:+ is an optional flat hash of attribution tags applied to this single
-  # call: they propagate to the provider's native request-metadata field, and
-  # are stamped as +riffer.tag.*+ on every span the call emits. See
-  # +docs/AGENTS.md+ for the per-provider mapping. The reserved key
-  # +user_id+ also maps to the provider's native user identifier where one
-  # exists. Riffer adds the default tags +kind+ (+"agent"+) and +agent+ (the
-  # agent identifier); a caller tag with the same key wins.
-  #
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Riffer::Agent::Response
   def generate: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Riffer::Agent::Response
 
-  # Streams a response from the agent as an +Enumerator+ of
-  # +Riffer::StreamEvents+ whose block-form +each+ returns the final
-  # Riffer::Agent::Response. See +#generate+ for prompt/files/tags semantics.
-  #
-  # Raises Riffer::ArgumentError if structured output is configured.
-  #
   # --
   # : (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[(String | Symbol), untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
   def stream: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::User::FilePart]?, ?tags: Hash[String | Symbol, untyped]) -> Enumerator[Riffer::StreamEvents::Base, Riffer::Agent::Response]
 
-  # Interrupts the agent loop from an +on_message+ callback. Equivalent to
-  # <tt>throw :riffer_interrupt, reason</tt>.
   # --
   # : (?(String | Symbol)?) -> void
   def interrupt!: (?(String | Symbol)?) -> void
 
-  # Snapshots this resolved agent into a self-contained, provider-neutral wire
-  # hash.
   # --
   # : () -> Hash[Symbol, untyped]
   def to_h: () -> Hash[Symbol, untyped]
 
-  # Snapshots this resolved agent into a wire JSON string. The +*+ absorbs the
-  # JSON generator state argument so <tt>JSON.generate(agent)</tt> works too.
+  # The +*+ absorbs JSON's generator-state argument so
+  # <tt>JSON.generate(agent)</tt> works.
   # --
   # : (*untyped) -> String
   def to_json: (*untyped) -> String

data/sig/generated/riffer/config/amazon_bedrock.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/riffer/config/amazon_bedrock.rb with RBS::Inline
+
+class Riffer::Config::AmazonBedrock
+  attr_reader api_token: String?
+
+  attr_reader region: String?
+
+  attr_accessor client: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def api_token=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def region=: (untyped) -> void
+end

data/sig/generated/riffer/config/anthropic.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/riffer/config/anthropic.rb with RBS::Inline
+
+class Riffer::Config::Anthropic
+  attr_reader api_key: String?
+
+  attr_accessor client: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def api_key=: (untyped) -> void
+end

data/sig/generated/riffer/config/azure_open_ai.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/riffer/config/azure_open_ai.rb with RBS::Inline
+
+class Riffer::Config::AzureOpenAI
+  attr_reader api_key: String?
+
+  attr_reader endpoint: String?
+
+  attr_accessor client: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def api_key=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def endpoint=: (untyped) -> void
+end

data/sig/generated/riffer/config/evals.rbs

@@ -0,0 +1,13 @@
+# Generated from lib/riffer/config/evals.rb with RBS::Inline
+
+class Riffer::Config::Evals
+  attr_reader judge_model: String?
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def judge_model=: (untyped) -> void
+end

data/sig/generated/riffer/config/files.rbs

@@ -0,0 +1,43 @@
+# Generated from lib/riffer/config/files.rb with RBS::Inline
+
+class Riffer::Config::Files
+  attr_reader allow_downloads: bool
+
+  attr_reader max_bytes: Integer
+
+  attr_reader timeout: Integer
+
+  attr_reader max_per_message: Integer?
+
+  attr_reader runner: Riffer::Runner
+
+  attr_reader downloader: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def allow_downloads=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def max_bytes=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def timeout=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def max_per_message=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def runner=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def downloader=: (untyped) -> void
+end

data/sig/generated/riffer/config/gemini.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/riffer/config/gemini.rb with RBS::Inline
+
+class Riffer::Config::Gemini
+  attr_reader api_key: String?
+
+  attr_accessor client: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def api_key=: (untyped) -> void
+end

data/sig/generated/riffer/config/mcp.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/config/mcp.rb with RBS::Inline
+
+class Riffer::Config::Mcp
+  attr_reader credentials: untyped
+
+  attr_reader discovery_runner: Riffer::Runner
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def credentials=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def discovery_runner=: (untyped) -> void
+end

data/sig/generated/riffer/config/open_ai.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/riffer/config/open_ai.rb with RBS::Inline
+
+class Riffer::Config::OpenAI
+  attr_reader api_key: String?
+
+  attr_reader base_url: String?
+
+  attr_accessor client: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def api_key=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def base_url=: (untyped) -> void
+end

data/sig/generated/riffer/config/open_router.rbs

@@ -0,0 +1,15 @@
+# Generated from lib/riffer/config/open_router.rb with RBS::Inline
+
+class Riffer::Config::OpenRouter
+  attr_reader api_key: String?
+
+  attr_accessor client: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def api_key=: (untyped) -> void
+end

data/sig/generated/riffer/config/pricing/rates.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/config/pricing/rates.rb with RBS::Inline
+
+class Riffer::Config::Pricing::Rates
+  attr_reader input: Float
+
+  attr_reader output: Float
+
+  attr_reader cache_read: Float?
+
+  attr_reader cache_write: Float?
+
+  # --
+  # : (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
+  def initialize: (input: Float, output: Float, ?cache_read: Float?, ?cache_write: Float?) -> void
+
+  # --
+  # : (input_tokens: Integer, output_tokens: Integer, ?cache_read_tokens: Integer?, ?cache_write_tokens: Integer?) -> Float
+  def cost_for: (input_tokens: Integer, output_tokens: Integer, ?cache_read_tokens: Integer?, ?cache_write_tokens: Integer?) -> Float
+end

data/sig/generated/riffer/config/pricing.rbs

@@ -0,0 +1,31 @@
+# Generated from lib/riffer/config/pricing.rb with RBS::Inline
+
+class Riffer::Config::Pricing
+  @rates: Hash[String, Riffer::Config::Pricing::Rates]
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : ((String | Array[String]), input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
+  def set: (String | Array[String], input: Numeric, output: Numeric, ?cache_read: Numeric?, ?cache_write: Numeric?) -> void
+
+  # --
+  # : (String) -> Riffer::Config::Pricing::Rates?
+  def rates_for: (String) -> Riffer::Config::Pricing::Rates?
+
+  # --
+  # : () -> bool
+  def empty?: () -> bool
+
+  private
+
+  # --
+  # : (untyped, String) -> Float
+  def coerce_rate: (untyped, String) -> Float
+
+  # --
+  # : (untyped, String) -> Float?
+  def coerce_optional_rate: (untyped, String) -> Float?
+end

data/sig/generated/riffer/config/skills.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/riffer/config/skills.rb with RBS::Inline
+
+class Riffer::Config::Skills
+  attr_reader default_activate_tool: singleton(Riffer::Tool)
+
+  attr_reader default_backend: (Riffer::Skills::Backend | Proc)?
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (singleton(Riffer::Tool)) -> void
+  def default_activate_tool=: (singleton(Riffer::Tool)) -> void
+
+  # --
+  # : ((Riffer::Skills::Backend | Proc)?) -> void
+  def default_backend=: ((Riffer::Skills::Backend | Proc)?) -> void
+end

data/sig/generated/riffer/config/tracing.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/riffer/config/tracing.rb with RBS::Inline
+
+class Riffer::Config::Tracing
+  attr_reader enabled: bool
+
+  attr_reader capture_messages: bool
+
+  attr_reader backend: untyped
+
+  # --
+  # : () -> void
+  def initialize: () -> void
+
+  # --
+  # : (untyped) -> void
+  def enabled=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def capture_messages=: (untyped) -> void
+
+  # --
+  # : (untyped) -> void
+  def backend=: (untyped) -> void
+end