plai_testr 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c248d4cb1b694d6260effa15b48ef4805638dfc19691f622defc0564c5334328
+  data.tar.gz: 32b542793975ea15359ca7b6d6def786656fd362b72d490fcd810a20fac98a26
+SHA512:
+  metadata.gz: 0f21750ca5f57820932d029dcc5cd5461c9633568246dd1e7578155fc2445ac7eb90486c64c02063596b86b69b606a28ee98b26a4924e45e85ab9992f950a85b
+  data.tar.gz: c6ef28a4491f87a94ccfcbd8591af5cd2ecac0b5f1722b8a174cbce01e4a91ffce628a45ac8199a8004fbfd58526058e518f1716977add17f0744f26eea2a4e2

data/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## 0.1.1 (2026-10-23)
+
+- Author name in the gemspec and license.
+
+## 0.1.0 (2026-10-23, yanked)
+
+First public release.
+
+- `plai_testr new` creates a playtesting app with two example games (Hearts, Gin Rummy); `plai_testr generate game` adds a game skeleton.
+- `play` runs one model game with preflight checks; `botrun` plays many bot-only games and reports balance; `resume`, `compare`, `list` and `preflight` round it out.
+- Games list their legal moves as a numbered menu; the model picks one. Bot rules can play obvious moves (hybrid mode) or every move (bot mode).
+- Personas (`personas.yml`) and bot parameters (`bots.yml`) per game.
+- Checkpoints after every decision; resume refuses sessions whose game has changed.
+- Configurable decision limit and model settings in `config/plai_testr.rb`.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Aaron H
+
+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.

data/README.md

