ollama-dsl 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 775de2cdc17ae09fb547faea949611649239240373f313ee83ed6bedab93dea6
-  data.tar.gz: cf5aceffa25ece0e9cc72e5bbbcd9b84041a1fecc06029fef148f41ebfc970d9
+  metadata.gz: cc69d14a5c3e7e436b59da35482e5fc77d49689fefceb1fdb4bfab84a3ed7c76
+  data.tar.gz: dee5bee8fbc4401ce92644e18a7e92980ae8db1942d8f1877b2836d9ac999054
 SHA512:
-  metadata.gz: 4577a9ba783ecaaaffe938808493f09d5f0683e14934a49fe2f2b651ecece665967ef1b9bd62e56b73f130b55cc5784fd4b5f2666e41dea77865bbc5e5bd2160
-  data.tar.gz: d892cb895e152792a7e2316c94023da931e626de4be368b608b5b8178e73295f050be6b4e04151beb4caccd6cf83891f25a9752f57936497178bcc8e62e545b9
+  metadata.gz: 5409975d8ebd80860eecaa4a6fe9dd7a106701c108f85a2cdfd7bafe41280472059a419c06b5da6f9f51cbaf22b9fe784d6a82cde9f7e6c1f13f748124ad341c
+  data.tar.gz: '084f29acb614e165d63dc3bad4dd1cd5ead88a45f5642d60b8670114612ff810d790d8a4a666c167696fc16489f566d924c3d6f6eeff9b3d084cff530b1250f4'

data/CHANGELOG.md

@@ -1,5 +1,21 @@
+```markdown
 ## [Unreleased]
 
+## [0.1.2] - 2026-10-04
+
+- Added `Agent` with Ollama tool calling support
+- Added `Tool` abstraction for executable tools
+- Added tool execution loop
+- Added tool definitions for Ollama
+- Added RSpec tests for tools
+
+## [0.1.1] - 2025-11-04
+
+- Updated client to support agent tool calling
+- Updated DSL entry point
+- Updated examples
+
 ## [0.1.0] - 2025-08-22
 
 - Initial release
+```

data/README.md

@@ -1,37 +1,183 @@
 # Ollama::Dsl
 
