ollama_agent 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 73ed8cb32bcabdd008dee785606c96aefc9bf626a3c3a1187b7bab8ef68c9627
+  data.tar.gz: 150f32efcba0bd8602cd571654bcfc8f42b99af56873a57d792202bb957b4701
+SHA512:
+  metadata.gz: 18ce5ec435f2b8330e2684dd116bd33b9e399d93857a5469365902a19a3f99b61bf7d227df746b5bbe82d7b77c4f952b3e2ad8ac61b204498e4d07f469978de0
+  data.tar.gz: fd59f660457f2de80e949a098283b38eeccb94cb9daa757158d76d3f457a1f0926ef30f5f5e98ba864ef7504470842775c971ed0a373f48ba8e26b6b0ecdc129

data/.cursor/.gitignore

@@ -0,0 +1 @@
+plans/

data/.cursor/skills/ollama-agent-patterns/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: ollama-agent-patterns
+description: >-
+  Blueprint for building a CLI Ollama-based coding agent (Ruby gem) with design
+  patterns and judicious metaprogramming—Facade, Template Method, Factory/Registry,
+  Builder, Adapter, Proxy, Command, Observer, Strategy, State, and tool DSLs. Use
+  when working on ollama_agent, ollama-client integration, tools, LLM adapters,
+  prompts, streaming, patch application, or when the user asks for agent
+  architecture, extensibility, registries, or Ruby metaprogramming for agents.
+---
+
+# Skill: Ollama Agent — Design Patterns & Metaprogramming
+
+## 1. Overview
+
+Blueprint for a **CLI coding agent** (e.g. `ollama_agent`) that uses **ollama-client** to chat with tools: read/search files, apply small unified diffs from natural language. Patterns keep the design **extensible and maintainable** without front-loading complexity.
+
+## 2. Core components & patterns
+
+| Component | Pattern(s) | Purpose |
+|-----------|------------|---------|
+| **Agent** | Facade, Template Method | Simple API (`run`); skeleton loop with overridable steps. |
+| **Tools** | Factory Method, Command, Registry | Load/execute tools; optional logging/replay/undo. |
+| **LLM client** | Adapter, (optional) Proxy | Swap backends; logging/metrics without forking core. |
+| **Prompts** | Builder | Fluent construction of messages + tools + options. |
+| **Streaming** | Observer | Multiple subscribers for tokens (UI, logs). |
+| **Patch application** | Strategy | Swap `patch(1)` vs Ruby-native apply, etc. |
+| **Conversation** | State | Phases (idle, tools, confirmation) without giant `if/else`. |
+
+**Client lifetime:** **Singleton** is optional. Prefer **injectable** `Ollama::Client` (or adapter) for tests and per-run config (`timeout`, `base_url`, `api_key`).
+
+## 3. Principles
+
+1. **Start simple** — add Factory, State, Strategy when duplication or branching hurts; do not adopt every pattern up front.
+2. **Core loop stays explicit** — readable `run` / tool loop; collaborators (`Adapter`, `PromptBuilder`, `ToolCommand`) hide detail, not `send` spaghetti.
+3. **Metaprogramming at boundaries** — registration / DSLs at tool edges; avoid dynamic dispatch in error paths and hot loops unless measured.
+4. **Workspace rules** — validated tool schemas; loggable/replayable actions; **no hardcoded model names** (runtime config).
+
+## 4. Pattern map (where code lives)
+
+| Area | Patterns | Role |
+|------|-----------|------|
+| **Agent** | Facade, Template Method | Single entry; fixed loop with overridable hooks. |
+| **Tools** | Factory, Command, Registry | Instantiate tools; optional command objects for audit. |
+| **LLM** | Adapter, Proxy | Backends; cross-cutting logging/rate limits. |
+| **Prompts** | Builder | Messages + tools + options. |
+| **Streaming** | Observer | Fan-out from client `hooks`. |
+| **Patches** | Strategy | Pluggable apply path. |
+| **Conversation** | State | Explicit phases when control flow grows. |
+
+### Target layout (illustrative)
+
+A fuller **pattern-oriented** tree (with `bin/console`, `commands/`, `strategies/`, `states/`, etc.) and a **“this repo today”** note live in **reference.md** under *Recommended gem structure*. Migrate only when complexity justifies new directories.
+
+```
+ollama_agent/
+├── exe/ollama_agent
+├── lib/ollama_agent.rb
+└── lib/ollama_agent/
+    ├── agent.rb
+    ├── cli.rb
+    ├── prompt_builder.rb      # Builder (optional)
+    ├── tool_registry.rb
+    ├── tools/base.rb
+    ├── tools/
+    ├── llm/base_adapter.rb
+    ├── llm/ollama_adapter.rb
+    ├── llm/logging_proxy.rb
+    ├── commands/tool_command.rb
+    ├── observers/
+    ├── strategies/
+    └── states/
+```
+
+## 5. Creational patterns (summary)
+
+- **Factory + registry** — Replace a growing `case` with `ToolRegistry.get(name)`; auto-register via `inherited` **or** explicit `tool_name` + hash (clearer than magic naming).
+- **Builder** — `PromptBuilder` when message construction branches; skip until you have real optional composition.
+- **Singleton** — Avoid as default for HTTP clients; use when you truly need one process-wide resource and tests can still stub.
+
+## 6. Structural patterns (summary)
+
+- **Adapter** — Common `chat(messages:, tools:, **options)` surface for Ollama vs future providers.
+- **Proxy** — Wrap adapter for logging/metrics; keep thin.
+- **Facade** — `Agent#run` — already the right shape.
+
+## 7. Behavioral patterns (summary)
+
+- **Command** — Wrap tool invocations when you need queues, structured logs, or replay; **undo** only with a real story (VCS/snapshots).
+- **Observer** — Fan-out streaming tokens; compose with ollama-client `hooks`.
+- **Strategy** — `PatchStrategy` if you need non-`patch` apply paths.
+- **State** — When confirmation + tool rounds + idle become tangled.
+- **Template Method** — Base agent class only if you have **multiple** agent variants sharing one loop.
+
+## 8. Metaprogramming (judicious)
+
+| Technique | Use when | Caution |
+|-----------|----------|--------|
+| **`inherited` + registry** | Many tools, stable naming | Keep in sync with **tool JSON schema**; consider explicit `tool_name`. |
+| **Tool DSL** (`tool :name do …`) | Repetition dominates | Stack traces and IDE nav suffer; keep DSL thin. |
+| **`send` for hooks** | Fixed event names | Prefer explicit methods for public API. |
+| **`method_missing`** | Rare delegation | Not for core tool dispatch — use a Hash/registry. |
+| **Plugin `extend`** | Third-party tools | Document load order and sandbox rules. |
+
+## 9. When to avoid heavy metaprogramming
+
+- Main agent loop and **error handling** — explicit flow wins.
+- **Performance-sensitive** inner loops — measure before dynamic dispatch.
+- **Public APIs** — stable, documented entry points over hidden DSL magic.
+
+## 10. Summary
+
+| Pattern | Benefit |
+|---------|---------|
+| Factory Method | Decouples tool creation from call sites. |
+| Builder | Composes prompts/options without positional arg soup. |
+| Singleton | Single shared resource (use sparingly for HTTP clients). |
+| Adapter | Multiple LLM backends behind one shape. |
+| Proxy | Cross-cutting concerns on the client. |
+| Facade | Hides orchestration from CLI users. |
+| Command | Tool calls as objects (log/replay/queue). |
+| Observer | Decoupled streaming consumers. |
+| Strategy | Swappable patch application. |
+| State | Explicit conversation phases. |
+| Template Method | Shared loop, varied steps. |
+| Metaprogramming | Less boilerplate at **boundaries** only. |
+
+**Start with straightforward code; refactor into patterns when pain appears.**
+
+## 11. Full code examples
+
+Runnable snippets (registry, `PromptBuilder`, adapters, proxy, command, observer, strategy, state, template-method skeleton, DSL sketch) live in **[reference.md](reference.md)**. Prefer copying from there and adapting to the real `ollama-client` API and this repo’s `SandboxedTools` / `tools_schema` constraints.

