elelem 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 72a4cd636b39b6f30cc0520c3445a3b8748625fd5ca52f15b05d27349a0701b4
-  data.tar.gz: 12c55aaf15f42e7607fb60ed78500b44655ba6eaab857601ec58073378587866
+  metadata.gz: f6da2ace697aa7b578edd8144e10eb779677b24e58d62f1a4a4c88ed042c85b0
+  data.tar.gz: ea9e8728d8632514352f34788d200cf8f7f09205e85527ba63b04f5c11fb6c1c
 SHA512:
-  metadata.gz: '018856c824b90cbbe658c3b117f683737f14c34f493ba3629281cd7318c11d039585b829e201a9a8bf591619747d2d6c7f1f3568f53a79c40222632a706303ac'
-  data.tar.gz: ab3132d4613f560dfb97e7bcfa406e5f49ac66f5e642ec85f77c1a25d030825f1a7d9f6401d54dd6eb3f767ec69506b8f114e3a269324fb5fd72f0ca97827a0d
+  metadata.gz: 874c019ad05cd113e1c68114648834f2b7a420ea9f3bfe07a378766e117def9a15467d80548d470274c81507524fc1ab5379db92843c1ed5dee66efbb14299bd
+  data.tar.gz: 14b4b17556f3fc5830d7579c69b8cbb30048d631135d973aa6368933801e48e3ac3485d3c7b1ba1559b69810d99916a368aa6a860cff3866d1c94df9754ee9e7

data/README.md

@@ -23,24 +23,24 @@ gem install elelem
 
 ## Usage
 
-Start an interactive chat session:
+Start elelem:
 
 ```bash
-elelem chat
+elelem
 ```
 
 ## Tools
 
-Use the plugin API to add tools.
+elelem ships with `read`, `write` and `execute`. Use the plugin API to add more.
 
 ## Contributing
 
 ```bash
-$ git clone https://git.mokhan.ca/elelem/elelem.git
+git clone https://github.com/elelem-sh/elelem.git
 ```
 
 Send me a patch via email. For instructions see https://git-send-email.io/.
 
 ## License
 
-MIT – see the bundled `LICENSE.txt`.
+MIT. See the bundled `LICENSE.txt`.

data/exe/elelem

@@ -3,12 +3,6 @@
 
 require "elelem/cli"
 
-begin
-  require "elelem/builtins"
-rescue LoadError
-  warn "elelem: gem install elelem-builtins for the default tools and commands"
-end
-
 Signal.trap("INT") { exit 1 }
 
 Elelem::CLI.new(ARGV).run

data/lib/elelem/agent.rb

@@ -2,94 +2,63 @@
 
 module Elelem
   class Agent
-    attr_reader :conversation, :toolbox, :input, :output, :commands
+    attr_reader :conversation, :toolbox, :output
     attr_accessor :provider
 
-    def initialize(provider, toolbox: Toolbox.new, input: NullInput.new, output: NullOutput.new, system_prompt: nil, commands: nil)
+    def initialize(provider, toolbox: Toolbox.new, output: NullOutput.new, template: nil, system_prompt: nil)
       @provider = provider
       @toolbox = toolbox
-      @commands = commands || Commands.new
       @output = output
-      @input = input
-      @conversation = Conversation.new
-      @system_prompt = SystemPrompt.new(system_prompt)
-    end
-
-    def repl
-      output.say "elelem v#{VERSION}"
-      loop do
-        line = input.ask("> ")
-        break if line.nil?
-        next if line.empty?
-        line.start_with?("/") ? command(line) : turn(line)
-      end
+      @conversation = Conversation.new(template: template, system_prompt: system_prompt)
     end
 
     def context
-      @conversation.to_a(system_prompt: @system_prompt.render)
+      @conversation.to_a
     end
 
+    # A provider error leaves the turn: the caller decides how to report it.
     def turn(prompt)
       @conversation.add(role: "user", content: prompt)
-      ctx = []
-      content = nil
-
-      loop do
-        output.waiting
-        content, tool_calls = fetch_response(ctx)
-        output.say(content, as: :markdown)
-        break if tool_calls.empty?
-
-        ctx << { role: "assistant", content: content, tool_calls: tool_calls }.compact
-        tool_calls.each do |tool_call|
-          ctx << { role: "tool", tool_call_id: tool_call[:id], content: process(tool_call).to_json }
-        end
-      end
-
+      content = run_until_done([])
       @conversation.add(role: "assistant", content: content)
       content
     end
 
     private
 
