ollama_agent 0.3.0 → 1.0.0

data/lib/ollama_agent/tools/base.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  module Tools
+    # Base class for all typed, permissioned, auditable tools.
+    #
+    # Subclasses must implement #call(args, context:) and define:
+    #   - name         String
+    #   - description  String
+    #   - input_schema Hash   (JSON schema for arguments)
+    #
+    # @example
+    #   class MyTool < OllamaAgent::Tools::Base
+    #     tool_name        "my_tool"
+    #     tool_description "Does something useful"
+    #     tool_risk        :low
+    #     tool_schema      { type: "object", properties: { ... }, required: [...] }
+    #
+    #     def call(args, context:)
+    #       { result: args["input"].upcase }
+    #     end
+    #   end
+    class Base
+      RISK_LEVELS = %i[low medium high critical].freeze
+
+      class << self
+        def tool_name(name = nil)
+          @tool_name = name.to_s if name
+          @tool_name || raise(NotImplementedError, "#{self}.tool_name not set")
+        end
+
+        def tool_description(desc = nil)
+          @tool_description = desc if desc
+          @tool_description || ""
+        end
+
+        def tool_risk(level = nil)
+          @tool_risk = level.to_sym if level
+          @tool_risk || :low
+        end
+
+        def tool_requires_approval(flag = nil)
+          @tool_requires_approval = flag unless flag.nil?
+          @tool_requires_approval.nil? ? (@tool_risk || :low) == :high || (@tool_risk || :low) == :critical : @tool_requires_approval
+        end
+
+        def tool_schema(schema = nil)
+          @tool_schema = schema if schema
+          @tool_schema || { type: "object", properties: {}, required: [] }
+        end
+
+        def tool_output_schema(schema = nil)
+          @tool_output_schema = schema if schema
+          @tool_output_schema
+        end
+
+        def inherited(subclass)
+          super
+          # subclass inherits nil overrides so defaults still apply
+        end
+      end
+
+      attr_reader :name, :description, :input_schema, :output_schema, :risk_level, :requires_approval
+
+      def initialize
+        @name               = self.class.tool_name
+        @description        = self.class.tool_description
+        @input_schema       = self.class.tool_schema
+        @output_schema      = self.class.tool_output_schema
+        @risk_level         = self.class.tool_risk
+        @requires_approval  = self.class.tool_requires_approval
+      end
+
+      # Execute the tool.
+      # @param args    [Hash]   validated argument hash
+      # @param context [Hash]   runtime context: { root:, read_only:, run_id:, … }
+      # @return [String, Hash]  result surfaced back to the model
+      def call(args, context: {})
+        raise NotImplementedError, "#{self.class}#call not implemented"
+      end
+
+      # JSON schema formatted for Ollama / OpenAI tool_call
+      def to_ollama_schema
+        {
+          type: "function",
+          function: {
+            name:        @name,
+            description: @description,
+            parameters:  @input_schema
+          }
+        }
+      end
+
+      # Anthropic-format tool definition
+      def to_anthropic_schema
+        {
+          name:         @name,
+          description:  @description,
+          input_schema: @input_schema
+        }
+      end
+
+      def to_s
+        "#<Tool:#{@name} risk=#{@risk_level} approval=#{@requires_approval}>"
+      end
+    end
+  end
+end

