truffle 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c83bac38456b5457ce9a27d9ae82d0c3e13f88d94c01a3e205bb4854cec9c14
+  data.tar.gz: 12967cb3deeeefe37534703064f7bc1e7041888a308e4337cc60e08a4d587b8e
+SHA512:
+  metadata.gz: bc709412da01c71f9130bb9c24889b74af6a5438c222912b09b07f399ac2111440d10e161a606102f47bac8985b9f976aba3e75cacf35967b8ef538b5b52dd06
+  data.tar.gz: bc39da2fd510350510f0fb5f171183cf241284f9d7647e6b277ade821dbc8f8f72bf3b421f82eac3eb276ae00544c0434213e2a14757e933f78e2e07ecd4f33f

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to Truffle are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project aims to follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+### Changed
+- Renamed the project from "Pith" to **Truffle** (gem `truffle`, module
+  `Truffle`, repo `truffle-dev/truffle-rb`).
+- Reframed as a from-scratch, byte-for-byte-faithful port of
+  [pi](https://github.com/earendil-works/pi) with no runtime gem dependencies.
+  Dropped the planned `ruby_llm` adapter; every provider is hand-written.
+
+### Added
+- `NORTH_STAR.md`: the project's fixed destination.
+- `docs/BRAIN.md`: the self-updating continuity file (locked invariants plus a
+  compacted mutable state) read and updated on every build run.
+- Rewritten `ROADMAP.md` mapping Phases 1–5 to pi's package structure.
+
+## [0.1.0] - 2026-06-28
+
+First release. The agent-core runtime, ported from
+[pi](https://github.com/earendil-works/pi) to plain Ruby.
+
+### Added
+- `Truffle::Agent`: the agent loop (prompt -> tool calls -> tool results -> answer)
+  with a `max_turns` guard and an ordered event stream.
+- Tool DSL via `Truffle.tool` / `Truffle::Tool.define`: typed params, JSON Schema
+  generation, string-key to keyword-arg symbolization, and error capture that
+  feeds tool failures back to the model instead of crashing the loop.
+- `Truffle::Toolbox`: a named, enumerable collection of tools.
+- Provider seam (`Truffle::Providers::Base`) and a dependency-free OpenAI Chat
+  Completions provider built on `Net::HTTP`.
+- Event API (`Agent#on`) for `agent_start`, `turn_start`, `message`,
+  `tool_call`, `tool_result`, `turn_end`, `agent_end`.
+- `examples/calculator.rb`: a runnable multi-tool demo.
+- Test suite: hermetic minitest tests plus one live OpenAI round-trip test,
+  skipped unless `OPENAI_API_KEY` is set.
+- `script/rb`: run any command in a `ruby:3.3-slim` container for hosts without
+  a local Ruby.
+
+[Unreleased]: https://github.com/truffle-dev/truffle-rb/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/truffle-dev/truffle-rb/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Truffle
+
+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,214 @@
+# Truffle
+
+A complete **agent harness for Ruby**, built from scratch. Truffle gives you the
+loop that turns a language model into an agent: it sends a prompt, lets the model
+ask for tools, runs those tools, feeds the results back, and repeats until the
+model answers. It is a faithful port of
+[pi](https://github.com/earendil-works/pi) to idiomatic Ruby. No framework, no
+service, no runtime gem dependencies. Plain Ruby and the standard library.
+
+```ruby
+require "truffle"
+
+weather = Truffle.tool("get_weather", "Look up the weather for a city") do
+  param :city, :string, "city name", required: true
+  run { |city:| "It is 22C and sunny in #{city}." }
+end
+
+agent = Truffle.agent(
+  provider: :openai,
+  model: "gpt-4o-mini",
+  system_prompt: "You are a concise assistant. Use tools when they help.",
+  tools: [weather]
+)
+
+puts agent.run("What's the weather in Lisbon?")
+# => "It's 22C and sunny in Lisbon right now."
+```
+
+The model decided to call `get_weather(city: "Lisbon")`, Truffle ran your Ruby
+block, handed the result back, and the model wrote the final answer. That whole
+round trip is the agent loop, and it is the thing Truffle exists to give you.
+
+![Truffle test suite and a live three-tool agent run](docs/screenshot-tests.png)
+
+*The full suite (unit tests plus one live OpenAI round-trip) passing, and the
+calculator example chaining three real tool calls to reach 240.*
+
+## Why Truffle
+
+Ruby has been missing a tiny, readable **agent runtime**: the part that owns the
+turn loop, the tool dispatch, the message history, and the events a UI hangs off.
+Truffle is that runtime, written from scratch.
+
+It is a faithful port of [pi](https://github.com/earendil-works/pi), the
+self-extensible coding agent harness. The aim is a byte-for-byte-faithful Ruby
+port of pi's agent core, growing into a full harness with skills, commands,
+sessions, and memory. You can read the whole loop in one sitting
+(`lib/truffle/agent.rb`) and understand exactly what your agent does.
+
+- **Provider-agnostic, built from scratch.** The agent talks to a single `chat`
+  seam. A provider is any object that answers `chat(messages:, tools:, model:)`.
+  An OpenAI provider ships in the box, written against the wire API directly with
+  no client gem. Anthropic and other providers follow the same hand-written path.
+- **Tools are plain blocks.** Define a tool with a name, a description, typed
+  params, and a Ruby block. Truffle generates the JSON Schema the model needs and
+  symbolizes the model's arguments back into keyword args for you.
+- **Observable.** Subscribe to `agent_start`, `tool_call`, `tool_result`,
+  `agent_end`, and more. Build a TUI, a log stream, or a web view without the
+  harness knowing how it is rendered.
+- **Dependency-free core.** The OpenAI provider uses `Net::HTTP` and the JSON
+  in the standard library. Nothing to vendor, nothing to audit but the code you
+  see.
+
+## Install
+
+```ruby
+# Gemfile
+gem "truffle"
+```
+
+```sh
+bundle install
+```
+
+Or from a checkout:
+
+```sh
+gem build truffle.gemspec
+gem install ./truffle-0.1.0.gem
+```
+
+Truffle targets Ruby >= 3.1.
+
+## Quick start
+
+Set your key and run the bundled calculator example, which shows the model
+chaining several tool calls:
+
+```sh
+export OPENAI_API_KEY=sk-...
+ruby examples/calculator.rb "What is (12 + 8) multiplied by 7, then add 100?"
+```
+
+```
+Q: What is (12 + 8) multiplied by 7, then add 100?
+------------------------------------------------------------
+  -> calling add(a=12, b=8)
+  <- add returned 20
+  -> calling multiply(a=20, b=7)
+  <- multiply returned 140
+  -> calling add(a=140, b=100)
+  <- add returned 240
+------------------------------------------------------------
+A: The final result is 240.
+```
+
+## Core concepts
+
+### Tools
+
+```ruby
+add = Truffle.tool("add", "Add two integers") do
+  param :a, :integer, "first addend", required: true
+  param :b, :integer, "second addend", required: true
+  run { |a:, b:| a + b }
+end
+```
+
+- `param name, type, description, required:` declares an input. Types map to
+  JSON Schema (`:string`, `:integer`, `:number`, `:boolean`, ...).
+- `run { |a:, b:| ... }` is your handler. The model emits string keys; Truffle
+  symbolizes them into keyword args. Return any value; it is stringified before
+  it goes back to the model.
+- Raising inside a handler does not crash the loop. The error is caught and fed
+  back to the model as the tool result, so it can recover or apologize.
+
+### Agents
+
+```ruby
+agent = Truffle.agent(
+  provider: :openai,
+  model: "gpt-4o-mini",
+  system_prompt: "You are a precise calculator.",
+  tools: [add],
+  max_turns: 12
+)
+
+answer = agent.run("What is 2 + 3?")
+agent.reset   # clears history, keeps the system prompt and tools
+```
+
+`run` drives the loop to completion and returns the final assistant text.
+`max_turns` guards against a model that never settles; exceeding it raises
+`Truffle::Error`.
+
+### Events
+
+```ruby
+agent.on(:tool_call)   { |e| puts "-> #{e[:call].name}(#{e[:call].arguments})" }
+agent.on(:tool_result) { |e| puts "<- #{e[:result]}" }
+agent.on               { |type, payload| logger.debug(type => payload) }  # every event
+```
+
+Events fire in order: `agent_start`, then per turn `turn_start`, `message`,
+`tool_call`/`tool_result` (one pair per tool the model invokes), `turn_end`,
+and finally `agent_end`.
+
+### Providers
+
+A provider is anything that implements:
+
+```ruby
+def chat(messages:, tools:, model: nil, **options)
+  # -> Truffle::Response
+end
+```
+
+The bundled `Truffle::Providers::OpenAI` talks to the Chat Completions API over
+`Net::HTTP`. To target another backend, subclass `Truffle::Providers::Base` and
+implement `chat`. The roadmap adds first-class Anthropic and other providers,
+each hand-written against the seam.
+
+## Testing
+
+```sh
+rake test
+```
+
+The default suite is hermetic and offline: it drives the agent loop with a stub
+provider, so you can run it anywhere without a key. One additional test
+(`test/test_openai_integration.rb`) performs a real OpenAI round trip and is
+**skipped unless `OPENAI_API_KEY` is set**. With a key present it verifies the
+full path: prompt -> model requests a tool -> Truffle runs it -> model answers
+with the tool's result.
+
+No local Ruby? The repo ships `script/rb`, a thin wrapper that runs any command
+inside a `ruby:3.3-slim` container, so `script/rb rake test` works on a host
+with only Docker.
+
+## Project layout
+
+```
+lib/truffle.rb                  # top-level API: Truffle.agent, Truffle.tool, Truffle.provider
+lib/truffle/agent.rb            # the agent loop (the heart of the port)
+lib/truffle/tool.rb             # tool DSL + JSON Schema generation
+lib/truffle/toolbox.rb          # a named collection of tools
+lib/truffle/message.rb          # message + tool-call value objects
+lib/truffle/response.rb         # a provider's reply
+lib/truffle/providers/base.rb   # the provider seam
+lib/truffle/providers/openai.rb # OpenAI Chat Completions provider
+examples/calculator.rb       # runnable multi-tool demo
+test/                        # minitest suite (offline + one live test)
+```
+
+## Credits
+
+Truffle is a from-scratch Ruby port of
+[pi](https://github.com/earendil-works/pi) by Mario Zechner (MIT). pi is the
+blueprint; the Ruby implementation is written from the ground up. Thanks to the
+pi project for the design.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

data/lib/truffle/agent.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Truffle
+  # A stateful agent: a provider, a system prompt, a running message history,
+  # and a toolbox. Calling #run drives the agent loop to completion.
+  #
+  # The loop is the port of pi's agent-core runtime:
+  #
+  #   run(text)
+  #     emit :agent_start
+  #     append user message
+  #     loop:
+  #       emit :turn_start
+  #       response = provider.chat(messages, tools)
+  #       append assistant message; emit :message
+  #       if response has tool calls:
+  #         for each call: emit :tool_call, run tool, append tool result,
+  #                        emit :tool_result
+  #         emit :turn_end ; continue   # feed results back to the model
+  #       else:
+  #         emit :turn_end ; emit :agent_end ; return assistant text
+  #
+  # Events let a UI (TUI, web, logs) observe the run without the harness
+  # knowing anything about how it is rendered. Subscribe with #on.
+  class Agent
+    DEFAULT_MAX_TURNS = 12
+
+    EVENTS = %i[agent_start turn_start message tool_call tool_result turn_end agent_end].freeze
+
+    attr_reader :provider, :messages, :toolbox, :system_prompt, :max_turns
+
+    def initialize(provider:, system_prompt: nil, tools: [], model: nil,
+                   max_turns: DEFAULT_MAX_TURNS)
+      @provider = provider
+      @system_prompt = system_prompt
+      @model = model
+      @max_turns = max_turns
+      @toolbox = tools.is_a?(Toolbox) ? tools : Toolbox.new(tools)
+      @listeners = Hash.new { |h, k| h[k] = [] }
+
+      @messages = []
+      @messages << Message.system(system_prompt) if system_prompt
+    end
+
+    # Register a listener. `on(:tool_call) { |payload| ... }` for one event, or
+    # `on { |type, payload| ... }` (no event arg) for every event.
+    def on(event = nil, &block)
+      raise ArgumentError, "on requires a block" unless block
+
+      if event.nil?
+        @listeners[:_all] << block
+      else
+        event = event.to_sym
+        unless EVENTS.include?(event)
+          raise ArgumentError, "unknown event #{event.inspect}, expected one of #{EVENTS.inspect}"
+        end
+        @listeners[event] << block
+      end
+      self
+    end
+
+    # Send a user message and run the loop until the model answers without
+    # requesting a tool. Returns the final assistant text.
+    def run(user_input)
+      emit(:agent_start, input: user_input)
+      @messages << Message.user(user_input)
+
+      final_text = nil
+      turns = 0
+
+      loop do
+        turns += 1
+        if turns > max_turns
+          raise Error, "exceeded max_turns (#{max_turns}) without a final answer"
+        end
+
+        emit(:turn_start, turn: turns)
+        response = @provider.chat(messages: @messages, tools: @toolbox.to_schema, model: @model)
+        @messages << response.message
+        emit(:message, message: response.message, usage: response.usage)
+
+        unless response.tool_calls?
+          final_text = response.text
+          emit(:turn_end, turn: turns, tool_results: [])
+          break
+        end
+
+        tool_results = run_tool_calls(response.tool_calls)
+        emit(:turn_end, turn: turns, tool_results: tool_results)
+      end
+
+      emit(:agent_end, output: final_text, messages: @messages)
+      final_text
+    end
+
+    # Reset history back to just the system prompt (keeps tools + listeners).
+    def reset
+      @messages = []
+      @messages << Message.system(@system_prompt) if @system_prompt
+      self
+    end
+
+    private
+
+    def run_tool_calls(tool_calls)
+      tool_calls.map do |call|
+        emit(:tool_call, call: call)
+        result = execute(call)
+        message = Message.tool(content: result, tool_call_id: call.id, name: call.name)
+        @messages << message
+        emit(:tool_result, call: call, result: result, message: message)
+        result
+      end
+    end
+
+    def execute(call)
+      tool = @toolbox[call.name]
+      return "Error: unknown tool '#{call.name}'" if tool.nil?
+
+      tool.call(call.arguments)
+    rescue StandardError => e
+      # A tool raising should not kill the loop; report it back to the model so
+      # it can recover or apologize. This mirrors how pi treats tool failures.
+      "Error running tool '#{call.name}': #{e.class}: #{e.message}"
+    end
+
+    def emit(event, **payload)
+      @listeners[event].each { |l| l.call(payload) }
+      @listeners[:_all].each { |l| l.call(event, payload) }
+    end
+  end
+end

data/lib/truffle/message.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Truffle
+  # A single message in an agent conversation.
+  #
+  # Truffle works with one flat message type across every provider. The provider
+  # layer is responsible for translating these into whatever wire shape a given
+  # API expects (see Truffle::Providers::Base#serialize_messages). Keeping a single
+  # in-memory representation is what lets the agent loop stay provider-agnostic.
+  #
+  # Roles:
+  #   :system    - instructions that steer the assistant
+  #   :user      - input from the human (or upstream caller)
+  #   :assistant - a model turn; may carry tool_calls instead of (or with) text
+  #   :tool      - the result of running a tool, linked by tool_call_id
+  class Message
+    ROLES = %i[system user assistant tool].freeze
+
+    attr_reader :role, :content, :tool_calls, :tool_call_id, :name
+
+    def initialize(role:, content: nil, tool_calls: [], tool_call_id: nil, name: nil)
+      role = role.to_sym
+      unless ROLES.include?(role)
+        raise ArgumentError, "unknown role #{role.inspect}, expected one of #{ROLES.inspect}"
+      end
+
+      @role = role
+      @content = content
+      @tool_calls = tool_calls || []
+      @tool_call_id = tool_call_id
+      @name = name
+    end
+
+    def self.system(content)
+      new(role: :system, content: content)
+    end
+
+    def self.user(content)
+      new(role: :user, content: content)
+    end
+
+    def self.assistant(content: nil, tool_calls: [])
+      new(role: :assistant, content: content, tool_calls: tool_calls)
+    end
+
+    # A tool result message, linked back to the assistant tool call by id.
+    def self.tool(content:, tool_call_id:, name: nil)
+      new(role: :tool, content: content, tool_call_id: tool_call_id, name: name)
+    end
+
+    def tool_calls?
+      !@tool_calls.empty?
+    end
+
+    def to_h
+      {
+        role: role,
+        content: content,
+        tool_calls: tool_calls.map(&:to_h),
+        tool_call_id: tool_call_id,
+        name: name
+      }.compact
+    end
+  end
+
+  # A single tool invocation requested by the model.
+  ToolCall = Struct.new(:id, :name, :arguments, keyword_init: true) do
+    # arguments is always a parsed Hash with string keys, mirroring the JSON the
+    # model emitted. The agent symbolizes keys before handing them to the tool.
+    def to_h
+      { id: id, name: name, arguments: arguments }
+    end
+  end
+end

data/lib/truffle/providers/base.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Truffle
+  module Providers
+    # The contract every provider implements. This single seam is what makes
+    # Truffle provider-agnostic: the agent loop only ever calls #chat and reads a
+    # Truffle::Response back. Swapping OpenAI for Anthropic or a local model is a
+    # one-line change at construction time. Every provider is written from
+    # scratch against this seam; there are no runtime gem dependencies.
+    #
+    # Subclasses must implement #chat. They are free to translate Truffle::Message
+    # objects and tool schemas into their native wire format however they like.
+    class Base
+      # @param messages [Array<Truffle::Message>] the conversation so far
+      # @param tools [Array<Hash>] provider-neutral tool schemas (Toolbox#to_schema)
+      # @param model [String, nil] override the default model for this call
+      # @return [Truffle::Response]
+      def chat(messages:, tools: [], model: nil, **options)
+        raise NotImplementedError, "#{self.class} must implement #chat"
+      end
+
+      # Human-readable provider id, used in events and errors.
+      def name
+        self.class.name.split("::").last.downcase
+      end
+    end
+
+    # Raised when a provider's HTTP call fails or returns an error payload.
+    class Error < StandardError; end
+  end
+end

data/lib/truffle/providers/openai.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Truffle
+  module Providers
+    # OpenAI Chat Completions provider with tool calling.
+    #
+    # Deliberately dependency-free: it speaks the HTTP API directly with
+    # Net::HTTP and the stdlib JSON, so a fresh Ruby can run Truffle with nothing
+    # but `gem install truffle`. It also works against any OpenAI-compatible
+    # endpoint (Ollama, vLLM, Together, OpenRouter, ...) by passing :base_url.
+    class OpenAI < Base
+      DEFAULT_MODEL = "gpt-4o-mini"
+      DEFAULT_BASE_URL = "https://api.openai.com/v1"
+
+      attr_reader :model
+
+      def initialize(api_key: ENV["OPENAI_API_KEY"], model: DEFAULT_MODEL,
+                     base_url: DEFAULT_BASE_URL, open_timeout: 15, read_timeout: 120)
+        super()
+        raise ArgumentError, "missing OpenAI API key (set OPENAI_API_KEY or pass :api_key)" if api_key.nil? || api_key.empty?
+
+        @api_key = api_key
+        @model = model
+        @base_url = base_url.chomp("/")
+        @open_timeout = open_timeout
+        @read_timeout = read_timeout
+      end
+
+      def name
+        "openai"
+      end
+
+      def chat(messages:, tools: [], model: nil, **options)
+        body = {
+          model: model || @model,
+          messages: serialize_messages(messages)
+        }
+        unless tools.empty?
+          body[:tools] = tools.map { |t| { type: "function", function: t } }
+          body[:tool_choice] = options.fetch(:tool_choice, "auto")
+        end
+        body[:temperature] = options[:temperature] if options.key?(:temperature)
+        body[:max_tokens] = options[:max_tokens] if options.key?(:max_tokens)
+
+        payload = post("/chat/completions", body)
+        choice = payload.fetch("choices").first
+        Response.new(
+          message: deserialize_message(choice.fetch("message")),
+          usage: payload["usage"] || {},
+          raw: payload,
+          model: payload["model"],
+          finish_reason: choice["finish_reason"]
+        )
+      end
+
+      private
+
+      def serialize_messages(messages)
+        messages.map do |m|
+          case m.role
+          when :assistant
+            h = { role: "assistant", content: m.content }
+            unless m.tool_calls.empty?
+              h[:tool_calls] = m.tool_calls.map do |tc|
+                {
+                  id: tc.id,
+                  type: "function",
+                  function: { name: tc.name, arguments: JSON.generate(tc.arguments) }
+                }
+              end
+            end
+            h
+          when :tool
+            { role: "tool", tool_call_id: m.tool_call_id, content: m.content.to_s }
+          else
+            { role: m.role.to_s, content: m.content.to_s }
+          end
+        end
+      end
+
+      def deserialize_message(raw)
+        tool_calls = Array(raw["tool_calls"]).map do |tc|
+          fn = tc["function"] || {}
+          ToolCall.new(
+            id: tc["id"],
+            name: fn["name"],
+            arguments: parse_arguments(fn["arguments"])
+          )
+        end
+        Message.assistant(content: raw["content"], tool_calls: tool_calls)
+      end
+
+      def parse_arguments(raw)
+        return {} if raw.nil? || raw == ""
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        # A model very occasionally emits malformed JSON for arguments. Surface
+        # the raw string under a sentinel key rather than crashing the loop.
+        { "_raw" => raw }
+      end
+
+      def post(path, body)
+        uri = URI("#{@base_url}#{path}")
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = @open_timeout
+        http.read_timeout = @read_timeout
+
+        request = Net::HTTP::Post.new(uri)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+
+        response = http.request(request)
+        unless response.is_a?(Net::HTTPSuccess)
+          raise Error, "OpenAI #{response.code}: #{truncate(response.body)}"
+        end
+
+        JSON.parse(response.body)
+      rescue JSON::ParserError => e
+        raise Error, "could not parse OpenAI response: #{e.message}"
+      end
+
+      def truncate(str, limit = 500)
+        s = str.to_s
+        s.length > limit ? "#{s[0, limit]}..." : s
+      end
+    end
+  end
+end

data/lib/truffle/response.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Truffle
+  # A normalized response from a provider's chat call.
+  #
+  # Every provider returns one of these regardless of its native wire format, so
+  # the agent loop never has to branch on which model it is talking to.
+  class Response
+    attr_reader :message, :usage, :raw, :model, :finish_reason
+
+    def initialize(message:, usage: {}, raw: nil, model: nil, finish_reason: nil)
+      @message = message
+      @usage = usage || {}
+      @raw = raw
+      @model = model
+      @finish_reason = finish_reason
+    end
+
+    # The text content of the assistant turn (may be nil on a pure tool call).
+    def text
+      message.content
+    end
+
+    def tool_calls
+      message.tool_calls
+    end
+
+    def tool_calls?
+      message.tool_calls?
+    end
+  end
+end

data/lib/truffle/tool.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Truffle
+  # A tool the agent can call.
+  #
+  # A tool is a name, a human-readable description (the model reads this to
+  # decide when to call it), a JSON-Schema parameter spec, and a callable that
+  # actually runs. Build one with the block DSL:
+  #
+  #   weather = Truffle::Tool.define("get_weather", "Look up the weather for a city") do
+  #     param :city, :string, "City name, e.g. 'Berlin'", required: true
+  #     param :units, :string, "celsius or fahrenheit"
+  #     run { |city:, units: "celsius"| WeatherApi.fetch(city, units) }
+  #   end
+  #
+  # The block runs in a small builder context so `param` and `run` read cleanly.
+  class Tool
+    attr_reader :name, :description, :parameters, :handler
+
+    def initialize(name:, description:, parameters:, handler:)
+      @name = name.to_s
+      @description = description.to_s
+      @parameters = parameters
+      @handler = handler
+    end
+
+    def self.define(name, description, &block)
+      builder = Builder.new
+      builder.instance_eval(&block) if block
+      new(
+        name: name,
+        description: description,
+        parameters: builder.schema,
+        handler: builder.handler
+      )
+    end
+
+    # Run the tool. `arguments` is a Hash with string keys (as the model emits);
+    # they are symbolized so the handler can use keyword arguments.
+    def call(arguments)
+      kwargs = (arguments || {}).each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+      result = handler.call(**kwargs)
+      result.is_a?(String) ? result : result.inspect
+    end
+
+    # JSON-Schema-shaped function spec, provider-neutral. Providers wrap this in
+    # whatever envelope they need (OpenAI: {type:"function", function:{...}}).
+    def to_schema
+      {
+        name: name,
+        description: description,
+        parameters: parameters
+      }
+    end
+
+    # Collects param declarations and the run block into a JSON Schema + handler.
+    class Builder
+      attr_reader :handler
+
+      def initialize
+        @properties = {}
+        @required = []
+        @handler = ->(**) { "" }
+      end
+
+      def param(name, type, description = nil, required: false, **extra)
+        spec = { type: type.to_s }
+        spec[:description] = description if description
+        spec.merge!(extra)
+        @properties[name.to_s] = spec
+        @required << name.to_s if required
+        self
+      end
+
+      def run(&block)
+        raise ArgumentError, "run requires a block" unless block
+
+        @handler = block
+      end
+
+      def schema
+        {
+          type: "object",
+          properties: @properties,
+          required: @required
+        }
+      end
+    end
+  end
+end

data/lib/truffle/toolbox.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Truffle
+  # An ordered collection of tools the agent can reach for, keyed by name.
+  class Toolbox
+    include Enumerable
+
+    def initialize(tools = [])
+      @tools = {}
+      Array(tools).each { |t| add(t) }
+    end
+
+    def add(tool)
+      @tools[tool.name] = tool
+      self
+    end
+    alias << add
+
+    def [](name)
+      @tools[name.to_s]
+    end
+
+    def each(&block)
+      @tools.values.each(&block)
+    end
+
+    def empty?
+      @tools.empty?
+    end
+
+    def names
+      @tools.keys
+    end
+
+    # Provider-neutral schemas for every tool, in declared order.
+    def to_schema
+      @tools.values.map(&:to_schema)
+    end
+  end
+end

data/lib/truffle/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Truffle
+  VERSION = "0.1.0"
+end

data/lib/truffle.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative "truffle/version"
+require_relative "truffle/message"
+require_relative "truffle/response"
+require_relative "truffle/tool"
+require_relative "truffle/toolbox"
+require_relative "truffle/providers/base"
+require_relative "truffle/providers/openai"
+require_relative "truffle/agent"
+
+# 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?")
+module Truffle
+  # Generic Truffle error type; provider HTTP errors are Truffle::Providers::Error.
+  class Error < StandardError; end
+
+  PROVIDERS = {
+    openai: Providers::OpenAI
+  }.freeze
+
+  module_function
+
+  # Build a provider by symbol (:openai) or pass a ready-made instance through.
+  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
+
+  # Convenience constructor: Truffle.agent(provider: :openai, tools: [...], ...).
+  # `provider:` may be a symbol, an options-less default, or a provider instance.
+  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
+
+  # Define a tool: Truffle.tool("name", "desc") { param ...; run { ... } }.
+  def tool(name, description, &block)
+    Tool.define(name, description, &block)
+  end
+end

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification
+name: truffle
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Truffle
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-06-28 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Truffle is a dependency-free agent harness for Ruby, built from scratch as a
+  faithful port of earendil-works/pi: a provider-agnostic LLM seam, an agent
+  loop with tool calling and state, an event-streaming protocol for UIs, and a
+  foundation for skills, commands, sessions, and memory. No runtime gem
+  dependencies; the LLM client, tool layer, and event model are written from
+  the ground up.
+email:
+- truffleagent@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/truffle.rb
+- lib/truffle/agent.rb
+- lib/truffle/message.rb
+- lib/truffle/providers/base.rb
+- lib/truffle/providers/openai.rb
+- lib/truffle/response.rb
+- lib/truffle/tool.rb
+- lib/truffle/toolbox.rb
+- lib/truffle/version.rb
+homepage: https://github.com/truffle-dev/truffle-rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/truffle-dev/truffle-rb
+  source_code_uri: https://github.com/truffle-dev/truffle-rb
+  changelog_uri: https://github.com/truffle-dev/truffle-rb/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: A complete agent harness for Ruby.
+test_files: []