jrubyagents 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f365fc9c08f376ff08dcf933c1968829f15a79e518758ba79f8e82e2b8562452
+  data.tar.gz: 4e9e8eb4add2dbec0ceb7c2e175133ed8d1ec12fa2bcb6719c124fbf032b3301
+SHA512:
+  metadata.gz: fbf21991c23fd1418939c1152f67995a1502db87fa08cc29f739c9cb58440a437a3a41d9ffacff21ae098ddfc3ad49d22ae418f72bb50b9a7de5b2a8e047948a
+  data.tar.gz: 6afa4e9696415fad82e3969216060b1ef396aaa846ce3fd9e4bafe7c13cef0e6834b8ba18ecaecdb3b54b074c64303816d7abc254d6909ac071c0584e51c1b74

data/.ruby-version

@@ -0,0 +1 @@
+3.4.8

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## 0.2.0
+
+Tools, MCP filtering, observability, and code agent improvements.
+
+- **FileRead tool** -- Read file contents with path expansion and 50k char truncation
+- **FileWrite tool** -- Write files with automatic parent directory creation
+- **ListGems tool** -- Lists available Ruby gems; auto-included in CodeAgent
+- **`tool_from_mcp`** -- Load a single tool from an MCP server by name
+- **Run export** -- `to_h` / `to_json` on Memory, RunResult, and all step types for serialization
+- **Richer callbacks** -- `Callback` base class with `on_run_start`, `on_step_start`, `on_step_end`, `on_tool_call`, `on_error`, `on_run_end`; backward-compatible with existing `step_callbacks`
+- **`memory.replay`** -- Pretty-print a completed run with syntax-highlighted code and metrics
+- **Code agent prompt** -- Tells the model about available Ruby stdlib and gems so it uses `net/http`, `json`, etc. without being asked
+
+## 0.1.0
+
+Initial release.
+
+- **CodeAgent** -- LLM writes and executes Ruby code in a sandboxed fork
+- **ToolCallingAgent** -- LLM calls tools via structured tool_calls (OpenAI-style)
+- **Model adapters** -- OpenAI, Anthropic, and Ollama out of the box
+- **Tool DSL** -- Define tools as classes or inline blocks
+- **MCP client** -- Load tools from any MCP server via stdio transport
+- **Structured output** -- Validate final answers against JSON Schema or custom procs
+- **Prompt customization** -- Override system prompts, planning prompts, or inject instructions
+- **Final answer checks** -- Validation procs that can reject and retry answers
+- **Step-by-step execution** -- `agent.step()` for debugging and custom UIs
+- **Planning** -- Optional periodic re-planning during long runs
+- **Managed agents** -- Nest agents as tools for multi-agent workflows
+- **CLI** -- `rubyagents` command with interactive mode, tool loading, and MCP support

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chris Hasiński
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,255 @@
+# Rubyagents
+
+A radically simple, code-first AI agent framework for Ruby. Inspired by [smolagents](https://github.com/huggingface/smolagents).
+
+LLMs write and execute Ruby code -- not JSON blobs. This means tool calls are just method calls, variables persist between steps, and the full power of Ruby is available to the agent at every turn.
+
+## Installation
+
+```bash
+gem install rubyagents
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "rubyagents"
+```
+
+Requires Ruby 3.2+. JRuby 10.0.3.0+ is also supported — the sandbox automatically switches from fork-based to thread-based execution, and platform-specific gems (lipgloss) are skipped gracefully.
+
+## Quick start
+
+```ruby
+require "rubyagents"
+
+agent = Rubyagents::CodeAgent.new(model: "anthropic/claude-sonnet-4-20250514")
+agent.run("What is the 118th Fibonacci number?")
+```
+
+The agent will think, write Ruby code, execute it in a sandbox, and return the answer.
+
+## Model support
+
+Pass a model string as `provider/model_name`:
+
+```ruby
+# Anthropic
+Rubyagents::CodeAgent.new(model: "anthropic/claude-sonnet-4-20250514")
+
+# OpenAI
+Rubyagents::CodeAgent.new(model: "openai/gpt-4o")
+
+# Ollama (local)
+Rubyagents::CodeAgent.new(model: "ollama/qwen2.5:3b")
+```
+
+Set API keys via environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`.
+
+## Agent types
+
+**CodeAgent** -- the LLM writes Ruby code that gets executed in a sandboxed environment. Tools are available as methods. Variables persist between steps. On MRI, code runs in a forked child process for full isolation; on JRuby, a thread-based executor is used automatically since fork is unavailable — no configuration needed.
+
+```ruby
+agent = Rubyagents::CodeAgent.new(model: "anthropic/claude-sonnet-4-20250514")
+```
+
+**ToolCallingAgent** -- the LLM uses structured tool calls (OpenAI function calling style). Better for models with strong tool_call support.
+
+```ruby
+agent = Rubyagents::ToolCallingAgent.new(model: "openai/gpt-4o")
+```
+
+## Custom tools
+
+Define tools as classes:
+
+```ruby
+class StockPrice < Rubyagents::Tool
+  tool_name "stock_price"
+  description "Gets the current stock price for a ticker symbol"
+  input :ticker, type: :string, description: "Stock ticker symbol (e.g. AAPL)"
+  output_type :number
+
+  def call(ticker:)
+    # Your implementation here
+    182.52
+  end
+end
+
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: [StockPrice]
+)
+```
+
+Or define them inline:
+
+```ruby
+weather = Rubyagents.tool(:weather, "Gets weather for a city", city: "City name") do |city:|
+  "72F and sunny in #{city}"
+end
+
+agent = Rubyagents::CodeAgent.new(model: "anthropic/claude-sonnet-4-20250514", tools: [weather])
+```
+
+## MCP tools
+
+Load tools from any [MCP](https://modelcontextprotocol.io/) server:
+
+```ruby
+tools = Rubyagents.tools_from_mcp(command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
+
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: tools
+)
+```
+
+## Structured output
+
+Validate final answers against a JSON Schema or custom proc:
+
+```ruby
+schema = {
+  "type" => "object",
+  "required" => ["name", "age"],
+  "properties" => {
+    "name" => { "type" => "string" },
+    "age" => { "type" => "integer" }
+  }
+}
+
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  output_type: schema
+)
+```
+
+If the output doesn't match, the agent retries automatically.
+
+## Final answer checks
+
+Add validation procs that can reject answers and force retries:
+
+```ruby
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  final_answer_checks: [
+    ->(answer, memory) { answer.length > 10 },
+    ->(answer, memory) { !answer.include?("I don't know") }
+  ]
+)
+```
+
+## Prompt customization
+
+Inject additional instructions without overriding the full system prompt:
+
+```ruby
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  instructions: "Always respond in French. Use metric units."
+)
+```
+
+Or fully replace prompts:
+
+```ruby
+templates = Rubyagents::PromptTemplates.new(
+  system_prompt: "You are a data analyst. Tools: {{tool_descriptions}}"
+)
+
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  prompt_templates: templates
+)
+```
+
+## Step-by-step execution
+
+Run one step at a time for debugging or custom UIs:
+
+```ruby
+agent = Rubyagents::CodeAgent.new(model: "anthropic/claude-sonnet-4-20250514")
+
+agent.step("What is 2+2?")
+agent.step until agent.done?
+
+puts agent.final_answer_value
+```
+
+## Multi-agent workflows
+
+Nest agents as tools:
+
+```ruby
+researcher = Rubyagents::ToolCallingAgent.new(
+  model: "openai/gpt-4o",
+  name: "researcher",
+  description: "Researches topics on the web",
+  tools: [Rubyagents::WebSearch]
+)
+
+manager = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  agents: [researcher]
+)
+
+manager.run("Find out when Ruby 3.4 was released and summarize the key features")
+```
+
+## Planning
+
+Enable periodic re-planning during long runs:
+
+```ruby
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  planning_interval: 3,  # Re-plan every 3 steps
+  max_steps: 15
+)
+```
+
+## CLI
+
+```bash
+# Simple query
+rubyagents "What is the 10th prime number?"
+
+# With options
+rubyagents -m anthropic/claude-sonnet-4-20250514 -t web_search "Who won the latest Super Bowl?"
+
+# Tool-calling agent
+rubyagents -a tool_calling -m openai/gpt-4o "What is 6 * 7?"
+
+# With MCP tools
+rubyagents --mcp "npx -y @modelcontextprotocol/server-filesystem /tmp" "List files in /tmp"
+
+# Interactive mode
+rubyagents -i
+```
+
+## Configuration
+
+| Option | Default | Description |
+|---|---|---|
+| `model:` | -- | Model string (`provider/model_name`) |
+| `tools:` | `[]` | Array of Tool classes or instances |
+| `agents:` | `[]` | Array of Agent instances (become callable tools) |
+| `max_steps:` | `10` | Maximum agent steps before stopping |
+| `planning_interval:` | `nil` | Re-plan every N steps |
+| `instructions:` | `nil` | Extra instructions appended to system prompt |
+| `prompt_templates:` | `nil` | `PromptTemplates` to override system/planning prompts |
+| `output_type:` | `nil` | Hash (JSON Schema) or Proc for output validation |
+| `final_answer_checks:` | `[]` | Array of procs `(answer, memory) -> bool` |
+| `step_callbacks:` | `[]` | Array of procs `(step, agent:) -> void` |
+
+## Credits
+
+- [@khasinski](https://github.com/khasinski) — creator and maintainer of rubyagents
+- [@parolkar](https://github.com/parolkar) — JRuby compatibility support
+
+## License
+
+MIT

data/ROADMAP.md

@@ -0,0 +1,56 @@
+# Roadmap
+
+Gaps identified by comparing rubyagents with [smolagents](https://github.com/huggingface/smolagents), prioritized for Ruby developers building agents.
+
+## Phase 5 -- Core DX (high impact, low effort)
+
+These make the framework usable for real work.
+
+- [x] **MCP client for tools** -- Load tools from any MCP server (stdio + HTTP). This is the single biggest ecosystem unlock since MCP servers already exist for databases, APIs, file systems, browsers, etc. Ruby devs shouldn't have to rewrite tools that already exist.
+- [x] **Structured output** -- Let agents return typed results (not just strings). Accept a schema or Data class, validate the final answer against it. Enables agents as reliable building blocks in larger apps.
+- [x] **Prompt customization** -- Expose `PromptTemplates` object (system prompt, planning, managed agent) so users can override prompts without subclassing. Add `instructions:` parameter for injecting custom rules.
+- [x] **`agent.step()` method** -- Single-step execution for debugging and building custom UIs. Returns the step, lets the caller inspect/modify memory before continuing.
+- [x] **`final_answer_checks`** -- List of validation procs run before accepting a final answer. If any returns false, the agent keeps going. Cheap way to add guardrails.
+
+## Phase 6 -- Model & tool ecosystem (high impact, medium effort)
+
+Broader model support and tool discovery. The RubyLLM migration (replacing 3 hand-rolled adapters with a single wrapper) completed most of the model items here.
+
+- [x] **RubyLLM universal adapter** -- Replaced OpenAI, Anthropic, and Ollama adapters with a single RubyLLM wrapper. Supports 800+ models across OpenAI, Anthropic, Gemini, DeepSeek, OpenRouter, Ollama, and any OpenAI-compatible endpoint. Auto-configures from env vars.
+- [x] **Rate limiting (basic)** -- RubyLLM provides built-in `max_retries` and `retry_interval` for 429s. Per-minute quotas are not yet exposed.
+- [x] **More built-in tools** -- File read/write tools. Google search and Wikipedia search remain TODO.
+- [x] **Tool.from_mcp** -- Load a single tool from an MCP server by name (vs loading all tools from a server).
+
+## Phase 7 -- Observability & debugging (medium impact, medium effort)
+
+Understanding what agents actually do.
+
+- [ ] **Structured logging** -- JSON-structured logs per step with run_id, step_number, thought, action, observation, timing, tokens. Emit to any Ruby logger.
+- [x] **`memory.replay`** -- Pretty-print a completed run to the terminal (like smolagents' `agent.replay()`).
+- [x] **Run export** -- Serialize a run (memory + steps + metadata) to JSON for later analysis or replay.
+- [x] **Callbacks for observability** -- Richer callback interface: `on_step_start`, `on_step_end`, `on_tool_call`, `on_error`. Current `step_callbacks` only fires after completion.
+
+## Phase 8 -- Sandboxing & security (medium impact, high effort)
+
+For production use where agent code can't be trusted.
+
+- [ ] **Docker executor** -- Run agent code in a Docker container instead of a fork. Filesystem isolation, network control, resource limits.
+- [ ] **Import/require allowlist** -- Restrict which Ruby gems/stdlib modules agent code can load in the sandbox (like smolagents' `additional_authorized_imports`).
+- [ ] **Operation count limit** -- Cap iterations/operations in the sandbox to prevent infinite loops eating CPU (smolagents caps at 1M operations).
+
+## Phase 9 -- Advanced features (lower priority, nice to have)
+
+- [ ] **Agent serialization** -- `agent.save(dir)` / `Agent.load(dir)` for persisting agent configuration (tools, prompts, model, settings).
+- [ ] **Media types in tools** -- Support image/audio inputs and outputs for multimodal agents.
+- [ ] **Async/parallel tool calls** -- ToolCallingAgent processes multiple tool calls concurrently (like smolagents' `max_tool_threads`).
+- [ ] **Web UI** -- Lightweight web interface for interactive agent sessions (alternative to CLI). Could be a simple Rack app or use Hotwire.
+- [ ] **Persistent memory** -- Long-term memory across runs (conversation history, learned facts). Could be file-based or backed by SQLite.
+
+## Not planned
+
+These exist in smolagents but don't fit rubyagents' design goals:
+
+- **Hub sharing** -- No equivalent to HuggingFace Hub in Ruby. Gems are the distribution mechanism.
+- **LangChain/Gradio interop** -- Python-specific ecosystems.
+- **WASM executor** -- Ruby WASM support is too immature.
+- **MLX/vLLM adapters** -- Python-only inference runtimes. RubyLLM covers local models via Ollama.

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/custom_tool.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rubyagents"
+
+class StockPrice < Rubyagents::Tool
+  tool_name "stock_price"
+  description "Gets the current stock price for a ticker symbol"
+  input :ticker, type: :string, description: "Stock ticker symbol (e.g. AAPL)"
+  output_type :number
+
+  def call(ticker:)
+    # Simulated stock prices for demo
+    prices = { "AAPL" => 182.52, "GOOGL" => 141.80, "TSLA" => 248.42, "RIVN" => 14.73 }
+    prices.fetch(ticker.upcase, "Unknown ticker: #{ticker}")
+  end
+end
+
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: [StockPrice]
+)
+
+agent.run("What's the difference in stock price between AAPL and TSLA?")

data/examples/fibonacci.rb

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rubyagents"
+
+agent = Rubyagents::CodeAgent.new(model: "anthropic/claude-sonnet-4-20250514")
+agent.run("What is the 118th Fibonacci number?")

data/examples/with_tools.rb

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rubyagents"
+require_relative "../lib/rubyagents/tools/web_search"
+
+agent = Rubyagents::CodeAgent.new(
+  model: "anthropic/claude-sonnet-4-20250514",
+  tools: [Rubyagents::WebSearch]
+)
+
+agent.run("What year was Ruby created and who created it?")

data/exe/rubyagents

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/rubyagents"
+
+Rubyagents::CLI.run