omniai-tools 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 04d1c28a8b8a92c2cc6c0ada9976d58ee2aed291fe25368356ce9a055b14cc7e
-  data.tar.gz: 5afcc660cd72ef9ed7cea14fb6478a3239af14d8e519e3ba2bb89c32ccfaeb97
+  metadata.gz: f361e26584723aa8d30ba41edaefafb44a7e08c5c6345656dbf25e37c965448d
+  data.tar.gz: c718feeb39dfdd1c2c5ff9a2976ece26eec48aae12f52405724fc21209101d32
 SHA512:
-  metadata.gz: f1331d0fc5ed4b89072e8d793620b7531d240556bca49be4a6a9b16e3368a96df3d8ca7a45c4e50198d97850b50ee13319875d4a8152ea8e7c93676d3eb81653
-  data.tar.gz: 39ac4a40cbcafe9876e51c9a7a5f8b63c3d51c9bfc7f63afe6a47e209ed0ee6acbdb8d7c5845e3f9b7fab3ed6dac8eb946eda1a69d900f8a3d897cee67bb3b52
+  metadata.gz: fa14b3333edc0b235e046d9f408f75f201ea37be76435d897873fb7585999cd0aeac3d36c86c16e72a772ab6a28f48dd40560074767720736583de79a80d8847
+  data.tar.gz: 6ec511fc27bae83abdf0d827572ad2784419039b0d37d128d5670b19d58645a8e6efd82bfb7132397473181b56897f966314396a76172aaec33883826ff14f12

data/Gemfile

@@ -16,4 +16,5 @@ gem "rubocop-factory_bot"
 gem "rubocop-rake"
 gem "rubocop-rspec"
 gem "simplecov"
+gem "sqlite3"
 gem "yard"

data/README.md