data/lib/ollama_agent/tools/git_tools.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+require_relative "base"
+
+module OllamaAgent
+  module Tools
+    # Shared helper for git-* tools (instance-level `git_run`, not a module function).
+    class GitBase < Base
+      private
+
+      def git_run(cmd, cwd:)
+        stdout, stderr, _status = Open3.capture3(cmd, chdir: cwd)
+        out = stdout.strip
+        err = stderr.strip
+        result = [out, (err.empty? ? nil : "stderr: #{err}")].compact.join("\n")
+        result.empty? ? "(no output)" : result
+      rescue Errno::ENOENT
+        "Error: git not found on PATH"
+      end
+    end
+
+    # Git status — read-only, no approval needed
+    class GitStatus < GitBase
+      tool_name        "git_status"
+      tool_description "Show the working tree status (staged, unstaged, untracked files)"
+      tool_risk        :low
+      tool_requires_approval false
+      tool_schema({
+                    type: "object",
+                    properties: {
+                      short: { type: "boolean", description: "Use short format (default: false)" }
+                    },
+                    required: []
+                  })
+
+      def call(args, context: {})
+        root  = context[:root] || Dir.pwd
+        short = args["short"] ? "--short" : "--porcelain=v1"
+        git_run("git status #{short}", cwd: root)
+      end
+    end
+
+    # Git diff — read-only
+    class GitDiff < GitBase
+      tool_name        "git_diff"
+      tool_description "Show changes between commits, working tree, or index"
+      tool_risk        :low
+      tool_requires_approval false
+      tool_schema({
+                    type: "object",
+                    properties: {
+                      ref: { type: "string", description: "Commit, branch, or tag to diff against (default: HEAD)" },
+                      cached: { type: "boolean", description: "Show staged changes (--cached)" },
+                      path: { type: "string", description: "Limit diff to this path" }
+                    },
+                    required: []
+                  })
+
+      MAX_DIFF_BYTES = 32_768
+
+      def call(args, context: {})
+        root   = context[:root] || Dir.pwd
+        ref    = args["ref"]
+        cached = args["cached"] ? "--cached" : ""
+        path   = args["path"]
+
+        cmd_parts = ["git diff", cached, ref, "--", path].compact.reject(&:empty?)
+        output = git_run(cmd_parts.join(" "), cwd: root)
+        output.byteslice(0, MAX_DIFF_BYTES).then { |o| output.bytesize > MAX_DIFF_BYTES ? "#{o}\n...[truncated]" : o }
+      end
+    end
+
+    # Git log — read-only
+    class GitLog < GitBase
+      tool_name        "git_log"
+      tool_description "Show commit history"
+      tool_risk        :low
+      tool_requires_approval false
+      tool_schema({
+                    type: "object",
+                    properties: {
+                      n: { type: "integer", description: "Number of commits (default 10)", minimum: 1, maximum: 100 },
+                      oneline: { type: "boolean", description: "One-line format" },
+                      author: { type: "string", description: "Filter by author" },
+                      path: { type: "string", description: "Limit to commits touching this path" }
+                    },
+                    required: []
+                  })
+
+      def call(args, context: {})
+        root    = context[:root] || Dir.pwd
+        n       = [args["n"]&.to_i || 10, 100].min
+        format  = args["oneline"] ? "--oneline" : "--pretty=format:%h %s (%an, %ar)"
+        author  = args["author"]  ? "--author=#{Shellwords.shellescape(args["author"])}" : ""
+        path    = args["path"]
+
+        cmd_parts = ["git log", "-n #{n}", format, author, "--", path].compact.reject(&:empty?)
+        git_run(cmd_parts.join(" "), cwd: root)
+      end
+    end
+
+    # Git commit — requires approval
+    class GitCommit < GitBase
+      tool_name        "git_commit"
+      tool_description "Stage specified files and create a git commit"
+      tool_risk        :medium
+      tool_requires_approval true
+      tool_schema({
+                    type: "object",
+                    properties: {
+                      message: { type: "string", description: "Commit message", minLength: 3 },
+                      files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Files to stage (use ['.'] for all changed files — use carefully)"
+                      },
+                      all: { type: "boolean", description: "Stage all tracked changes (-a flag)" }
+                    },
+                    required: ["message"]
+                  })
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- staging branches + commit
+      def call(args, context: {})
+        return "git_commit is disabled in read-only mode" if context[:read_only]
+
+        root    = context[:root] || Dir.pwd
+        message = args["message"].to_s.strip
+        return "Error: commit message is required" if message.empty?
+
+        files = Array(args["files"])
+        all   = args["all"]
+
+        # Stage files
+        if all
+          git_run("git add -u", cwd: root)
+        elsif files.any?
+          safe_files = files.map { |f| Shellwords.shellescape(f) }.join(" ")
+          git_run("git add #{safe_files}", cwd: root)
+        end
+
+        git_run("git commit -m #{Shellwords.shellescape(message)}", cwd: root)
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+
+    # Git branch list — read-only
+    class GitBranch < GitBase
+      tool_name        "git_branch"
+      tool_description "List branches or show current branch"
+      tool_risk        :low
+      tool_requires_approval false
+      tool_schema({
+                    type: "object",
+                    properties: {
+                      all: { type: "boolean", description: "Include remote branches" },
+                      current: { type: "boolean", description: "Show current branch name only" }
+                    },
+                    required: []
+                  })
+
+      def call(args, context: {})
+        root = context[:root] || Dir.pwd
+
+        if args["current"]
+          git_run("git rev-parse --abbrev-ref HEAD", cwd: root)
+        elsif args["all"]
+          git_run("git branch -a", cwd: root)
+        else
+          git_run("git branch", cwd: root)
+        end
+      end
+    end
+  end
+end