data/.cursor/skills/ollama-agent-patterns/reference.md

@@ -0,0 +1,428 @@
+# Reference: patterns & Ruby snippets
+
+Concise examples for `ollama_agent`-style gems. Adapt names to the real `ollama-client` API.
+
+## Factory Method + registry (`inherited`)
+
+```ruby
+# lib/ollama_agent/tools/base.rb
+module OllamaAgent
+  module Tools
+    class Base
+      def initialize(args)
+        @args = args
+      end
+
+      def call
+        raise NotImplementedError
+      end
+
+      def self.inherited(subclass)
+        return if subclass.name.nil?
+
+        name = subclass.name.split("::").last.underscore
+        ToolRegistry.register(name, subclass)
+      end
+    end
+  end
+end
+
+# lib/ollama_agent/tools/registry.rb — or tool_registry.rb at module root
+module OllamaAgent
+  module Tools
+    class ToolRegistry
+      @tools = {}
+      class << self
+        def register(name, klass)
+          @tools[name.to_s] = klass
+        end
+
+        def get(name)
+          @tools[name.to_s]
+        end
+      end
+    end
+  end
+end
+```
+
+## Builder (`PromptBuilder`)
+
+```ruby
+class PromptBuilder
+  attr_reader :messages, :tools, :options
+
+  def initialize
+    @messages = []
+    @tools = []
+    @options = {}
+  end
+
+  def system(content)
+    @messages << { role: "system", content: content }
+    self
+  end
+
+  def user(content)
+    @messages << { role: "user", content: content }
+    self
+  end
+
+  def add_tool(tool_def)
+    @tools << tool_def
+    self
+  end
+
+  def temperature(value)
+    @options[:temperature] = value
+    self
+  end
+
+  def build
+    { messages: @messages, tools: @tools, options: @options }
+  end
+end
+```
+
+## Singleton (optional client holder)
+
+```ruby
+require "singleton"
+
+class OllamaClientWrapper
+  include Singleton
+
+  attr_reader :client
+
+  def initialize
+    @client = Ollama::Client.new(model: ENV.fetch("OLLAMA_MODEL"))
+  end
+end
+```
+
+Prefer **dependency injection** of a client/adapter in tests instead of `Singleton` when practical.
+
+## Adapter + Proxy
+
+```ruby
+# lib/ollama_agent/llm/base_adapter.rb
+module OllamaAgent
+  module LLM
+    class BaseAdapter
+      def chat(messages:, tools:, **options)
+        raise NotImplementedError
+      end
+    end
+  end
+end
+
+# lib/ollama_agent/llm/ollama_adapter.rb
+module OllamaAgent
+  module LLM
+    class OllamaAdapter < BaseAdapter
+      def initialize(client = Ollama::Client.new)
+        @client = client
+      end
+
+      def chat(messages:, tools:, **options)
+        @client.chat(messages: messages, tools: tools, **options)
+      end
+    end
+  end
+end
+
+# lib/ollama_agent/llm/logging_proxy.rb
+module OllamaAgent
+  module LLM
+    class LoggingProxy
+      def initialize(adapter, logger: $stderr)
+        @adapter = adapter
+        @logger = logger
+      end
+
+      def chat(...)
+        @logger.puts "LLM chat request"
+        @adapter.chat(...)
+      end
+    end
+  end
+end
+```
+
+## Command (tool execution)
+
+```ruby
+class ToolCommand
+  attr_reader :name, :args, :result
+
+  def initialize(name, args)
+    @name = name
+    @args = args
+  end
+
+  def execute
+    klass = Tools::ToolRegistry.get(@name)
+    raise KeyError, "Unknown tool: #{@name}" unless klass
+
+    @result = klass.new(@args).call
+  end
+
+  def undo
+    # Optional: revert file edits, etc.
+  end
+end
+```
+
+## Observer (streaming)
+
+```ruby
+class Agent
+  def initialize(adapter:)
+    @adapter = adapter
+    @observers = []
+  end
+
+  def add_observer(observer)
+    @observers << observer
+  end
+
+  def notify_observers(token, logprobs)
+    @observers.each { |obs| obs.update(token, logprobs) }
+  end
+end
+```
+
+Wire `on_token` (or equivalent) from `ollama-client` to `notify_observers`.
+
+## Strategy (patch application)
+
+```ruby
+class PatchStrategy
+  def apply(path, diff)
+    raise NotImplementedError
+  end
+end
+
+class SystemPatchStrategy < PatchStrategy
+  def apply(path, diff)
+    IO.popen(["patch", "-p1", "-f", path.to_s], "w") { |stdin| stdin.write(diff) }
+  end
+end
+```
+
+## State (conversation phases)
+
+```ruby
+class AgentState
+  def handle(agent, response)
+    raise NotImplementedError
+  end
+end
+
+class IdleState < AgentState
+  def handle(agent, response)
+    # transition when tool calls appear
+  end
+end
+
+class ToolExecutionState < AgentState
+  def handle(agent, response)
+    # run tools, append results, return to idle
+  end
+end
+```
+
+## Template Method (agent loop)
+
+```ruby
+class BaseAgent
+  def run(query)
+    messages = build_initial_messages(query)
+    loop do
+      response = send_to_llm(messages)
+      if tool_calls?(response)
+        messages << assistant_message(response)
+        process_tool_calls(tool_calls(response), messages)
+      else
+        handle_final_response(response, messages)
+        break
+      end
+    end
+  end
+
+  def build_initial_messages(query)
+    raise NotImplementedError
+  end
+
+  def send_to_llm(messages)
+    raise NotImplementedError
+  end
+
+  def process_tool_calls(_tool_calls, _messages)
+    raise NotImplementedError
+  end
+
+  def handle_final_response(_response, _messages)
+    raise NotImplementedError
+  end
+end
+```
+
+## Metaprogramming: tool DSL (optional)
+
+```ruby
+class BaseTool
+  def self.tool(name, description, &block)
+    define_method(:call, &block)
+    Tools::ToolRegistry.register(name.to_s, self)
+  end
+end
+```
+
+Prefer explicit subclasses + `inherited` registration if the DSL obscures tests.
+
+## Dynamic hooks
+
+```ruby
+def trigger_hook(event)
+  m = :"on_#{event}"
+  send(m) if respond_to?(m, true)
+end
+```
+
+## Putting it together (illustrative)
+
+```ruby
+module OllamaAgent
+  class Agent
+    def initialize(adapter:, tool_registry: Tools::ToolRegistry)
+      @adapter = adapter
+      @tool_registry = tool_registry
+      @state = IdleState.new
+      @observers = []
+    end
+
+    def run(query)
+      built = PromptBuilder.new
+        .system(SYSTEM_PROMPT)
+        .user(query)
+        .temperature(0.2)
+        .build
+
+      messages = built[:messages]
+      # Loop: @adapter.chat with messages/tools/options; @state.handle; execute tools via ToolCommand
+    end
+
+    def add_observer(observer)
+      @observers << observer
+    end
+
+    def execute_tool(tool_call)
+      klass = @tool_registry.get(tool_call.name)
+      raise KeyError, "Unknown tool: #{tool_call.name}" unless klass
+
+      command = ToolCommand.new(tool_call.name, tool_call.arguments)
+      command.execute
+      command.result
+    end
+  end
+end
+```
+
+## Main entry `require` pattern
+
+```ruby
+# lib/ollama_agent.rb
+require_relative "ollama_agent/version"
+require_relative "ollama_agent/tool_registry"
+require_relative "ollama_agent/tools/base"
+Dir[File.join(__dir__, "ollama_agent", "tools", "*.rb")].sort.each { |f| require f }
+# require LLM, commands, agent, cli
+```
+
+Skip globs if load order matters; require explicit files instead.
+
+---
+
+## Recommended gem structure (pattern-oriented layout)
+
+Use this when growing toward explicit registries, adapters, and strategies. Omit directories you do not need yet (e.g. `states/`, `strategies/`).
+
+```
+ollama_agent/
+├── bin/
+│   └── console
+├── exe/
+│   └── ollama_agent
+├── lib/
+│   ├── ollama_agent.rb
+│   ├── ollama_agent/
+│   │   ├── version.rb
+│   │   ├── cli.rb
+│   │   ├── agent.rb                 # Facade + template-method loop
+│   │   ├── prompt_builder.rb
+│   │   ├── tool_registry.rb       # name → class (not a process Singleton)
+│   │   ├── tools/
+│   │   │   ├── base.rb            # inherited hook / optional DSL
+│   │   │   ├── read_file.rb
+│   │   │   ├── search_code.rb
+│   │   │   └── edit_file.rb
+│   │   ├── llm/
+│   │   │   ├── base_adapter.rb
+│   │   │   ├── ollama_adapter.rb
+│   │   │   └── logging_proxy.rb
+│   │   ├── commands/
+│   │   │   └── tool_command.rb
+│   │   ├── observers/
+│   │   │   ├── base_observer.rb
+│   │   │   └── token_observer.rb
+│   │   ├── strategies/
+│   │   │   ├── patch_strategy.rb
+│   │   │   └── system_patch_strategy.rb
+│   │   └── states/
+│   │       ├── agent_state.rb
+│   │       ├── idle_state.rb
+│   │       └── tool_execution_state.rb
+├── spec/
+└── ollama_agent.gemspec
+```
+
+### Where each pattern lives
+
+| Pattern / concept | Location |
+|-------------------|----------|
+| Facade | `agent.rb` — `run` |
+| Template method | `agent.rb` — loop skeleton; subclasses override hooks if needed |
+| Builder | `prompt_builder.rb` |
+| Registry | `tool_registry.rb` — map of tool names to classes |
+| Factory / auto-registration | `tools/base.rb` — `inherited` (or explicit registration) |
+| Adapter | `llm/base_adapter.rb`, `llm/ollama_adapter.rb` |
+| Proxy | `llm/logging_proxy.rb` |
+| Command | `commands/tool_command.rb` |
+| Observer | `observers/` |
+| Strategy | `strategies/` — patch application |
+| State | `states/` — conversation phases |
+| Metaprogramming / DSL | `tools/base.rb` — optional `tool` class method |
+
+### `lib/ollama_agent.rb` require order (example)
+
+```ruby
+require_relative "ollama_agent/version"
+require_relative "ollama_agent/cli"
+require_relative "ollama_agent/agent"
+require_relative "ollama_agent/prompt_builder"
+require_relative "ollama_agent/tool_registry"
+require_relative "ollama_agent/tools/base"
+Dir[File.join(__dir__, "ollama_agent", "tools", "*.rb")].sort.each { |f| require f }
+# then llm/, commands/, strategies/, etc.
+```
+
+Prefer explicit `require_relative` per file when load order matters (subclasses after `Base`).
+
+### Benefits
+
+- Separation of concerns; isolated unit tests; clear extension points for tools, strategies, observers.
+
+### This repository today (flatter)
+
+The live `ollama_agent` gem currently uses a **smaller** layout: e.g. `sandboxed_tools.rb`, `tools_schema.rb`, `patch_support.rb`, `diff_path_validator.rb`, `agent_prompt.rb`, `ollama_connection.rb` — same responsibilities, fewer directories. Migrating to the tree above is optional and should follow real need (second LLM backend, multiple patch strategies, etc.).

