ollama_agent 0.1.0

data/README.md

@@ -0,0 +1,147 @@
+# ollama_agent
+
+Version: 0.1.0
+
+Ruby gem that runs a **CLI coding agent** against a local [Ollama](https://ollama.com) model. It exposes tools to **list files**, **read files**, **search the tree** (ripgrep or grep), and **apply unified diffs** so the model can make small, reviewable edits.
+
+## Features
+
+- Tool `list_files` – list project files.
+- Tool `read_file` – read file contents.
+- Tool `search_code` – search code with ripgrep or grep.
+- Tool `edit_file` – apply unified diffs safely.
+- CLI built with Thor, entry point `exe/ollama_agent`.
+
+## Requirements
+
+- Ruby ≥ 3.2
+- **Local:** Ollama running and a capable tool-calling model, **or**
+- **Ollama Cloud:** API key and a cloud-capable model name (see below)
+
+## Installation
+
+From RubyGems (when published) or from this repository:
+
+```bash
+bundle install
+```
+
+## Usage
+
+From the project you want the agent to modify (set the working directory accordingly):
+
+```bash
+bundle exec ruby exe/ollama_agent ask "Update the README.md with current codebase"
+```
+
+From this repository after `bundle install`, `ruby exe/ollama_agent` (without `bundle exec`) also works: the executable adds `lib` to the load path and loads `bundler/setup` when a `Gemfile` is present.
+
+Apply proposed patches without interactive confirmation:
+
+```bash
+bundle exec ruby exe/ollama_agent ask -y "Your task"
+```
+
+Long-running models (slow local inference):
+
+```bash
+bundle exec ruby exe/ollama_agent ask --timeout 300 "Your task"
+```
+
+Interactive REPL:
+
+```bash
+bundle exec ruby exe/ollama_agent ask --interactive
+```
+
+With a **thinking-capable** model, enable reasoning output:
+
+```bash
+OLLAMA_AGENT_THINK=true bundle exec ruby exe/ollama_agent ask -i
+# or
+bundle exec ruby exe/ollama_agent ask -i --think true
+```
+
+The CLI uses **ANSI colors** on a TTY (banner, prompt, patch prompts). **Assistant replies** are rendered as **Markdown** (headings, lists, bold, code fences) via `tty-markdown` when stdout is a TTY and **`NO_COLOR`** is unset. Disable Markdown rendering with **`OLLAMA_AGENT_MARKDOWN=0`**. Disable all colors with **`NO_COLOR`** or **`OLLAMA_AGENT_COLOR=0`**.
+
+When **thinking** is enabled, internal reasoning is shown in a **framed, dim** block labeled **Thinking**; the user-facing reply is labeled **Assistant** in green when the model returns both fields. Thinking text is **plain dim** by default (so it stays visually separate from the reply). Set **`OLLAMA_AGENT_THINKING_MARKDOWN=1`** to render thinking through Markdown too (muted colors).
+
+### Ollama Cloud
+
+[Ollama Cloud](https://docs.ollama.com/cloud) uses the same HTTP API as the local server, with HTTPS and a Bearer API key. The **ollama-client** gem sends `Authorization: Bearer <api_key>` when `Ollama::Config#api_key` is set (HTTPS is used when the URL scheme is `https`).
+
+1. Create a key at [ollama.com/settings/keys](https://ollama.com/settings/keys).
+2. Point the agent at the cloud host and pass the key (same env names as ollama-client’s docs):
+
+```bash
+export OLLAMA_BASE_URL="https://ollama.com"
+export OLLAMA_API_KEY="your_key"
+export OLLAMA_AGENT_MODEL="gpt-oss:120b-cloud"   # example; pick a cloud model from `ollama list` / the catalog
+bundle exec ruby exe/ollama_agent ask "Your task"
+```
+
+### Environment
+
+| Variable | Purpose |
+|----------|---------|
+| `OLLAMA_BASE_URL` | Ollama API base URL (default from ollama-client: `http://localhost:11434`; use `https://ollama.com` for cloud) |
+| `OLLAMA_API_KEY` | API key for Ollama Cloud (`https://ollama.com`); optional for local HTTP |
+| `OLLAMA_AGENT_MODEL` | Model name (overrides default from ollama-client) |
+| `OLLAMA_AGENT_ROOT` | Project root (defaults to current working directory) |
+| `OLLAMA_AGENT_DEBUG` | Set to `1` to print validation diagnostics on stderr |
+| `OLLAMA_AGENT_MAX_TURNS` | Max chat rounds with tool calls (default: 64) |
+| `OLLAMA_AGENT_TIMEOUT` | HTTP read/open timeout in seconds for Ollama requests (default **120**; use `ask --timeout` / `-t` to override per run) |
+| `OLLAMA_AGENT_PARSE_TOOL_JSON` | Set to `1` to run tools parsed from JSON lines in assistant text (fallback when the model does not emit native tool calls) |
+| `NO_COLOR` | Set (any value) to disable ANSI colors (see [no-color.org](https://no-color.org/)) |
+| `OLLAMA_AGENT_COLOR` | Set to `0` to disable colors even on a TTY |
+| `OLLAMA_AGENT_MARKDOWN` | Set to `0` to disable Markdown formatting of assistant replies (plain text only) |
+| `OLLAMA_AGENT_THINKING_MARKDOWN` | Set to `1` to render **thinking** text with Markdown (muted); default is plain dim text inside the Thinking frame |
+| `OLLAMA_AGENT_THINK` | Model **thinking** mode for compatible models: `true` / `false`, or `high` / `medium` / `low` (see ollama-client `think:`). Empty = omit (server default). |
+| `OLLAMA_AGENT_INDEX_REBUILD` | Set to `1` to drop the cached Prism Ruby index before the next symbol search in this process |
+| `OLLAMA_AGENT_RUBY_INDEX_MAX_FILES` | Max `.rb` files to parse per index build (default **5000**) |
+| `OLLAMA_AGENT_RUBY_INDEX_MAX_FILE_BYTES` | Skip Ruby files larger than this many bytes (default **512000**) |
+| `OLLAMA_AGENT_RUBY_INDEX_MAX_LINES` | Max result lines for `search_code` class/module/method modes (default **200**) |
+| `OLLAMA_AGENT_RUBY_INDEX_MAX_CHARS` | Max characters of index output per search (default **60000**) |
+| `OLLAMA_AGENT_MAX_READ_FILE_BYTES` | Max bytes for a **full** `read_file` (no line range); larger files return an error (default **2097152**, 2 MiB). Line-range reads stream and are not limited by this cap. |
+| `OLLAMA_AGENT_INDEX_REBUILD` | The Prism index is rebuilt when this env value **changes** (e.g. unset → `1`); it is **not** rebuilt on every tool call while it stays `1`. |
+
+## Troubleshooting
+
+- **Use a tool-capable model** — Set `OLLAMA_AGENT_MODEL` to a model that supports function/tool calling (e.g. a recent coder-tuned variant). If the model only prints `{"name": "read_file", ...}` in plain text, tools never run unless you enable `OLLAMA_AGENT_PARSE_TOOL_JSON=1`.
+- **Malformed diffs** — Headers must look like `git diff`: `--- a/file` then `+++ b/file` then a unified hunk line starting with `@@` (not legacy `--- N,M ----`). Do not put commas after path tokens. The gem normalizes some mistakes and runs `patch --dry-run` before applying.
+- **Request timeouts** — The agent defaults to a **120s** HTTP timeout (longer than ollama-client’s 30s). If you still hit `Ollama::TimeoutError`, raise it with `OLLAMA_AGENT_TIMEOUT=300`, `bundle exec ruby exe/ollama_agent ask --timeout 300 "..."`, or `-t 300`. Ensure the variable name is exactly `OLLAMA_AGENT_TIMEOUT` (a leading typo such as `vOLLAMA_AGENT_TIMEOUT` is ignored).
+
+## How it works
+
+1. The CLI starts `OllamaAgent::Agent`, which loops on `Ollama::Client#chat` with tool definitions.
+2. Tools are executed in-process under a **path sandbox** (`OLLAMA_AGENT_ROOT`).
+3. **`search_code`** defaults to **ripgrep/grep** (`mode` omitted or `text`). For Ruby, use `mode` **`method`**, **`class`**, **`module`**, or **`constant`** to query a **Prism** parse index (built lazily on first use). **`read_file`** accepts optional **`start_line`** / **`end_line`** (1-based, inclusive) to read only part of a file.
+4. Patches are validated and checked with **`patch --dry-run`** before you confirm (unless `-y`).
+
+## Development
+
+```bash
+bundle exec rspec
+bundle exec rubocop
+```
+
+### CI and RubyGems release
+
+- **CI** — [`.github/workflows/main.yml`](.github/workflows/main.yml) runs **RSpec** and **RuboCop** on pushes to `main` / `master` and on pull requests (Ruby **3.3.4** and **3.2.0**).
+- **Release** — [`.github/workflows/release.yml`](.github/workflows/release.yml) runs on tags `v*`. It checks that the tag matches `OllamaAgent::VERSION` in [`lib/ollama_agent/version.rb`](lib/ollama_agent/version.rb), builds with `gem build ollama_agent.gemspec`, and pushes to RubyGems.
+
+Repository **secrets** (Settings → Secrets and variables → Actions):
+
+| Secret | Purpose |
+|--------|---------|
+| `RUBYGEMS_API_KEY` | RubyGems API key with **push** scope |
+| `RUBYGEMS_OTP_SECRET` | Base32 secret for **TOTP** (RubyGems MFA); the workflow uses `rotp` to generate a one-time code for `gem push` |
+
+Release steps:
+
+1. Bump `OllamaAgent::VERSION` in `lib/ollama_agent/version.rb` and commit to `main`.
+2. Tag: `git tag v0.1.0` (must match the version string) and `git push origin v0.1.0`.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/exe/ollama_agent

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+gem_root = File.expand_path("..", __dir__)
+$LOAD_PATH.unshift(File.join(gem_root, "lib"))
+
+# From a checkout, load the Gemfile so ollama-client and other deps resolve without `bundle exec`.
+gemfile = File.join(gem_root, "Gemfile")
+require "bundler/setup" if File.file?(gemfile)
+
+require "ollama_agent"
+
+OllamaAgent::CLI.start(ARGV)

data/lib/ollama_agent/agent.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require_relative "agent_prompt"
+require_relative "console"
+require_relative "ollama_connection"
+require_relative "tools_schema"
+require_relative "sandboxed_tools"
+require_relative "think_param"
+require_relative "timeout_param"
+require_relative "tool_content_parser"
+
+module OllamaAgent
+  # Runs a tool-calling loop against Ollama: read files, search, apply unified diffs.
+  class Agent
+    include SandboxedTools
+
+    MAX_TURNS = 64
+    # ollama-client defaults to 30s; multi-turn tool chats often need longer on local hardware.
+    DEFAULT_HTTP_TIMEOUT = 120
+
+    attr_reader :client, :root
+
+    # rubocop:disable Metrics/ParameterLists -- CLI and tests pass explicit dependencies
+    def initialize(client: nil, model: nil, root: nil, confirm_patches: true, http_timeout: nil, think: nil)
+      @model = model || default_model
+      @root = File.expand_path(root || ENV.fetch("OLLAMA_AGENT_ROOT", Dir.pwd))
+      @confirm_patches = confirm_patches
+      @http_timeout_override = http_timeout
+      @think = think
+      @client = client || build_default_client
+    end
+    # rubocop:enable Metrics/ParameterLists
+
+    def run(query)
+      messages = [
+        { role: "system", content: system_prompt },
+        { role: "user", content: query }
+      ]
+
+      execute_agent_turns(messages)
+    end
+
+    private
+
+    def execute_agent_turns(messages)
+      max_turns.times do
+        message = chat_assistant_message(messages)
+        tool_calls = tool_calls_from(message)
+
+        messages << message.to_h
+        return if tool_calls.empty?
+
+        append_tool_results(messages, tool_calls)
+      end
+
+      warn "ollama_agent: maximum tool rounds (#{max_turns}) reached" if ENV["OLLAMA_AGENT_DEBUG"] == "1"
+    end
+
+    def tool_calls_from(message)
+      calls = message.tool_calls || []
+      return calls unless calls.empty? && ToolContentParser.enabled?
+
+      ToolContentParser.synthetic_calls(message.content)
+    end
+
+    def max_turns
+      Integer(ENV.fetch("OLLAMA_AGENT_MAX_TURNS", MAX_TURNS.to_s))
+    rescue ArgumentError, TypeError
+      MAX_TURNS
+    end
+
+    def chat_assistant_message(messages)
+      response = @client.chat(**chat_request_args(messages))
+
+      message = response.message
+      raise Error, "Empty assistant message" if message.nil?
+
+      announce_assistant_content(message)
+      message
+    end
+
+    def chat_request_args(messages)
+      args = {
+        messages: messages,
+        tools: TOOLS,
+        model: @model,
+        options: { temperature: 0.2 }
+      }
+      th = resolve_think
+      args[:think] = th unless th.nil?
+      args
+    end
+
+    def announce_assistant_content(message)
+      Console.puts_assistant_message(message)
+    end
+
+    def resolve_think
+      ThinkParam.resolve(@think)
+    end
+
+    def default_model
+      ENV["OLLAMA_AGENT_MODEL"] || Ollama::Config.new.model
+    end
+
+    def build_default_client
+      config = Ollama::Config.new
+      @http_timeout_seconds = resolved_http_timeout_seconds
+      config.timeout = @http_timeout_seconds
+      OllamaConnection.apply_env_to_config(config)
+      Ollama::Client.new(config: config)
+    end
+
+    def resolved_http_timeout_seconds
+      parsed = TimeoutParam.parse_positive(@http_timeout_override)
+      return parsed if parsed
+
+      parsed = TimeoutParam.parse_positive(ENV.fetch("OLLAMA_AGENT_TIMEOUT", nil))
+      return parsed if parsed
+
+      DEFAULT_HTTP_TIMEOUT
+    end
+
+    def system_prompt
+      AgentPrompt.text
+    end
+
+    def append_tool_results(messages, tool_calls)
+      tool_calls.each do |tool_call|
+        result = execute_tool(tool_call.name, tool_call.arguments || {})
+        messages << tool_message(tool_call, result)
+      end
+    end
+
+    def tool_message(tool_call, result)
+      msg = {
+        role: "tool",
+        name: tool_call.name,
+        content: result.to_s
+      }
+      id = tool_call.id
+      msg[:tool_call_id] = id if id && !id.to_s.empty?
+      msg
+    end
+  end
+end

data/lib/ollama_agent/agent_prompt.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  # System prompt for the coding agent (kept separate to keep Agent small and testable).
+  module AgentPrompt
+    def self.text
+      <<~PROMPT
+        You are a coding assistant with tools: list_files, read_file, search_code, edit_file.
+        Work only under the project root. Briefly state your plan, then use tools.
+
+        Large Ruby codebases: use search_code with mode "method", "class", "module", or "constant" to locate definitions
+        via the Prism index (substring match on names), then read_file with start_line/end_line for only the lines you need.
+        Use search_code mode "text" (default) for ripgrep-style matches in any file type.
+
+        Do not paste JSON tool calls or {"name": ...} blocks in your reply text. Tools run only when the host
+        receives native tool calls from the model API—not from prose. Never put commas after --- or +++ file lines.
+
+        For README or documentation updates that should reflect the codebase:
+        1) list_files on "." or "lib" (and read ollama_agent.gemspec if present) to see structure.
+        2) read_file every file you will change before editing (e.g. README.md, lib/ollama_agent.rb).
+        3) edit_file last with a unified diff in `git diff` / patch(1) form: `--- a/<path>` then `+++ b/<same path>` (no
+           trailing commas). The next line must be a unified hunk header starting with `@@` (two at-signs), e.g.
+           `@@ -12,5 +12,5 @@`, then unchanged lines prefixed with a space, `-` removed, `+` added. Never use legacy lines like
+           `--- 2,1 ----`. Do not append editor markers such as `*** End Patch` or `*** Begin Patch`—only what `git diff`
+           would print; those markers are not valid patch input.
+
+        Markdown bullets: in unified diff, the first character of each line is the opcode. A line starting with `-` is a
+        removal from the old file—not a bullet. To add a bullet line `- item` to the file, the diff line must start with
+        `+` then the rest: `+ - item` (plus, space, dash, …). Same for any new line whose text begins with `-`.
+
+        Do not paste, paraphrase, or echo any sample diff from this system message—there is none. Every `-` and `+` line
+        must match real text from your read_file results (or your intended replacement for those exact lines). Never
+        invent hunks from memory or placeholders.
+
+        Never put @@ before the +++ line for the same file. When the task is done, reply with a brief summary and stop
+        calling tools.
+
+        When the API exposes separate reasoning ("thinking") and main message text ("content"): put internal planning only
+        in thinking; put the full user-visible reply (greetings, explanations, summaries) in content so the host can style
+        them as the assistant message.
+      PROMPT
+    end
+  end
+end

data/lib/ollama_agent/cli.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require "thor"
+
+require_relative "agent"
+
+module OllamaAgent
+  # Thor CLI for single-shot and interactive agent sessions.
+  class CLI < Thor
+    desc "ask [QUERY]", "Run a natural-language task (reads, search, patch)"
+    method_option :model, type: :string, desc: "Ollama model (default: OLLAMA_AGENT_MODEL or ollama-client default)"
+    method_option :interactive, type: :boolean, aliases: "-i", desc: "Interactive REPL"
+    method_option :yes, type: :boolean, aliases: "-y", desc: "Apply patches without confirmation"
+    method_option :root, type: :string, desc: "Project root (default: OLLAMA_AGENT_ROOT or cwd)"
+    method_option :timeout, type: :numeric, aliases: "-t", desc: "HTTP timeout seconds (default 120)"
+    method_option :think, type: :string, desc: "Thinking mode: true|false|high|medium|low (see OLLAMA_AGENT_THINK)"
+    def ask(query = nil)
+      agent = build_agent
+
+      if options[:interactive]
+        start_interactive(agent)
+      elsif query
+        agent.run(query)
+      else
+        puts Console.error_line("Error: provide a QUERY or use --interactive")
+        exit 1
+      end
+    end
+
+    private
+
+    def build_agent
+      Agent.new(
+        model: options[:model],
+        root: options[:root],
+        confirm_patches: !options[:yes],
+        http_timeout: options[:timeout],
+        think: options[:think]
+      )
+    end
+
+    def start_interactive(agent)
+      puts Console.welcome_banner("Ollama Agent (type 'exit' to quit)")
+      use_readline = interactive_readline_usable?
+
+      loop do
+        input = interactive_readline_line(use_readline)
+        break if input.nil?
+
+        line = input.chomp
+        break if line == "exit"
+
+        agent.run(line)
+      end
+    end
+
+    def interactive_readline_usable?
+      require "readline"
+      true
+    rescue LoadError
+      false
+    end
+
+    def interactive_readline_line(use_readline)
+      if use_readline
+        Readline.readline(Console.prompt_prefix, true)
+      else
+        print Console.prompt_prefix
+        $stdin.gets
+      end
+    end
+  end
+end

data/lib/ollama_agent/console.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module OllamaAgent
+  # ANSI styling for TTY output. Respects https://no-color.org/ via NO_COLOR.
+  # Assistant replies use tty-markdown when enabled (headings, lists, bold, code blocks).
+  module Console
+    module_function
+
+    # Muted tty-markdown palette so "Thinking" stays visually distinct from the main reply
+    # (default TTY::Markdown theme uses cyan/yellow like normal assistant output).
+    THINKING_MARKDOWN_THEME = {
+      em: :bright_black,
+      header: %i[bright_black bold],
+      hr: :bright_black,
+      link: %i[bright_black underline],
+      list: :bright_black,
+      strong: %i[bright_black bold],
+      table: :bright_black,
+      quote: :bright_black,
+      image: :bright_black,
+      note: :bright_black,
+      comment: :bright_black
+    }.freeze
+
+    THINKING_FRAME_WIDTH = 44
+
+    def color_enabled?
+      $stdout.tty? && ENV["NO_COLOR"].to_s.empty? && ENV["OLLAMA_AGENT_COLOR"] != "0"
+    end
+
+    def markdown_enabled?
+      $stdout.tty? && ENV["NO_COLOR"].to_s.empty? && ENV["OLLAMA_AGENT_MARKDOWN"] != "0"
+    end
+
+    # Thinking uses dim plain text by default so it stays visually separate from the main reply.
+    # Set OLLAMA_AGENT_THINKING_MARKDOWN=1 to render thinking through tty-markdown (muted theme).
+    def thinking_markdown_enabled?
+      markdown_enabled? && ENV["OLLAMA_AGENT_THINKING_MARKDOWN"] == "1"
+    end
+
+    def style(text, *codes)
+      return text.to_s unless color_enabled?
+
+      t = text.to_s
+      return t if t.empty? || codes.flatten.compact.empty?
+
+      "\e[#{codes.flatten.compact.join(";")}m#{t}\e[0m"
+    end
+
+    def bold(text) = style(text, 1)
+    def dim(text) = style(text, 2)
+    def cyan(text) = style(text, 36)
+    def green(text) = style(text, 32)
+    def yellow(text) = style(text, 33)
+    def red(text) = style(text, 31)
+    def magenta(text) = style(text, 35)
+
+    def welcome_banner(text)
+      bold(cyan(text))
+    end
+
+    def prompt_prefix
+      cyan("> ")
+    end
+
+    def assistant_output(text)
+      green(text)
+    end
+
+    # Renders Markdown to the terminal (bold, lists, fenced code) when enabled; otherwise plain green text.
+    def format_assistant(text)
+      return assistant_output(text) unless markdown_enabled?
+
+      markdown_parse(text) || assistant_output(text)
+    end
+
+    def format_thinking(text)
+      line = thinking_frame_line
+      header = "#{magenta(bold("Thinking"))}\n#{line}\n"
+      body = if thinking_markdown_enabled?
+               markdown_parse(text, thinking: true) || dim(text.to_s)
+             else
+               dim(text.to_s)
+             end
+      "#{header}#{body}\n#{line}"
+    end
+
+    def assistant_reply_heading
+      bold(green("Assistant"))
+    end
+
+    def thinking_frame_line
+      dim("-" * THINKING_FRAME_WIDTH)
+    end
+
+    class << self
+      private
+
+      def markdown_parse(text, thinking: false)
+        require "tty-markdown"
+        theme = thinking ? THINKING_MARKDOWN_THEME : {}
+        TTY::Markdown.parse(text.to_s, theme: theme)
+      rescue LoadError, StandardError
+        nil
+      end
+
+      def write_assistant_reply(content, thinking_present)
+        puts if thinking_present
+        puts assistant_reply_heading if thinking_present
+        puts format_assistant(content)
+      end
+    end
+
+    # Prints thinking (if any) then main content; duck-types #thinking and #content.
+    def puts_assistant_message(message)
+      t = message.thinking
+      c = message.content
+      thinking_present = t && !t.to_s.empty?
+
+      puts format_thinking(t) if thinking_present
+      write_assistant_reply(c, thinking_present) if c && !c.to_s.empty?
+    end
+
+    def patch_title(text)
+      bold(yellow(text))
+    end
+
+    def apply_prompt(text)
+      yellow(text)
+    end
+
+    def error_line(text)
+      red(text)
+    end
+  end
+end