-    def command(line)
-      parts = line.delete_prefix("/").split(" ", 2)
-      name, args = parts[0], parts[1]
-      commands.run(name, args) || output.say(commands.names.join(" "))
-    rescue => e
-      Elelem.logger.warn("agent: #{e.message}")
-      output.say(e.message, as: :error)
-    end
+    # Tool calls and their results stay out of the conversation: only the
+    # prompt and the final reply are kept.
+    def run_until_done(ctx)
+      loop do
+        content, tool_calls = fetch(ctx)
+        return content if tool_calls.empty?
 
-    def process(tool_call)
-      name, args = tool_call[:name], tool_call[:arguments]
-      output.doing(toolbox.tool_for(name).name, args)
-      Elelem.logger.debug("agent: #{name}(#{args.inspect})")
-      result = toolbox.run(name.to_s, args)
-      Elelem.logger.debug("agent: #{name} -> #{result.inspect}")
-      result
+        ctx.push({ role: "assistant", content: content, tool_calls: tool_calls }, *tool_calls.map { |c| process(c) })
+      end
     end
 
-    def fetch_response(ctx)
-      content = String.new
-      tool_calls = []
+    def fetch(ctx)
+      output.waiting
+      [String.new, []].tap do |content, tool_calls|
+        provider.fetch(@conversation.to_a(ctx), toolbox.to_a) { |event| handle_event(event, content, tool_calls) }
+        output.say(content, as: :markdown)
+      end
+    end
 
-      provider.fetch(@conversation.to_a(system_prompt: @system_prompt.render) + ctx, toolbox.to_a) do |event|
-        case event[:type]
-        when "saying"
-          content << event[:text].to_s
-        when "thinking"
-          output.thinking(event[:text])
-        when "doing"
-          tool_calls << { id: event[:id], name: event[:name], arguments: event[:arguments] }
-        end
+    def handle_event(event, content, tool_calls)
+      case event[:type]
+      when "saying" then content << event[:text].to_s
+      when "thinking" then output.thinking(event[:text])
+      when "doing" then tool_calls << { id: event[:id], name: event[:name], arguments: event[:arguments] }
       end
+    end
 
-      [content, tool_calls]
-    rescue => e
-      Elelem.logger.warn("agent: #{e.message}")
-      output.say(e.message, as: :error)
-      ["Error: #{e.message}", []]
+    def process(call)
+      name, args = call.values_at(:name, :arguments)
+      output.doing(toolbox.tool_for(name)&.name || "#{name}?", args)
+      result = toolbox.run(name.to_s, args).to_json
+      Elelem.logger.debug("agent: #{name}(#{args.inspect}) -> #{result}")
+      { role: "tool", tool_call_id: call[:id], content: result }
     end
   end
 end

data/lib/elelem/builtins/terminal.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Builtins
+    # Output for a person at a terminal: dots while the model thinks, markdown
+    # through glow, files through bat, and a copy of everything in a private
+    # transcript under $XDG_STATE_HOME/elelem/sessions.
+    class Terminal < Output
+      def initialize(stream: $stdout, **)
+        super
+        @dots_thread = nil
+        @at_line_start = true
+      end
+
+      def say(text, as: nil)
+        stop_dots
+        super
+      end
+
+      def print(text)
+        stop_dots
+        super
+      end
+
+      def doing(name, args, state: "+")
+        gap
+        super
+      end
+
+      def waiting
+        stop_dots
+        @dots_thread = Thread.new do
+          until Thread.current[:stop]
+            @stream.print "."
+            @stream.flush
+            sleep 0.1
+          end
+        end
+      end
+
+      def display_file(path, fallback: nil)
+        system("bat", "--paging=never", "--", path) || super
+      end
+
+      private
+
+      def render(text, as)
+        case as
+        when :error then "\n  x #{text}"
+        when :markdown then markdown(text)
+        else text
+        end
+      end
+
+      def markdown(text)
+        gap
+        width = begin
+          @stream.winsize[1]
+        rescue StandardError
+          80
+        end
+        IO.popen(["glow", "-s", "dark", "-w", width.to_s, "-"], "r+") do |io|
+          io.write(text)
+          io.close_write
+          io.read
+        end
+      rescue Errno::ENOENT
+        text
+      end
+
+      def gap
+        stop_dots
+        write("\n") unless @at_line_start
+      end
+
+      def stop_dots
+        return unless @dots_thread
+
+        @dots_thread[:stop] = true
+        @dots_thread.join
+        @dots_thread = nil
+        write("\n")
+      end
+
+      def write(text)
+        @stream.print text
+        @at_line_start = text.end_with?("\n")
+        (@transcript ||= open_transcript).print text
+      end
+
+      def open_transcript
+        state_dir = File.join(ENV.fetch("XDG_STATE_HOME", File.expand_path("~/.local/state")), "elelem", "sessions")
+        FileUtils.mkdir_p(state_dir, mode: 0o700)
+        File.chmod(0o700, state_dir)
+        session_id = "#{Time.now.utc.strftime("%Y%m%dT%H%M%SZ")}-#{Process.pid}"
+        path = File.join(state_dir, "#{session_id}.transcript")
+        File.open(path, "a", 0o600).tap { |f| f.sync = true } # rubocop:disable Style/FileOpen
+      end
+    end
+  end
+end