@@ -0,0 +1,176 @@
+# PlAI Testr
+
+Automated tabletop game playtesting with local LLM players via [Ollama](https://ollama.com).
+
+Your game lists the legal moves each turn as a numbered menu; a model (or a scripted bot) picks one; PlAI Testr applies it, checkpoints, and writes a markdown report. Bots alone can play thousands of games in minutes for balance numbers; model players add reasoning and end-of-game feedback.
+
+## Requirements
+
+- Ruby 3.4+
+- [Ollama](https://ollama.com), local or on your network (not needed for bot-only runs)
+
+## Quick start
+
+```sh
+gem install plai_testr        # or in a Gemfile: gem 'plai_testr', github: 'armahillo/plai_testr'
+plai_testr new my_playtests   # an app with two example games: Hearts and Gin Rummy
+cd my_playtests
+bundle install
+
+bundle exec plai_testr hearts botrun --games 100   # bots only, no model: a report in seconds
+bundle exec plai_testr gin_rummy play              # one model game (pulls qwen3:8b if missing)
+```
+
+Reports land in `games/<game>/reports/`. Add your own game with `bundle exec plai_testr generate game my_game`, then fill in the hooks below. The generated app's `AGENTS.md` walks an AI coding assistant through building a harness, so you can have your own agent do it.
+
+## Commands
+
+```
+plai_testr <game> play      [--seed N] [--model M] [--think] [--mode llm|hybrid|bot] [--players N] [--personas A,B] [--referee M]
+plai_testr <game> botrun    [--games N | --seeds 1,2,3] [--players N] [--personas all|A,B]
+plai_testr <game> resume    <session_id>
+plai_testr <game> preflight
+plai_testr <game> compare   [--since ID]
+plai_testr <game> list
+plai_testr new <dir>
+plai_testr generate game <name>
+```
+
+- `play` runs one game. Without `--seed` it picks one from 1–100 and prints it. Before playing, preflight checks Ollama, pulls missing models, warms them up, measures the first prompt against the context size, and plays 5 bot games to catch menu bugs. `--skip-preflight` skips all of that.
+- `--mode hybrid` lets the bot play moves it marks *obvious*; `--mode bot` uses no model.
+- `botrun` plays many bot-only games in memory and writes one report: endings, wins by persona and seat with 95% ranges, game length, bot rules used, warnings and crashes.
+- `--quiet` shows a progress line and the result; `--verbose` adds raw model output (`play`) or every game (`botrun`).
+- Ctrl+C (or SIGTERM) saves and stops after the current move; a botrun finishes its game and reports. A second Ctrl+C quits at once.
+- Errors print one line. `PLAI_TESTR_DEBUG=1` shows the backtrace; mistakes in game code (`MoveError`) always do.
+
+## Writing a game
+
+`generate game` creates `games/<name>/` with everything below. The examples in [`templates/examples/`](templates/examples) are complete games to copy from.
+
+```
+games/<name>/
+  lib/<name>.rb             Requires the game and calls PlaiTestr.register
+  lib/<name>/bot.rb         Bot rules (bot_choice), included in the runner
+  lib/<name>/session/       Runner (rules engine)
+  lib/<name>/state/         GameState / PlayerState subclasses
+  data/rules.json           Name, version, player count, card deck, numbers the engine uses
+  data/rules.md             Rules text the model players read
+  data/personas.yml         Optional: strategy and play styles for model players
+  data/bots.yml             Optional: parameters the bot rules read
+  spec/
+```
+
+### Hooks
+
+A game subclasses `PlaiTestr::Session::Runner`. These hooks are its public API ([`runner.rb`](lib/plai_testr/session/runner.rb)):
+
+| Hook | Required | Purpose |
+|---|---|---|
+| `setup` | yes | Build the starting state. Not called on resume. |
+| `legal_moves(player)` | yes | The menu: an array of `option(...)` entries |
+| `apply_action_effects(player, action)` | yes | Apply the chosen move's action to `@game_state` |
+| `next_player` | | Who acts next (default: alternate) |
+| `pick_range(player)` | | `[min, max]` to pick several options at once |
+| `game_over?` | | Default: `status['game_over']` |
+| `turn_phase(player)` | | Short step label for the console and report |
+| `rules_text_for`, `view_text_for`, `prompt_note_for` | | Prompt text: rules, the player's view, a one-off note |
+| `recent_events_for(player)` | | Recent events from the event log (default: the last 8 this player may see) |
+| `persona_for(player)` | | Strategy text for the system prompt (default: built from `personas.yml`) |
+| `display_name(player)` | | Name in the console and reports (default: the persona's key, title-cased, else the player id) |
+| `bot_choice(player, moves, pick: nil)` | | Bot rules: `nil` or `{ 'choice' => n, 'rule' => name, 'obvious' => bool }` (`'choices'` on pick turns) |
+| `think_about?(player)` | | With `--think`: whether this turn gets thinking (default: every turn) |
+| `debrief_questions`, `debrief_view_for` | | End-of-game feedback questions |
+| `report_sections`, `report_debrief?` | | Extra report sections; false to render the debrief yourself |
+| `botrun_stats` | | Game-specific numbers for one botrun game |
+
+Helpers for hooks: `option`, `menu(player)` (the menu as the runner sees it), `data`, `log(text, to: nil, turn: decision)`, `event_log`, `persona(player)`, `persona_name(player)`, `bot_strategy_for(player)`, `@rng`, `@rules`, `@game_state`, `out`. Specs drive a runner with `setup`, `play_turn`, `play_out` and the hooks above.
+
+### Moves
+
+```ruby
+def legal_moves(player)
+  hand(player).map { |card| option("Play #{card['name']}", public: "played #{card['name']}", play: { value: card['uid'] }) }
+end
+
+def apply_action_effects(player, action)
+  case action
+  in { play: { value: uid } }  then play(player, uid)
+  in { pass: { value: uids } } then pass(player, uids)
+  end
+end
+```
+
+`label` (the first argument) is what the acting player sees; `public:` is what others see; `log:` is a shorter console line. An action has one name; `value:` is the main parameter and others sit beside it. Moves and actions have symbol keys, so `apply_action_effects` can pattern-match them; a hand-written move with string keys is converted. On a pick turn the chosen values arrive together: `{ pass: { value: [42, 17, 9] } }`. Every menu is checked before it is used: a misspelled key or a malformed action raises `PlaiTestr::MoveError` naming the hook, player, decision and option. A menu with one option is applied without asking anyone.
+
+### State
+
+`@game_state` ([`game_state.rb`](lib/plai_testr/state/game_state.rb)) holds `turn` (decisions so far), `players`, `status` and `data`; each `player_state(name)` ([`player_state.rb`](lib/plai_testr/state/player_state.rb)) holds `score`, `hand` and `data`.
+
+- `status` belongs to the runner: set `game_over`, `winner` and `end_reason` when the game ends, with `@game_state.apply_changes('status' => {...})`.
+- `data` is the game's own state, as plain JSON-safe values so checkpoints work without extra code.
+- Subclass `GameState` to name your keys (`def step = @data['step']`) and to hide information per player with `data_for(observer)`; subclass `PlayerState` and override `serialize_for` / `public_data` to choose what opponents see. The examples show both.
+
+### Personas and bots
+
+`data/personas.yml` gives model players a shared `basic_strategy` and play styles under `personas`; `data/bots.yml` gives the bot rules parameters, per persona, read with `bot_strategy_for(player)`. Both files are optional and the generated copies explain their format. Each player gets a persona from `--personas a,b` or at random per seed; `botrun --personas all` cycles every pairing.
+
+### Randomness and limits
+
+- Use `@rng` for all randomness. It is reset for each decision from the seed and the decision number, so the same seed and the same choices always give the same game, interrupted or not.
+- When the model never gives a valid answer, the bot's choice is played instead (or a random legal move from a separate generator), and the turn is flagged.
+- Every game stops at a decision limit (`end_reason: 'decision_limit_reached'`, no winner) so a buggy game cannot run forever. Set `max_decisions:` in `PlaiTestr.register`; otherwise the app backstop applies.
+
+### Nested decisions and rulings
+
+- [FrameQueue](docs/frame_queue.md): attacks and responses, triggered effects, decisions inside decisions.
+- [Referee](docs/referee.md): yes/no rulings on free-text conditions by a second model.
+
+## Configuration
+
+`config/plai_testr.rb` in the app (generated, all commented out):
+
+```ruby
+PlaiTestr.configure do |config|
+  config.max_decisions  = 100_000       # backstop for games without their own limit
+  config.player_model   = 'qwen3:8b'
+  config.ollama_host    = 'localhost'
+  config.ollama_port    = 11434
+  config.model_settings = { context_size: 8192 }
+end
+```
+
+A game can override model settings in `PlaiTestr.register(..., model_settings: { ... })`.
+
+| Model setting | Default | Used for |
+|---|---|---|
+| `context_size` | 8192 | Menu turns without `--think`; the referee |
+| `long_context_size` | 16384 | Sessions with `--think`; the debrief |
+| `menu_budget` | 512 | Output tokens for a menu answer |
+| `think_budget` | 8192 | Output tokens for a thinking turn |
+| `debrief_budget` | 1024 | Output tokens for the debrief |
+| `referee_budget` | 2048 | Output tokens for a ruling |
+| `temperature` | 0.6 | Player sampling |
+
+Values outside the hard limits are clamped with a warning: context sizes between 2048 and the model's own maximum, temperature 0–2, budgets above 0 and below the context size. The values used are recorded in each report. Environment variables set the defaults: `PLAI_TESTR_PLAYER_MODEL`, `PLAI_TESTR_REFEREE_MODEL`, `PLAI_TESTR_OLLAMA_HOST`, `PLAI_TESTR_OLLAMA_PORT`.
+
+## Session output
+
+- `sessions/<id>/state.json`: the checkpoint, replaced atomically after every decision
+- `sessions/<id>/transcript.jsonl`: one JSON object per decision, with the model's reasoning. After a crash the last line may be cut off; skip lines that do not parse.
+- `sessions/<id>/think.log`: every model reply with Ollama's timings
+- `reports/<id>.md`: the session report
+
+`resume` continues an interrupted session exactly, or refuses: if the game's data, code or the gem version changed since the session started, start a new one with `play`.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+```
+
+`lib/plai_testr/` holds the gem: [`session/runner.rb`](lib/plai_testr/session/runner.rb) (the decision loop and hooks), [`agents/`](lib/plai_testr/agents) (Ollama client, player and referee prompts), [`reporter/`](lib/plai_testr/reporter), [`state/`](lib/plai_testr/state), [`cli.rb`](lib/plai_testr/cli.rb), [`preflight.rb`](lib/plai_testr/preflight.rb), [`botrun.rb`](lib/plai_testr/botrun.rb). `templates/` holds what `new` and `generate game` copy, including the example games and their specs.
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/bin/plai_testr

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require 'plai_testr'
+
+PlaiTestr::CLI.start(ARGV)

data/docs/frame_queue.md

@@ -0,0 +1,123 @@
+# Nested decisions with FrameQueue
+
+Most turns are one decision: the active player picks from a menu. Some games need decisions *inside* other decisions: an attack the defender may block, a card that triggers an opponent's response, an effect that asks someone else to choose. `PlaiTestr::Session::FrameQueue` handles these.
+
+## The idea
+
+A **frame** is one pending step: a hash with a `type`, the `player` who decides it (if anyone), and any data the step needs. Frames live on a stack in game state, so a checkpoint saved in the middle of an attack resumes in the middle of that attack.
+
+- The frame on top of the stack is the current decision. `next_player` and `legal_moves` read it.
+- When the player picks a move, `resolve_frame(params)` pops the frame and calls `on_<type>(frame, params)`.
+- Handlers push new frames for whatever happens next. **The last frame pushed resolves first.**
+- Frames marked `auto: true` need no decision: they are popped and resolved with `on_<type>(frame)` as soon as they reach the top.
+- When the stack is empty, `schedule_frames` pushes the next normal turn.
+
+## What you implement
+
+| Method | Purpose |
+|---|---|
+| `frame_queue` | The array that holds the frames, kept in `@game_state.data` |
+| `schedule_frames` | Push the next turn's frame(s) when the stack is empty |
+| `on_<type>(frame, params)` | Resolve a decision frame |
+| `on_<type>(frame)` | Resolve an `auto` frame |
+| `halt_frames?` | Optional. Stop resolving (default: `game_over?`). A good place for end checks and safety caps |
+| `intercept_frame(frame)` | Optional. Return true to stop before a frame and handle it in your own code (e.g. hand maintenance) |
+
+You call `advance_frames` once at the end of `setup`, and `resolve_frame(action.values.first)` from `apply_action_effects`. `frame_for(type, player, **data)` builds a frame. The hooks in the table are public; `advance_frames`, `resolve_frame`, `frame` and `frame_for` are private helpers your runner calls.
+
+## Example: attack and block
+
+Each turn the attacker plays a card. The defender may block with a card of equal or higher value, or take the damage. Damage is an `auto` frame, so it resolves without a decision; reaching 10 damage loses.
+
+```ruby
+module Strike
+  module Session
+    class Runner < PlaiTestr::Session::Runner
+      include PlaiTestr::Session::FrameQueue
+
+      HAND_SIZE = 4
+      KNOCKOUT  = 10
+
+      def setup
+        deck = PlaiTestr::Deck.build(@rules).shuffle(random: @rng)
+        players.each { |p| hand(p).concat(deck.shift(HAND_SIZE)) }
+        data.merge!('queue' => [], 'deck' => deck, 'damage' => players.to_h { |p| [p, 0] }, 'attacker' => players.first)
+        advance_frames
+      end
+
+      def frame_queue = data['queue']
+
+      def schedule_frames
+        attacker = data['attacker']
+        hand(attacker).concat(data['deck'].shift(HAND_SIZE - hand(attacker).length))
+        frame_queue.push(frame_for('attack', attacker))
+      end
+
+      def halt_frames?
+        end_game(nil, 'deck_empty') if !game_over? && data['deck'].empty? && hand(data['attacker']).empty?
+        game_over?
+      end
+
+      def next_player = frame['player']
+
+      def legal_moves(player)
+        case frame['type']
+        when 'attack'
+          hand(player).map { |c| option("Attack with #{c['name']}", attack: { value: c['uid'] }) }
+        when 'block'
+          blockers = hand(player).select { |c| c['value'] >= frame['value'] }
+          blockers.map { |c| option("Block with #{c['name']}", block: { value: c['uid'] }) } + [option("Take #{frame['value']} damage", block: {})]
+        end
+      end
+
+      def apply_action_effects(_player, action) = resolve_frame(action.values.first)
+
+      private
+
+      def on_attack(frame, params)
+        card     = take(frame['player'], params[:value])
+        defender = opponent(frame['player'])
+        frame_queue.push(frame_for('block', defender, value: card['value']))
+      end
+
+      def on_block(frame, params)
+        if params[:value]
+          take(frame['player'], params[:value])
+        else
+          frame_queue.push(frame_for('damage', frame['player'], auto: true, amount: frame['value']))
+        end
+        data['attacker'] = frame['player']
+      end
+
+      def on_damage(frame)
+        data['damage'][frame['player']] += frame['amount']
+        end_game(opponent(frame['player']), 'knockout') if data['damage'][frame['player']] >= KNOCKOUT
+      end
+
+      def end_game(winner, reason)
+        @game_state.apply_changes('status' => { 'game_over' => true, 'winner' => winner, 'end_reason' => reason })
+      end
+
+      def take(player, uid) = hand(player).delete_at(hand(player).index { |c| c['uid'] == uid })
+      def opponent(player)  = (players - [player]).first
+      def players           = @game_state.players
+      def hand(player)      = @game_state.player_state(player).hand
+    end
+  end
+end
+```
+
+The sequence for one exchange:
+
+1. The stack is empty, so `schedule_frames` pushes `attack` for Player 1.
+2. Player 1 attacks; `on_attack` pushes `block` for Player 2. It is not `auto`, so play stops for Player 2's decision.
+3. Player 2 takes the damage; `on_block` pushes an `auto` `damage` frame, which resolves at once.
+4. The stack is empty again, so `schedule_frames` pushes `attack` for Player 2.
+
+## Tips
+
+- **Stack order.** To have A happen before B, push B first, then A.
+- **Pick-N frames.** Put `pick: [min, max]` on the frame and return `frame['pick']` from `pick_range`.
+- **Say what the frame is for.** `turn_phase` can return `frame['type']`, and views should say why the player is deciding ("Player 1 attacks with Blade 5: block or take 5 damage").
+- **Cap runaway auto-frame loops in `halt_frames?`.** The decision limit (`max_decisions`) counts only decisions, so a loop of `auto` frames never reaches it. Count resolved frames and end the game past a limit the players never see.
+- **Bot rules** read `frame['type']` the same way `legal_moves` does.

data/docs/referee.md

@@ -0,0 +1,59 @@
+# Yes/no rulings with the referee
+
+Prefer encoding rules in Ruby: it is fast, deterministic and testable. Some conditions are awkward to encode, though, especially free-text card conditions in a game that is still changing ("If your opponent is ahead…", "If this is your first attack this turn…"). The referee is a second model that answers one yes/no question about such a condition.
+
+## How it works
+
+Run with `--referee <model>` (or set `PLAI_TESTR_REFEREE_MODEL`). The runner then has `@referee`, an `Agents::RefereeAgent`; without the option, `@referee` is `nil`.
+
+```ruby
+@referee.ruling(question: 'Is the condition on Ambush met?', facts: "...")
+# => { 'met' => true, 'why' => 'The opponent has 12 points and the player has 8.', 'fallback' => false }
+```
+
+The referee sees only the game's name, the question and the facts you pass, with thinking on and temperature 0.1. If it cannot produce a valid answer after retries, it returns `met: false` with `fallback: true`.
+
+Nothing calls the referee for you, and rulings are not added to reports automatically. Your runner asks, records and reports.
+
+## Example: a card with a free-text condition
+
+Cards in `rules.json` carry their condition as text:
+
+```json
+{ "name": "Ambush", "value": 2, "condition": "your opponent has more points than you", "bonus": 3, "copies": 2 }
+```
+
+When a card with a condition is played, the runner asks for a ruling and records it (`data` and `log` are runner helpers):
+
+```ruby
+def bonus_for(player, card)
+  return 0 unless card['condition']
+
+  ruling = ruling("Is this condition met for #{player}: #{card['condition']}?", view_text_for(player))
+  ruling['met'] ? card['bonus'] : 0
+end
+
+def ruling(question, facts)
+  result = if @referee
+             @referee.ruling(question: question, facts: facts)
+           else
+             { 'met' => false, 'why' => 'no referee: run with --referee to rule on conditions', 'fallback' => true }
+           end
+  (data['rulings'] ||= []) << result.merge('turn' => @game_state.turn + 1, 'question' => question)
+  log("Ruling: #{question} #{result['met'] ? 'Yes' : 'No'} (#{result['why']})")
+  result
+end
+
+def report_sections
+  rows = data.fetch('rulings', []).map { |r| "| #{r['turn']} | #{r['question']} | #{r['met'] ? 'yes' : 'no'} | #{r['why']}#{' (fallback)' if r['fallback']} |" }
+  ["## Rulings\n\n| Turn | Question | Met | Why |\n|---|---|---|---|\n#{rows.join("\n")}"]
+end
+```
+
+## Things to know
+
+- **Facts are everything.** The referee knows nothing about the game state except the facts string. Passing the deciding player's view (`view_text_for`) is a good default; add anything the question depends on.
+- **Botruns and `--mode bot` have no referee.** Decide the fallback on purpose (above: the condition is not met) and say so in the log, or give the bot its own Ruby check for the condition.
+- **Rulings break seed reproducibility.** The same seed can play differently when a ruling changes. Record every ruling, as above, so a report shows why.
+- **Rulings are slow.** Each is a model call with thinking on. Ask only when the condition actually matters (a card with a condition was played), never on every turn.
+- **Turn rulings into code.** When a condition comes up often and the designer agrees on what it means, encode it in Ruby and keep the referee for the rest.

data/lib/plai_testr/agents/ollama_client.rb

@@ -0,0 +1,177 @@
+module PlaiTestr
+  module Agents
+    class OllamaClient
+      READ_TIMEOUT       = 300
+      MAX_RETRIES        = 3
+      CONTEXT_WARN_RATIO = 0.9
+      SPINNER_FRAMES     = %w[⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏].freeze
+      UNREACHABLE        = [Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::EADDRNOTAVAIL, SocketError, Net::OpenTimeout].freeze
+
+      def initialize(host: PlaiTestr.config.ollama_host, port: PlaiTestr.config.ollama_port, think_log: nil, out: $stdout, verbose: false)
+        @host        = host
+        @port        = port
+        @think_log   = think_log
+        @out         = out
+        @verbose     = verbose
+        @frame_index = 0
+        @tty         = out.tty?
+      end
+
+      # `think`, `format` and `keep_alive` are top-level request fields in Ollama's /api/chat;
+      # only sampling/runtime settings belong in `options`. `format` may be "json" or a JSON schema.
+      def chat(model:, messages:, temperature: 0.7, think: nil, num_predict: nil, num_ctx: nil, format: nil, keep_alive: nil)
+        options = { temperature: temperature }
+        options[:num_predict] = num_predict unless num_predict.nil?
+        options[:num_ctx]     = num_ctx     unless num_ctx.nil?
+
+        payload = { model: model, messages: messages, stream: true, options: options }
+        payload[:think]      = think      unless think.nil?
+        payload[:format]     = format     unless format.nil?
+        payload[:keep_alive] = keep_alive unless keep_alive.nil?
+
+        response = post('/api/chat', payload)
+        used     = response['prompt_eval_count']
+        return response unless used && num_ctx && used >= num_ctx * CONTEXT_WARN_RATIO
+
+        File.open(@think_log, 'a') { |f| f.puts "[WARNING] context nearly full: #{used}/#{num_ctx} prompt tokens (model=#{model})\n---\n\n" } if @think_log
+        response.merge('context_full' => true)
+      end
+
+      def model_names
+        request(Net::HTTP::Get.new('/api/tags')) { |response| JSON.parse(response.body) }.fetch('models', []).map { |m| m['name'] }
+      end
+
+      def context_length(model)
+        info = request(json_post('/api/show', model: model)) { |response| JSON.parse(response.body) }.fetch('model_info', {})
+        info["#{info['general.architecture']}.context_length"]
+      end
+
+      def pull(model)
+        request(json_post('/api/pull', model: model, stream: true), read_timeout: nil) do |response|
+          each_line(response) do |data|
+            raise ModelError, "Pulling #{model} failed: #{data['error']}" if data['error']
+
+            @out.print "\r  Pulling #{model}: #{data['status']}#{" #{(100.0 * data['completed'] / data['total']).round}%" if data['total'].to_i.positive? && data['completed']}\e[K"
+          end
+        end
+        @out.puts
+      end
+
+      private
+
+      def json_post(path, payload)
+        Net::HTTP::Post.new(path, 'Content-Type' => 'application/json').tap { |r| r.body = JSON.generate(payload) }
+      end
+
+      def request(req, read_timeout: 10, &block)
+        http              = Net::HTTP.new(@host, @port)
+        http.open_timeout = 5
+        http.read_timeout = read_timeout
+        http.request(req) do |response|
+          raise ModelError, "Ollama API error #{response.code} for #{req.path}: #{response.read_body}" unless response.is_a?(Net::HTTPSuccess)
+
+          return block.call(response)
+        end
+      rescue *UNREACHABLE => e
+        raise ModelError, "Cannot reach Ollama at #{@host}:#{@port} (#{e.class}: #{e.message})"
+      end
+
+      def each_line(response)
+        buffer = +''
+        response.read_body do |chunk|
+          buffer << chunk
+          while (newline = buffer.index("\n"))
+            data = parse_line(buffer.slice!(0, newline + 1))
+            yield data if data
+          end
+        end
+        data = parse_line(buffer)
+        yield data if data
+      end
+
+      def parse_line(line)
+        JSON.parse(line) unless line.strip.empty?
+      rescue JSON::ParserError
+        nil
+      end
+
+      def post(path, payload)
+        attempts = 0
+        begin
+          attempts += 1
+          post_once(path, payload)
+        rescue Net::ReadTimeout, Errno::ECONNRESET, EOFError => e
+          clear_spinner
+          raise ModelError, "Ollama stopped responding (#{e.class}) after #{attempts} tries" if attempts >= MAX_RETRIES
+
+          wait = 2**attempts
+          warn "  [connection error: #{e.class} — retrying in #{wait}s]"
+          sleep wait
+          retry
+        end
+      end
+
+      def post_once(path, payload)
+        content     = +''
+        thinking    = +''
+        final_chunk = nil
+
+        request(json_post(path, payload), read_timeout: READ_TIMEOUT) do |response|
+          each_line(response) do |data|
+            piece = data.dig('message', 'content').to_s
+            content  << piece
+            thinking << data.dig('message', 'thinking').to_s
+            final_chunk = data if data['done']
+            @verbose ? @out.print(piece) : advance_spinner
+          end
+        end
+
+        clear_spinner
+        raise ModelError, 'Ollama API error: stream ended without a done chunk' unless final_chunk
+
+        @out.puts "\n  [#{format_stats(final_chunk).strip}]" if @verbose
+        write_think_log(payload[:model], thinking.empty? ? content : "<think>\n#{thinking.strip}\n</think>\n#{content}", final_chunk)
+        final_chunk.merge('message' => { 'role' => 'assistant', 'content' => content })
+      end
+
+      def write_think_log(model, content, stats = {})
+        return unless @think_log
+
+        File.open(@think_log, 'a') do |f|
+          f.puts "[#{Time.now.utc.iso8601}] model=#{model}#{format_stats(stats)}"
+          f.puts content
+          f.puts '---'
+          f.puts
+        end
+      end
+
+      def format_stats(stats)
+        nanos = 1_000_000_000.0
+        rate  = ->(count, duration) { count && duration.to_i.positive? ? (count / (duration / nanos)).round(1) : nil }
+        {
+          'prompt_tokens' => stats['prompt_eval_count'],
+          'prompt_tps'    => rate.call(stats['prompt_eval_count'], stats['prompt_eval_duration']),
+          'eval_tokens'   => stats['eval_count'],
+          'eval_tps'      => rate.call(stats['eval_count'], stats['eval_duration']),
+          'load_s'        => stats['load_duration'] && (stats['load_duration'] / nanos).round(2),
+          'total_s'       => stats['total_duration'] && (stats['total_duration'] / nanos).round(2)
+        }.filter_map { |key, value| " #{key}=#{value}" unless value.nil? }.join
+      end
+
+      def advance_spinner
+        return unless @tty
+
+        @out.print "\r  #{SPINNER_FRAMES[@frame_index % SPINNER_FRAMES.length]}"
+        @out.flush
+        @frame_index += 1
+      end
+
+      def clear_spinner
+        return unless @tty
+
+        @out.print "\r   \r"
+        @out.flush
+      end
+    end
+  end
+end