rixie 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8323f9bcb6b861edc4ef4db226ea11787008d527b68002827308795e4931bedd
+  data.tar.gz: cb598addd4243e6dc89140183b144017ace53b5e2774c861c8f37198583be079
+SHA512:
+  metadata.gz: eb038298807744075f868d8fd45053b32f6512939a5c51b5d798ffbdf4d59bdb11eb88477f836545bd179970839be4ce1c4f6c93b77a3a98e25a693cdcc0f766
+  data.tar.gz: de459ad3a0dcab97f37b0972f42bd642207bb6193d137bcd232a3ff7afb547e25121f1205f2ad0cef3a1203a892dd76f87c24d030c916869cae513fc6a056926

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-29
+
+Initial release. Requires Ruby 3.4 or newer.
+
+### Added
+
+- Conceptual hierarchy: `Session → Task → Run → Agent` with the think+act loop.
+- Strategies: `Simple`, `PlanExecute`, `ReAct`.
+- Built-in tools: `HumanInput`, `Fetch`, `WebSearch`, `WikipediaSearch`,
+  `CurrentTime`, `Calculator`, `FileRead`, `FileList`, `FileSearch`.
+- LLM provider support: `openai` and any OpenAI-compatible endpoint
+  (GitHub Models, Ollama).
+- MCP (Model Context Protocol) HTTP client for importing remote tools.
+- Interactive CLI (`bin/rixie`) with slash commands, tab completion,
+  and markdown rendering.
+- Streaming via `Session#live`.
+- Context compression via `Session#compress!`.
+- Multi-agent orchestration: wrap a `Session` as a tool.
+- Event bus with pluggable subscribers. Built-in:
+  `Subscribers::Logger` (text) and `Subscribers::JsonLogger` (one JSON
+  object per event). Both dispatch through `Subscribers::EventSeverity`,
+  which maps each event to a `::Logger` severity (`:debug` for
+  per-iteration events, `:warn` for failures, `:info` otherwise).
+- Shared `Rixie::Http::Client` with SSRF protection, gzip/deflate
+  decoding, and `allow_private:` opt-out for trusted endpoints.
+- Optional runtime dependencies: `openai`, `nokogiri`, `cli-ui`.
+  Each raises `Rixie::ConfigurationError` with an actionable message
+  when used without the gem installed.
+
+[Unreleased]: https://github.com/madogiwa0124/rixie/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/madogiwa0124/rixie/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 madogiwa0124
+
+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,69 @@
+# Rixie
+
+AI agent orchestration for Ruby.
+
+## Overview
+
+Rixie is a standalone Ruby gem for orchestrating AI agents — no Rails required.
+
+An **Agent** thinks and acts via an LLM and a set of tools, looping until it reaches a final answer. A **Session** manages the full conversation, accumulating history across multiple chats. A **Strategy** controls how a goal is accomplished: the default `Simple` strategy runs a single agent loop, while `PlanExecute` first builds a step-by-step plan and then executes each step in sequence.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "rixie"
+```
+
+Rixie keeps its runtime footprint small. The following gems are **optional** — add them only for the features you actually use. Each is loaded lazily and raises `Rixie::ConfigurationError` with an actionable message if missing.
+
+```ruby
+gem "openai"     # required for the openai / ollama provider adapter (and any OpenAI-compatible endpoint)
+gem "nokogiri"   # required for Rixie::Tool::Fetch and Rixie::Tool::WebSearch (DuckDuckGo HTML parsing)
+gem "cli-ui"     # required to run the `rixie` CLI (bin/rixie)
+```
+
+## Quick Start
+
+```ruby
+require "rixie"
+
+Rixie.configure do |config|
+  config.default_provider = "openai"
+  config.default_model    = "gpt-4.1-mini"
+end
+
+session = Rixie::Session.new(instructions: "You are a helpful assistant.")
+puts session.chat("What is the capital of France?")
+# => "The capital of France is Paris."
+```
+
+## Architecture
+
+```
+Session          # manages the full conversation; accumulates history across chats
+└── Task         # accomplishes a single goal; owns a Strategy
+    └── Run × N  # one LLM loop per step; calls Agent#think
+        └── Agent         # thinks and acts: calls the LLM, executes tools, loops until done
+```
+
+| Class | Responsibility |
+| --- | --- |
+| `Session` | Entry point. Resolves config, creates `Agent` and `LLM::Client`, exposes `chat` and `live`. |
+| `Task` | Runs a `Strategy` and accumulates `Run` results. Manages an `EventListener`. |
+| `Run` | Calls `agent.think` once. Accumulates tool-call steps. |
+| `Agent` | The think-act loop: calls the LLM, executes tools, emits events. |
+| `Strategy` | Controls how many Runs a Task executes. `Simple` = 1 Run; `PlanExecute` = plan + N Runs. |
+
+## Features
+
+- **[Configuration](docs/configuration.md)** — Configure providers, models, and persistence. Use OpenAI-compatible endpoints (GitHub Models, Ollama) or plug in a custom LLM adapter.
+- **[CLI](docs/cli.md)** — Interactive REPL with slash commands, tab completion, and extensibility via custom commands and tools.
+- **[Tools](docs/tools.md)** — Define your own tools and use the built-ins: web (Fetch, WebSearch, WikipediaSearch), filesystem (FileRead, FileList, FileSearch), utilities (CurrentTime, Calculator), and HumanInput for human-in-the-loop flows.
+- **[Strategies](docs/strategies.md)** — `Simple` for single-loop tasks, `PlanExecute` for plan-then-execute multi-step tasks, `ReAct` for explicit Thought → Action → Observation reasoning traces.
+- **[MCP](docs/mcp.md)** — Connect to any MCP (Model Context Protocol) server over HTTP and import its tools automatically.
+- **[Multi-Agent Orchestration](docs/multi-agent.md)** — Compose agents by wrapping a `Session` as a tool, with isolated context per sub-agent.
+- **[Subscribers](docs/subscribers.md)** — Observe agent behavior via the event bus — built-in logging plus pluggable subscribers (e.g. OpenTelemetry).
+- **[Streaming](docs/streaming.md)** — Stream tokens, tool calls, and lifecycle events via `Session#live`.
+- **[Context Compression](docs/context-compression.md)** — Summarize accumulated history to control token usage in long sessions.