data/lib/elelem/builtins.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Elelem
+  module Builtins
+    def self.sh(cmd, args: [], cwd: Dir.pwd, env: {}, timeout: nil)
+      output = StringIO.new
+      options = { chdir: cwd }
+      options[:pgroup] = true if timeout
+
+      Open3.popen2e(env, cmd, *args, **options) do |stdin, out, wait_thr|
+        stdin.close
+        timed_out = false
+        watchdog = timeout && Thread.new do
+          sleep(timeout)
+          timed_out = true
+          terminate(wait_thr.pid)
+        end
+
+        out.each_line do |line|
+          line = line.force_encoding(Encoding::UTF_8).scrub
+          yield line if block_given?
+          output.write(line)
+        end
+        timed_out ? watchdog&.join : watchdog&.kill
+
+        status = wait_thr.value
+        note = timed_out ? "\n[command timed out after #{timeout}s]" : ""
+        { exit_status: status.exitstatus || (timed_out ? 124 : 1), content: truncate(output.string) + note }
+      rescue Interrupt
+        # In its own process group the command never sees Ctrl-C, so stop it here.
+        terminate(wait_thr.pid) if timeout
+        raise
+      end
+    end
+
+    def self.truncate(content, limit: 10_000)
+      return content if content.length <= limit
+
+      half = limit / 2
+      elided = content.length - limit
+      "#{content[0, half]}\n[#{elided} characters elided]\n#{content[-half, half]}"
+    end
+
+    def self.terminate(pid)
+      Process.kill("TERM", -pid)
+      sleep 0.5
+      Process.kill("KILL", -pid)
+    rescue Errno::ESRCH
+      nil
+    end
+  end
+end

data/lib/elelem/cli.rb

@@ -7,70 +7,65 @@ require "reline"
 
 module Elelem
   class CLI
-    COMMANDS = %w[chat ask files help].freeze
+    COMMANDS = %w[chat ask help].freeze
+    USAGE = <<~TEXT.freeze
+      Usage: #{File.basename($PROGRAM_NAME)} [command] [options] [args]
+      \nCommands:
+        chat              Interactive REPL (default)
+        ask <prompt>      One-shot query (reads stdin if piped)
+        help              Show this help
+      \nOptions:
+    TEXT
+    private_constant :USAGE
 
     def initialize(args, provider: "stub")
       @provider = provider
-      @args = parse(args)
+      @provider_options = {}
+      @parser = OptionParser.new(USAGE) { |o| describe_options(o) }
+      @args = @parser.parse!(args)
     end
 
     def run
       command = @args.shift || "chat"
-      abort "Unknown command: #{command}" unless COMMANDS.include?(command)
-      send(command)
+      COMMANDS.include?(command) ? send(command) : abort("Unknown command: #{command}")
+    rescue StandardError, ScriptError => e
+      Elelem.logger.debug("cli: #{e.message}\n#{e.backtrace.join("\n")}")
+      abort "elelem: #{e.message}"
     end
 
     private
 
-    def parse(args)
-      @parser = OptionParser.new do |o|
-        o.banner = "Usage: #{File.basename($PROGRAM_NAME)} [command] [options] [args]"
-        o.separator "\nCommands:"
-        o.separator "  chat              Interactive REPL (default)"
-        o.separator "  ask <prompt>      One-shot query (reads stdin if piped)"
-        o.separator "  files             Output files as XML (no options)"
-        o.separator "  help              Show this help"
-        o.separator "\nOptions:"
-        o.on("-p", "--provider NAME", "Provider to use (default: #{@provider})") { |p| @provider = p }
-        o.on("-h", "--help", "Show this help") { puts o; exit }
-      end
-      @parser.parse!(args)
+    def describe_options(parser)
+      parser.on("-p", "--provider NAME", "Provider to use (default: #{@provider})") { |p| @provider = p }
+      parser.on("--model NAME", "Model to use, passed to the provider") { |m| @provider_options[:model] = m }
+      parser.on("--system-prompt TEXT", "Role text prepended to the system prompt") { |s| @system_prompt = s }
+      parser.on("-h", "--help", "Show this help") { puts(parser) || exit }
     end
 
