aigency 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c413cf37072efae1aa6df896884d291ee9bac175a1154e579d85833692f55959
+  data.tar.gz: feaacbce278ae242f36bd8f2b3024d014bb200dad97679f6fb023986def493ec
+SHA512:
+  metadata.gz: '09ba427def6dcce5abcb433c76d44276c58af597ad15f703e1cfb3503e8a527f2944951314c6a2a53e3b91cc54005d54c996e659288d4726e71d0565a33e7cef'
+  data.tar.gz: e4ef1fea768cd49fad82edf2ea4086b792118c545c7d12ea8772e0ba7c694793fa45c3024552ca35b9677d15a744a133a6f94bcf5f98a952008a6e5fefd9834b

data/README.md

@@ -0,0 +1,47 @@
+# Aigency
+
+A framework for creating AI agents with RubyLLM.
+
+## Installation
+
+Install the gem from the command line:
+
+```bash
+gem install aigency
+```
+
+Or add it to your Gemfile:
+
+```ruby
+gem 'aigency'
+```
+
+## Usage
+
+### Creating a New Aigent
+
+The recommended way to create an aigent is to give it a dedicated system user.
+
+```bash
+useradd aigent_user
+sudo su - aigent_user
+```
+
+Once you're logged in as the aigent user, create the aigent directory:
+
+```bash
+aigency enlist
+cd aigent
+bundle install
+rake setup
+```
+
+The bare minimum configuration you need to do is setting `openai_api_base` and `openai_api_key` in `config/aigent.yml`.
+
+Test the aigent with with the `rake say` task.
+
+```bash
+rake say["How many fibers are intertwined in a shredded wheat biscuit?"]
+```
+
+See the aigent's README (scaffold/README.md in this codebase) for more information.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/exe/aigency

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# turn off warning diagnostics from Ruby
+$VERBOSE=nil
+
+require 'aigency'
+
+Aigency::Shell.start(ARGV)

