riffer 0.17.0 → 0.20.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 849df927faaf4614ad3a4833aafa5323731d3c1f4a7a8687db35ee5d341eb334
-  data.tar.gz: 1d992d83487a673fef8714d6f72811eb94fdb5e646e33612eb18ac915257b832
+  metadata.gz: '09506e8a2dfa346e49231fa598f1e899066a5597ddd5b6738758ca49594ca7c2'
+  data.tar.gz: 684dc3caf2f6a59d052adb51a5c33bdf0a5542a2a375f188a1bc0a600a7df5ef
 SHA512:
-  metadata.gz: f1967690dfbe21181d4670117de7563936c05dd7d7303597378584acba35a0543de292fb9e4f72d9ed71789d4b73dc17023ce1d1c0bba27434dea93646dccc4d
-  data.tar.gz: 71b4c1568a2b4f5f420f3546283f5c56bc979b8234734049a8df714363faf132f36bc892dabc3e62702c59c43e74ad7e697fb702c772f2bfdec6f56950c0a1fb
+  metadata.gz: 2b1c4119f8afac1367aac6a7d9caddd656a598dab1ad44c921802864e73815d19c3a4f96e554483d9062c9e87864bd870e8af260b9d7f5922331bdcc714ccb52
+  data.tar.gz: 5f8387e02a6b2638550e59265980c8de6ce9422b77f905dcc019360e039d59ffb5b8d76310ba90819f7f7b51a5af34588b0de40782255c57215d4bf32ca862c8

data/.agents/architecture.md

@@ -4,7 +4,7 @@
 
 ### Agent (`lib/riffer/agent.rb`)
 
-Base class for AI agents. Subclass and use DSL methods `model`, `instructions`, and `structured_output` to configure. Orchestrates message flow, LLM calls, tool execution, and structured output parsing via a generate/stream loop.
+Base class for AI agents. Subclass and use DSL methods `model`, `instructions`, `structured_output`, and `skills` to configure. Orchestrates message flow, LLM calls, tool execution, structured output parsing, and skill activation via a generate/stream loop.
 
 ```ruby
 class EchoAgent < Riffer::Agent
@@ -40,6 +40,22 @@ Adapters for LLM APIs. The base class uses a template-method pattern — `genera
 
 Providers are registered in `Riffer::Providers::Repository::REPO` with identifiers (e.g., `openai`, `amazon_bedrock`).
 