data/bin/rixie

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "rixie"
+require "rixie/cli"
+
+Rixie::CLI.start(ARGV)

data/lib/rixie/agent/compressor.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Rixie
+  class Agent
+    class Compressor
+      DEFAULT_SUMMARIZATION_INSTRUCTIONS = <<~INSTRUCTIONS
+        You are a conversation summarizer.
+        Summarize the following conversation history concisely,
+        preserving key facts, decisions, and context needed
+        for future interactions. Do not add commentary.
+      INSTRUCTIONS
+
+      def initialize(base_agent:, summarization_instructions: DEFAULT_SUMMARIZATION_INSTRUCTIONS)
+        @base_agent = base_agent
+        @summarization_instructions = summarization_instructions
+      end
+
+      def instructions
+        @summarization_instructions
+      end
+
+      def tools
+        []
+      end
+
+      def think(messages:, listener:)
+        internal_agent.think(messages:, listener:)
+      end
+
+      private
+
+      def internal_agent
+        @internal_agent ||= Agent.new(
+          instructions: instructions,
+          tools: tools,
+          llm_client: @base_agent.llm_client
+        )
+      end
+    end
+  end
+end

data/lib/rixie/agent/plan.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Rixie
+  class Agent
+    class Plan
+      PLAN_DONE_TOOL = Rixie::Tool.new(
+        name: "plan_done",
+        description: "Call this tool when the plan is complete.",
+        input_schema: {
+          type: "object",
+          properties: {
+            steps: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  title: {type: "string"},
+                  description: {type: "string"}
+                },
+                required: ["title", "description"]
+              }
+            }
+          },
+          required: ["steps"]
+        },
+        call: ->(_args) { "Planning complete." },
+        return_direct: true
+      )
+
+      DEFAULT_PLANNING_INSTRUCTIONS = <<~INSTRUCTIONS
+        Make a plan to accomplish the given task. Do not output any text — call plan_done directly with the plan steps.
+      INSTRUCTIONS
+
+      def initialize(base_agent:, planning_instructions: DEFAULT_PLANNING_INSTRUCTIONS)
+        @base_agent = base_agent
+        @planning_instructions = planning_instructions
+      end
+
+      def instructions
+        [@base_agent.instructions, @planning_instructions].join("\n\n")
+      end
+
+      def tools
+        @base_agent.tools + [PLAN_DONE_TOOL]
+      end
+
+      def think(messages:, listener:)
+        internal_agent.think(messages:, listener:)
+      end
+
+      private
+
+      def internal_agent
+        @internal_agent ||= Agent.new(
+          instructions: instructions,
+          tools: tools,
+          llm_client: @base_agent.llm_client
+        )
+      end
+    end
+  end
+end

