active_harness CLAUDE.md

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

There is no automated test suite in this repo yet (no test/ directory, no Rakefile) and no linter. Ruby 2.6+ compatibility is required — no endless def, no numbered block params.

Architecture

Three Primary Abstractions

ActiveHarness::Agent (lib/active_harness/agent.rb + lib/active_harness/agent/) Single LLM call with a model chain, system prompt, hooks, retry policy, and optional streaming. Call pattern: MyAgent.call(input: "...", context: {}, params: {}, memory: nil, models: nil, token: nil, stream: nil). Returns self; result is on agent.result (a Result struct). Can also be instantiated and called inline: agent.call("new input").

ActiveHarness::Tribunal (lib/active_harness/tribunal.rb + subdirs) Runs multiple agents 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.

ActiveHarness::Pipeline (lib/active_harness/pipeline.rb + subdirs) Sequential chain of agents, tribunals, and lambdas as named steps. Each step can have a stop_if lambda; when it fires, pipeline.stopped? becomes true and subsequent steps are skipped. Step results are readable via the pipeline.steps enumerator (yields step_name, executor, result) and are also forwarded as context[step_name] to downstream steps. Each step's output replaces the payload only when step.transform? is true (i.e., a use agent rather than a tribunal that only produces a verdict).