active_harness: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

ActiveHarness is a Ruby gem (active_harness) for building production-grade LLM pipelines. It wraps individual LLM calls with retry logic, fallback chains, observability hooks, cost tracking, streaming, and consensus-based decisions. Works in plain Ruby and Rails. Current version: 0.2.x.

Commands

# Install dependencies (gem has no Gemfile — use bundler in consuming apps)
bundle install

# Build gem artifact
make build

# Bump patch version, sync, and release to RubyGems
make up

# Bump minor version
make up/minor

# Bump major version
make up/major

Tests (minitest, currently covering Tool, Agent and provider tool-calling; scripted LLM in test/test_helper.rb) run with:

ruby -Ilib -Itest -e 'Dir["test/**/*_test.rb"].each { |f| require "./#{f}" }'

They need the concurrent-ruby and active_harness_pricing gems (or a sibling ../ActiveHarnessPricing checkout). No Rakefile, no linter. Ruby 2.6+ compatibility is required — no endless def, no numbered block params.

Architecture

Primary Abstractions

ActiveHarness::Request (lib/active_harness/request.rb + lib/active_harness/request/) Single LLM call with a model chain, system prompt, hooks, retry policy, and optional streaming. Call pattern: MyRequest.call(input: "...", context: {}, params: {}, memory: nil, models: nil, token: nil, stream: nil). Returns self; result is on request.result (a Result struct). Can also be instantiated and called inline: request.call("new input"). input is a String or an Array of messages (a conversation; there is no separate messages: keyword); helpers input_text / transcript, and result.warnings / on :warning for soft remarks (e.g. only the last user message was taken from a multi-message input).

ActiveHarness::Tribunal (lib/active_harness/tribunal.rb + subdirs) Runs multiple requests in parallel via concurrent-ruby's Concurrent::Future. Computes a verdict from all successful results using either a :unanimous/:majority built-in strategy or a custom process { |results| ... } block. Tolerates partial failure via may_fail: N. Returns self; verdict is on tribunal.verdict.