data/lib/rixie/agent/re_act.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Rixie
+  class Agent
+    class ReAct
+      DEFAULT_REACT_INSTRUCTIONS = <<~INSTRUCTIONS
+        You are operating in ReAct (Reasoning + Acting) mode.
+
+        For every step that requires a tool, FIRST output your reasoning as plain text BEFORE making the tool call. Format your reasoning as:
+
+        Thought: <one or two sentences explaining what you need to do next and why>
+
+        Then make exactly ONE tool call. Do not call multiple tools at once.
+
+        After the tool returns (an Observation), produce another Thought before the next Action, or provide the final answer if you have enough information to respond.
+
+        The reasoning trace is essential — always include a Thought before each Action.
+      INSTRUCTIONS
+
+      def initialize(base_agent:, react_instructions: DEFAULT_REACT_INSTRUCTIONS)
+        @base_agent = base_agent
+        @react_instructions = react_instructions
+      end
+
+      def instructions
+        [@base_agent.instructions, @react_instructions].compact.reject(&:empty?).join("\n\n")
+      end
+
+      def tools
+        @base_agent.tools
+      end
+
+      def llm_client
+        @base_agent.llm_client
+      end
+
+      def think(messages:, listener:)
+        internal_agent.think(messages:, listener:)
+      end
+
+      private
+
+      def internal_agent
+        @internal_agent ||= Agent.new(
+          instructions: instructions,
+          tools: tools,
+          llm_client: @base_agent.llm_client,
+          parallel_tool_calls: false
+        )
+      end
+    end
+  end
+end