+Each provider declares a preferred skill adapter via `self.skills_adapter` (Markdown for most, XML for Anthropic).
+
+### Skills (`lib/riffer/skills/`)
+
+Support for the [Agent Skills spec](https://agentskills.io/). Skills are packaged as directories containing `SKILL.md` files with YAML frontmatter. The framework discovers skills through a pluggable backend, injects metadata into the system prompt, and provides a tool (`skill_activate`) for the LLM to load full skill instructions on demand.
+
+- `Config` - DSL configuration object (`backend`, `adapter`, `activate`)
+- `Backend` - base class interface (`list_skills`, `read_skill`)
+- `FilesystemBackend` - built-in filesystem scanner
+- `Frontmatter` - parsed YAML frontmatter value object with `.parse(raw)` class method
+- `Context` - coordinates discovery, activation, caching, and prompt rendering for a generation cycle
+- `Adapter` - base class for skill adapters (`render_catalog`, `activate_tool`)
+- `MarkdownAdapter` - default Markdown skill adapter
+- `XmlAdapter` - XML skill adapter for Anthropic/Claude
+- `ActivateTool` - default tool the LLM calls to activate a skill
+
 ### Messages (`lib/riffer/messages/`)
 
 Typed message objects that extend `Riffer::Messages::Base`:
@@ -65,6 +81,10 @@ Structured events for streaming responses:
 - `WebSearchDone` - web search completion with query and sources
 - `Interrupt` - callback interrupted the agent loop
 
+### Per-Call State Reset
+
+Each call to `generate` or `stream` resets `context`, tools, tool runtime, model, skills state, and the interrupted flag via `prepare_run`. Only the message history and cumulative `token_usage` persist across calls. This means `context:` must be passed on every call.
+
 ### Stopping the Loop Early
 
 Two mechanisms can stop the agent loop before the LLM finishes naturally:
@@ -75,10 +95,41 @@ Two mechanisms can stop the agent loop before the LLM finishes naturally:
 
 ### Resuming After an Interrupt
 
-`agent.resume` or `agent.resume_stream` continues an interrupted loop. Both accept `messages:` for cross-process resume from persisted data.
+Two resume paths:
+
+- **In-memory** — call `generate` or `stream` again with a string on the same agent instance. The message history is preserved and the new user message is appended.
+- **Cross-process** — pass persisted messages as an array to a new agent instance. Array input uses messages as-is (no system message prepend). Passing an array to an agent that already has messages raises `Riffer::ArgumentError`.
+
+```ruby
+agent.generate('Continue')              # in-memory resume
+MyAgent.new.stream(persisted_messages)  # cross-process resume
+```
 
 On resume, `execute_pending_tool_calls` detects tool calls from the last assistant message that lack corresponding tool result messages and executes them before entering the LLM loop. This handles the case where an interrupt fired mid-way through tool execution.
 
+### Runner (`lib/riffer/runner.rb`)
+
+Concurrency primitive for batch execution. Subclasses implement `#map(items, context: nil, &block)` to control how items are processed. The `context` keyword carries the agent's context hash, enabling runners that need it for job serialization or routing.
+
+Built-in runners:
+- `Sequential` — processes items in the current thread via `Array#map`
+- `Threaded` — processes items concurrently using a thread pool with configurable `max_concurrency`
+
+```ruby
+runner = Riffer::Runner::Threaded.new(max_concurrency: 3)
+runner.map(items, context: ctx) { |item| process(item) }
+```
+
+### ToolRuntime (`lib/riffer/tool_runtime.rb`)
+
+Composes with a Runner to execute tool calls. Provides `#execute` as the public entry point and `#around_tool_call` as a hook for instrumentation. Passes the agent context through to the runner.
+
+Built-in runtimes:
+- `Inline` — uses `Runner::Sequential` (default)
+- `Threaded` — uses `Runner::Threaded`
+
+Context flow: `Agent#execute_tool_calls` → `ToolRuntime#execute(tool_calls, tools:, context:)` → `Runner#map(tool_calls, context:) { dispatch }` → `Tool#call(context:, **args)`
+
 ## Key Patterns
 
 - Model config accepts a `provider/model` string (e.g., `openai/gpt-4`) or a Proc/lambda that returns one
@@ -105,6 +156,17 @@ lib/
     params.rb            # Parameter collection with DSL and validation
     structured_output.rb # Structured output schema wrapper
     stream_events.rb     # Stream events namespace/module
+    skills.rb            # Skills namespace/module
+    skills/
+      config.rb          # DSL configuration object
+      adapter.rb         # Adapter base class (render_catalog, activate_tool)
+      markdown_adapter.rb # Default Markdown skill adapter
+      xml_adapter.rb     # XML skill adapter for Anthropic/Claude
+      backend.rb         # Backend base class (interface)
+      filesystem_backend.rb # Built-in filesystem backend
+      frontmatter.rb     # Parsed YAML frontmatter value object with .parse
+      context.rb         # Skills context for a generation cycle
+      activate_tool.rb   # Default skill_activate tool
     structured_output/
       result.rb          # Parse/validation result object
     helpers/

data/.agents/rdoc.md

@@ -4,18 +4,30 @@ Use RDoc prose comments for public API descriptions and RBS inline annotations f
 
 ## Parameters and Return Types
 
-Describe parameters in the RDoc prose comment. Use a single `#:` line for the RBS method signature (see [rbs-inline.md](rbs-inline.md) for the full type annotation syntax):
+Describe parameters using RDoc labeled list syntax. Use a single `#:` line for the RBS method signature (see [rbs-inline.md](rbs-inline.md) for the full type annotation syntax):
 
 ```ruby
 # Creates a new agent.
 #
-# +name+ - the agent name.
-# +options+ - optional configuration.
+# [name] the agent name.
+# [options] optional configuration.
 #
+#--
 #: (String, ?options: Hash[Symbol, untyped]) -> void
 def initialize(name, options: {})
 ```
 
+Always add `#--` (RDoc stop directive) on the line before a standalone `#:` type annotation. Without it, RDoc treats `#:` as a label-list marker and corrupts the preceding comment into a `<pre>` block. Inline `#:` on the same line as code (e.g., `attr_reader :name #: String`) does not need this.
+
+## Inline Code
+
+Use `+word+` for single-word inline code. For multi-word expressions (containing spaces, colons, or brackets), use `<tt>multi word expression</tt>`:
+
+```ruby
+# Returns +nil+ when no instructions are configured.
+# Equivalent to <tt>throw :riffer_interrupt, reason</tt>.
+```
+
 ## Attributes and Constants
 
 Use `#:` inline syntax (on the same line) for attribute and constant types:
@@ -37,7 +49,7 @@ Document with prose:
 
 ## Examples
 
-Include usage examples as indented code blocks:
+Include usage examples as indented code blocks (2 extra spaces of indent):
 
 ```ruby
 # Creates a new agent.

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.17.0"
+  ".": "0.20.0"
 }

data/.ruby-version

@@ -1 +1 @@
-3.4.8
+3.4.8

data/CHANGELOG.md

@@ -5,6 +5,35 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.20.0](https://github.com/janeapp/riffer/compare/riffer/v0.19.0...riffer/v0.20.0) (2026-03-26)
+
+
+### Features
+
+* add fibers tool runtime using async gem ([#178](https://github.com/janeapp/riffer/issues/178)) ([67fd344](https://github.com/janeapp/riffer/commit/67fd34493126559b99a00cc3402a6adabefc14ea))
+
+
+### Bug Fixes
+
+* correct RDoc formatting for docs.riffer.ai ([#182](https://github.com/janeapp/riffer/issues/182)) ([2f2fbc9](https://github.com/janeapp/riffer/commit/2f2fbc997281ef4a546a58e44233e325a25c41d5))
+
+## [0.19.0](https://github.com/janeapp/riffer/compare/riffer/v0.18.0...riffer/v0.19.0) (2026-03-25)
+
+
+### Features
+
+* Add Azure OpenAI provider ([#167](https://github.com/janeapp/riffer/issues/167)) ([5d34fcd](https://github.com/janeapp/riffer/commit/5d34fcd4a98a6bcfa768c50fea7c25959eca5f1d))
+* expose message history in eval results ([#171](https://github.com/janeapp/riffer/issues/171)) ([c8b1aec](https://github.com/janeapp/riffer/commit/c8b1aeceb40a173c70d4be445fb82bba10113b87))
+* provide agent context to runners ([#181](https://github.com/janeapp/riffer/issues/181)) ([23c9282](https://github.com/janeapp/riffer/commit/23c9282d4f2076d1ff6185f99bcf855f158ccb0d))
+
+## [0.18.0](https://github.com/janeapp/riffer/compare/riffer/v0.17.0...riffer/v0.18.0) (2026-03-13)
+
+
+### Features
+
+* add support for agent skills ([#151](https://github.com/janeapp/riffer/issues/151)) ([8847d54](https://github.com/janeapp/riffer/commit/8847d54dede875f207d0e0b28bb64039d3c2e69f))
+* Unify generate/stream API with multi-turn support, remove resume methods ([#165](https://github.com/janeapp/riffer/issues/165)) ([58826df](https://github.com/janeapp/riffer/commit/58826df27806bb10afe1c7ad94322cc643d049f9))
+
 ## [0.17.0](https://github.com/janeapp/riffer/compare/riffer/v0.16.1...riffer/v0.17.0) (2026-03-06)
 
 

data/README.md

@@ -34,7 +34,7 @@ end
 
 # Define an agent
 class EchoAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are an assistant that repeats what the user says.'
 end
 

data/Rakefile

@@ -17,8 +17,7 @@ RDoc::Task.new do |rdoc|
   rdoc.rdoc_files.include("README.md", "CHANGELOG.md", "LICENSE.txt", "docs/**/*.md", "docs_providers/**/*.md")
   rdoc.rdoc_files.include("lib/**/*.rb")
 
-  # Use Markdown where available and ensure UTF-8
-  rdoc.options << "--charset" << "utf-8" << "--markup" << "markdown"
+  rdoc.options << "--charset" << "utf-8"
 end
 
 task docs: :rdoc

data/docs/01_OVERVIEW.md

@@ -10,7 +10,7 @@ The Agent is the central orchestrator for AI interactions. It manages messages,
 
 ```ruby
 class MyAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are a helpful assistant.'
 end
 ```
@@ -43,7 +43,7 @@ Agents can return structured JSON responses that conform to a schema. The respon
 
 ```ruby
 class SentimentAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   structured_output do
     required :sentiment, String
     required :score, Float

data/docs/02_GETTING_STARTED.md

@@ -68,7 +68,7 @@ Riffer.configure do |config|
 end
 
 class GreetingAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You are a friendly assistant. Greet the user warmly.'
 end
 
@@ -109,7 +109,7 @@ class TimeTool < Riffer::Tool
 end
 
 class TimeAgent < Riffer::Agent
-  model 'openai/gpt-4o'
+  model 'openai/gpt-5-mini'
   instructions 'You can tell the user the current time.'
   uses_tools [TimeTool]
 end