@@ -6,11 +6,59 @@
 [![Yard](https://img.shields.io/badge/docs-site-blue.svg)](https://omniai-tools.ksylvest.com)
 [![CircleCI](https://img.shields.io/circleci/build/github/ksylvest/omniai-tools)](https://circleci.com/gh/ksylvest/omniai-tools)
 
-`OmniAI::Tools` is a library of pre-built tools to simplify integrating common tasks w/ [OmniAI](https://github.com/ksylvest/omniai).
+`OmniAI::Tools` is a library of pre-built tools to simplify integrating common tasks with [OmniAI](https://github.com/ksylvest/omniai).
+
+## Database
+
+Database tools are focused on running SQL statements:
+
+```ruby
+require "omniai/openai"
+require "omniai/tools"
+
+require "sqlite3"
+
+db = SQLite3::Database.new(":memory:")
+
+client = OmniAI::OpenAI::Client.new
+logger = Logger.new($stdout)
+
+tools = [
+  OmniAI::Tools::Database::SqliteTool.new(logger:, db:),
+]
+
+puts "Type 'exit' or 'quit' to leave."
+
+prompt = OmniAI::Chat::Prompt.build do |builder|
+  builder.system "Use tools to manage a database as requested."
+end
+
+loop do
+  print "# "
+  text = gets.strip
+  break if %w[exit quit].include?(text)
+
+  prompt.user(text)
+  response = client.chat(prompt, stream: $stdout, tools:)
+  prompt.assistant(response.text)
+end
+```
+
+```
+Type 'exit' or 'quit' to leave.
+# Generate tables for artists, albums, songs, bands, members and populate it with data surrounding the Beatles.
+
+CREATE TABLE artists (id INTEGER PRIMARY KEY, name TEXT NOT NULL)
+CREATE TABLE bands (id INTEGER PRIMARY KEY, name TEXT NOT NULL)
+CREATE TABLE members (id INTEGER PRIMARY KEY, artist_id INTEGER, band_id INTEGER, FOREIGN KEY(artist_id) REFERENCES artists(id), FOREIGNKEY(band_id) REFERENCES bands(id))"
+CREATE TABLE albums (id INTEGER PRIMARY KEY, title TEXT NOT NULL, band_id INTEGER, FOREIGN KEY(band_id) REFERENCES bands(id))
+CREATE TABLE songs (id INTEGER PRIMARY KEY, title TEXT NOT NULL, album_id INTEGER, FOREIGN KEY(album_id) REFERENCES albums(id))
+...
+```
 
 ## Disk
 
-Disk tools are focused on creating / updating / deleting files and directories within a "root":
+Disk tools are focused on creating, updating, and deleting files and directories within a "root":
 
 ```ruby
 require "omniai/openai"
@@ -53,7 +101,7 @@ end
 
 ## Docker
 
-Disk tools are focused on running commands through Docker via compose:
+Docker tools are focused on running commands through Docker via Compose:
 
 ```ruby
 require "omniai/openai"
@@ -72,7 +120,7 @@ tools = [
 puts "Type 'exit' or 'quit' to leave."
 
 prompt = OmniAI::Chat::Prompt.build do |builder|
-  builder.system "Use tools to interact with docker."
+  builder.system "Use tools to interact with Docker."
 end
 
 loop do

data/lib/omniai/tools/database/base_tool.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+
+module OmniAI
+  module Tools
+    module Database
+      # @example
+      #   tool = OmniAI::Tools::Database::SqliteTool.new
+      #   tool.execute(path: "./foo/bar")
+      class BaseTool < OmniAI::Tool
+        # @param logger [IO] An optional logger for debugging executed commands.
+        def initialize(logger: Logger.new(IO::NULL))
+          super()
+          @logger = logger
+        end
+
+        # @example
+        #   tool = OmniAI::Tools::Database::BaseTool.new
+        #   tool.execute(statements: ["SELECT * FROM people"])
+        #
+        # @param statements [Array<String>]
+        #
+        # @return [Array<Hash>]
+        def execute(statements:)
+          [].tap do |executions|
+            statements.map do |statement|
+              execution = perform(statement:)
+              executions << execution
+              break unless execution[:status].eql?(:ok)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omniai/tools/database/sqlite_tool.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "sqlite3"
+
+module OmniAI
+  module Tools
+    module Database
+      # @example
+      #   tool = OmniAI::Tools::Database::SqliteTool.new
+      #   tool.execute(path: "./foo/bar")
+      class SqliteTool < BaseTool
+        description <<~TEXT
+          Executes SQL commands (INSERT / UPDATE / SELECT / etc) on a database.
+
+          Example:
+
+          STATEMENTS:
+
+              [
+                'CREATE TABLE people (id INTEGER PRIMARY KEY, name TEXT NOT NULL)',
+                'INSERT INTO people (name) VALUES ('John')',
+                'INSERT INTO people (name) VALUES ('Paul')',
+                'SELECT * FROM people',
+                'DROP TABLE people'
+              ]
+
+          RESULT:
+
+              [
+                {
+                  "status": "OK",
+                  "statement": "CREATE TABLE people (id INTEGER PRIMARY KEY, name TEXT NOT NULL)",
+                  "result": "..."
+                },
+                {
+                  "status": "OK",
+                  "statement": "INSERT INTO people (name) VALUES ('John')"
+                  "result": "..."
+                },
+                {
+                  "status": "OK",
+                  "statement": "INSERT INTO people (name) VALUES ('Paul')",
+                  "result": "..."
+                },
+                {
+                  "status": "OK",
+                  "statement": "SELECT * FROM people",
+                  "result": "..."
+                },
+                {
+                  "status": "OK",
+                  "statement": "DROP TABLE people",
+                  "result": "..."
+                }
+              ]
+        TEXT
+
+        parameter(
+          :statements,
+          :array,
+          description: "A list of SQL statements to run sequentially.",
+          items: OmniAI::Schema.string(description: 'A SQL statement to run (e.g. "SELECT * FROM ...").')
+        )
+
+        required %i[statements]
+
+        # @param logger [IO] An optional logger for debugging executed commands.
+        # @param db [SQLite3::Database] A sqlite database.
+        def initialize(db:, logger: Logger.new(IO::NULL))
+          super(logger:)
+          @db = db
+        end
+
+        # @example
+        #   tool = OmniAI::Tools::Database::BaseTool.new
+        #   tool.execute(statements: ["SELECT * FROM people"])
+        #
+        # @param statements [Array<String>]
+        #
+        # @return [Array<Hash>]
+        def execute(statements:)
+          [].tap do |executions|
+            statements.map do |statement|
+              execution = perform(statement:)
+              executions << execution
+              break unless execution[:status].eql?(:ok)
+            end
+          end
+        end
+
+      protected
+
+        # @param statement [String]
+        #
+        # @return [Hash]
+        def perform(statement:)
+          @logger.info(%(#{self.class.name}#perform statement=#{statement.inspect}))
+
+          result = @db.execute2(statement)
+
+          { status: :ok, statement:, result: }
+        rescue ::SQLite3::Exception => e
+          @logger.warn("ERROR: #{e.message}")
+
+          { status: :error, statement:, result: e.message }
+        end
+      end
+    end
+  end
+end

data/lib/omniai/tools/disk/directory_move_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OmniAI
+  module Tools
+    module Disk
+      # @example
+      #   tool = OmniAI::Tools::Disk::DirectoryCreateTool.new(root: "./project")
+      #   tool.execute(path: "./foo/bar")
+      class DirectoryCreateTool < BaseTool
+        description "Creates a directory."
+
+        parameter :old_path, :string, description: "a path (e.g. `./old`)"
+        parameter :new_path, :string, description: "a path (e.g. `./new`)"
+
+        required %i[old_path new_path]
+
+        # @param old_path [String]
+        # @param new_path [String]
+        #
+        # @return [String]
+        def execute(old_path:, new_path:)
+          @logger.info("#{self.class.name}#execute path=#{path.inspect}")
+
+          FileUtils.mv(old_path, new_path)
+        rescue SecurityError => e
+          @logger.error(e.message)
+          raise e
+        end
+      end
+    end
+  end
+end

data/lib/omniai/tools/disk/file_delete_tool.rb

@@ -7,9 +7,9 @@ module OmniAI
       #   tool = OmniAI::Tools::Disk::FileDeleteTool.new(root: "./project")
       #   tool.execute(path: "./README.md")
       class FileDeleteTool < BaseTool
-        description "reads the contents of a file"
+        description "Deletes a file."
 
-        parameter :path, :string, description: "a path to the directory (e.g. `./foo/bar`)"
+        parameter :path, :string, description: "a path to the file (e.g. `./README.md`)"
 
         required %i[path]
 

data/lib/omniai/tools/disk/file_move_tool.rb

@@ -4,13 +4,13 @@ module OmniAI
   module Tools
     module Disk
       # @example
-      #   tool = OmniAI::Tools::Disk::FileDeleteTool.new(root: "./project")
+      #   tool = OmniAI::Tools::Disk::FileMoveTool.new(root: "./project")
       #   tool.execute(
       #     old_path: "./README.txt",
       #     new_path: "./README.md",
       #   )
       class FileMoveTool < BaseTool
-        description "moves a file"
+        description "Moves a file."
 
         parameter :old_path, :string, description: "a path (e.g. `./old.rb`)"
         parameter :new_path, :string, description: "a path (e.g. `./new.rb`)"

data/lib/omniai/tools/disk/file_read_tool.rb

@@ -7,7 +7,7 @@ module OmniAI
       #   tool = OmniAI::Tools::Disk::FileReadTool.new(root: "./project")
       #   tool.execute(path: "./README.md") # => "..."
       class FileReadTool < BaseTool
-        description "reads the contents of a file"
+        description "Reads the contents of a file."
 
         parameter :path, :string, description: "a path (e.g. `./main.rb`)"
 

data/lib/omniai/tools/disk/file_replace_tool.rb

@@ -11,7 +11,7 @@ module OmniAI
       #     path: "README.md"
       #   )
       class FileReplaceTool < BaseTool
-        description "replace a specific string in a file (old_text => new_text)"
+        description "Replaces a specific string in a file (old_text => new_text)."
 
         parameter :old_text, :string, description: "the old text (e.g. `puts 'ABC'`)"
         parameter :new_text, :string, description: "the new text (e.g. `puts 'DEF'`)"

data/lib/omniai/tools/disk/file_write_tool.rb

@@ -7,7 +7,7 @@ module OmniAI
       #    tool = OmniAI::Tools::Disk::FileWriteTool.new(root: "./project")
       #    tool.execute(path: "./README.md", text: "Hello World")
       class FileWriteTool < BaseTool
-        description "Write the contents of a file."
+        description "Writes the contents of a file."
 
         parameter :path, :string, description: "a path for the file (e.g. `./main.rb`)"
         parameter :text, :string, description: "the text to write to the file (e.g. `puts 'Hello World'`)"

data/lib/omniai/tools/disk/summary_tool.rb

@@ -7,7 +7,7 @@ module OmniAI
       #   tool = OmniAI::Tools::Disk::SummaryTool.new(root: "./project")
       #   tool.execute
       class SummaryTool < BaseTool
-        description "Summarize the contents (files and directories) of the project."
+        description "Summarizes the contents (files and directories) of the project."
 
         # @return [String]
         def execute

data/lib/omniai/tools/docker/compose_run_tool.rb

@@ -9,12 +9,12 @@ module OmniAI
       #   tool = OmniAI::Tools::Docker::ComposeRunTool.new(root: "./project")
       #   tool.execute(service: "app", command: "rspec" args: ["spec/main_spec.rb"])
       class ComposeRunTool < BaseTool
-        description "Run a command via docker with arguments on the project (e.g. `rspec spec/main_spec.rb`)."
+        description "Runs a command via Docker with arguments on the project (e.g. `rspec spec/main_spec.rb`)."
 
-        parameter :service, :string, description: "the service to run the command against (e.g. `app`)"
-        parameter :command, :string, description: "the command to run (e.g. `rspec`)"
-        parameter :args, :array, description: "the arguments for the command",
-          items: OmniAI::Tool::Property.string(description: "an argument for the command (e.g. `spec/main_spec.rb`)")
+        parameter :service, :string, description: "The service to run the command on (e.g. `app`)."
+        parameter :command, :string, description: "The command to run (e.g. `rspec`)."
+        parameter :args, :array, description: "The arguments for the command.",
+          items: OmniAI::Schema.string(description: "An argument for the command (e.g. `spec/main_spec.rb`).")
 
         # @param service [String]
         # @param command [String]

data/lib/omniai/tools/version.rb

@@ -2,6 +2,6 @@
 
 module OmniAI
   module Tools
-    VERSION = "0.2.0"
+    VERSION = "0.4.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: omniai-tools
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kevin Sylvestre
 bindir: exe
 cert_chain: []
-date: 2025-04-23 00:00:00.000000000 Z
+date: 2025-05-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: omniai
@@ -49,9 +49,12 @@ files:
 - bin/console
 - bin/setup
 - lib/omniai/tools.rb
+- lib/omniai/tools/database/base_tool.rb
+- lib/omniai/tools/database/sqlite_tool.rb
 - lib/omniai/tools/disk/base_tool.rb
 - lib/omniai/tools/disk/directory_create_tool.rb
 - lib/omniai/tools/disk/directory_delete_tool.rb
+- lib/omniai/tools/disk/directory_move_tool.rb
 - lib/omniai/tools/disk/file_create_tool.rb
 - lib/omniai/tools/disk/file_delete_tool.rb
 - lib/omniai/tools/disk/file_move_tool.rb