data/lib/rixie/agent.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Rixie
+  class Agent
+    Thought = Data.define(:type, :content, :tool_calls, :tool_results) do
+      def tool_call? = type == :tool_call
+      def finish? = type == :finish
+    end
+
+    ThinkResult = Data.define(:content, :thoughts)
+
+    DEFAULT_MAX_STEPS = 10
+
+    attr_reader :instructions, :tools, :llm_client, :parallel_tool_calls
+
+    def initialize(instructions:, llm_client:, tools: [], max_steps: nil, parallel_tool_calls: false)
+      @instructions = instructions
+      @tools = tools
+      @max_steps = max_steps || DEFAULT_MAX_STEPS
+      @parallel_tool_calls = parallel_tool_calls
+      @tool_executor = ToolExecutor.new(tools: tools)
+      @llm_client = llm_client
+    end
+
+    def with_llm_client(llm_client)
+      Agent.new(
+        instructions: @instructions,
+        tools: @tools,
+        max_steps: @max_steps,
+        llm_client: llm_client,
+        parallel_tool_calls: @parallel_tool_calls
+      )
+    end
+
+    def think(messages:, listener:)
+      thoughts = []
+      tool_call_count = 0
+      step_count = 0
+
+      loop do
+        step_count += 1
+        listener.emit(Event::LlmCallStart.new(step_count: step_count))
+        thought = llm_call(messages:) { |event| listener.emit(event) }
+
+        if thought.tool_call?
+          raise MaxStepsExceededError, "Max steps (#{@max_steps}) exceeded" if tool_call_count >= @max_steps
+          tool_call_count += 1
+          results = call_thought_tools(
+            on_start: ->(tc) { listener.emit(Event::ToolCallStart.new(tool_call: tc)) },
+            thought: thought,
+            on_end: ->(tc, result) { listener.emit(Event::ToolCallEnd.new(tool_call: tc, result: result)) },
+            parallel: @parallel_tool_calls
+          )
+
+          listener.emit(Event::ToolCallsCompleted.new(tool_calls: thought.tool_calls, tool_results: results))
+
+          thought = record_thought(thoughts, thought, results)
+          append_thought_messages(messages, thought)
+
+          if @tool_executor.return_direct?(thought.tool_calls)
+            listener.emit(Event::Finished.new(content: nil))
+            return ThinkResult.new(content: nil, thoughts: thoughts)
+          end
+        elsif thought.finish?
+          thoughts << thought
+          listener.emit(Event::ThoughtCompleted.new(thought: thought))
+          listener.emit(Event::Finished.new(content: thought.content))
+          return ThinkResult.new(content: thought.content, thoughts: thoughts)
+        else
+          raise Rixie::AgentError, "Unknown thought type: #{thought.type.inspect}"
+        end
+      end
+    end
+
+    private
+
+    def call_thought_tools(on_start:, thought:, on_end:, parallel:)
+      thought.tool_calls.each { |tc| on_start.call(tc) }
+      results = parallel ? concurrent_map(thought.tool_calls) { |tc| @tool_executor.execute(tc) } : thought.tool_calls.map { |tc| @tool_executor.execute(tc) }
+      thought.tool_calls.zip(results).each { |tc, result| on_end.call(tc, result) }
+      results
+    end
+
+    def concurrent_map(items, &block)
+      # Capture exceptions as values inside each thread so no thread dies with an unhandled exception.
+      # This prevents stderr noise from Thread.report_on_exception and ensures all threads are joined
+      # before raising. Ruby has no safe cancellation, so we always wait for every thread to finish.
+      threads = items.map do |item|
+        Thread.new do
+          {ok: block.call(item)}
+        rescue => e
+          {err: e}
+        end
+      end
+      outcomes = threads.map(&:value)
+      first_error = outcomes.find { |o| o.key?(:err) }&.fetch(:err)
+      raise first_error if first_error
+      outcomes.map { |o| o[:ok] }
+    end
+
+    def record_thought(thoughts, thought, results)
+      thought = thought.with(tool_results: results)
+      thoughts << thought
+      thought
+    end
+
+    def append_thought_messages(messages, thought)
+      messages << Message::Assistant.new(content: thought.content, tool_calls: thought.tool_calls)
+      thought.tool_results.each { |r| messages << Message::Tool.new(tool_call_id: r.tool_call_id, content: r.content) }
+    end
+
+    def llm_call(messages:, &on_event)
+      response = @llm_client.call(messages, tools: @tool_executor.definitions) { |event| on_event.call(event) }
+      raise LLM::ResponseTruncatedError, "LLM response truncated (finish_reason=length)" if response.finish_reason == "length"
+      if response.has_tool_calls?
+        Thought.new(type: :tool_call, content: response.content, tool_calls: response.tool_calls, tool_results: nil)
+      else
+        Thought.new(type: :finish, content: response.content, tool_calls: [], tool_results: nil)
+      end
+    end
+  end
+end

data/lib/rixie/cli/commands/base.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Rixie
+  class CLI
+    module Commands
+      class Base
+        def initialize(renderer:)
+          @renderer = renderer
+        end
+
+        def name
+          raise NotImplementedError
+        end
+
+        def description
+          raise NotImplementedError
+        end
+
+        def call(arg, cli:)
+          raise NotImplementedError
+        end
+
+        def complete(input)
+          []
+        end
+
+        private
+
+        attr_reader :renderer
+      end
+    end
+  end
+end