data/lib/aigency/aigent.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'yaml'
+
+module Aigency
+  class Aigent
+    # @return [IO]
+    attr_reader :log
+
+    def initialize(directory)
+      @base_directory = File.absolute_path(directory)
+      @log = $stdout
+      load_requires
+    end
+
+    # @return [String]
+    def name
+      @name ||= config('aigent')['name'] || "an Aigent"
+    end
+
+    # Get the aigent directory with optional additional paths.
+    #
+    # @param paths [Array<String>] Additional paths
+    # @return [String] The complete path
+    def directory(*paths)
+      File.join(@base_directory, *paths)
+    end
+
+    # Get the aigent data directory with optional additional paths.
+    #
+    # @param paths [Array<String>] Additional paths
+    # @return [String] The complete path
+    def data(*paths)
+      directory('data', *paths)
+    end
+
+    # Initialize a RubyLLM::Chat.
+    #
+    # @param extra [Array<String>] Additional instructions
+    # @return [RubyLLM::Chat]
+    def brief(*extra)
+      chat = rubyllm_context.chat(provider: :openai)
+      Tools.registry.each { |klass| chat.with_tool(klass.new(self)) }
+      chat.with_instructions(build_instructions(extra), append: true)
+      # @todo This should be configurable
+      chat.with_params(max_tokens: max_tokens)
+    end
+
+    def load filename, *extra, out: $stdout
+      stream File.read(filename), *extra, out: out
+    end
+
+    def stream text, *extra, with: [], out: $stdout
+      original_log = @log
+      @log = out
+      brief(*extra).ask text, with: with do |chunk|
+        @log.print chunk.thinking&.text
+        @log.print chunk.content
+      end.tap { @log = original_log }
+    end
+
+    # @param name [String]
+    # @return [Hash]
+    def config(name)
+      configs[name] ||= read_config(name)
+    end
+
+    # Initialize the aigent's tool configurations.
+    #
+    # @param only [Array<String>] Limit the tools being configured
+    # @param overwrite [Boolean] Replace existing configs if true
+    def setup(only: [], overwrite: false)
+      only = [only].flatten.compact
+      config_count = 0
+      Tools.config_map.each do |name, text|
+        next unless only.empty? || only.include?(name)
+
+        dir = directory('config')
+        FileUtils.mkdir_p dir
+        path = File.join(dir, "#{name}.yml")
+        if overwrite || !File.file?(path)
+          doing = File.file?(path) ?  'Overwriting' : 'Writing new'
+          log.puts "#{doing} config for #{name}"
+          File.write path, text
+          config_count += 1
+        else
+          log.puts "Config for #{name} exists, skipping"
+        end
+      end
+      dir_count = 0
+      Tools.directories.each do |path|
+        absolute = directory(path)
+        next if File.directory?(absolute)
+
+        FileUtils.mkdir_p absolute
+        dir_count += 1
+      end
+      log.puts "#{config_count} config files initialized."
+      log.puts "#{dir_count} directories created."
+    end
+
+    # Run code in an exclusive lock
+    #
+    def lock(&block)
+      File.open(data('lock'), 'w') do |file|
+        file.flock(File::LOCK_EX)
+        file.write(Process.pid)
+        file.flush
+        block&.call
+      end
+    end
+
+    # Run code if an exclusive lock is available or skip if a lock exists
+    #
+    def try_with_lock(&block)
+      File.open(data('lock'), 'w') do |file|
+        acquired = file.flock(File::LOCK_EX|File::LOCK_NB)
+        return unless acquired
+        file.write(Process.pid)
+        file.flush
+        block&.call
+      end
+    end
+    alias nonblock try_with_lock
+
+    # True if an exclusive lock exists
+    #
+    def locked?
+      File.open(data('lock'), File::RDWR|File::CREAT) do |file|
+        result = file.flock(File::LOCK_EX|File::LOCK_NB)
+        return !result
+      end
+    end
+    alias busy? locked?
+
+    def instructions
+      @instructions ||= build_instructions([])
+    end
+
+    private
+
+    def configs
+      @configs ||= {}
+    end
+
+    def read_config(name)
+      base = directory('config')
+      filename = if name =~ /(\.yaml|\.yml)$/
+        name
+      else
+        "#{name}.yml"
+      end
+      full_path = File.join(directory, 'config', filename)
+      if File.file?(full_path)
+        YAML.load_file(full_path)
+      else
+        warn "Config name #{name} not found at #{full_path}"
+        {}
+      end
+    end
+
+    def identity_file
+      @identity_file ||= File.join(directory, 'IDENTITY.md')
+    end
+
+    def identity_file?
+      File.file?(identity_file)
+    end
+
+    def base_instructions
+      @base_instructions ||= identity_file? ? File.read(identity_file) : "You are a helpful AI assistant."
+    end
+
+    def build_instructions(extra)
+      [base_instructions].concat tool_prompts
+                         .push "Today's date is #{DateTime.now.strftime('%B %e, %Y')}."
+                         .concat extra
+                         .join("\n\n")
+    end
+
+    def tool_prompts
+      Tools.config_map
+           .keys
+           .map { |name| config(name)['prompt'] }
+           .compact
+    end
+
+    def load_requires
+      read_requires.each { |name| require name }
+    end
+
+    def read_requires
+      config('aigent')['require'] || []
+    end
+
+    def max_tokens
+      @max_tokens ||= (config('aigent')['max_tokens'] || -1).to_i
+    end
+
+    def rubyllm_context
+      RubyLLM.context do |config|
+        config.openai_api_base = config('aigent')['openai_api_base']
+        config.openai_api_key = config('aigent')['openai_api_key']
+      end
+    end
+  end
+end

data/lib/aigency/shell.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+require 'thor'
+
+module Aigency
+  class Shell < Thor
+    map %i[new] => :enlist
+    desc "enlist [DIRECTORY]", "Enable the current user as an aigent"
+    option :directory, type: :string, desc: 'Aigent directory', default: File.join(Dir.home, 'aigent')
+    def enlist
+      directory = options[:directory]
+      puts "Installing aigent at #{directory}"
+      if File.exist?(directory)
+        if !File.directory?(directory)
+          raise "#{directory} is not a directory."
+        end
+        if !Dir.empty?(directory)
+          raise "#{directory} is not empty."
+        end
+      end
+      FileUtils.mkdir(directory) unless File.directory?(directory)
+      FileUtils.copy_entry(File.join(GEM_PATH, 'scaffold'), directory)
+    end
+  end
+end

