ruby-skill-bench 0.1.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 58713d379ef4db5ce99a695309440159115257fee5b995ed6c6b8f1cbdca13b7
-  data.tar.gz: 52cab6f8913582728c66fa1d34d3109958c5c5c33bbf9ffd5969f5b5cb13908e
+  metadata.gz: d2ad524e13bc006a56f0197d07b3ba7b0ce2f99f60b61f0739c3d5bc0d75a687
+  data.tar.gz: a920c473148b52584653acbb1e91cb3973791c09de6c4df994a77c097eabc476
 SHA512:
-  metadata.gz: 74cc26703d9cb9da5362ed0450987e02af86847025c7c687d6519b191f921a300bce66a166a5596a956bedb7c6b52c45cc29a003bf3f93df8e491565608ca9af
-  data.tar.gz: 1dce2943558b3c0672be0950905e140892546928f0ddb89ddcd5b6457d99e9b562915f77239e3ab71d290737ed1705977f5f4abfc4f5eed505ec9783fa28d46f
+  metadata.gz: c1f131af9bcde90e7fc3a7e6bef7f3770edfa4e2826ee19c3aabf5c210d6d3b6e5bdd460778a87f6fdc77b5b99bc17b2225e1b79de31674ad4acfe1bbc89f862
+  data.tar.gz: d8e3791c91242b25779afa3a21c57daeb06995bc4c65b01ca6f378a69491aeec95c5844ea541e5dcaf18b46d8e7f153ffb38ff2bb060ab5dacd653c8c1026bcd

data/README.md

@@ -7,6 +7,21 @@
 
 *A high-fidelity evaluation engine for benchmarking AI agent skills across any stack (Rails-first, but extensible).*
 
