zephira 0.1.0

data/lib/zephira/completions/file_names.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Completions
+    class FileNames
+      def self.complete(input:, agent:)
+        return [] unless input.start_with?("@")
+
+        prefix = input[1..]
+        pattern = if prefix.include?("/")
+          prefix.end_with?("/") ? "#{prefix}*" : File.join(File.dirname(prefix), "#{File.basename(prefix)}*")
+        else
+          "#{prefix}*"
+        end
+
+        Dir.glob(pattern).map do |path|
+          "@#{path}#{File.directory?(path) ? "/" : ""}"
+        end
+      end
+    end
+  end
+end

data/lib/zephira/completions/slash_commands.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Completions
+    class SlashCommands
+      def self.complete(input:, agent:)
+        return [] unless input.start_with?("/")
+
+        prefix = input[1..] || ""
+        agent.commands.constants
+          .map(&:name)
+          .grep(/\A#{Regexp.escape(prefix)}/)
+          .map { |cmd| "/#{cmd}" }
+      end
+    end
+  end
+end

data/lib/zephira/completions.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Completions
+    def self.load(paths:)
+      paths.each do |path|
+        Dir.glob(File.join(path, "**", "*.rb")).each { |file| require file }
+      end
+      new
+    end
+
+    def constants
+      @constants ||= ::Zephira::Completions.constants(false).map do |name|
+        ::Zephira::Completions.const_get(name)
+      end
+    end
+
+    def complete_all(input:, agent:)
+      constants.flat_map { |completion| completion.complete(input: input, agent: agent) }.uniq
+    end
+  end
+end

data/lib/zephira/config.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Zephira
+  class Config
+    def self.read(key)
+      project_config_path = File.join(Dir.pwd, ".zephira.yml")
+      global_config_path = File.expand_path("~/.zephira.yml")
+
+      project_config = File.exist?(project_config_path) ? (YAML.load_file(project_config_path) || {})[key] : nil
+      global_config = File.exist?(global_config_path) ? (YAML.load_file(global_config_path) || {})[key] : nil
+
+      ENV[key] || project_config || global_config
+    end
+  end
+end

data/lib/zephira/formatter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Zephira
+  class Formatter
+    FORMAT_STRINGS = {
+      color_white: "\e[37m",
+      color_red: "\e[31m",
+      color_dark_red: "\e[91m",
+      color_green: "\e[32m",
+      color_grey: "\e[90m",
+      format_bold: "\e[1m",
+      format_italic: "\e[3m",
+      format_underlined: "\e[4m",
+      format_strikethrough: "\e[9m",
+      format_bold_italic: "\e[1;3m",
+      format_bold_underlined: "\e[1;4m",
+      format_italic_underlined: "\e[3;4m",
+      format_bold_strikethrough: "\e[1;9m",
+      format_italic_strikethrough: "\e[3;9m",
+      format_underlined_strikethrough: "\e[4;9m",
+      format_clear: "\e[0m"
+    }.freeze
+
+    class << self
+      def format(string, indent: 0)
+        raise ArgumentError, "Indent must be a non-negative integer" unless indent.is_a?(Integer) && indent >= 0
+
+        string.each_line.map do |line|
+          indented_line = (" " * indent) + line.chomp
+
+          FORMAT_STRINGS.each do |key, value|
+            indented_line.gsub!("###{key.upcase}##", value)
+          end
+
+          # replace any remaining format strings with the clear format
+          # this avoids having malformed format strings left in the output
+          indented_line.gsub!(/##\w+##/, style(:clear))
+
+          indented_line
+        end.join("\n")
+      end
+
+      def available_formats
+        FORMAT_STRINGS.except(:format_clear).map do |key, value|
+          format_string = "###{key.to_s.upcase}##"
+          description = "#{key.to_s.split("_")[1..].join(" ")} text"
+          "#{format_string} for #{description}"
+        end + ["##FORMAT_CLEAR## to clear all formatting"]
+      end
+
+      def color(color, string = nil)
+        color_code = FORMAT_STRINGS[:"color_#{color}"]
+        raise ArgumentError, "Invalid color: #{color}" unless color_code
+
+        return color_code if string.nil?
+        "#{color_code}#{string}#{style(:clear)}"
+      end
+
+      def style(style, string = nil)
+        style_code = FORMAT_STRINGS[:"format_#{style}"]
+        raise ArgumentError, "Invalid style: #{style}" unless style_code
+
+        return style_code if string.nil?
+        "#{style_code}#{string}#{style(:clear)}"
+      end
+    end
+  end
+end

data/lib/zephira/history.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "time"
+
+module Zephira
+  class History
+    STORAGE_DIR = ".zephira"
+    STORAGE_FILE = "history.jsonl"
+    COMPACTION_CHUNK_SIZE = 10
+
+    attr_reader :messages, :session_start
+
+    def initialize(messages = [])
+      @storage_dir = File.join(Dir.pwd, STORAGE_DIR)
+      @storage_file = File.join(@storage_dir, STORAGE_FILE)
+
+      FileUtils.mkdir_p(@storage_dir)
+
+      if messages.empty? && File.file?(@storage_file) && File.size(@storage_file) > 0
+        @messages = load_from_disk
+      else
+        @messages = messages.dup
+        write_all_to_disk
+      end
+
+      @session_start = @messages.size
+    end
+
+    def append(role:, content:, tool_calls: nil, tool_call_id: nil)
+      entry = {
+        role: role,
+        content: content,
+        tool_calls: tool_calls,
+        tool_call_id: tool_call_id,
+        timestamp: Time.now.iso8601
+      }.compact
+      @messages << entry
+      persist_entry(entry)
+    end
+
+    def size
+      @messages.sum { |message| Tokens.estimate(message[:content]) }
+    end
+
+    def compact(response_model:, api_key:, agent:, token_limit: Float::INFINITY)
+      return unless size > token_limit
+
+      chunks = []
+      while size > token_limit && !@messages.empty?
+        chunks << @messages.shift(COMPACTION_CHUNK_SIZE)
+      end
+
+      chunks.each do |chunk|
+        conversation = chunk.map { |message| "#{message[:role]}: #{message[:content]}" }.join("\n")
+        summary = response_model.simple_inference(
+          api_key: api_key,
+          agent: agent,
+          messages: [{role: "user", content: "Summarize the following conversation:\n#{conversation}"}]
+        )
+
+        @messages.unshift(
+          role: "system",
+          content: "[Summary of #{chunk.size} messages]\n#{summary}",
+          timestamp: Time.now.iso8601
+        )
+      end
+
+      write_all_to_disk
+    end
+
+    def clear
+      @messages.clear
+      write_all_to_disk
+    end
+
+    def clear_session
+      return unless @session_start
+      @messages = @messages[0...@session_start]
+      write_all_to_disk
+    end
+
+    def compact_tool_messages!
+      @messages = @messages
+        .reject { |message| message[:role] == "tool" }
+        .map do |message|
+          next message unless message[:tool_calls]&.any?
+
+          summary_lines = message[:tool_calls].map do |tool_call|
+            name = tool_call.dig(:function, :name) || tool_call.dig("function", "name")
+            arguments = tool_call.dig(:function, :arguments) || tool_call.dig("function", "arguments")
+            arguments = JSON.parse(arguments, symbolize_names: true)
+            "- `#{name}` with intent `#{arguments[:intent]}`"
+          end
+          summary_lines.unshift("Agent used tool(s):\n")
+          {role: "assistant", content: summary_lines.join("\n"), timestamp: message[:timestamp]}
+        end
+
+      write_all_to_disk
+    end
+
+    private
+
+    def load_from_disk
+      File.readlines(@storage_file).map { |line| JSON.parse(line, symbolize_names: true) }
+    end
+
+    def persist_entry(entry)
+      File.open(@storage_file, "a") { |file| file.puts JSON.generate(entry) }
+    end
+
+    def write_all_to_disk
+      File.open(@storage_file, "w") { |file| @messages.each { |entry| file.puts JSON.generate(entry) } }
+    end
+  end
+end

data/lib/zephira/logger.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Zephira
+  class Logger
+    LOG_LEVELS = %i[debug info warn error].freeze
+
+    attr_reader :logfile, :log_level
+
+    def initialize(file_path:, log_level: :debug)
+      FileUtils.mkdir_p(File.dirname(file_path))
+      @logfile = File.open(file_path, "a")
+      @log_level = log_level
+
+      raise ArgumentError, "Invalid log level: #{log_level}" unless LOG_LEVELS.include?(log_level)
+    end
+
+    def debug(message, **args)
+      log(:debug, message, **args)
+    end
+
+    def info(message, **args)
+      log(:info, message, **args)
+    end
+
+    def error(message, **args)
+      log(:error, message, **args)
+    end
+
+    def warn(message, **args)
+      log(:warn, message, **args)
+    end
+
+    def log(level, message, **args)
+      return unless should_log?(level)
+
+      @logfile.puts "#{Time.now} - #{level.to_s.strip.upcase} - #{message} - #{args.inspect}"
+      @logfile.flush
+    end
+
+    def should_log?(level)
+      LOG_LEVELS.index(level) >= LOG_LEVELS.index(@log_level)
+    end
+  end
+end

data/lib/zephira/models/base_model.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Zephira
+  module Models
+    # Base class for all model definitions.
+    #
+    # To add a new model:
+    #   1. Drop a new file in `lib/zephira/models/<name>.rb` — it is auto-loaded.
+    #   2. Subclass `BaseModel` and implement `model_name` and `context_limit`.
+    #   3. Optionally override `backend` to point at a specific backend class.
+    #      Defaults to `Backends::OpenAiCompatible` (works for any provider with an
+    #      OpenAI-compatible API). For provider-specific quirks (Mistral, Anthropic
+    #      tool-call shape, etc.) define a dedicated backend class and return it
+    #      from `backend`.
+    #
+    # `ENV["ZEPHIRA_BACKEND"]` overrides per-model `backend` for debugging.
+    class BaseModel
+      def self.model_name
+        raise NotImplementedError, "You must implement the model_name method"
+      end
+
+      def self.context_limit
+        raise NotImplementedError, "You must implement the context_limit method"
+      end
+
+      # Override in subclasses to bind a model to a specific backend class.
+      def self.backend
+        Zephira::Backends::OpenAiCompatible
+      end
+
+      def self.backend_class
+        identifier = ENV["ZEPHIRA_BACKEND"]
+        if identifier
+          found = Zephira::Backends.find_by_name(identifier)
+          return found if found
+        end
+        backend
+      end
+
+      def self.format_tools(tools)
+        tools.to_h.map do |tool|
+          {
+            type: "function",
+            function: {
+              name: tool[:name],
+              description: tool[:description],
+              parameters: tool[:parameters]
+            }
+          }
+        end
+      end
+
+      def self.inference(api_key:, agent:, messages: [], base_url: nil)
+        client = backend_class.new(api_key: api_key, base_url: base_url)
+
+        loop do
+          agent.thinking(self)
+          response = client.chat(
+            model_name: model_name,
+            messages: messages,
+            agent: agent,
+            tools: format_tools(agent.tools)
+          )
+
+          tool_calls = Array(response["tool_calls"]).select { |tool_call| tool_call["type"] == "function" }
+
+          if tool_calls.empty?
+            content = response["content"]
+            return (content.nil? || content.empty?) ? nil : content
+          end
+
+          messages << {role: "assistant", content: response["content"], tool_calls: response["tool_calls"]}
+          agent.history.append(role: "assistant", content: response["content"], tool_calls: response["tool_calls"])
+
+          dispatch_tool_calls(tool_calls, agent: agent).each do |call, content|
+            messages << {role: "tool", tool_call_id: call["id"], content: content}
+            agent.history.append(role: "tool", tool_call_id: call["id"], content: content)
+          end
+        end
+      end
+
+      # Returns an array of [call, content] pairs in the original order. Read-only
+      # tools are run concurrently via threads (network/disk I/O releases the GVL);
+      # mutating tools run sequentially after, in original order.
+      def self.dispatch_tool_calls(tool_calls, agent:)
+        results = Array.new(tool_calls.size)
+
+        read_only_calls = []
+        mutating_calls = []
+        tool_calls.each_with_index do |call, index|
+          if agent.tools.read_only?(call["function"]["name"])
+            read_only_calls << [index, call]
+          else
+            mutating_calls << [index, call]
+          end
+        end
+
+        threads = read_only_calls.map do |index, call|
+          Thread.new do
+            args = parse_tool_arguments(call, agent: agent)
+            result = agent.run_tool(name: call["function"]["name"], args: args)
+            results[index] = [call, serialize_tool_result(result)]
+          end
+        end
+        threads.each(&:join)
+
+        mutating_calls.each do |index, call|
+          args = parse_tool_arguments(call, agent: agent)
+          result = agent.run_tool(name: call["function"]["name"], args: args)
+          results[index] = [call, serialize_tool_result(result)]
+        end
+
+        results
+      end
+
+      def self.simple_inference(api_key:, messages:, agent: nil, base_url: nil)
+        client = backend_class.new(api_key: api_key, base_url: base_url)
+        agent.thinking(self) if agent.respond_to?(:thinking)
+        client.chat(model_name: model_name, messages: messages, agent: agent)["content"]
+      end
+
+      def self.parse_tool_arguments(call, agent:)
+        raw = call["function"]["arguments"] || "{}"
+        JSON.parse(raw, symbolize_names: true)
+      rescue JSON::ParserError => exception
+        agent&.logger&.error("Failed to parse tool arguments for #{call["function"]["name"]}: #{exception.message}. Raw: #{raw.inspect}")
+        {}
+      end
+
+      def self.serialize_tool_result(result)
+        return result unless result.is_a?(Hash) && result.key?(:outcome)
+
+        if result[:outcome] == "success"
+          result[:data].is_a?(String) ? result[:data] : JSON.pretty_generate([result[:data]])
+        else
+          result[:error].to_s
+        end
+      end
+    end
+  end
+end

data/lib/zephira/models/chat_gpt41.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    class ChatGpt41 < BaseModel
+      def self.model_name
+        "gpt-4.1"
+      end
+
+      def self.context_limit
+        1_047_576
+      end
+    end
+  end
+end

data/lib/zephira/models/chat_gpt41_mini.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    class ChatGpt41Mini < BaseModel
+      def self.model_name
+        "gpt-4.1-mini"
+      end
+
+      def self.context_limit
+        1_047_576
+      end
+    end
+  end
+end

data/lib/zephira/models/claude_35_sonnet.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    class Claude35Sonnet < BaseModel
+      def self.model_name
+        "claude-3-5-sonnet-20241022"
+      end
+
+      def self.context_limit
+        200_000
+      end
+    end
+  end
+end

data/lib/zephira/models/gpt_5_4.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    class Gpt54 < BaseModel
+      def self.model_name
+        "gpt-5.4"
+      end
+
+      def self.context_limit
+        1_047_576
+      end
+    end
+  end
+end

data/lib/zephira/models/gpt_5_5.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    class Gpt55 < BaseModel
+      def self.model_name
+        "gpt-5.5"
+      end
+
+      def self.context_limit
+        1_047_576
+      end
+    end
+  end
+end

data/lib/zephira/models/gpt_o4_mini.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    class GptO4Mini < BaseModel
+      def self.model_name
+        "o4-mini"
+      end
+
+      def self.context_limit
+        200_000
+      end
+    end
+  end
+end

data/lib/zephira/models/llama4.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    class Llama4 < BaseModel
+      def self.model_name
+        "meta-llama/llama-4-maverick-17b-128e-instruct"
+      end
+
+      def self.context_limit
+        131_072
+      end
+    end
+  end
+end

data/lib/zephira/models.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Zephira
+  module Models
+    require_relative "models/base_model"
+    Dir[File.join(__dir__, "models", "*.rb")].each { |file| require file }
+
+    def self.available
+      constants(false)
+        .map { |const| const_get(const) }
+        .reject { |const| const == BaseModel }
+        .select { |const| const.respond_to?(:model_name) }
+    end
+
+    def self.find_by_name(name)
+      available.find { |model| model.model_name.casecmp(name.to_s).zero? }
+    end
+  end
+end