data/lib/rixie/cli/commands/compress.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Rixie
+  class CLI
+    module Commands
+      class Compress < Base
+        def name = "compress"
+
+        def description = "Compress conversation context into a summary (optionally keep N recent entries)"
+
+        def call(arg, cli:)
+          keep_recent = parse_keep_recent(arg)
+          return renderer.error("Invalid argument: expected a non-negative integer") if keep_recent.nil?
+
+          if cli.current_context_length.zero?
+            renderer.info("Context", "Already empty, nothing to compress")
+            return
+          end
+
+          before_size = cli.current_context_size
+          renderer.start_spinner
+          cli.compress!(keep_recent: keep_recent)
+          renderer.stop_spinner
+
+          after_size = cli.current_context_size
+          if after_size >= before_size
+            renderer.info("Notice", "Compression did not reduce context size (~#{before_size} → ~#{after_size} tokens). Context may be too small to benefit from compression.")
+          else
+            renderer.success("Compressed ~#{before_size} → ~#{after_size} tokens")
+          end
+        rescue => e
+          renderer.stop_spinner
+          renderer.error(e.message)
+        end
+
+        private
+
+        def parse_keep_recent(arg)
+          return 0 if arg.nil? || arg.strip.empty?
+
+          n = Integer(arg.strip)
+          (n >= 0) ? n : nil
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rixie/cli/commands/context.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Rixie
+  class CLI
+    module Commands
+      class Context < Base
+        def name = "context"
+
+        def description = "Show current context size"
+
+        def call(_arg, cli:)
+          renderer.info("Context size", "~#{cli.current_context_size} tokens")
+          renderer.info("Entries", cli.current_context_length.to_s)
+        end
+      end
+    end
+  end
+end

data/lib/rixie/cli/commands/help.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Rixie
+  class CLI
+    module Commands
+      class Help < Base
+        def name = "help"
+
+        def description = "Show available commands"
+
+        def call(_arg, cli:)
+          renderer.heading("Commands:")
+          cli.commands.each do |cmd|
+            renderer.text("#{renderer.accent("/#{cmd.name}")}  — #{cmd.description}")
+          end
+          renderer.text("#{renderer.accent("exit")}  — Quit")
+        end
+      end
+    end
+  end
+end

data/lib/rixie/cli/commands/model.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Rixie
+  class CLI
+    module Commands
+      class Model < Base
+        def name = "model"
+
+        def description = "Switch LLM model"
+
+        def call(arg, cli:)
+          if arg && !arg.empty?
+            new_model = arg.strip
+            return if new_model.empty?
+
+            cli.switch_model(new_model)
+            renderer.success("Model set to #{renderer.bold(new_model)}")
+          else
+            renderer.info("Current", cli.current_model)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rixie/cli/commands/strategy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rixie
+  class CLI
+    module Commands
+      class Strategy < Base
+        STRATEGIES = {
+          "simple" => Rixie::Strategy::Simple,
+          "plan-execute" => Rixie::Strategy::PlanExecute,
+          "re-act" => Rixie::Strategy::ReAct
+        }.freeze
+
+        def name = "strategy"
+
+        def description = "Switch execution strategy"
+
+        def call(arg, cli:)
+          if arg && !arg.empty?
+            set_strategy(arg.strip, cli:)
+          else
+            renderer.info("Current", cli.strategy_name)
+            renderer.heading("Available:")
+            renderer.list(STRATEGIES.keys, selected: cli.strategy_name)
+          end
+        end
+
+        def complete(input)
+          arg = input.delete_prefix("/strategy ")
+          STRATEGIES.keys.select { |s| s.start_with?(arg) }.map { |s| "/strategy #{s}" }
+        end
+
+        def resolve(name)
+          STRATEGIES[name]&.new
+        end
+
+        private
+
+        def set_strategy(name, cli:)
+          if STRATEGIES.key?(name)
+            cli.strategy_name = name
+            renderer.success("Strategy set to #{renderer.bold(name)}")
+          else
+            renderer.error("Unknown strategy: #{name}")
+            renderer.text("Available: #{STRATEGIES.keys.join(", ")}")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rixie/cli/commands.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "commands/base"
+require_relative "commands/strategy"
+require_relative "commands/model"
+require_relative "commands/context"
+require_relative "commands/compress"
+require_relative "commands/help"