+## Part of the AI Skill Ecosystem
+
+This repo is one of 6 in a composable AI skill ecosystem:
+
+| Repo | Role |
+|------|------|
+| [`ruby-core-skills`](https://github.com/igmarin/ruby-core-skills) | 15 shared Ruby skills + process discipline |
+| [`rails-agent-skills`](https://github.com/igmarin/rails-agent-skills) | 28 Rails-specific skills + 9 agents |
+| [`hanakai-yaku`](https://github.com/igmarin/hanakai-yaku) | 35 Hanami/dry-rb skills + 10 agents |
+| [`agnostic-planning-skills`](https://github.com/igmarin/agnostic-planning-skills) | 10 planning skills + 4 agents |
+| [`agent-mcp-runtime`](https://github.com/igmarin/agent-mcp-runtime) | Rust CLI runtime (pack resolution, MCP) |
+| [**`ruby-skill-bench`**](https://github.com/igmarin/ruby-skill-bench) | Benchmark/eval engine |
+
+See the [Ecosystem Overview](https://github.com/igmarin/agent-mcp-runtime/blob/main/docs/ecosystem.md) for the full architecture.
+
 ---
 
 ## Features
@@ -343,6 +358,77 @@ Both skill contexts are concatenated and sent to the agent. The judge evaluates
 
 ---
 
+## Multi-Repo Skill Benchmarking
+
+Skills in the ecosystem are split across multiple repos:
+- `ruby-core-skills` — 15 shared Ruby skills (DDD, patterns, process discipline)
+- `rails-agent-skills` — 28 Rails-specific skills
+- `hanakai-yaku` — 35 Hanami/dry-rb skills
+
+To benchmark a skill from an external repo, use the `--skill` flag:
+
+```bash
+# Benchmark a core skill
+skill-bench run evals/skills/write-yard-docs/basic \
+  --skill /path/to/ruby-core-skills/skills/patterns/write-yard-docs
+
+# Benchmark a Rails skill
+skill-bench run evals/skills/code-review/pr-review \
+  --skill /path/to/rails-agent-skills/skills/code-quality/code-review
+```
+
+### Config-Based Multi-Repo Resolution
+
+Configure `skill_sources` in `skill-bench.json` to automatically resolve skills across repos without `--skill` every time:
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-4o",
+  "skill_sources": {
+    "core": "../ruby-core-skills/skills",
+    "rails": "../rails-agent-skills/skills",
+    "hanami": "../hanakai-yaku/skills"
+  }
+}
+```
+
+Each key is a source name (for logging), each value is a path to a `skills/` directory. When a skill is not found locally, SkillBench iterates through `skill_sources` and uses the first match.
+
+### Pack-Based Resolution (`--pack`)
+
+Resolve skills via the ecosystem registry manifest (from `agent-mcp-runtime`):
+
+```bash
+# Run an eval using the Rails pack's version of code-review
+skill-bench run evals/skills/code-review/basic \
+  --skill code-review \
+  --pack rails
+
+# Override the default registry manifest path
+skill-bench run evals/skills/code-review/basic \
+  --skill code-review \
+  --pack rails \
+  --registry-manifest /path/to/registry.json
+```
+
+### Variant Comparison (`compare`)
+
+Compare the same skill across two pack variants to measure context-dependent performance:
+
+```bash
+skill-bench compare code-review \
+  --variant-a "pack:rails" \
+  --variant-b "pack:hanami" \
+  --eval evals/skills/code-review/basic
+```
+
+The `--variant` spec supports two forms:
+- `pack:<name>` — resolve via registry manifest
+- `/absolute/path` or `relative/path` — use a direct path
+
+---
+
 ## File Reference: What Lives on Disk
 
 SkillBench creates and manages three files in your project. Understanding them helps you iterate faster.
@@ -773,6 +859,151 @@ bundle exec ruby -Itest test/integration_test.rb
 - `test/agent_eval/` — CLI, models, and service tests
 - `test/clients/` — Provider client tests
 
+---
+
+## Security
+
+### Threat Model
+
+Ruby Skill Bench is designed with security as a primary concern. The system executes AI agents in isolated environments and must protect against various attack vectors:
+
+- **Path Traversal:** Preventing agents from accessing files outside the sandbox
+- **Command Injection:** Preventing execution of arbitrary shell commands
+- **Resource Exhaustion:** Preventing denial-of-service through resource consumption
+- **Information Leakage:** Protecting sensitive data like API keys
+
+### Security Features
+
+#### Path Traversal Protection
+
+- **Symlink Validation:** All symlinks are validated to ensure they don't escape the sandbox
+- **TOCTOU Mitigation:** Path validation is re-checked after directory creation operations
+- **Path Normalization:** All paths are normalized and validated against working directory boundaries
+- **Character Validation:** Paths are validated against strict character patterns
+
+#### Command Execution Security
+
+- **Command Allowlist:** Only explicitly allowed commands can be executed
+- **Dangerous Commands Blocklist:** Dangerous commands (bash, curl, sudo, etc.) are always blocked
+- **Shell Tokenization:** Commands are tokenized before execution to prevent shell injection
+- **Docker Isolation:** Commands can be executed in isolated Docker containers with hardened security settings
+
+#### Docker Security Hardening
+
+When Docker is available, containers are launched with hardened security settings:
+
+- **Non-root User:** Containers run as a non-root user
+- **Privilege Prevention:** `--security-opt no-new-privileges` prevents privilege escalation
+- **Capability Dropping:** All Linux capabilities are dropped except minimal needed ones
+- **Network Isolation:** `--network none` disables network access
+- **Read-only Root:** Container filesystem is read-only (except for mounted volumes)
+
+#### Resource Limits
+
+- **File Size Limits:** Individual files in context hydration are limited to 50KB
+- **Total Context Size:** Total context size is limited to 1MB to prevent memory exhaustion
+- **Execution Timeout:** Commands are limited to a configurable timeout (default: 30 seconds)
+- **Max Iterations:** Agent loops are limited to prevent infinite loops
+
+### API Key Security
+
+- **Environment Variables:** API keys are loaded from environment variables, not hardcoded
+- **Configuration Hierarchy:** Keys can be set in `skill-bench.json` or environment variables
+- **No Logging:** API keys are never logged or exposed in error messages
+- **Provider-Specific Keys:** Each provider uses its own API key configuration
+
+### Best Practices for Users
+
+1. **Never Commit API Keys:** Never commit `skill-bench.json` with API keys to version control
+2. **Use Environment Variables:** Prefer environment variables for sensitive configuration
+3. **Minimal Command Allowlist:** Only allow commands necessary for your evals
+4. **Regular Updates:** Keep dependencies updated to patch security vulnerabilities
+5. **Review Changes:** Review skill files before execution to ensure they don't contain malicious code
+
+### Reporting Security Issues
+
+If you discover a security vulnerability:
+
+1. **Do Not Open a Public Issue:** Send a private email to the maintainers
+2. **Provide Details:** Include steps to reproduce and potential impact
+3. **Allow Time for Fix:** Give maintainers time to address the issue before disclosure
+4. **Follow Responsible Disclosure:** Follow responsible disclosure practices
+
+---
+
+## Troubleshooting
+
+### Common Issues and Solutions
+
+#### Configuration Issues
+
+**Problem:** "Config load failed, using mock provider"
+- **Solution:** Ensure your `skill-bench.json` file is properly formatted JSON and contains required fields
+- **Check:** Verify the file exists in your project root or home directory
+
+**Problem:** "API Key not set for [Provider]"
+- **Solution:** Set the appropriate environment variable (e.g., `SKILL_BENCH_OPENAI_API_KEY`) or add it to your `skill-bench.json`
+- **Check:** Run `env | grep SKILL_BENCH` to verify environment variables are set
+
+**Problem:** "No allowed commands configured"
+- **Solution:** Add `allowed_commands` array to your `skill-bench.json` with the commands you want to allow
+- **Check:** Ensure commands are in the allowlist and not in the dangerous commands list
+
+#### Execution Issues
+
+**Problem:** "Command execution timed out"
+- **Solution:** Increase `max_execution_time` in your `skill-bench.json` or simplify the task
+- **Check:** Verify the command isn't hanging or waiting for input
+
+**Problem:** "Docker container failed to start"
+- **Solution:** Ensure Docker is running and you have permissions to run Docker commands
+- **Check:** Run `docker info` to verify Docker daemon is accessible
+
+**Problem:** "Context hydration failed"
+- **Solution:** Verify the source path exists and is a directory
+- **Check:** Ensure the path is within the base directory and file sizes are under limits
+
+#### Network Issues
+
+**Problem:** "Network Error: Connection refused"
+- **Solution:** Check your internet connection and API provider status
+- **Check:** Verify the base URL in your configuration is correct
+
+**Problem:** "API Request failed: 429"
+- **Solution:** This is a rate limit error. The system will retry automatically
+- **Check:** Reduce request frequency or check your API quota
+
+#### Test Failures
+
+**Problem:** Tests fail with "WebMock::NetConnectNotAllowedError"
+- **Solution:** This occurs when tests try to make real HTTP requests. Ensure test stubs are properly configured
+- **Check:** Verify WebMock is properly stubbing the expected URLs
+
+**Problem:** "E2E sibling repositories not present"
+- **Solution:** This is expected if you don't have the agent-mcp-runtime repository cloned
+- **Check:** These tests will be skipped and won't affect the overall test results
+
+### Debug Mode
+
+For detailed debugging, you can enable verbose logging:
+
+```bash
+# Set environment variable for verbose logging
+export SKILL_BENCH_DEBUG=true
+skill-bench run my-eval --skill=my-skill
+```
+
+### Getting Help
+
+If you encounter issues not covered here:
+
+1. Check the [GitHub Issues](https://github.com/igmarin/ruby-skill-bench/issues) for similar problems
+2. Create a new issue with detailed information about your environment and the problem
+3. Include Ruby version, SkillBench version, and error messages
+4. Provide steps to reproduce the issue
+
+---
+
 ## CI/CD Integration
 
 GitHub Actions workflow included (`.github/workflows/ci.yml`):

data/lib/skill_bench/agent/react_agent.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../constants'
 require_relative 'react_agent/step'
 require_relative 'react_agent/loop_runner'
 
@@ -29,7 +30,7 @@ module SkillBench
       def initialize(params)
         @system_prompt = params[:system_prompt]
         @initial_prompt = params[:initial_prompt]
-        @max_iterations = params[:max_iterations] || 25
+        @max_iterations = params[:max_iterations] || Constants::ReactAgent::DEFAULT_MAX_ITERATIONS
         @working_dir = params[:working_dir] || Dir.pwd
         @container_id = params[:container_id]
         @client_params = params[:client_params] || {}

data/lib/skill_bench/cli/compare_command.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../services/compare_option_parser'
+require_relative '../services/variant_parser'
+require_relative '../services/comparison_runner'
+require_relative '../services/comparison_reporter'
+require_relative '../services/exit_code_calculator'
+
+module SkillBench
+  module Cli
+    # Handles the `skill-bench compare` command.
+    # Runs the same eval with two skill variants and reports the comparison.
+    class CompareCommand
+      # Parses argv and executes the comparison.
+      #
+      # @param argv [Array<String>] Raw CLI arguments
+      # @return [Integer] Exit code
+      def self.call(argv)
+        new(argv).call
+      end
+
+      # @param argv [Array<String>] Raw CLI arguments
+      def initialize(argv)
+        @argv = argv
+      end
+
+      # Parses options, runs both variants, and prints a comparison report.
+      #
+      # @return [Integer] Exit code (0 if both pass, 1 otherwise)
+      def call
+        options = Services::CompareOptionParser.call(@argv)
+
+        skill_name = @argv.shift
+        return error_missing_skill unless skill_name
+        return error_missing_variant_a unless options[:variant_a]
+        return error_missing_variant_b unless options[:variant_b]
+        return error_missing_eval unless options[:eval]
+
+        variant_a = Services::VariantParser.call(options[:variant_a])
+        variant_b = Services::VariantParser.call(options[:variant_b])
+
+        puts "--- Running Variant A: #{options[:variant_a]} ---"
+        puts "--- Running Variant B: #{options[:variant_b]} ---"
+
+        results = Services::ComparisonRunner.call(
+          variant_a,
+          variant_b,
+          skill_name,
+          options[:eval]
+        )
+
+        Services::ComparisonReporter.call(
+          results[:result_a],
+          results[:result_b],
+          options[:variant_a],
+          options[:variant_b]
+        )
+
+        Services::ExitCodeCalculator.call(results[:result_a], results[:result_b])
+      rescue SkillBench::HelpRequested
+        0
+      rescue StandardError => e
+        warn "Error: #{e.message}"
+        1
+      end
+
+      private
+
+      def error_missing_skill
+        warn 'Error: skill name is required'
+        warn 'Usage: skill-bench compare <skill-name> --variant-a <spec> --variant-b <spec> --eval <path>'
+        1
+      end
+
+      def error_missing_variant_a
+        warn 'Error: --variant-a is required'
+        1
+      end
+
+      def error_missing_variant_b
+        warn 'Error: --variant-b is required'
+        1
+      end
+
+      def error_missing_eval
+        warn 'Error: --eval is required'
+        1
+      end
+    end
+  end
+end

data/lib/skill_bench/cli/help_printer.rb

@@ -19,11 +19,19 @@ module SkillBench
               Providers: #{providers}
               --force    Overwrite existing config file
 
-            run <eval> --skill <name> [--skill <name>] [--format FORMAT]
+            run <eval> --skill <name> [--skill <name>] [--format FORMAT] [--pack NAME]
               Run an evaluation
               --skill    Skill to use (can be specified multiple times)
+              --pack     Pack context for registry-based skill resolution
+              --registry-manifest PATH  Path to registry.json manifest
               --format   Output format: human, json, junit (default: human)
 
+            compare <skill-name> --variant-a SPEC --variant-b SPEC --eval PATH
+              Compare the same skill across two pack variants
+              --variant-a  First variant (e.g., "pack:rails" or "/path/to/skill")
+              --variant-b  Second variant (e.g., "pack:hanami")
+              --eval       Path to the eval directory
+
             skill new <name> [--mode MODE] [--template TYPE]
               Create a new skill
               --mode     simple, advanced, or rails (default: simple)

data/lib/skill_bench/cli/run_command.rb

@@ -29,7 +29,7 @@ module SkillBench
 
         eval_name = @argv.shift
         return error_missing_eval unless eval_name
-        return error_missing_skill if options[:skill_names].empty?
+        return error_missing_skill if options[:skill_names].empty? && !options[:pack]
 
         options[:eval_name] = eval_name
         exec_options = options.reject { |key| key == :format }
@@ -48,6 +48,8 @@ module SkillBench
         OptionParser.new do |opts|
           opts.banner = 'Usage: skill-bench run <eval> [options]'
           opts.on('--skill NAME', 'Skill to use (can be specified multiple times)') { |v| options[:skill_names] << v }
+          opts.on('--pack NAME', 'Pack context for skill resolution') { |v| options[:pack] = v }
+          opts.on('--registry-manifest PATH', 'Path to registry.json manifest') { |v| options[:registry_manifest] = v }
           opts.on('--format FORMAT', 'Output format (human, json, junit)') { |v| options[:format] = v.to_sym }
           opts.on('-h', '--help', 'Prints this help') do
             puts opts
@@ -58,13 +60,13 @@ module SkillBench
 
       def error_missing_eval
         warn 'Error: eval name is required'
-        warn 'Usage: skill-bench run <eval> --skill <name>'
+        warn 'Usage: skill-bench run <eval> [--skill <name>] [--pack <name>]'
         1
       end
 
       def error_missing_skill
-        warn 'Error: skill name is required'
-        warn 'Usage: skill-bench run <eval> --skill <name>'
+        warn 'Error: skill name or pack is required'
+        warn 'Usage: skill-bench run <eval> --skill <name> [--pack <name>]'
         1
       end
     end

data/lib/skill_bench/cli.rb

@@ -2,6 +2,7 @@
 
 require_relative 'cli/init_command'
 require_relative 'cli/run_command'
+require_relative 'cli/compare_command'
 require_relative 'cli/skill_command'
 require_relative 'cli/eval_command'
 require_relative 'cli/help_printer'
@@ -18,6 +19,7 @@ module SkillBench
     # @param argv [Array<String>] Raw CLI arguments.
     # @return [Integer] Exit code.
     def self.call(argv)
+      Config.reset
       new(argv).call
     end
 
@@ -35,10 +37,11 @@ module SkillBench
 
       subcommand = @argv.shift
       case subcommand
-      when 'init'  then Cli::InitCommand.call(@argv)
-      when 'run'   then Cli::RunCommand.call(@argv)
-      when 'skill' then Cli::SkillCommand.call(@argv)
-      when 'eval'  then Cli::EvalCommand.call(@argv)
+      when 'init'    then Cli::InitCommand.call(@argv)
+      when 'run'     then Cli::RunCommand.call(@argv)
+      when 'compare' then Cli::CompareCommand.call(@argv)
+      when 'skill'   then Cli::SkillCommand.call(@argv)
+      when 'eval'    then Cli::EvalCommand.call(@argv)
       when '-h', '--help', 'help'
         help.call
       else

data/lib/skill_bench/clients/all.rb

@@ -2,6 +2,7 @@
 
 require_relative 'response_parser'
 require_relative 'response_error_handler'
+require_relative 'response_builder'
 require_relative 'request_builder'
 require_relative 'retry_handler'
 require_relative 'base_client'
@@ -17,3 +18,4 @@ require_relative 'providers/opencode'
 require_relative 'providers/groq'
 require_relative 'providers/deepseek'
 require_relative 'providers/openrouter'
+require_relative 'providers/mock'

data/lib/skill_bench/clients/base_client.rb

@@ -4,6 +4,7 @@ require_relative '../config'
 require_relative 'provider_config'
 require_relative 'response_parser'
 require_relative 'response_error_handler'
+require_relative 'response_builder'
 require_relative 'request_builder'
 require_relative 'retry_handler'
 
@@ -135,7 +136,7 @@ module SkillBench
                   else
                     "#{missing.first} not set for #{@provider_display_name}"
                   end
-        { success: false, response: { error: { message: message } }, result: message, status: 'error' }
+        ResponseBuilder.error(message: message)
       end
 
       # Extracts the message hash from the provider's specific response body structure.
@@ -182,10 +183,6 @@ module SkillBench
         message = extract_message(parsed)
         return missing_message_response(response, parsed) unless ResponseParser.valid_message?(message)
 
-        success_response(parsed, message)
-      end
-
-      def success_response(parsed, message)
         content = ResponseParser.extract_content(message)
         {
           success: true,

data/lib/skill_bench/clients/providers/mock.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative '../provider_registry'
+require 'json'
+
+module SkillBench
+  module Clients
+    module Providers
+      # Mock LLM client for testing and local validation.
+      class Mock
+        SkillBench::Clients::ProviderRegistry.register(:mock, self)
+
+        # Mock call implementation to simulate LLM responses for test suites.
+        #
+        # @param system_prompt [String] system prompt instructions.
+        # @param messages [Array<Hash>] chat history messages.
+        # @param _options [Hash] additional keyword options.
+        # @return [Hash] mock response hash.
+        def self.call(system_prompt:, messages:, **_options)
+          _ = system_prompt
+          prompt = messages.first[:content] || messages.first['content'] || ''
+
+          # Parse dimensions from prompt
+          dimensions = {}
+          prompt.scan(/-\s+([^:]+):\s+max_score=(\d+)/).each do |name, max_score|
+            max = max_score.to_i
+            # Give baseline slightly lower score than context to simulate improvement
+            is_context = prompt.match?(/## Skill Context\s+\S+/)
+            score = is_context ? (max * 0.95).round : (max * 0.8).round
+            dimensions[name] = {
+              'score' => score,
+              'max_score' => max,
+              'reasoning' => "Mock evaluation for #{name}"
+            }
+          end
+
+          dimensions['correctness'] = { 'score' => 8, 'max_score' => 10, 'reasoning' => 'Mock correctness' } if dimensions.empty?
+
+          content = {
+            'dimensions' => dimensions,
+            'overall_reasoning' => 'Mock evaluation overall reasoning'
+          }.to_json
+
+          {
+            success: true,
+            response: {
+              message: {
+                content: content
+              }
+            }
+          }
+        end
+      end
+    end
+  end
+end

data/lib/skill_bench/clients/request_builder.rb

@@ -1,22 +1,20 @@
 # frozen_string_literal: true
 
 require 'faraday'
+require_relative '../constants'
 
 module SkillBench
   module Clients
     # Builds and executes HTTP requests to LLM provider APIs.
     # Encapsulates Faraday connection setup and request execution.
     class RequestBuilder
-      DEFAULT_OPEN_TIMEOUT = 10
-      DEFAULT_TIMEOUT = 120
-
       # Creates a Faraday connection with JSON middleware.
       #
       # @param base_url [String] The API base URL
       # @param open_timeout [Integer] Connection open timeout in seconds
       # @param timeout [Integer] Request timeout in seconds
       # @return [Faraday::Connection] Configured Faraday connection
-      def self.build_connection(base_url, open_timeout: DEFAULT_OPEN_TIMEOUT, timeout: DEFAULT_TIMEOUT)
+      def self.build_connection(base_url, open_timeout: Constants::HttpClient::DEFAULT_OPEN_TIMEOUT, timeout: Constants::HttpClient::DEFAULT_TIMEOUT)
         Faraday.new(url: base_url) do |f|
           f.request :json
           f.response :json

data/lib/skill_bench/clients/response_builder.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module SkillBench
+  module Clients
+    # Service object for building standardized response hashes.
+    # Eliminates duplication of error response formatting across the codebase.
+    class ResponseBuilder
+      # Builds a standardized error response.
+      #
+      # @param message [String] The error message.
+      # @param status [String] The status identifier (default: 'error').
+      # @return [Hash] Standardized error response hash.
+      def self.error(message:, status: 'error')
+        {
+          success: false,
+          response: { error: { message: message } },
+          result: message,
+          status: status
+        }
+      end
+
+      # Builds a standardized success response.
+      #
+      # @param content [String] The response content.
+      # @param metadata [Hash] Additional metadata to include in response.
+      # @return [Hash] Standardized success response hash.
+      def self.success(content:, metadata: {})
+        {
+          success: true,
+          result: content,
+          response: { content: content }.merge(metadata),
+          status: 'success'
+        }
+      end
+
+      # Builds a standardized API error response.
+      #
+      # @param error_message [String] The API error message.
+      # @param usage [Hash] Token usage information.
+      # @return [Hash] Standardized API error response hash.
+      def self.api_error(error_message:, usage: {})
+        {
+          success: false,
+          result: "API Error: #{error_message}",
+          usage: usage,
+          response: { error: { message: "API Error: #{error_message}" } },
+          status: 'error'
+        }
+      end
+
+      # Builds a standardized network error response.
+      #
+      # @param error_message [String] The network error message.
+      # @return [Hash] Standardized network error response hash.
+      def self.network_error(error_message:)
+        {
+          success: false,
+          response: { error: { message: "Network Error: #{error_message}" } },
+          result: "Network Error: #{error_message}",
+          status: 'error'
+        }
+      end
+
+      # Builds a standardized parsing error response.
+      #
+      # @param error_message [String] The parsing error message.
+      # @return [Hash] Standardized parsing error response hash.
+      def self.parsing_error(error_message:)
+        {
+          success: false,
+          response: { error: { message: "Parsing Error: #{error_message}" } },
+          result: "Parsing Error: #{error_message}",
+          status: 'error'
+        }
+      end
+
+      # Builds a standardized unexpected error response.
+      #
+      # @param error_message [String] The unexpected error message.
+      # @return [Hash] Standardized unexpected error response hash.
+      def self.unexpected_error(error_message:)
+        {
+          success: false,
+          response: { error: { message: "Unexpected Error: #{error_message}" } },
+          result: "Unexpected Error: #{error_message}",
+          status: 'error'
+        }
+      end
+    end
+  end
+end