data/lib/ollama_agent/tools/http_tools.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "json"
+require_relative "base"
+
+module OllamaAgent
+  module Tools
+    # HTTP GET tool — for fetching documentation, APIs, public resources.
+    class HttpGet < Base
+      tool_name        "http_get"
+      tool_description "Fetch a URL via HTTP GET and return the response body (text/JSON only)"
+      tool_risk        :medium
+      tool_requires_approval false
+      tool_schema({
+        type: "object",
+        properties: {
+          url: {
+            type: "string",
+            description: "Full URL to fetch (must be https:// or http://)",
+            minLength: 10
+          },
+          headers: {
+            type: "object",
+            description: "Optional HTTP headers as key-value pairs"
+          },
+          max_bytes: {
+            type: "integer",
+            description: "Truncate response at this many bytes (default 32768, max 131072)",
+            minimum: 1,
+            maximum: 131_072
+          }
+        },
+        required: ["url"]
+      })
+
+      DEFAULT_MAX_BYTES = 32_768
+      ALLOWED_SCHEMES   = %w[http https].freeze
+      ALLOWED_CONTENT_TYPES = %w[
+        text/plain text/html text/markdown application/json application/xml
+        text/xml text/csv application/yaml text/yaml
+      ].freeze
+
+      def initialize(allowed_hosts: nil, denied_hosts: nil, timeout: 15, **opts)
+        super()
+        @allowed_hosts = allowed_hosts
+        @denied_hosts  = Array(denied_hosts)
+        @timeout       = timeout
+      end
+
+      def call(args, context: {})
+        url       = args["url"].to_s.strip
+        max_bytes = [args["max_bytes"]&.to_i || DEFAULT_MAX_BYTES, 131_072].min
+
+        uri = parse_and_validate_url!(url)
+        check_host!(uri.host)
+
+        headers = build_headers(args["headers"])
+        fetch(uri, headers: headers, max_bytes: max_bytes)
+      end
+
+      private
+
+      def parse_and_validate_url!(url)
+        uri = URI.parse(url)
+        unless ALLOWED_SCHEMES.include?(uri.scheme)
+          raise OllamaAgent::Error, "http_get: only #{ALLOWED_SCHEMES.join("/")} URLs are allowed"
+        end
+
+        uri
+      rescue URI::InvalidURIError => e
+        raise OllamaAgent::Error, "http_get: invalid URL — #{e.message}"
+      end
+
+      def check_host!(host)
+        if @allowed_hosts && !@allowed_hosts.any? { |pat| pat === host }
+          raise OllamaAgent::Error, "http_get: host #{host} is not on the allowlist"
+        end
+
+        if @denied_hosts.any? { |pat| pat === host }
+          raise OllamaAgent::Error, "http_get: host #{host} is blocked"
+        end
+
+        # Block private/internal addresses
+        if private_address?(host)
+          raise OllamaAgent::Error, "http_get: requests to internal/private addresses are blocked"
+        end
+      end
+
+      def private_address?(host)
+        return false if host.nil?
+
+        private_patterns = [
+          /\A127\./,
+          /\A10\./,
+          /\A172\.(1[6-9]|2\d|3[01])\./,
+          /\A192\.168\./,
+          /\Alocalhost\z/i,
+          /\A::1\z/,
+          /\A0\.0\.0\.0\z/,
+          /\.local\z/i
+        ]
+        private_patterns.any? { |pat| pat === host }
+      end
+
+      def build_headers(custom)
+        headers = {
+          "User-Agent" => "OllamaAgent/#{OllamaAgent::VERSION rescue "0"} (+https://github.com/shubhamtaywade82/ollama_agent)"
+        }
+        return headers unless custom.is_a?(Hash)
+
+        # Strip dangerous headers
+        safe_custom = custom.reject { |k, _| k.to_s.downcase.match?(/authorization|cookie|set-cookie/) }
+        headers.merge(safe_custom)
+      end
+
+      def fetch(uri, headers:, max_bytes:)
+        use_ssl  = uri.scheme == "https"
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: use_ssl,
+                                   read_timeout: @timeout, open_timeout: 5) do |http|
+          req = Net::HTTP::Get.new(uri)
+          headers.each { |k, v| req[k] = v }
+          http.request(req)
+        end
+
+        handle_response(response, max_bytes)
+      rescue Net::OpenTimeout, Net::ReadTimeout
+        "Error: request timed out after #{@timeout}s"
+      rescue SocketError => e
+        "Error: #{e.message}"
+      end
+
+      def handle_response(resp, max_bytes)
+        status = resp.code.to_i
+        ct     = resp["content-type"].to_s.split(";").first.strip
+
+        unless (200..299).cover?(status)
+          return "HTTP #{status}: #{resp.message}"
+        end
+
+        unless ALLOWED_CONTENT_TYPES.any? { |allowed| ct.start_with?(allowed) }
+          return "Blocked: content-type #{ct.inspect} is not a text or JSON type"
+        end
+
+        body = resp.body.to_s.encode("UTF-8", invalid: :replace, undef: :replace)
+        body = body.byteslice(0, max_bytes) + "\n...[truncated]" if body.bytesize > max_bytes
+        body
+      end
+    end
+
+    # HTTP POST tool — for sending data to APIs
+    class HttpPost < Base
+      tool_name        "http_post"
+      tool_description "Send a JSON POST request to an API endpoint"
+      tool_risk        :high
+      tool_requires_approval true
+      tool_schema({
+        type: "object",
+        properties: {
+          url:     { type: "string", description: "Full URL", minLength: 10 },
+          body:    { type: "object", description: "JSON body to send" },
+          headers: { type: "object", description: "Optional HTTP headers" }
+        },
+        required: ["url", "body"]
+      })
+
+      def initialize(allowed_hosts: nil, timeout: 30, **opts)
+        super()
+        @allowed_hosts = allowed_hosts
+        @timeout       = timeout
+      end
+
+      def call(args, context: {})
+        return "http_post is disabled in read-only mode" if context[:read_only]
+
+        url  = args["url"].to_s.strip
+        body = args["body"]
+
+        uri = URI.parse(url)
+        raise OllamaAgent::Error, "http_post: only https/http URLs" unless %w[http https].include?(uri.scheme)
+
+        if @allowed_hosts && !@allowed_hosts.any? { |pat| pat === uri.host }
+          raise OllamaAgent::Error, "http_post: host #{uri.host} not on allowlist"
+        end
+
+        headers = (args["headers"] || {}).merge("Content-Type" => "application/json")
+
+        Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                        read_timeout: @timeout, open_timeout: 5) do |http|
+          req      = Net::HTTP::Post.new(uri)
+          headers.each { |k, v| req[k] = v }
+          req.body = JSON.generate(body)
+          resp     = http.request(req)
+          "HTTP #{resp.code}: #{resp.body.to_s.byteslice(0, 8192)}"
+        end
+      rescue StandardError => e
+        "Error: #{e.message}"
+      end
+    end
+  end
+end