data/.env.example

@@ -0,0 +1,27 @@
+# Example environment variables for OllamaAgent gem
+# Disable colored output (set to any value to respect https://no-color.org/)
+NO_COLOR=
+# Enable colored output (default: enabled). Set to "0" to disable.
+OLLAMA_AGENT_COLOR=1
+# Enable markdown rendering in terminal (default: enabled). Set to "0" to disable.
+OLLAMA_AGENT_MARKDOWN=1
+# Render thinking output with markdown (default: disabled). Set to "1" to enable.
+OLLAMA_AGENT_THINKING_MARKDOWN=0
+# Base URL for Ollama server
+OLLAMA_BASE_URL=https://ollama.com
+# API key for Ollama (if required)
+OLLAMA_API_KEY=your_api_key_here
+# Think parameter: true/false/high/medium/low (default: true)
+OLLAMA_AGENT_THINK=1
+# Root directory for the agent (default: current working directory)
+OLLAMA_AGENT_ROOT=.
+# Debug mode (set to "1" for verbose output)
+OLLAMA_AGENT_DEBUG=0
+# Maximum tool rounds (default: 64)
+OLLAMA_AGENT_MAX_TURNS=64
+# Model to use (default: from Ollama config)
+OLLAMA_AGENT_MODEL=gpt-oss:120b-cloud
+# HTTP timeout in seconds for Ollama requests
+OLLAMA_AGENT_TIMEOUT=120
+# Parse tool JSON from assistant output (set to "1" to enable)
+OLLAMA_AGENT_PARSE_TOOL_JSON=0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-03-21
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"ollama_agent" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["shubhamtaywade82@gmail.com"](mailto:"shubhamtaywade82@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Shubham Taywade
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.