-A Ruby DSL for interacting with Ollama LLMs, allowing streaming and structured prompts.
+[![Gem Version](https://badge.fury.io/rb/ollama-dsl.svg)](https://badge.fury.io/rb/ollama-dsl)
+[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue)](https://rubydoc.info/gems/ollama-dsl)
 
-Ollama DSL provides an easy-to-use Ruby interface to communicate with Ollama local or remote language models. It supports building prompts with system/user roles, handling streaming responses, and chaining prompts seamlessly.
+A Ruby DSL for interacting with Ollama LLMs, with support for streaming, structured prompts, agents, and tool calling.
 
-## Installation
+Ollama DSL provides an easy-to-use Ruby interface for communicating with local or remote Ollama language models. It supports system and user prompts, streaming responses, prompt chaining, and building agents that can execute custom Ruby tools.
 
+## Installation
 
-Install the gem and add to the application's Gemfile by executing:
+Install the gem:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install ollama-dsl
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+Or add it to your `Gemfile`:
+
+```ruby
+gem "ollama-dsl"
+```
+
+Then run:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle install
 ```
 
-## Usage
+If you want to use it directly from GitHub:
+
+```ruby
+gem "ollama-dsl", git: "https://github.com/rafaelmerlotto/ollama-dsl.git"
+```
+
+## Basic Example
+
+```ruby
+require "ollama/dsl"
+
+Ollama::Dsl.run do
+  model "llama3"
+
+  system "You are a marketing expert assistant."
+  user "Write a catchy Instagram post title about artisanal coffee."
+
+  on_chunk { |token| print token }
+
+  on_done do |text|
+    puts "\n\nFinal response:\n#{text}"
+  end
+
+  self
+end
+```
+
+## Agents
+
+Ollama DSL also provides an `Agent` abstraction for building tool-enabled automations.
+
+An agent can:
+
+* Receive a user instruction
+* Decide which registered tool to use
+* Execute the tool in Ruby
+* Send the tool result back to Ollama
+* Continue the execution loop until the task is completed
+
+### Example
+
+```ruby
+require "ollama/dsl"
+
+session = Ollama::Dsl::Session.new
+
+agent = Ollama::Dsl::Agent.new(
+  session,
+  model: "gpt-oss:20b"
+)
+
+agent.tool(
+  "create_file",
+  "Create a text file with the given filename and content.",
+  parameters: {
+    type: "object",
+    properties: {
+      filename: {
+        type: "string",
+        description: "The name of the file to create."
+      },
+      content: {
+        type: "string",
+        description: "The content to write into the file."
+      }
+    },
+    required: ["filename", "content"]
+  }
+) do |filename:, content:|
+  File.write(filename, content)
+
+  "File #{filename} was created successfully."
+end
+
+puts agent.run(
+  "Create a file called hello.txt containing Hello from my AI agent."
+)
+```
+
+The agent uses Ollama's native tool calling capabilities to decide when a tool should be executed.
+
+Tools are not limited to file operations. You can define tools for any Ruby automation your application needs.
+
+For example:
+
+```ruby
+agent.tool("get_time", "Get the current time.", parameters: {
+  type: "object",
+  properties: {}
+}) do
+  Time.now.to_s
+end
+```
+
+## Tool Calling
+
+Tools consist of three main parts:
+
+* A name
+* A description
+* A parameter schema and Ruby block
 
-TODO: Write usage instructions here
+The description and parameter schema are sent to Ollama, allowing the model to decide when and how to use the tool.
+
+The Ruby block contains the actual implementation that is executed by the agent.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies.
+
+Run the test suite with:
+
+```bash
+bundle exec rspec
+```
+
+You can also run:
+
+```bash
+bundle exec rake
+```
+
+for the project's Rake tasks.
+
+To open an interactive console:
+
+```bash
+bin/console
+```
+
+To install this gem onto your local machine:
+
+```bash
+bundle exec rake install
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To release a new version, update the version number in `version.rb`, then run:
+
+```bash
+bundle exec rake release
+```
+
+This will create a git tag for the version, push the git commits and tag, and publish the gem to RubyGems.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/ollama-dsl. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/ollama-dsl/blob/main/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at:
+
+https://github.com/rafaelmerlotto/ollama-dsl
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Code of Conduct](https://github.com/rafaelmerlotto/ollama-dsl/blob/main/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -39,4 +185,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Ollama::Dsl project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/ollama-dsl/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting with the Ollama::Dsl project's codebases, issue trackers and mailing lists is expected to adhere to the [Code of Conduct](https://github.com/rafaelmerlotto/ollama-dsl/blob/main/CODE_OF_CONDUCT.md).

data/examples/agent.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "ollama/dsl/session"
+require "ollama/dsl/agent"
+
+session = Ollama::Dsl::Session.new
+
+agent = Ollama::Dsl::Agent.new(
+  session,
+  model: "gpt-oss:20b"
+)
+
+agent.tool(
+  "create_file",
+  "Create a text file with the given filename and content.",
+  parameters: {
+    type: "object",
+    properties: {
+      filename: {
+        type: "string",
+        description: "The name of the file to create."
+      },
+      content: {
+        type: "string",
+        description: "The content to write into the file."
+      }
+    },
+    required: ["filename", "content"]
+  }
+) do |filename:, content:|
+  File.write(filename, content)
+
+  "File #{filename} was created successfully."
+end
+
+result = agent.run(
+  "Create a file called hello.txt containing exactly: Hello from my AI agent."
+)
+
+puts result

data/examples/use_case.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
-$LOAD_PATH.unshift(File.expand_path(".", __dir__))
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 
-require_relative "dsl/session"
-require_relative "dsl/dsl"
-require_relative "dsl/client"
+require "ollama/dsl/session"
+require "ollama/dsl/dsl"
+require "ollama/dsl/client"
 
 session = Ollama::Dsl::Session.new
 dsl = Ollama::Dsl::DSL.new(session)

data/lib/ollama/dsl/agent.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative "tool"
+require_relative "client"
+
+module Ollama
+  module Dsl
+    class Agent
+      attr_reader :tools
+
+      def initialize(session, model: "llama3")
+        @session = session
+        @model = model
+        @tools = {}
+        @client = Client.new
+      end
+
+      def tool(name, description, parameters:, &block)
+        @tools[name.to_s] = Tool.new(
+          name,
+          description,
+          parameters: parameters,
+          &block
+        )
+      end
+
+      def run(instruction)
+        @session.add("user", instruction)
+
+        loop do
+          response = @client.chat(
+            model: @model,
+            messages: @session.messages,
+            tools: tool_definitions
+          )
+
+          message = response.fetch("message")
+
+          tool_calls = message["tool_calls"]
+
+          if tool_calls.nil? || tool_calls.empty?
+            final_answer = message["content"].to_s
+
+            @session.add("assistant", final_answer)
+
+            return final_answer
+          end
+
+          @session.messages << message
+
+          tool_calls.each do |tool_call|
+            execute_tool(tool_call)
+          end
+        end
+      end
+
+      private
+
+      def tool_definitions
+        @tools.values.map(&:definition)
+      end
+
+      def execute_tool(tool_call)
+        function = tool_call.fetch("function")
+
+        name = function.fetch("name")
+        arguments = function["arguments"] || {}
+
+        tool = @tools[name]
+
+        raise "Unknown tool: #{name}" unless tool
+
+        result = tool.call(arguments)
+
+        @session.messages << {
+          role: "tool",
+          content: result.to_s
+        }
+      end
+    end
+  end
+end

data/lib/ollama/dsl/client.rb

@@ -11,17 +11,19 @@ module Ollama
         @ollama_host = URI(host)
       end
 
+      # Used by DSL for streaming responses
       def stream(path, payload)
-
         uri = URI("#{@ollama_host}#{path}")
 
-        # POST request
-        req = Net::HTTP::Post.new(uri, { "Content-Type" => "application/json" })
-        req.body = payload.to_json
+        request = Net::HTTP::Post.new(
+          uri,
+          { "Content-Type" => "application/json" }
+        )
+
+        request.body = payload.merge(stream: true).to_json
 
-        # Response streaming
         Net::HTTP.start(uri.hostname, uri.port) do |http|
-          http.request(req) do |response|
+          http.request(request) do |response|
             response.read_body do |chunk|
               begin
                 json = JSON.parse(chunk)
@@ -32,6 +34,42 @@ module Ollama
           end
         end
       end
+
+      # Used by Agent for tool calling
+      def chat(model:, messages:, tools: nil)
+        payload = {
+          model: model,
+          messages: messages,
+          stream: false
+        }
+
+        payload[:tools] = tools if tools && !tools.empty?
+
+        post("/api/chat", payload)
+      end
+
+      private
+
+      def post(path, payload)
+        uri = URI("#{@ollama_host}#{path}")
+
+        request = Net::HTTP::Post.new(
+          uri,
+          { "Content-Type" => "application/json" }
+        )
+
+        request.body = payload.to_json
+
+        response = Net::HTTP.start(uri.hostname, uri.port) do |http|
+          http.request(request)
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise "Ollama request failed: #{response.code} #{response.body}"
+        end
+
+        JSON.parse(response.body)
+      end
     end
   end
 end

data/lib/ollama/dsl/tool.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Ollama
+  module Dsl
+    class Tool
+      attr_reader :name, :description, :parameters
+
+      def initialize(name, description, parameters:, &block)
+        @name = name.to_s
+        @description = description
+        @parameters = parameters
+        @block = block
+      end
+
+      def definition
+        {
+          type: "function",
+          function: {
+            name: @name,
+            description: @description,
+            parameters: @parameters
+          }
+        }
+      end
+
+      def call(arguments = {})
+        @block.call(**arguments.transform_keys(&:to_sym))
+      end
+    end
+  end
+end

data/lib/ollama/dsl/version.rb

@@ -2,6 +2,6 @@
 
 module Ollama
   module Dsl
-    VERSION = "0.1.0"
+    VERSION = "0.1.2"
   end
 end

data/lib/ollama/dsl.rb

@@ -2,6 +2,12 @@
 
 require 'json'
 require_relative "dsl/version"
+require_relative "dsl/session"
+require_relative "dsl/dsl"
+require_relative "dsl/client"
+require_relative "dsl/agent"
+require_relative "dsl/tool"
+
 
 
 module Ollama

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ollama-dsl
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Rafael
@@ -23,11 +23,14 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- examples/agent.rb
 - examples/use_case.rb
 - lib/ollama/dsl.rb
+- lib/ollama/dsl/agent.rb
 - lib/ollama/dsl/client.rb
 - lib/ollama/dsl/dsl.rb
 - lib/ollama/dsl/session.rb
+- lib/ollama/dsl/tool.rb
 - lib/ollama/dsl/version.rb
 - sig/ollama/dsl.rbs
 homepage: https://github.com/rafaelmerlotto/ollama-dsl