data/lib/aigency/tool.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Aigency
+  # A subclass of RubyLLM::Tool with aigent integration.
+  #
+  class Tool < RubyLLM::Tool
+    include Usability
+  end
+end

data/lib/aigency/tools.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Tools
+    # @return [Array<Class<Tool>>]
+    def self.registry
+      @registry ||= []
+    end
+
+    # @return [Hash{String => String}]
+    def self.config_map
+      @configs ||= {}
+    end
+
+    # @return [Array<String>]
+    def self.directories
+      @directories ||= []
+    end
+
+    # Register a tool.
+    #
+    # @param klass [Class<Tool>]
+    # @return [void]
+    def self.register klass
+      registry.push klass
+    end
+
+    # Define a default configuration.
+    #
+    # @param name [String] The name of the config section
+    # @param text [String] YAML-formatted config data
+    # @return [void]
+    def self.configure name, text
+      config_map[name] = text
+    end
+
+    # Define directories to be created relative to an aigent's root.
+    #
+    def self.mkdir_p *paths
+      directories.concat paths
+    end
+  end
+
+  Tools.configure 'aigent', <<~EOF
+    name: an Aigent
+    openai_api_base: https://api.openai.com/v1
+    openai_api_key: CHANGE_ME
+    require:
+      - aigency/email
+      - aigency/wikipedia
+      - aigency/workspace
+  EOF
+
+  Tools.mkdir_p 'data/chats', 'data/log'
+end

data/lib/aigency/usability.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Usability
+    attr_reader :aigent
+
+    def initialize(aigent)
+      @aigent = aigent
+      post_initialize
+    end
+
+    def post_initialize
+    end
+
+    # Subclasses need to implement functionality here.
+    #
+    # @abstract
+    def execute(**opts)
+      raise 'Not implemented'
+    end
+
+    def self.included other
+      other.extend ClassMethods
+    end
+
+    module ClassMethods
+      def execute(aigent, **opts)
+        new(aigent).execute(**opts)
+      end
+    end
+  end
+end

data/lib/aigency/version.rb

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

data/lib/aigency/workspace/directory_deleter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class DirectoryDeleter < Tool
+      desc "Deletes a directory from your private workspace"
+
+      def execute(dirname:)
+        puts "Deleting directory #{dirname}"
+
+        resolved = File.absolute_path(dirname, aigent.data('workspace'))
+        return { dirname: dirname, success: false, error: "Permission denied" } unless resolved.start_with?(aigent.data('workspace'))
+        return { dirname: dirname, success: false, error: "Permission denied" } if resolved.include?('/.git/') || resolved.end_with?('/.git')
+        return { dirname: dirname, success: false, error: "Not a directory" } if File.file?(resolved)
+        return { dirname: dirname, sucess: false, error: "Directory not found" } unless File.directory?(resolved)
+
+        FileUtils.rm_rf(resolved)
+        { dirname: dirname, success: true }
+      end
+    end
+  end
+end
+
+Aigency::Tools.register Aigency::Workspace::DirectoryDeleter

data/lib/aigency/workspace/directory_reader.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class DirectoryReader < Tool
+      desc "Gets the contents of a directory from your private workspace"
+
+      def execute(directory_name:)
+        aigent.log.puts "[Workspace::DirectoryReader] Reading #{directory_name}"
+        directory = aigent.data('workspace')
+        resolved = File.absolute_path(directory_name, directory)
+        return { directory: directory_name,
+                 success: false,
+                 error: "Permission denied. Path must be local to #{directory}" } unless resolved.start_with?(directory)
+
+        if File.directory?(resolved)
+          {
+            directory: directory_name,
+            success: true,
+            entries: Dir[File.join(resolved, '*')].map { |dir| dir[resolved.length+1..]}
+          }
+        else
+          {
+            directory: directory_name,
+            success: false,
+            error: "Not a directory"
+          }
+        end
+      end
+    end
+  end
+end
+
+Aigency::Tools.register Aigency::Workspace::DirectoryReader

