Module: Truffle

Defined in:
lib/truffle.rb,
lib/truffle/tool.rb,
lib/truffle/agent.rb,
lib/truffle/message.rb,
lib/truffle/toolbox.rb,
lib/truffle/version.rb,
lib/truffle/response.rb,
lib/truffle/providers/base.rb,
lib/truffle/providers/openai.rb

Overview

Truffle is a complete agent harness for Ruby, built from scratch.

It is a faithful port of earendil-works/pi to idiomatic Ruby: the agent-core runtime (tool calling, state, and an event-streaming protocol), with a provider-agnostic LLM seam written from the ground up and no runtime gem dependencies.

Quick start:

require "truffle"

add = Truffle::Tool.define("add", "Add two integers") do
param :a, :integer, required: true
param :b, :integer, required: true
run { |a:, b:| a + b }
end

agent = Truffle.agent(
provider: :openai,
system_prompt: "You are a precise calculator. Use tools for arithmetic.",
tools: [add]
)
puts agent.run("What is 21 plus 21?")

Defined Under Namespace

Modules: Providers Classes: Agent, Error, Message, Response, Tool, ToolCall, Toolbox

Constant Summary collapse

PROVIDERS = 
{
  openai: Providers::OpenAI
}.freeze
VERSION = 
"0.1.0"

Class Method Summary collapse

Class Method Details

.agent(provider:, system_prompt: nil, tools: [], model: nil, max_turns: Agent::DEFAULT_MAX_TURNS, **provider_options) ⇒ Object

Convenience constructor: Truffle.agent(provider: :openai, tools: [...], ...). provider: may be a symbol, an options-less default, or a provider instance.



57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/truffle.rb', line 57

def agent(provider:, system_prompt: nil, tools: [], model: nil,
          max_turns: Agent::DEFAULT_MAX_TURNS, **provider_options)
  prov = provider(provider, **provider_options)
  Agent.new(
    provider: prov,
    system_prompt: system_prompt,
    tools: tools,
    model: model,
    max_turns: max_turns
  )
end

.provider(name, **options) ⇒ Object

Build a provider by symbol (:openai) or pass a ready-made instance through.

Raises:



46
47
48
49
50
51
52
53
 
# File 'lib/truffle.rb', line 46

def provider(name, **options)
  return name if name.is_a?(Providers::Base)

  klass = PROVIDERS[name.to_sym]
  raise Error, "unknown provider #{name.inspect}, known: #{PROVIDERS.keys.inspect}" if klass.nil?

  klass.new(**options)
end

.tool(name, description, &block) ⇒ Object

Define a tool: Truffle.tool("name", "desc") { param ...; run { ... } }.



70
71
72
 
# File 'lib/truffle.rb', line 70

def tool(name, description, &block)
  Tool.define(name, description, &block)
end