relay.app 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86ff616504751463b8f52d81dadebd1ac6a64d0258891af2072bac9b1409195d
+  data.tar.gz: 8296385a194399d28d981e0def2f45616db12582dfeb4f375587e66a5ee5d2a8
+SHA512:
+  metadata.gz: c211e06e2f5497419e68caab08d305b0506f58945a25f958e869b7b1ee821945d82b964f2e351015da0ce85acecb4722aca0629f0272dc76cedd42a8dd16ccf3
+  data.tar.gz: 1856dc06dfdb09efa579498920c27306a43da5aa7173f25210e3e63c089cd6bb64697b6938c5e484481b638d12542f42782559a8a69fab2492ad6c922a323fbc

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## v0.1.0
+
+First stable release.
+
+### Change
+
+* **Load tools during boot through `Relay.reload`** <br>
+  Call `Relay.reload` from app boot so Relay registers tools before the
+  first request, instead of waiting for a later reload pass.
+
+* **Load user tools from `~/.relay/tools`** <br>
+  Extend `Relay.reload` to load tools from both `app/tools/*.rb` and
+  `~/.relay/tools/*.rb`, so user-installed tools participate in the same
+  registration flow as built-in tools.
+
+### Fix
+
+* **Warn and continue on tool load failures** <br>
+  Rescue tool load errors during `Relay.reload`, print a warning with the
+  exception and backtrace, and continue loading the remaining tool files
+  instead of aborting the full reload pass.

data/LICENSE

@@ -0,0 +1,17 @@
+Copyright (C) 2026
+Antar Azri <azantar@proton.me>
+0x1eef <0x1eef@hardenedbsd.org>
+
+Permission to use, copy, modify, and/or distribute this
+software for any purpose with or without fee is hereby
+granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS
+ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO
+EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
+RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
+OF THIS SOFTWARE.

data/README.md