data/lib/aigency/workspace/file_deleter.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class FileDeleter < Tool
+      desc "Deletes a file from your private workspace"
+
+      def execute(filename:)
+        aigent.log.puts "[Workspace::FileDeleter] Deleting file #{filename}"
+
+        directory = aigent.data('directory')
+        resolved = File.absolute_path(filename, directory)
+        return { filename: filename, error: "Permission denied" } unless resolved.start_with?(directory)
+        return { filename: filename, error: "Permission denied" } if resolved.include?('/.git/')
+        return { filename: filename, error: "File does not exist" } unless File.file?(resolved)
+
+        File.delete resolved
+        { filename: filename, success: true }
+      end
+    end
+  end
+end
+
+Aigency::Tools.register Aigency::Workspace::FileDeleter

data/lib/aigency/workspace/file_reader.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    class FileReader < Tool
+      desc "Reads a file from your private workspace"
+
+      def execute(filename:)
+        aigent.log.puts "[Workspace::FileReader] Reading #{filename}"
+
+        directory = aigent.data('workspace')
+        resolved = File.absolute_path(filename, directory)
+        return { filename: filename, success: false, error: "Permission denied" } unless resolved.start_with?(directory)
+
+        if File.file?(resolved)
+          {
+            filename: filename,
+            success: true,
+            content: File.read(resolved)
+          }
+        else
+          {
+            filename: filename,
+            success: false,
+            error: "File not found"
+          }
+        end
+      end
+    end
+  end
+end
+
+Aigency::Tools.register Aigency::Workspace::FileReader

data/lib/aigency/workspace/file_writer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Aigency
+  module Workspace
+    class FileWriter < Tool
+      desc "Writes a file to your private workspace"
+
+      def execute(filename:, content:)
+        aigent.log.puts "[Workspace::FileWriter] Writing #{filename}"
+
+        directory = aigent.data('workspace')
+        resolved = File.absolute_path(filename, directory)
+        return { filename: filename, success: false, error: "Permission denied" } unless resolved.start_with?(directory)
+
+        FileUtils.mkdir_p File.dirname(resolved)
+        File.write resolved, content
+        return { filename: filename, success: true }
+      end
+    end
+  end
+end
+
+Aigency::Tools.register Aigency::Workspace::FileWriter

data/lib/aigency/workspace.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Aigency
+  module Workspace
+    require 'aigency/workspace/directory_reader'
+    require 'aigency/workspace/file_reader'
+    require 'aigency/workspace/file_writer'
+  end
+
+  Tools.mkdir_p 'data/workspace'
+end

data/lib/aigency.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require 'ruby_llm'
+
+# Core
+require 'aigency/version'
+require 'aigency/usability'
+require 'aigency/tool'
+require 'aigency/tools'
+require 'aigency/aigent'
+require 'aigency/shell'
+
+# Extensions
+require 'aigency/workspace'
+
+module Aigency
+  GEM_PATH = File.absolute_path(File.join(__dir__, '..'))
+
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/scaffold/.gitignore

@@ -0,0 +1 @@
+data

data/scaffold/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gem "dotenv"
+gem "rake", "~> 13.0"
+gem "whenever", "~> 1.1"
+
+gem "ruby_llm"
+gem "aigency", path: "../aigency"

data/scaffold/IDENTITY.md

@@ -0,0 +1 @@
+You are a helpful AI assistant.

data/scaffold/README.md

@@ -0,0 +1,74 @@
+# Your Aigent
+
+An aigent (AI agent) is an intelligent assistant powered by language models through OpenAI-compatible APIs. It can read and write files in its private workspace and perform scheduled tasks on your behalf.
+
+## Configuration
+
+### Install dependencies
+
+```bash
+bundle install
+```
+
+### Initial setup
+
+```bash
+rake setup
+```
+
+### 1. Configure the Aigent
+
+Configure the aigent's settings in `config/aigent.yml`.
+
+#### OpenAI-Compatible Providers
+
+If you're using a local AI server or any other provider that is compatible with OpenAI, you can set the OPENAI_API_BASE config option to point there instead (e.g., `http://localhost:8080/v1`).
+
+### 2. Define the Aigent's Personality
+
+Edit `IDENTITY.md` to define how your aigent should behave:
+
+```markdown
+You are a professional assistant named Alex. You respond in a friendly but concise manner.
+```
+
+This file sets the foundation for all the aigent's responses.
+
+## Usage
+
+### Interactive Mode
+
+Talk to your aigent using the Rake task:
+
+```bash
+rake say["Tell me about project progress"]
+```
+
+### The Workspace
+
+Your aigent has read/write access to everything in the `data/workspace` directory.
+
+### Scheduling Tasks
+
+The project includes the `whenever` gem for scheduling. Example of a scheduled task:
+
+```ruby
+# config/schedule.rb
+
+# Every day at 9am, the aigent will run the prompt in the DAILY_TASKS.md file
+every 1.day, at: '9am' do
+  rake 'load[DAILY_TASKS.md]'
+end
+```
+
+Add the scheduled tasks to your crontab:
+
+```bash
+bundle exec whenever --update-crontab
+```
+
+(Note: the `whenever` gem does not work on Windows.)
+
+## Aigent Tools
+
+You can give your aigent more functionality by installing additional tools. It ships with the `Workspace` tool, which gives it full read/write access to the `data/workspace` directory.