-    def help
-      puts @parser
-    end
+    def help = puts(@parser)
 
     def chat
-      Elelem.start(provider: @provider)
-    rescue => e
-      Elelem.logger.warn("cli: #{e.message}\n#{e.backtrace.join("\n")}")
-      abort "elelem: #{e.message}"
+      Elelem.start(provider: @provider, provider_options: @provider_options, system_prompt: @system_prompt)
     end
 
+    # When stdout is piped, progress goes to stderr and only the reply to stdout.
     def ask
-      abort "Usage: elelem-chat ask <prompt>" if @args.empty?
-      prompt = @args.join(" ")
-      prompt = "#{prompt}\n\n```\n#{$stdin.read}\n```" if $stdin.stat.pipe?
+      abort "Usage: elelem ask <prompt>" if @args.empty?
+
       piped = !$stdout.tty?
-      output = Elelem::Output.new(stream: piped ? $stderr : $stdout)
-      reply = Elelem.ask(prompt, provider: @provider, output: output)
-      abort "elelem: no reply" if reply.to_s.strip.empty?
-      Elelem::Output.new.say(reply, as: :markdown) if piped
-    rescue => e
-      Elelem.logger.warn("cli: #{e.message}\n#{e.backtrace.join("\n")}")
-      abort "elelem: #{e.message}"
+      reply = Elelem.ask(prompt_for_ask, provider: @provider, output: Output.new(stream: piped ? $stderr : $stdout),
+                                         provider_options: @provider_options, system_prompt: @system_prompt)
+      print_reply(reply, piped: piped)
+    end
+
+    def prompt_for_ask
+      prompt = @args.join(" ")
+      $stdin.stat.then { |s| s.pipe? || s.file? } ? "#{prompt}\n\n```\n#{$stdin.read}\n```" : prompt
     end
 