data/lib/ollama_agent/tools/memory_tools.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module OllamaAgent
+  module Tools
+    # Store a fact in long-term memory for future sessions.
+    class MemoryStore < Base
+      tool_name        "memory_store"
+      tool_description "Store a key-value fact in persistent long-term memory for use in future sessions"
+      tool_risk        :low
+      tool_requires_approval false
+      tool_schema({
+        type: "object",
+        properties: {
+          key:       { type: "string", description: "Unique key for this fact", minLength: 1 },
+          value:     { type: "string", description: "Value to store" },
+          namespace: { type: "string", description: "Namespace (default: 'default')" }
+        },
+        required: ["key", "value"]
+      })
+
+      def call(args, context: {})
+        memory = context[:memory_manager]
+        return "memory_store: no memory manager in context" unless memory
+
+        key       = args["key"].to_s.strip
+        value     = args["value"].to_s
+        namespace = args["namespace"] || "default"
+
+        memory.remember(key, value, tier: :long_term, namespace: namespace)
+        "Stored: #{key} = #{value.inspect[0, 80]}"
+      end
+    end
+
+    # Recall a fact from long-term memory.
+    class MemoryRecall < Base
+      tool_name        "memory_recall"
+      tool_description "Recall a stored fact from long-term memory by key"
+      tool_risk        :low
+      tool_requires_approval false
+      tool_schema({
+        type: "object",
+        properties: {
+          key:       { type: "string", description: "Key to look up", minLength: 1 },
+          namespace: { type: "string", description: "Namespace (default: 'default')" }
+        },
+        required: ["key"]
+      })
+
+      def call(args, context: {})
+        memory = context[:memory_manager]
+        return "memory_recall: no memory manager in context" unless memory
+
+        key       = args["key"].to_s.strip
+        namespace = args["namespace"] || "default"
+        value     = memory.recall(key, namespace: namespace)
+
+        value.nil? ? "No memory found for key: #{key}" : value.to_s
+      end
+    end
+
+    # List stored memory keys
+    class MemoryList < Base
+      tool_name        "memory_list"
+      tool_description "List all keys stored in long-term memory"
+      tool_risk        :low
+      tool_requires_approval false
+      tool_schema({
+        type: "object",
+        properties: {
+          namespace: { type: "string", description: "Namespace to list (default: 'default')" }
+        },
+        required: []
+      })
+
+      def call(args, context: {})
+        memory = context[:memory_manager]
+        return "memory_list: no memory manager in context" unless memory
+
+        namespace = args["namespace"] || "default"
+        entries   = memory.list(namespace: namespace)
+
+        return "No memories stored in namespace: #{namespace}" if entries.empty?
+
+        entries.map { |k, v| "#{k}: #{v.to_s[0, 60]}" }.join("\n")
+      end
+    end
+
+    # Delete a stored memory key
+    class MemoryDelete < Base
+      tool_name        "memory_delete"
+      tool_description "Delete a key from long-term memory"
+      tool_risk        :medium
+      tool_requires_approval false
+      tool_schema({
+        type: "object",
+        properties: {
+          key:       { type: "string", description: "Key to delete", minLength: 1 },
+          namespace: { type: "string", description: "Namespace (default: 'default')" }
+        },
+        required: ["key"]
+      })
+
+      def call(args, context: {})
+        memory = context[:memory_manager]
+        return "memory_delete: no memory manager in context" unless memory
+
+        key       = args["key"].to_s.strip
+        namespace = args["namespace"] || "default"
+        memory.forget(key, namespace: namespace)
+        "Deleted memory key: #{key}"
+      end
+    end
+  end
+end