data/scaffold/Rakefile

@@ -0,0 +1,30 @@
+require "bundler/setup"
+require 'yaml'
+require 'dotenv/load'
+require 'aigency'
+
+desc "Run a prompt from a file"
+task :load, [:filename] do |_, args|
+  aigent = Aigency::Aigent.new('.')
+  aigent.nonblock do
+    filename = File.join('data', 'chats', "#{Time.now.strftime("%Y-%m-%d_%H%M%S")}_load_#{args[:filename].gsub('/', '_')}.txt")
+    File.open(filename, 'w') do |file|
+      aigent.load args[:filename], out: file
+    rescue StandardError => e
+      file.puts "[#{e.class}]: #{e.message}"
+      file.puts e.backtrace
+    end
+  end
+end
+
+desc "Talk to the aigent"
+task :say, [:text] do |_, args|
+  aigent = Aigency::Aigent.new('.')
+  aigent.stream args[:text]
+end
+
+desc "Set up aigent configurations"
+task :setup do
+  aigent = Aigency::Aigent.new('.')
+  aigent.setup
+end

data/scaffold/config/aigent.yml

@@ -0,0 +1,6 @@
+name: an Aigent
+openai_api_base: https://api.openai.com/v1
+openai_api_key: CHANGE_ME
+# max_tokens: 65536
+# require:
+#   - aigency-example

data/scaffold/config/schedule.rb

@@ -0,0 +1,24 @@
+# Use this file to easily define all of your cron jobs.
+#
+# It's helpful, but not entirely necessary to understand cron before proceeding.
+# http://en.wikipedia.org/wiki/Cron
+
+# Example:
+#
+# set :output, "/path/to/my/cron_log.log"
+#
+# every 2.hours do
+#   command "/usr/bin/some_great_command"
+#   runner "MyModel.some_method"
+#   rake "some:great:rake:task"
+# end
+#
+# every 4.days do
+#   runner "AnotherModel.prune_old_records"
+# end
+
+# Learn more: http://github.com/javan/whenever
+
+# every 1.day do
+#   rake "load[DAILY.md]"
+# end

data/sig/aigency.rbs

@@ -0,0 +1,4 @@
+module Aigency
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: aigency
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Fred Snyder
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fileutils
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+email:
+- fsnyder@castwide.com
+executables:
+- aigency
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- exe/aigency
+- lib/aigency.rb
+- lib/aigency/aigent.rb
+- lib/aigency/shell.rb
+- lib/aigency/tool.rb
+- lib/aigency/tools.rb
+- lib/aigency/usability.rb
+- lib/aigency/version.rb
+- lib/aigency/workspace.rb
+- lib/aigency/workspace/directory_deleter.rb
+- lib/aigency/workspace/directory_reader.rb
+- lib/aigency/workspace/file_deleter.rb
+- lib/aigency/workspace/file_reader.rb
+- lib/aigency/workspace/file_writer.rb
+- scaffold/.gitignore
+- scaffold/Gemfile
+- scaffold/IDENTITY.md
+- scaffold/README.md
+- scaffold/Rakefile
+- scaffold/config/aigent.yml
+- scaffold/config/schedule.rb
+- sig/aigency.rbs
+licenses: []
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: A framework for building agentic AI workers.
+test_files: []