-    def files
-      files = $stdin.stat.pipe? ? $stdin.readlines : `git ls-files`.lines
-      puts "<documents>"
-      files.each_with_index do |line, i|
-        path = line.strip
-        next if path.empty? || !File.file?(path)
-        puts %Q{<document index="#{i + 1}"><source>#{path}</source><document_content><![CDATA[#{File.read(path)}]]></document_content></document>}
-      end
-      puts "</documents>"
-     end
+    def print_reply(reply, piped:)
+      abort "elelem: no reply" if reply.to_s.strip.empty?
+      $stdout.puts(reply) if piped
+    end
   end
 end

data/lib/elelem/commands.rb

@@ -4,6 +4,8 @@ module Elelem
   class Commands
     include Enumerable
 
+    Command = Struct.new(:description, :completions, :handler)
+
     def initialize(registry = {})
       @registry = registry
     end
@@ -13,22 +15,21 @@ module Elelem
     end
 
     def register(name, description: "", completions: nil, &handler)
-      @registry[name] = SlashCommand.new(name, description, completions, &handler)
+      @registry[name] = Command.new(description, completions, handler)
     end
 
+    # completions is a list, or a lambda that returns one.
     def completions_for(name, partial = "")
-      cmd = command_for(name)
-      return [] unless cmd && cmd.completions
-
-      options = cmd.completions.respond_to?(:call) ? cmd.completions.call : cmd.completions
+      options = @registry[name]&.completions || []
+      options = options.call if options.respond_to?(:call)
       options.select { |o| o.start_with?(partial) }
     end
 
     def run(name, args = nil)
-      command = command_for(name)
+      command = @registry[name]
       return false unless command
 
-      command.call(args)
+      command.handler.call(args)
       true
     end
 
@@ -39,11 +40,5 @@ module Elelem
     def each
       @registry.each { |name, command| yield "/#{name}", command.description }
     end
-
-    private
-
-    def command_for(name)
-      @registry[name]
-    end
   end
 end

data/lib/elelem/config.rb

@@ -4,14 +4,14 @@ module Elelem
   module Config
     extend SingleForwardable
 
-    def_single_delegators :default, :build_provider, :build_agent, :apply, :reload, :names
+    def_single_delegators :default, :build_provider, :build_session, :apply, :reload, :names
 
     def self.default
       @default ||= Registry.new
     end
   end
 
-  def self.configure(&block)
-    Config.default.configure(&block)
+  def self.configure(&)
+    Config.default.configure(&)
   end
 end

data/lib/elelem/conversation.rb

@@ -1,25 +1,30 @@
 # frozen_string_literal: true
 
 module Elelem
+  # The messages of a session, behind the system prompt they are sent with.
   class Conversation
     ROLES = %w[user assistant tool].freeze
 
-    def initialize
+    def initialize(template: nil, system_prompt: nil)
       @messages = []
+      @template = SystemPrompt.new(template)
+      @system_prompt = system_prompt
     end
 
     def add(role:, content:, **extra)
       raise ArgumentError, "invalid role: #{role}" unless ROLES.include?(role)
+
       @messages << { role: role, content: content, **extra }.compact
     end
 
     def last = @messages.last
-    def length = @messages.length
     def clear! = @messages.clear
 
-    def to_a(system_prompt: nil)
-      base = system_prompt ? [{ role: "system", content: system_prompt }] : []
-      base + @messages
+    # The system prompt, the messages, then extra: the tool calls of a turn.
+    def to_a(extra = [])
+      # The role text is the model's own words, so it is never run as ERB.
+      system = [@system_prompt, @template.render].compact.join("\n\n")
+      [{ role: "system", content: system }, *@messages, *extra]
     end
   end
 end

data/lib/elelem/input.rb

@@ -4,14 +4,18 @@ require "reline"
 
 module Elelem
   class Input
-    def initialize(commands: [])
+    def initialize(commands: Commands.new)
       @commands = commands
       Reline.autocompletion = true
       Reline.completion_proc = ->(target, preposing) { complete(target, preposing) }
     end
 
     def ask(prompt)
-      Reline.readline(prompt, true)&.strip
+      Reline.readline(prompt, false)&.strip
+    end
+
+    def remember(line)
+      Reline::HISTORY << line
     end
 
     def interactive?
@@ -22,27 +26,14 @@ module Elelem
 
     def complete(target, preposing)
       line = "#{preposing}#{target}"
-
-      if line.start_with?("/") && !preposing.include?(" ")
-        return command_names.select { |c| c.start_with?(line) }
-      end
-
-      if preposing.start_with?("/") && preposing.include?(" ")
-        cmd_name = preposing.delete_prefix("/").split(" ", 2).first
-        return complete_command_args(cmd_name, target)
-      end
+      return @commands.names.select { |c| c.start_with?(line) } if line.start_with?("/") && !preposing.include?(" ")
+      return complete_command_args(preposing, target) if preposing.start_with?("/") && preposing.include?(" ")
 
       complete_files(target)
     end
 
-    def command_names
-      @commands.respond_to?(:names) ? @commands.names : @commands
-    end
-
-    def complete_command_args(cmd_name, partial)
-      return [] unless @commands.respond_to?(:completions_for)
-
-      @commands.completions_for(cmd_name, partial)
+    def complete_command_args(preposing, target)
+      @commands.completions_for(preposing.delete_prefix("/").split(" ", 2).first, target)
     end
 
     def complete_files(target)

data/lib/elelem/null_output.rb

@@ -2,6 +2,8 @@
 
 module Elelem
   class NullOutput < Output
-    def say(*, **) = nil
+    private
+
+    def write(_text) = nil
   end
 end

data/lib/elelem/output.rb

@@ -2,6 +2,12 @@
 
 module Elelem
   class Output
+    RENDERERS = {
+      error: ->(text) { "error: #{text}" },
+      markdown: ->(text) { "```\n#{text}\n```\n" }
+    }.freeze
+    private_constant :RENDERERS
+
     def initialize(stream: $stdout, **)
       @stream = stream
     end
@@ -26,8 +32,7 @@ module Elelem
       say "#{state} \e[36m#{name}\e[0m(#{args})"
     end
 
-    def waiting
-    end
+    def waiting; end
 
     def display_file(path, fallback: nil)
       say(fallback || path)
@@ -36,14 +41,7 @@ module Elelem
     private
 
     def render(text, as)
-      case as
-      when :error
-        return "error: #{text}"
-      when :markdown
-        "```\n" + text + "\n```\n"
-      else
-        text
-      end
+      RENDERERS[as]&.call(text) || text
     end
 
     def write(text)

data/lib/elelem/plugins/builtins.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+Elelem.configure do |config|
+  config.setup(:builtins) do |agent|
+    agent.commands.register("exit", description: "Exit elelem") { exit(0) }
+
+    agent.commands.register("clear", description: "Clear conversation history") do
+      agent.conversation.clear!
+      agent.output.say "  -> context cleared"
+    end
+
+    agent.commands.register("help", description: "Show available commands") do
+      agent.output.say agent.commands.map { |name, description| "#{name.ljust(12)} #{description}" }.join("\n")
+    end
+  end
+end