@@ -0,0 +1,132 @@
+## About
+
+Relay is a self-hostable LLM environment with support for OpenAI, DeepSeek,
+Anthropic, xAI and zAI out of the box. It is incredibly simple to setup
+and get started. The application is distributed as a RubyGem. It has a minimal
+set of dependencies - built on Roda, Sequel, Falcon, [llm.rb](https://github.com/llmrb/llm.rb),
+HTMX and web sockets.
+
+There is support for connecting to MCP servers too - both HTTP and stdio. You can
+add your own tools to `~/.relay/tools` which is a neat way to extend the environment
+with your own functionality. The database uses SQLite3 to keep things simple - the
+goal is to have something you can setup in under two minutes.
+
+## Getting started
+
+#### Install
+
+Install the gem:
+
+```sh
+gem install relay.app
+```
+
+Go through interactive setup, start the server, and visit
+http://localhost:9292.
+
+```sh
+relay setup
+relay start
+```
+
+## Features
+
+* Install and setup in 2 minutes
+* Localize your chats and mcp settings to your user account
+* Connect to multiple providers (OpenAI, xAI, Anthropic, Google, DeepSeek, zAI)
+* Connect to MCP servers
+* Cancel in-flight requests and tool execution cleanly
+* Run tools concurrently
+* Make it yours: extend and customize with your own tools and system prompt
+* Lightweight architecture
+
+## Sounds cool, how does it look?
+
+**Sign-in**
+
+![Relay screenshot](./relay3.png)
+
+**Chat**
+
+![Relay screenshot](./relay1.png)
+
+**MCP**
+
+![Relay screenshot](./relay2.png)
+
+## How easy is it to setup?
+
+Very easy.
+
+![demo](./demo.gif)
+
+## How do I add my own tool?
+
+Before running `relay start` you should add a `~/.relay/tools/<yourtool>.rb`.
+The tool will be automatically made available to the LLM. This is how a tool
+might look - it is not very useful because it does not emit command output
+but it serves as a simple example that you can modify and change to meet
+your requirements:
+
+```ruby
+class Shell < LLM::Tool
+  name "shell"
+  description "Run a shell command"
+  parameter :command, String, "The command to run"
+  parameter :arguments, Array[String], "The command arguments"
+  required %i[command]
+
+  def call(command:, arguments:)
+    {ok: system(command, *arguments)}
+  end
+end
+```
+
+## Wait, what is a tool?
+
+A tool contains a name, a description, and optional parameters. It is attached
+to a method, and that method that can be called. The model or LLM decides when
+and how to call a tool. A tool can do anything you can imagine, and it can extend
+the abilities of the LLM. Suddenly a LLM can search the web, run code, and anything
+you can think of. They're a powerful way to extend the capabilities of an LLM.
+
+An MCP server can also expose pre-packaged tools, and those can be especially
+powerful for talking to GitHub or your own Forgejo instance.
+
+## What are the default tools?
+
+The `relay-knowledge` tool returns documentation for both Relay
+and [llm.rb](https://github.com/llmrb/llm.rb) - ask about either
+of those, and you will be able to have an informed conversation
+about both. Good for learning how to use llm.rb, and write your
+own tools.
+
+There is also a set of tools that manage a playlist of songs that
+can be played inline in the chat, and you can also add your own
+songs or remove existing ones through the same tools. The only
+requirement is that it is a YouTube URL.
+
+## What provider is the best value?
+
+DeepSeek. I highly recommend it. The context window is 1M. I have been using it
+all the time - especially for Relay development, and despite my heavy usage, it
+cost only 80 cents overall. It's almost free. I used it **a lot**. I'd estimate
+that a 1M context window costs 14 cents or so.
+
+## What about Ollama and friends?
+
+[llm.rb](https://github.com/llmrb/llm.rb#readme) provides support ollama, llama.cpp,
+and any OpenAI-compatible endpoint. But Relay does not surface it as a feature. I haven't
+had the time or resources to setup either ollama or llamacpp locally.
+
+## Sources
+
+* [GitHub.com](https://github.com/llmrb/relay)
+* [GitLab.com](https://gitlab.com/llmrb/relay)
+* [Codeberg.org](https://codeberg.org/llmrb/relay)
+
+## License
+
+[BSD Zero Clause](https://choosealicense.com/licenses/0bsd/)
+<br>
+See [LICENSE](./LICENSE)

data/app/concerns/attachment.rb

@@ -0,0 +1,12 @@
+module Relay::Concerns
+  module Attachment
+    def attachment
+      Relay::Attachment.session(
+        session:,
+        root: Relay.home,
+        user: respond_to?(:user) ? user : nil,
+        provider: session["provider"]
+      )
+    end
+  end
+end

data/app/concerns/context.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Relay::Concerns
+  ##
+  # Shared Relay provider, model, and persisted context selection.
+  #
+  # This concern centralizes the session-backed logic for resolving the
+  # current provider, chat model, and
+  # {Relay::Models::Context Relay::Models::Context} so pages and routes
+  # stay in sync.
+  module Context
+    ##
+    # @return [String]
+    #  The requested provider, defaulting to deepseek.
+    def provider
+      session["provider"] || "deepseek"
+    end
+
+    ##
+    # @return [String, nil]
+    #  The requested model.
+    def model
+      session["model"] = normalize_model(session["model"])
+    end
+
+    ##
+    # @return [LLM::Provider]
+    #  The selected provider object.
+    def llm
+      ctx.llm
+    end
+
+    ##
+    # @return [Relay::Models::Context]
+    #  The active persisted context for the current user and provider.
+    def ctx
+      @ctx ||= begin
+        context = current_context || default_context
+        sync_context!(context)
+      end
+    end
+
+    ##
+    # @return [Array<Relay::Models::Context>]
+    #  Saved contexts for the current user and provider, newest first.
+    def contexts
+      @contexts ||= Relay::Models::Context.where(user_id: user.id, provider:)
+        .reverse_order(:updated_at)
+        .all
+        .select { valid_model?(_1[:model]) }
+        .select { _1.messages.any? }
+    end
+
+    ##
+    # @return [Array<Relay::Models::MCP>]
+    #  Saved MCP servers for the current user, newest first.
+    def mcps
+      @mcps ||= user ? Relay::Models::MCP.summary_dataset(user.mcps_dataset).
+        reverse_order(:created_at).
+        all : []
+    end
+
+    ##
+    # @return [Relay::Models::Context, nil]
+    #  The currently selected context for the session, if it matches the
+    #  current provider.
+    def current_context
+      return unless session["context_id"]
+      context = Relay::Models::Context.where(user_id: user.id, provider:, id: session["context_id"]).first
+      return context if context && valid_model?(context[:model])
+      session.delete("context_id")
+      nil
+    end
+
+    ##
+    # @return [Relay::Models::Context]
+    #  The default context for the current provider/model selection.
+    def default_context
+      Relay::Models::Context.where(user_id: user.id, provider:, model:)
+        .reverse_order(:updated_at)
+        .first || Relay::Models::Context.create(user_id: user.id, provider:, model:)
+    end
+
+    ##
+    # @param [Relay::Models::Context] context
+    # @return [Relay::Models::Context]
+    def sync_context!(context)
+      session["context_id"] = context.id
+      session["model"] = normalize_model(context[:model])
+      context
+    end
+
+    ##
+    # @return [Hash<String, LLM::Provider>]
+    #  A map of initialized LLM providers.
+    def llms
+      @llms ||= {
+        "openai" => LLM.openai(key: ENV["OPENAI_SECRET"]),
+        "google" => LLM.google(key: ENV["GOOGLE_SECRET"]),
+        "anthropic" => LLM.anthropic(key: ENV["ANTHROPIC_SECRET"]),
+        "deepseek" => LLM.deepseek(key: ENV["DEEPSEEK_SECRET"]),
+        "xai" => LLM.xai(key: ENV["XAI_SECRET"])
+      }.transform_values(&:persist!)
+    end
+
+    ##
+    # @return [Array<Relay::Models::ModelRecord>]
+    #  Models for the current provider.
+    def models
+      Relay::Models::ModelRecord.where(provider:).order(:name).all
+    end
+
+    ##
+    # @return [String]
+    #  Returns the default chat model for the current provider.
+    def default_model
+      case (provider = llms.fetch(self.provider)).name
+      when :deepseek then "deepseek-v4-flash"
+      when :openai then "gpt-5.4"
+      when :xai then "grok-3"
+      else provider.default_model
+      end
+    end
+
+    ##
+    # @param [String, nil] id
+    # @return [Boolean]
+    def valid_model?(id)
+      models.any? { _1.model_id == id }
+    end
+
+    ##
+    # @param [String, nil] id
+    # @return [String]
+    def normalize_model(id)
+      return id if id && valid_model?(id)
+      default_model
+    end
+
+    ##
+    # @return [Relay::Models::User, nil]
+    def user
+      @user ||= Relay::Models::User[session["user_id"]] if session["user_id"]
+    end
+
+  end
+end

data/app/concerns/roda.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Relay::Concerns
+  ##
+  # Shared Roda integration for Relay page and route base classes.
+  #
+  # This concern stores the current Roda instance, exposes the request
+  # object as `r`, and delegates unknown helper calls back to Roda so
+  # pages and routes can use methods like `view`, `partial`, `session`,
+  # `request`, and `response` without re-defining that plumbing.
+  module Roda
+    ##
+    # @param [Roda] roda
+    # @return [void]
+    def initialize(roda)
+      @roda = roda
+    end
+
+    ##
+    # @return [Roda::RodaRequest]
+    #  Alias the request object as `r` to match Roda route blocks.
+    def r
+      @roda.request
+    end
+
+    ##
+    # Delegates missing methods to the current Roda instance.
+    # @param [Symbol] name
+    # @param [Array] args
+    # @param [Hash] kwargs
+    # @return [Object]
+    def method_missing(name, *args, **kwargs, &block)
+      if @roda.respond_to?(name)
+        @roda.send(name, *args, **kwargs, &block)
+      else
+        super
+      end
+    end
+
+    ##
+    # Returns true when the current Roda instance can respond to a
+    # delegated method.
+    # @param [Symbol] name
+    # @param [Boolean] include_private
+    # @return [Boolean]
+    def respond_to_missing?(name, include_private = false)
+      @roda.respond_to?(name) || super
+    end
+  end
+end

data/app/concerns/view.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Relay::Concerns
+  ##
+  # Shared view-layer functionality for page and route renderers.
+  #
+  # This concern exists to hold presentation-focused helpers that shape
+  # data for templates and fragments, such as status-bar labels and
+  # formatted cost/context-window values. Keeping these helpers here
+  # separates view concerns from session/context resolution.
+  module View
+    ##
+    # @param [#to_s] text
+    # @return [String]
+    #  Returns up to two initials for compact UI badges.
+    def initials(text)
+      words = text.to_s.strip.split(/\s+/).reject(&:empty?)
+      return "?" if words.empty?
+      words.first(2).map { _1[0] }.join.upcase
+    end
+
+    ##
+    # @param [String] text
+    # @return [String]
+    #  Renders markdown to HTML for templates and fragments.
+    def markdown(text)
+      Relay.markdown(text)
+    end
+
+    ##
+    # @return [Hash]
+    #  Returns the status-bar payload for the current context.
+    def status_bar(status: "Ready", ctx: self.ctx, context_window: nil, cost: nil)
+      {
+        status:,
+        context_window: context_window || context_window(ctx),
+        cost: cost || format_cost(ctx.cost)
+      }
+    end
+
+    ##
+    # @param [String] status
+    # @return [Boolean]
+    #  Returns true when the status represents an interruptible request.
+    def cancellable?(status)
+      text = status.to_s
+      text.start_with?("Thinking", "Running", "Compacting")
+    end
+
+    ##
+    # @param [Relay::Models::Context] ctx
+    # @return [Hash]
+    #  Returns the current context-window display payload.
+    def context_window(ctx)
+      if ctx.compacted?
+        max = ctx.context_window || 0
+        {used: 0, max:, label: "Context compacted"}
+      else
+        used = ctx.usage.total_tokens || 0
+        max = ctx.context_window || 0
+        {used:, max:, label: "#{used} / #{max} tokens"}
+      end
+    rescue LLM::NoSuchModelError, LLM::NoSuchRegistryError
+      {used: 0, max: 0, label: "0 / 0 tokens"}
+    end
+
+    ##
+    # @param [String] cost
+    # @return [String]
+    #  Returns the formatted cost string.
+    def format_cost(cost)
+      return "unknown" if cost == "unknown"
+      "$#{cost}"
+    rescue LLM::NoSuchModelError, LLM::NoSuchRegistryError
+      "unknown"
+    end
+
+    ##
+    # @param [LLM::Provider]
+    # @return [String]
+    def format_name(name)
+      case name
+      when :openai then "OpenAI"
+      when :xai then "xAI"
+      when :deepseek then "DeepSeek"
+      else name.to_s.capitalize
+      end
+    end
+  end
+end

data/app/forms/mcp/forgejo.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+class Relay::Forms::MCP
+  ##
+  # The {Relay::Forms::MCP::Forgejo} class represents form state for
+  # Relay's Forgejo MCP preset.
+  class Forgejo < self
+    ##
+    # @return [String]
+    #  Returns the Forgejo instance URL
+    attr_reader :url
+
+    ##
+    # @return [String]
+    #  Returns the Forgejo access token
+    attr_reader :token
+
+    ##
+    # @param [String] url The Forgejo instance URL
+    # @param [String] token The Forgejo access token
+    # @param [Hash] attributes
+    # @return [Relay::Forms::MCP::Forgejo]
+    def initialize(url: "", token: "", **attributes)
+      super(**attributes)
+      @url = url.to_s.strip
+      @token = token.to_s.strip
+    end
+
+    ##
+    # @return [String]
+    #  Returns the preset id
+    def preset
+      "forgejo"
+    end
+
+    ##
+    # @return [String]
+    #  Returns the backing MCP transport
+    def transport
+      "stdio"
+    end
+
+    ##
+    # @return [Hash]
+    #  Returns the preset-specific MCP data overrides
+    def data
+      {
+        "env" => {
+          "FORGEJO_URL" => url,
+          "FORGEJO_TOKEN" => token
+        }
+      }
+    end
+  end
+end

data/app/forms/mcp/github.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+class Relay::Forms::MCP
+  ##
+  # The {Relay::Forms::MCP::GitHub} class represents form state for
+  # Relay's GitHub MCP preset.
+  class GitHub < self
+    ##
+    # @return [String]
+    #  Returns the GitHub bearer token without the `Bearer ` prefix
+    attr_reader :token
+
+    ##
+    # @param [String] token The GitHub bearer token without the `Bearer ` prefix
+    # @param [Hash] attributes
+    # @return [Relay::Forms::MCP::GitHub]
+    def initialize(token: "", **attributes)
+      super(**attributes)
+      @token = token.to_s.strip
+    end
+
+    ##
+    # @return [String]
+    #  Returns the preset id
+    def preset
+      "github"
+    end
+
+    ##
+    # @return [String]
+    #  Returns the backing MCP transport
+    def transport
+      "http"
+    end
+
+    ##
+    # @return [Hash]
+    #  Returns the preset-specific MCP data overrides
+    def data
+      {
+        "headers" => {
+          "Authorization" => "Bearer #{token}"
+        }
+      }
+    end
+  end
+end

data/app/forms/mcp.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Relay::Forms
+  ##
+  # The {Relay::Forms::MCP} class represents preset-backed MCP form state.
+  # It holds the shared persisted fields for Relay's MCP UI and dispatches
+  # to preset-specific subclasses for GitHub and Forgejo.
+  class MCP
+    ##
+    # @return [Integer, String, nil]
+    #  Returns the MCP row id when editing an existing server
+    attr_reader :id
+
+    ##
+    # @param [Relay::Models::MCP] mcp
+    #  The persisted MCP server
+    # @return [Relay::Forms::MCP]
+    #  A preset-specific form instance
+    def self.from_model(mcp)
+      common = {
+        id: mcp.id,
+        persisted: true
+      }
+      case preset = mcp.data["preset"]
+      when "forgejo"
+        attributes = common.merge(url: mcp.env["FORGEJO_URL"], token: mcp.env["FORGEJO_TOKEN"])
+        build(preset:, attributes:)
+      when "github"
+        attributes = common.merge(token: mcp.headers["Authorization"].to_s.delete_prefix("Bearer ").strip)
+        build(preset:, attributes:)
+      else
+        raise ArgumentError, "Unknown MCP preset: #{mcp.data["preset"].inspect}"
+      end
+    end
+
+    ##
+    # @param [Hash] params
+    #  The submitted MCP form params
+    # @return [Relay::Forms::MCP]
+    #  A preset-specific form instance
+    def self.from_params(params)
+      common = {
+        id: params["id"],
+        persisted: false
+      }
+      case preset = params["preset"]
+      when "forgejo"
+        attributes = common.merge(url: params["url"], token: params["token"])
+        build(preset:, attributes:)
+      when "github"
+        build(preset:, attributes: common.merge(token: params["token"]))
+      else
+        raise ArgumentError, "Unknown MCP preset: #{params["preset"].inspect}"
+      end
+    end
+
+    ##
+    # @param [String] preset
+    #  The MCP preset id
+    # @param [Hash] attributes
+    #  Shared form attributes
+    # @return [Relay::Forms::MCP]
+    #  A preset-specific form instance
+    def self.build(preset:, attributes: {})
+      case preset
+      when "forgejo" then Forgejo.new(**attributes)
+      when "github" then GitHub.new(**attributes)
+      else raise ArgumentError, "Unknown MCP preset: #{preset.inspect}"
+      end
+    end
+
+    ##
+    # @param [Integer, String, nil] id
+    #  The MCP row id
+    # @param [Boolean] persisted
+    #  Whether the form is backed by a persisted MCP row
+    def initialize(id: nil, persisted: false)
+      @id = id
+      @persisted = persisted
+    end
+
+    ##
+    # @return [Boolean]
+    #  Returns true when this form was built from a persisted MCP row
+    def persisted?
+      @persisted
+    end
+  end
+end

data/app/hooks/require_user.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Relay::Hooks
+  module RequireUser
+    def call(*args, **kwargs)
+      @user = Relay::Models::User[session["user_id"]]
+      @user.nil? ? r.redirect("/sign-in") : super(*args, **kwargs)
+    end
+  end
+end