mock_openai 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a1f8417e225e11b9232ee5da333fcfc9e430f00f9e624a11c39b2edf19aecc5c
+  data.tar.gz: '03789f11bd18f2365e79d7059935aa36460bd7335d0709487143a8533c3003dc'
+SHA512:
+  metadata.gz: 83536158b83e6c698a5bf6f4024c43f7268f98252ac59817346533cf8e8ff13d89adfd1bf5fda3d4ab101dcec37f8ed3c4d6caf27cae1bc585de03fca5497e16
+  data.tar.gz: d6ad10f230b13b1fedc0c1f01cb24654b9ce5f0a957dbe8fe920a9290676ad41968b0e65819ef497ba688cb2eeeda198cef955dee72be1c1157cbab9f36cb1cb

data/README.md

@@ -0,0 +1,126 @@
+<p align="center">
+  <img src="docs/assets/img/mockopenai_logo_medium.png" alt="MockOpenAI logo" />
+</p>
+
+# MockOpenAI
+
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://grymoire7.github.io/mockopenai)
+![Tests](https://github.com/grymoire7/mockopenai/actions/workflows/ruby.yml/badge.svg?branch=main)
+![Ruby Version](https://img.shields.io/badge/Ruby-%3E%3D%203.0-green?logo=Ruby&logoColor=red&label=Ruby%20version&color=green)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/grymoire7/mockopenai/blob/main/LICENSE)
+
+A local mock server for OpenAI-compatible and Anthropic APIs with deterministic responses
+and per-request failure simulation for any Ruby application.
+
+MockOpenAI lets you test any Ruby app that calls an LLM **without hitting real
+APIs**, spending real money, or waiting on rate limits. It supports the OpenAI
+Chat Completions API (`POST /v1/chat/completions`) and the Anthropic Messages
+API (`POST /v1/messages`). Works with Rails, Sinatra, CLI tools, background
+jobs, or plain Ruby scripts.
+
+---
+
+## Why MockOpenAI?
+
+- **No API keys needed**: zero token costs, zero network calls in CI
+- **Deterministic**: control exactly what the LLM "says" for each request
+- **Per-request failure modes**: simulate timeouts, rate limits, malformed JSON, and more
+- **No app changes**: no monkey-patching, no client wrapping, no test doubles
+- **Fast CI**: tests run at local speed, not API speed
+- **OpenAI + Anthropic**: supports `POST /v1/chat/completions` and `POST /v1/messages`
+
+Not sure if MockOpenAI is right for your project? See [When not to use MockOpenAI](https://grymoire7.github.io/mockopenai/when-not-to-use/).
+
+---
+
+## Installation
+
+```ruby
+# Gemfile
+group :test do
+  gem "mock_openai"
+end
+```
+
+```
+bundle install
+```
+
+---
+
+## Quick Start
+
+**RSpec:**
+
+```ruby
+# spec/rails_helper.rb
+require "mock_openai/rspec"
+
+# If your code makes real HTTP connections to the LLM API (CLI tools,
+# integration tests, background jobs), start the server once here:
+MockOpenAI.start_test_server!
+
+RubyLLM.configure do |config|
+  config.anthropic_api_base = MockOpenAI.server_url
+end
+```
+
+```ruby
+it "returns a canned response", :mock_openai do
+  MockOpenAI.set_responses([{ match: "Hello", response: "Hi!" }])
+  expect(MyService.call_openai("Hello")).to eq("Hi!")
+end
+```
+
+The `:mock_openai` tag wires everything up and resets state between tests automatically. `start_test_server!` is idempotent and blocks until the server is ready.
+
+**Minitest:**
+
+```ruby
+# test/test_helper.rb
+require "mock_openai/minitest"
+
+# If your code makes real HTTP connections to the LLM API (CLI tools,
+# integration tests, background jobs), start the server once here:
+MockOpenAI.start_test_server!
+
+RubyLLM.configure do |config|
+  config.anthropic_api_base = MockOpenAI.server_url
+end
+```
+
+```ruby
+class MyChatTest < Minitest::Test
+  include MockOpenAI::Minitest
+
+  def test_returns_canned_response
+    MockOpenAI.set_responses([{ match: "Hello", response: "Hi!" }])
+    assert_equal "Hi!", MyService.call_openai("Hello")
+  end
+end
+```
+
+`MockOpenAI::Minitest` hooks into `before_setup` and `after_teardown` to reset state automatically. `start_test_server!` is idempotent and blocks until the server is ready.
+
+---
+
+## Documentation
+
+Full documentation is available at **[grymoire7.github.io/mockopenai](https://grymoire7.github.io/mockopenai)**:
+
+- [Getting Started](https://grymoire7.github.io/mockopenai/getting-started/): installation, setup, first test
+- [Usage](https://grymoire7.github.io/mockopenai/usage/): in-process vs. standalone server modes
+- [Examples](https://grymoire7.github.io/mockopenai/examples/): multi-step conversations, failure modes, templates
+- [Reference](https://grymoire7.github.io/mockopenai/reference/): full API, RSpec tags, CLI, and configuration
+
+---
+
+## Contributing
+
+PRs welcome. Open an issue to discuss new failure modes, matchers, or integrations.
+
+---
+
+## License
+
+MIT

data/bin/mock-openai

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/mock_openai"
+
+MockOpenAI::CLI.run(ARGV)

data/lib/mock_openai/anthropic_response_builder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module MockOpenAI
+  class AnthropicResponseBuilder
+    def self.build(content:, model: "mock-claude-3")
+      {
+        "id" => "mock-msg-#{SecureRandom.hex(8)}",
+        "type" => "message",
+        "role" => "assistant",
+        "content" => [{"type" => "text", "text" => content}],
+        "model" => model,
+        "stop_reason" => "end_turn",
+        "stop_sequence" => nil,
+        "usage" => {"input_tokens" => 0, "output_tokens" => 0}
+      }
+    end
+  end
+end

data/lib/mock_openai/cli.rb

@@ -0,0 +1,54 @@
+# lib/mock_openai/cli.rb
+# frozen_string_literal: true
+
+require "optparse"
+
+module MockOpenAI
+  class CLI
+    SAMPLE_CONFIG = <<~YAML
+      # MockOpenAI configuration
+      # port: 4000
+      # timeout_seconds: 5
+      # default_response: "Mock response from MockOpenAI"
+    YAML
+
+    def self.run(argv = ARGV)
+      command = argv.first
+      case command
+      when "start"
+        port = 4000
+        OptionParser.new do |opts|
+          opts.on("--port=PORT", Integer) { |p| port = p }
+        end.parse!(argv[1..])
+        Server.start(port: port)
+      when "init"
+        path = config_file_path
+        if File.exist?(path)
+          puts "mock_openai.yml already exists at #{path}"
+        else
+          File.write(path, SAMPLE_CONFIG)
+          puts "Created #{path}"
+        end
+      when "check"
+        cfg = MockOpenAI.config
+        puts "MockOpenAI configuration:"
+        puts "  port:             #{cfg.port}"
+        puts "  timeout_seconds:  #{cfg.timeout_seconds}"
+        puts "  default_response: #{cfg.default_response}"
+        puts "  state_file:       #{cfg.state_file}"
+      else
+        puts "Usage: mock-openai <command> [options]"
+        puts ""
+        puts "Commands:"
+        puts "  start [--port=N]   Start the mock server (default port: 4000)"
+        puts "  init               Create a sample mock_openai.yml"
+        puts "  check              Show resolved configuration"
+        exit(1)
+      end
+    end
+
+    def self.config_file_path
+      "mock_openai.yml"
+    end
+  end
+end

data/lib/mock_openai/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module MockOpenAI
+  class Config
+    DEFAULTS = {
+      "port" => 4000,
+      "timeout_seconds" => 5,
+      "default_response" => "Mock response from MockOpenAI",
+      "state_file" => "tmp/mock_openai_state.json"
+    }.freeze
+
+    attr_reader :port, :timeout_seconds, :default_response, :state_file
+
+    def self.load(path = "mock_openai.yml")
+      file_config = File.exist?(path) ? YAML.safe_load_file(path) || {} : {}
+      merged = DEFAULTS.merge(file_config.transform_keys(&:to_s))
+      new(**merged.transform_keys(&:to_sym))
+    end
+
+    def initialize(port: DEFAULTS["port"], timeout_seconds: DEFAULTS["timeout_seconds"],
+      default_response: DEFAULTS["default_response"], state_file: DEFAULTS["state_file"])
+      @port = port
+      @timeout_seconds = timeout_seconds
+      @default_response = default_response
+      @state_file = state_file
+    end
+  end
+end

data/lib/mock_openai/failure_modes/base.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module FailureModes
+    REGISTRY = {} # populated by each subclass on require
+
+    def self.apply(mode, request:, response:)
+      key = mode.to_s
+      klass = REGISTRY.fetch(key) { raise ArgumentError, "Unknown failure mode: #{mode}" }
+      klass.new.apply(request: request, response: response)
+    end
+
+    class Base
+      def apply(request:, response:)
+        raise NotImplementedError, "#{self.class} must implement #apply"
+      end
+    end
+  end
+end

data/lib/mock_openai/failure_modes/internal_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module FailureModes
+    class InternalError < Base
+      def apply(request:, response:)
+        body = {
+          "error" => {
+            "type" => "server_error",
+            "message" => "Internal server error"
+          }
+        }
+        [500, {"Content-Type" => "application/json"}, [body.to_json]]
+      end
+    end
+
+    REGISTRY["internal_error"] = InternalError
+  end
+end

data/lib/mock_openai/failure_modes/malformed_json.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module FailureModes
+    class MalformedJson < Base
+      def apply(request:, response:)
+        [200, {"Content-Type" => "application/json"}, ['{ "choices": [ ']]
+      end
+    end
+
+    REGISTRY["malformed_json"] = MalformedJson
+  end
+end

data/lib/mock_openai/failure_modes/rate_limit.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module FailureModes
+    class RateLimit < Base
+      def apply(request:, response:)
+        body = {
+          "error" => {
+            "type" => "rate_limit_error",
+            "message" => "Rate limit exceeded",
+            "code" => "rate_limit_exceeded"
+          }
+        }
+        [429, {"Content-Type" => "application/json"}, [body.to_json]]
+      end
+    end
+
+    REGISTRY["rate_limit"] = RateLimit
+  end
+end

data/lib/mock_openai/failure_modes/timeout.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module FailureModes
+    class Timeout < Base
+      def apply(request:, response:)
+        :timeout
+      end
+    end
+
+    REGISTRY["timeout"] = Timeout
+  end
+end

data/lib/mock_openai/failure_modes/truncated_stream.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module FailureModes
+    class TruncatedStream < Base
+      def apply(request:, response:)
+        :stream_truncated
+      end
+    end
+
+    REGISTRY["truncated_stream"] = TruncatedStream
+  end
+end

data/lib/mock_openai/handlers/base.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module Handlers
+    class Base
+      JSON_HEADERS = {"Content-Type" => "application/json"}.freeze
+
+      def json_headers
+        JSON_HEADERS.dup
+      end
+
+      def call(env)
+        request = Rack::Request.new(env)
+        parsed = parse_json_body(request.body.read)
+        return error_response(400, "invalid_request_error", "Request body must be valid JSON") unless parsed
+
+        request_context = parse_request(parsed)
+        state = State.read
+        rule = Matcher.match(state["rules"] || [], request_context[:last_user_message].to_s)
+
+        result = resolve_content(rule, state, request_context)
+        log_request(env, rule ? (state["rules"] || []).index(rule) : nil, rule&.dig("failure_mode"))
+        result
+      end
+
+      private
+
+      # Template methods — subclasses must implement all three
+
+      def parse_request(body)
+        raise NotImplementedError, "#{self.class} must implement #parse_request"
+      end
+
+      def build_success_response(content, model)
+        raise NotImplementedError, "#{self.class} must implement #build_success_response"
+      end
+
+      def apply_failure_mode(mode, request_context)
+        raise NotImplementedError, "#{self.class} must implement #apply_failure_mode"
+      end
+
+      protected
+
+      def extract_text_content(content)
+        if content.is_a?(Array)
+          content.select { |b| b["type"] == "text" }.map { |b| b["text"] }.join
+        else
+          content.to_s
+        end
+      end
+
+      private
+
+      def resolve_content(rule, state, request_context)
+        model = request_context[:model]
+
+        if rule
+          if rule["failure_mode"]
+            return apply_failure_mode(rule["failure_mode"], request_context)
+          elsif rule["response"]
+            return build_success_response(rule["response"], model)
+          elsif rule["template"]
+            return build_success_response(
+              TemplateRenderer.render(rule["template"], request_context), model
+            )
+          end
+        end
+
+        if state["response_template"]
+          return build_success_response(
+            TemplateRenderer.render(state["response_template"], request_context), model
+          )
+        end
+
+        fallback = state["default_response"] || MockOpenAI.config.default_response
+        build_success_response(fallback, model)
+      end
+
+      def parse_json_body(body)
+        JSON.parse(body)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def error_response(status, type, message)
+        body = {"error" => {"type" => type, "message" => message}}
+        [status, json_headers, [body.to_json]]
+      end
+
+      def log_request(env, rule_index, failure_mode)
+        return unless MockOpenAI.verbose?
+        method = env["REQUEST_METHOD"]
+        path = env["PATH_INFO"]
+        rule_label = rule_index.nil? ? "none" : rule_index.to_s
+        mode_label = failure_mode.nil? ? "none" : failure_mode.to_s
+        puts "[MockOpenAI] #{method} #{path} | rule=#{rule_label} | mode=#{mode_label}"
+      end
+    end
+  end
+end

data/lib/mock_openai/handlers/chat_completions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module Handlers
+    class ChatCompletions < Base
+      private
+
+      def parse_request(body)
+        messages = body["messages"] || []
+        last_user = messages.reverse.find { |m| m["role"] == "user" }
+        system_msg = messages.find { |m| m["role"] == "system" }
+        {
+          last_user_message: extract_text_content(last_user&.dig("content")),
+          system_message: extract_text_content(system_msg&.dig("content")),
+          model: body["model"] || "mock-gpt-4"
+        }
+      end
+
+      def build_success_response(content, model)
+        response = ResponseBuilder.build(content: content, model: model)
+        [200, json_headers, [response.to_json]]
+      end
+
+      def apply_failure_mode(mode, request_context)
+        result = FailureModes.apply(mode, request: {}, response: {})
+        return handle_symbol_result(result) if result.is_a?(Symbol)
+        result
+      end
+
+      def handle_symbol_result(symbol)
+        case symbol
+        when :timeout
+          sleep(MockOpenAI.config.timeout_seconds)
+          [200, json_headers, [{"choices" => []}.to_json]]
+        when :stream_truncated
+          chunks = [
+            "data: {\"choices\":[{\"delta\":{\"content\":\"Hello\"}}]}\n\n",
+            "data: {\"choices\":[{\"delta\":{\"content\":\" world\"}}]}\n\n"
+          ]
+          [200, {"Content-Type" => "text/event-stream"}, chunks]
+        end
+      end
+    end
+  end
+end

data/lib/mock_openai/handlers/messages.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  module Handlers
+    class Messages < Base
+      private
+
+      def parse_request(body)
+        messages = body["messages"] || []
+        last_user = messages.reverse.find { |m| m["role"] == "user" }
+        {
+          last_user_message: extract_text_content(last_user&.dig("content")),
+          system_message: body["system"].to_s,
+          model: body["model"] || "mock-claude-3"
+        }
+      end
+
+      def build_success_response(content, model)
+        response = AnthropicResponseBuilder.build(content: content, model: model)
+        [200, json_headers, [response.to_json]]
+      end
+
+      def apply_failure_mode(mode, request_context)
+        result = FailureModes.apply(mode, request: {}, response: {})
+        return handle_symbol_result(result, request_context) if result.is_a?(Symbol)
+        result
+      end
+
+      def handle_symbol_result(symbol, request_context)
+        case symbol
+        when :timeout
+          sleep(MockOpenAI.config.timeout_seconds)
+          error_body = {"type" => "error", "error" => {"type" => "overloaded_error", "message" => "Overloaded"}}
+          [200, json_headers, [error_body.to_json]]
+        when :stream_truncated
+          chunks = [
+            "data: {\"type\":\"content_block_delta\",\"delta\":{\"type\":\"text_delta\",\"text\":\"Hello\"}}\n\n",
+            "data: {\"type\":\"content_block_delta\",\"delta\":{\"type\":\"text_delta\",\"text\":\" world\"}}\n\n"
+          ]
+          [200, {"Content-Type" => "text/event-stream"}, chunks]
+        end
+      end
+    end
+  end
+end

data/lib/mock_openai/matcher.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  class Matcher
+    def self.match(rules, last_user_message)
+      rules.each do |rule|
+        return rule if matches?(rule["match"], last_user_message)
+      end
+      nil
+    end
+
+    def self.matches?(pattern, text)
+      return false if pattern.nil?
+
+      # 1. Try regex match if pattern looks like a regex
+      if regex_like?(pattern)
+        begin
+          return true if Regexp.new(pattern).match?(text)
+        rescue RegexpError
+          puts "[MockOpenAI] Warning: invalid regex '#{pattern}', falling back to substring match"
+          # Fall through to substring match
+        end
+      end
+
+      # 2. Exact match
+      return true if pattern == text
+
+      # 3. Substring match
+      text.include?(pattern)
+    end
+
+    def self.regex_like?(pattern)
+      pattern.start_with?("^") ||
+        pattern.end_with?("$") ||
+        pattern.include?(".*") ||
+        pattern.include?("(") ||
+        pattern.include?("[")
+    end
+  end
+end

data/lib/mock_openai/minitest.rb

@@ -0,0 +1,18 @@
+# lib/mock_openai/minitest.rb
+# frozen_string_literal: true
+
+require "mock_openai"
+
+module MockOpenAI
+  module Minitest
+    def before_setup
+      super
+      MockOpenAI.reset!
+    end
+
+    def after_teardown
+      MockOpenAI.reset!
+      super
+    end
+  end
+end

data/lib/mock_openai/response_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module MockOpenAI
+  class ResponseBuilder
+    def self.build(content:, model: "mock-gpt-4")
+      {
+        "id" => "mock-chatcmpl-#{SecureRandom.hex(8)}",
+        "object" => "chat.completion",
+        "created" => Time.now.to_i,
+        "model" => model,
+        "choices" => [
+          {
+            "index" => 0,
+            "message" => {"role" => "assistant", "content" => content},
+            "finish_reason" => "stop"
+          }
+        ],
+        "usage" => {"prompt_tokens" => 0, "completion_tokens" => 0, "total_tokens" => 0}
+      }
+    end
+  end
+end

data/lib/mock_openai/router.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  class Router
+    NOT_FOUND_BODY = {
+      "error" => {"type" => "invalid_request_error", "message" => "Not found"}
+    }.to_json.freeze
+
+    def call(env)
+      request = Rack::Request.new(env)
+
+      case [request.request_method, request.path_info]
+      in ["POST", "/v1/chat/completions"]
+        Handlers::ChatCompletions.new.call(env)
+      in ["POST", "/v1/messages"]
+        Handlers::Messages.new.call(env)
+      else
+        [404, {"Content-Type" => "application/json"}, [NOT_FOUND_BODY]]
+      end
+    end
+  end
+end

data/lib/mock_openai/rspec/metadata.rb

@@ -0,0 +1,38 @@
+# lib/mock_openai/rspec/metadata.rb
+# frozen_string_literal: true
+
+module MockOpenAI
+  module RSpec
+    module Metadata
+      FAILURE_MODE_TAGS = {
+        mock_openai_timeout: :timeout,
+        mock_openai_rate_limit: :rate_limit,
+        mock_openai_malformed_json: :malformed_json,
+        mock_openai_internal_error: :internal_error,
+        mock_openai_truncated_stream: :truncated_stream
+      }.freeze
+    end
+  end
+end
+
+::RSpec.configure do |config|
+  # Generic tag: reset state before test
+  config.before(:each, :mock_openai) do
+    MockOpenAI.reset!
+  end
+
+  # Shortcut failure mode tags: reset then set mode
+  MockOpenAI::RSpec::Metadata::FAILURE_MODE_TAGS.each do |tag, mode|
+    config.before(:each, tag) do
+      MockOpenAI.reset!
+      MockOpenAI.set_failure_mode(mode)
+    end
+  end
+
+  # Reset after any mock_openai-tagged test
+  config.after(:each) do |example|
+    if example.metadata.keys.any? { |k| k.to_s.start_with?("mock_openai") }
+      MockOpenAI.reset!
+    end
+  end
+end

data/lib/mock_openai/rspec.rb

@@ -0,0 +1,5 @@
+# lib/mock_openai/rspec.rb
+# frozen_string_literal: true
+
+require "mock_openai"
+require "mock_openai/rspec/metadata"

data/lib/mock_openai/server.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "logger"
+require "socket"
+
+module MockOpenAI
+  class Server
+    def self.start(port: MockOpenAI.config.port)
+      state_file = MockOpenAI.config.state_file
+      FileUtils.mkdir_p(File.dirname(state_file))
+      State.reset! unless File.exist?(state_file)
+
+      if MockOpenAI.verbose?
+        puts "MockOpenAI v#{VERSION} started"
+        puts "  Listening on: http://localhost:#{port}"
+        puts "  State file:   #{state_file}"
+
+        config_status = File.exist?("mock_openai.yml") ? "mock_openai.yml" : "mock_openai.yml (not found, using defaults)"
+        puts "  Config:       #{config_status}"
+      end
+
+      run_rack_server(port: port)
+    end
+
+    def self.run_rack_server(port: MockOpenAI.config.port)
+      require "rackup"
+      logger = MockOpenAI.verbose? ? Logger.new($stdout) : Logger.new(IO::NULL)
+      Rackup::Server.start(
+        app: Router.new,
+        Port: port,
+        Host: "127.0.0.1",
+        server: :webrick,
+        Logger: logger,
+        AccessLog: []
+      )
+    end
+
+    def self.wait_until_ready(timeout: 5)
+      deadline = Time.now + timeout
+      loop do
+        TCPSocket.new("127.0.0.1", MockOpenAI.config.port).close
+        return
+      rescue Errno::ECONNREFUSED
+        raise "MockOpenAI server did not start within #{timeout}s" if Time.now > deadline
+        sleep 0.05
+      end
+    end
+  end
+end

data/lib/mock_openai/state.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+
+module MockOpenAI
+  class State
+    EMPTY = {
+      "rules" => [],
+      "response_template" => nil,
+      "default_response" => nil,
+      "metadata" => {}
+    }.freeze
+
+    def self.state_file
+      MockOpenAI.config.state_file
+    end
+
+    def self.write(rules:, response_template: nil, default_response: nil)
+      FileUtils.mkdir_p(File.dirname(state_file))
+      File.write(state_file, {
+        "rules" => rules,
+        "response_template" => response_template,
+        "default_response" => default_response,
+        "metadata" => {}
+      }.to_json)
+    end
+
+    def self.read
+      return EMPTY unless File.exist?(state_file)
+
+      JSON.parse(File.read(state_file))
+    rescue JSON::ParserError
+      puts "[MockOpenAI] Warning: state file is corrupt, using empty state"
+      EMPTY
+    end
+
+    def self.reset!
+      FileUtils.mkdir_p(File.dirname(state_file))
+      File.write(state_file, EMPTY.to_json)
+    end
+  end
+end

data/lib/mock_openai/template_renderer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  class TemplateRenderer
+    VARIABLES = {
+      "{{last_user_message}}" => ->(ctx) { ctx[:last_user_message].to_s },
+      "{{system_message}}" => ->(ctx) { ctx[:system_message].to_s },
+      "{{model}}" => ->(ctx) { ctx[:model].to_s }
+    }.freeze
+
+    def self.render(template, context)
+      VARIABLES.reduce(template) do |result, (placeholder, extractor)|
+        result.gsub(placeholder, extractor.call(context))
+      end
+    end
+  end
+end

data/lib/mock_openai/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module MockOpenAI
+  VERSION = "0.1.0"
+end

data/lib/mock_openai.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require_relative "mock_openai/version"
+require_relative "mock_openai/config"
+require_relative "mock_openai/state"
+require_relative "mock_openai/matcher"
+require_relative "mock_openai/response_builder"
+require_relative "mock_openai/anthropic_response_builder"
+require_relative "mock_openai/template_renderer"
+require_relative "mock_openai/failure_modes/base"
+require_relative "mock_openai/failure_modes/timeout"
+require_relative "mock_openai/failure_modes/rate_limit"
+require_relative "mock_openai/failure_modes/malformed_json"
+require_relative "mock_openai/failure_modes/internal_error"
+require_relative "mock_openai/failure_modes/truncated_stream"
+require_relative "mock_openai/handlers/base"
+require_relative "mock_openai/handlers/chat_completions"
+require_relative "mock_openai/handlers/messages"
+require_relative "mock_openai/router"
+require_relative "mock_openai/server"
+require_relative "mock_openai/cli"
+
+module MockOpenAI
+  @verbose = true
+
+  class << self
+    def config
+      @config ||= Config.load
+    end
+
+    def verbose?
+      @verbose
+    end
+
+    def start_test_server!
+      return if server_reachable?
+      @verbose = false
+      Thread.new { Server.start }
+      Server.wait_until_ready
+    end
+
+    def server_url
+      "http://127.0.0.1:#{config.port}"
+    end
+
+    def set_responses(rules)
+      State.write(rules: rules.map { |r| r.transform_keys(&:to_s) })
+    end
+
+    def set_failure_mode(mode)
+      set_responses([{"match" => ".*", "failure_mode" => mode.to_s}])
+    end
+
+    def reset!
+      State.reset!
+    end
+
+    def current_failure_mode
+      state = State.read
+      catch_all = state["rules"].find { |r| r["match"] == ".*" && r["failure_mode"] }
+      catch_all&.dig("failure_mode")&.to_sym
+    end
+
+    private
+
+    def server_reachable?
+      TCPSocket.new("127.0.0.1", config.port).close
+      true
+    rescue Errno::ECONNREFUSED
+      false
+    end
+  end
+end

metadata

@@ -0,0 +1,165 @@
+--- !ruby/object:Gem::Specification
+name: mock_openai
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tracy Atteberry
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rackup
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rack-test
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: standard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Drop-in mock server for testing Rails apps that use OpenAI-compatible
+  APIs. Provides deterministic responses and per-request failure simulation.
+executables:
+- mock-openai
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/mock-openai
+- lib/mock_openai.rb
+- lib/mock_openai/anthropic_response_builder.rb
+- lib/mock_openai/cli.rb
+- lib/mock_openai/config.rb
+- lib/mock_openai/failure_modes/base.rb
+- lib/mock_openai/failure_modes/internal_error.rb
+- lib/mock_openai/failure_modes/malformed_json.rb
+- lib/mock_openai/failure_modes/rate_limit.rb
+- lib/mock_openai/failure_modes/timeout.rb
+- lib/mock_openai/failure_modes/truncated_stream.rb
+- lib/mock_openai/handlers/base.rb
+- lib/mock_openai/handlers/chat_completions.rb
+- lib/mock_openai/handlers/messages.rb
+- lib/mock_openai/matcher.rb
+- lib/mock_openai/minitest.rb
+- lib/mock_openai/response_builder.rb
+- lib/mock_openai/router.rb
+- lib/mock_openai/rspec.rb
+- lib/mock_openai/rspec/metadata.rb
+- lib/mock_openai/server.rb
+- lib/mock_openai/state.rb
+- lib/mock_openai/template_renderer.rb
+- lib/mock_openai/version.rb
+homepage: https://github.com/grymoire7/mockopenai
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://grymoire7.github.io/mockopenai
+  homepage_uri: https://github.com/grymoire7/mockopenai
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.4
+specification_version: 4
+summary: A local mock server for OpenAI-compatible APIs
+test_files: []