active_harness 0.2.25 → 0.2.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2a3e44b6a9f63f595ee483620a0aac1080825ce3f1d585696930db1be0991f7
-  data.tar.gz: 28382baad847f75cfdc4613c143b325d9cd4b8b31913df2812e76ff33dbd80bf
+  metadata.gz: e251d772ac23a015473080cd54ec79dcd1d707b3ca9fa1c8de6132f8152fa873
+  data.tar.gz: 68674b1744f7696cb26cc02a505e60e8c6ae117c7f20a118a2e8102c8f0821f5
 SHA512:
-  metadata.gz: f0b0422ecb620e3d9749133d17dcfd66b0328cbaf60ebe17b8c835ceb8be94fdb7c94a3b980afa85a4251ba4b42acae05bb9ad5250c8ab3c9def0e92e9094ff6
-  data.tar.gz: 5e2502fbc8ad9cf559c9cd9aecb8ea8e78abc330f442991e99a21e8cf7a3b1aa4682f3e926b3632157932ee32f1549a3e5861764b4883f7271154d81ad4dbbdb
+  metadata.gz: 99ef61764b9c6b7564f1064c191cb89780670c7e24966556f3f52e3fa15b631e492c9c29a3ac7f601249db9515afed291fe2e6d6e333f9fb6c2043dbad22dac1
+  data.tar.gz: 8c8609086bc572183398cf20ff0ea2957e8acd8337db9dadfcb8045f1bbdbb7a708b3f3b27273809a717e91196abe4bf272778d521bfa0926338f0df03486e84

data/lib/active_harness/agent/models.rb

@@ -14,7 +14,7 @@ module ActiveHarness
       # Output format for this agent.
       #
       #   format :text   # default — output is returned as-is
-      #   format :json   # output is parsed; result.parsed is a Ruby Hash/Array
+      #   format :json   # output is parsed; result.processed is a Ruby Hash/Array
       def format(type)
         unless %i[text json].include?(type)
           raise ArgumentError, "Unknown format :#{type}. Valid values: :text, :json"

data/lib/active_harness/agent/output_parser.rb

@@ -39,7 +39,7 @@ module ActiveHarness
       begin
         parsed = JSON.parse(clean)
 
-        # :after_parse — return value replaces parsed result stored in Result
+        # :after_parse — return value replaces processed result stored in Result
         transform_hook(:after_parse, parsed)
       rescue JSON::ParserError => e
         # :parse_error — if hook returns non-nil, it is used as fallback value

data/lib/active_harness/agent.rb

@@ -140,13 +140,13 @@ module ActiveHarness
 
     def build_result(response, entry, attempts, elapsed)
       raw    = response[:content]
-      parsed = parse_output(raw)
+      processed = parse_output(raw)
       usage  = response[:usage]
 
       Result.new(
         input:          @input,
         output:         raw,
-        parsed:         parsed,
+        processed:      processed,
         system_prompt:  @system_prompt,
         provider:       entry[:provider],
         model:          entry[:model],

data/lib/active_harness/pipeline/README.md

@@ -0,0 +1,252 @@
+# Pipeline
+
+A pipeline chains multiple agents and tribunals into a sequential workflow.
+Each step receives the current payload, can transform it, and can stop the pipeline early.
+
+## Basic usage
+
+```ruby
+class SupportPipeline < ActiveHarness::Pipeline
+  step :translate, TranslationAgent
+
+  step :injection_guard do
+    use InjectionGuardAgent
+    stop_if ->(result) { result.processed["detected"] == true }
+  end
+
+  step :safety_tribunal do
+    use SafetyTribunal
+    stop_if ->(result) { result.verdict == false }
+  end
+end
+
+pipeline = SupportPipeline.new(input: "Hello", context: { user_id: 1 })
+pipeline.call
+
+pipeline.output       # => final payload string (nil if stopped)
+pipeline.stopped?     # => false
+pipeline.step_results # => { translate: <Result>, injection_guard: <Result>, ... }
+```
+
+## Step types
+
+There are two kinds of classes a step can use.
+
+**Agent step** — runs the agent, takes `result.output` as the new payload:
+
+```ruby
+step :translate, TranslationAgent
+```
+
+**Tribunal step** — runs the tribunal, returns a `Result` with `processed["verdict"]`.
+Payload is never updated by a tribunal step (it always has `stop_if`):
+
+```ruby
+step :safety_tribunal do
+  use SafetyTribunal
+  stop_if ->(result) { result.processed["verdict"] == false }
+end
+```
+
+## Payload propagation
+
+The payload starts as the value passed to `input:` and flows through the steps:
+
+| Condition | Payload after step |
+|-----------|--------------------|
+| Agent step, no `stop_if` | Updated to `result.output` |
+| Agent step with `stop_if` | Unchanged (guard step) |
+| Tribunal step | Unchanged |
+
+After each step the result is also stored in `context[step_name]`,
+so later steps can read earlier results via `@context[:translate]` etc.
+
+## Stopping the pipeline
+
+Any step can stop the pipeline by defining `stop_if`:
+
+```ruby
+step :injection_guard do
+  use InjectionGuardAgent
+  stop_if ->(result) { result.processed["detected"] == true }
+end
+```
+
+When the condition is true:
+- remaining steps are skipped
+- `pipeline.stopped?` returns `true`
+- `pipeline.stopped_at` holds the step name
+- `pipeline.output` is `nil`
+
+## Events and hooks
+
+```ruby
+class SupportPipeline < ActiveHarness::Pipeline
+  on_agent_event    do |event, result|  ... end  # fires for every agent inside
+  on_tribunal_event do |event, verdict| ... end  # fires for every tribunal inside
+  on_pipeline_event do |event, *args|   ... end  # :before_step, :after_step, :stopped, :complete
+end
+```
+
+Runtime streams can be passed at construction time:
+
+```ruby
+SupportPipeline.new(
+  input:   "...",
+  streams: { token: token_lambda, agent: agent_lambda }
+)
+```
+
+## Memory
+
+A memory object can be attached to the pipeline. It is loaded before the first step
+and a record is written after successful completion (skipped if the pipeline stops early):
+
+```ruby
+mem = ActiveHarness::Memory::JsonFile.new(file_name: "session_42")
+
+SupportPipeline.new(input: "...", memory: mem).call
+```
+
+---
+
+## Proposal: universal step interface
+
+Currently `Pipeline::Step` special-cases two concrete classes: `Agent` and `Tribunal`.
+This section explores making the pipeline open to any entity — a plain Ruby object,
+a lambda, a nested pipeline, an HTTP call, a cache lookup — with no inheritance required.
+
+The core question is: **what must a step return so the pipeline can drive it?**
+
+---
+
+### Option A — Duck-type protocol (minimal change)
+
+Define a lightweight protocol. Any object that satisfies it can be a step:
+
+```ruby
+# Contract: class responds to .new(input:, context:, params:, streams:)
+# Instance responds to .call → returns an object with:
+#   .output  — new payload (String or any value); nil keeps payload unchanged
+#   .stop?   — true signals the pipeline to halt (replaces stop_if in step DSL)
+
+class UppercaseStep
+  def initialize(input:, **); @input = input; end
+
+  def call
+    Pipeline::StepResult.new(output: @input.upcase)
+  end
+end
+
+step :upcase, UppercaseStep
+```
+
+`Pipeline::StepResult` would be a tiny value object:
+
+```ruby
+Pipeline::StepResult = Struct.new(:output, :stop, keyword_init: true) do
+  def stop? = stop
+end
+```
+
+**Pros:** almost no change to existing code; agents and tribunals get thin adapters.  
+**Cons:** every custom step must construct `StepResult`; slightly more boilerplate.
+
+---
+
+### Option B — Callable (lambda / proc) as a step
+
+Allow any `Proc`/`lambda` directly, without a wrapper class:
+
+```ruby
+step :sanitize, ->(payload, ctx) { payload.strip }
+
+step :length_guard, ->(payload, ctx) {
+  payload.length > 1000 ? Pipeline::Stop : payload
+}
+```
+
+Return value rules:
+- any value other than `Pipeline::Stop` → becomes new payload
+- `Pipeline::Stop` (or `Pipeline::Stop.new(reason)`) → halts the pipeline
+
+**Pros:** perfect for simple transformations and guards; zero boilerplate.  
+**Cons:** no access to `params:` or `streams:` without enlarging the lambda signature;
+harder to test in isolation.
+
+---
+
+### Option C — Rack-style env hash
+
+Each step receives and returns a single hash (`env`), similar to Rack middleware:
+
+```ruby
+# env keys: :input, :output, :context, :params, :streams
+# Return env to continue, return Pipeline::Stop to halt.
+
+class UppercaseStep
+  def call(env)
+    env.merge(output: env[:input].upcase)
+  end
+end
+
+class LengthGuard
+  def call(env)
+    env[:input].length > 1000 ? Pipeline::Stop.new("too long") : env
+  end
+end
+```
+
+Steps become stateless (no `initialize`) — a single instance can be reused:
+
+```ruby
+UPCASE = UppercaseStep.new
+
+step :upcase,       UPCASE
+step :length_guard, LengthGuard.new
+```
+
+**Pros:** stateless, composable, easy to test (`call(env)` in one line); nested
+pipelines become trivial — a pipeline is just another object with `call(env)`.  
+**Cons:** largest departure from the current API; requires migrating Agent/Tribunal wrappers.
+
+---
+
+### Option D — `Pipeline::Callable` module (explicit contract)
+
+A module that documents the contract and provides `StepResult` helpers:
+
+```ruby
+class EnrichStep
+  include ActiveHarness::Pipeline::Callable  # documents intent, no magic
+
+  def initialize(input:, context:, **); @input = input; @context = context; end
+
+  def call
+    data = ExternalService.fetch(@context[:user_id])
+    result(output: "#{@input} [enriched: #{data}]")  # helper from Callable
+  end
+end
+```
+
+Agents and Tribunals include `Callable` automatically, so they work as before.
+Any plain class can opt in with one `include`.
+
+**Pros:** clear opt-in contract; helpers reduce boilerplate; IDE-friendly.  
+**Cons:** still requires `include`; doesn't help lambdas or nested pipelines directly.
+
+---
+
+### Comparison
+
+| | No inheritance | Lambda support | Nested pipeline | Migration cost |
+|---|---|---|---|---|
+| **A — duck type** | yes | with wrapper | yes | low |
+| **B — lambda** | yes | native | no | low |
+| **C — Rack env** | yes | yes (`.call`) | yes (trivially) | high |
+| **D — module** | yes (opt-in) | with wrapper | yes | low |
+
+**Recommendation:** start with **B** (lambda steps) for simple cases and **A** (duck-type
+protocol + `StepResult`) for structured steps — both require minimal changes to the
+existing engine. Option C is the most powerful but is a bigger refactor; consider it
+if nested pipelines or stateless reuse become a real need.

data/lib/active_harness/pipeline.rb

@@ -7,7 +7,7 @@ module ActiveHarness
   #   class SupportPipeline < ActiveHarness::Pipeline
   #     step :injection_guard do
   #       use InjectionGuardAgent
-  #       stop_if ->(result) { result.parsed["detected"] == true }
+  #       stop_if ->(result) { result.processed["detected"] == true }
   #     end
   #
   #     step :translate, TranslationAgent   # shorthand — no stop_if
@@ -44,7 +44,7 @@ module ActiveHarness
       # Full block form:
       #   step :injection_guard do
       #     use InjectionGuardAgent
-      #     stop_if ->(result) { result.parsed["detected"] == true }
+      #     stop_if ->(result) { result.processed["detected"] == true }
       #   end
       def step(name, agent_class = nil, &block)
         pipeline_config[:steps] << Pipeline::Step.new(name, agent_class, &block)
@@ -210,23 +210,13 @@ module ActiveHarness
     end
 
     def execute_step(step)
-      if step.tribunal?
-        agent_streams = { token: @token_stream, agent: @agent_event_stream, tribunal: @tribunal_event_stream }.compact
-        step.agent_class.new(
-          input:    @payload,
-          context:  @context.dup,
-          params:   @params,
-          streams:  agent_streams
-        ).call
-      else
-        agent_streams = { token: @token_stream, agent: @agent_event_stream }.compact
-        step.agent_class.new(
-          input:    @payload,
-          context:  @context.dup,
-          params:   @params,
-          streams:  agent_streams
-        ).call.result
-      end
+      streams = { token: @token_stream, agent: @agent_event_stream, tribunal: @tribunal_event_stream }.compact
+      step.agent_class.new(
+        input:   @payload,
+        context: @context.dup,
+        params:  @params,
+        streams: streams
+      ).call.result
     end
   end
 end

data/lib/active_harness/result.rb

@@ -4,8 +4,20 @@ module ActiveHarness
   # Minimal result wrapper returned by Agent#call.
   #
   # output — raw string from the provider
-  # parsed — for format :json: a Ruby Hash/Array; for format :text: same as output
+  # processed — for format :json: a Ruby Hash/Array; for format :text: same as output
   # usage  — token counts: { input_tokens:, output_tokens:, total_tokens: } or nil for streaming
   # cost   — { input_cost:, output_cost:, total_cost: } in USD, or nil if pricing unavailable
-  Result = Struct.new(:input, :output, :parsed, :system_prompt, :provider, :model, :temperature, :model_list, :attempts, :execution_time, :usage, :cost, keyword_init: true)
+  Result = Struct.new(
+    :input,
+    :output,
+    :processed,
+    :system_prompt, 
+    :provider, :model,
+    :temperature,
+    :model_list,
+    :attempts,
+    :execution_time,
+    :usage,
+    :cost,
+    keyword_init: true)
 end

data/lib/active_harness/tribunal/dsl.rb

@@ -13,7 +13,7 @@ module ActiveHarness
       # Receives the full results array; return value becomes #verdict.
       # Takes priority over +verdict+ strategy if both are declared.
       #
-      #   process { |results| results.all? { |r| r.parsed["result"] == true } }
+      #   process { |results| results.all? { |r| r.processed["result"] == true } }
       def process(&block)
         tribunal_config[:process] = block
       end
@@ -31,11 +31,11 @@ module ActiveHarness
       # The block receives a single Result and must return a truthy/falsy value.
       #
       #   verdict :unanimous do |result|
-      #     result.parsed["result"] == true
+      #     result.processed["result"] == true
       #   end
       #
       #   verdict :majority, may_fail: 1 do |result|
-      #     result.parsed["result"] == true
+      #     result.processed["result"] == true
       #   end
       VALID_STRATEGIES = %i[unanimous majority].freeze
 

data/lib/active_harness/tribunal/processing.rb

@@ -2,7 +2,7 @@ module ActiveHarness
   class Tribunal
     # Instance-level process block — overrides class-level block.
     #
-    #   tribunal.process { |results| results.count { |r| r.parsed["ok"] } >= 2 }
+    #   tribunal.process { |results| results.count { |r| r.processed["ok"] } >= 2 }
     def process(&block)
       @process_block = block
       self

data/lib/active_harness/tribunal.rb

@@ -17,14 +17,14 @@ module ActiveHarness
   #     timeout: 7
   #   )
   #   tribunal.on(:after_agent) { |result| puts result.model }
-  #   tribunal.process { |results| results.all? { |r| r.parsed["result"] == true } }
+  #   tribunal.process { |results| results.all? { |r| r.processed["result"] == true } }
   #   tribunal.call
   #
   # Subclass with DSL:
   #   class ContentQualityTribunal < ActiveHarness::Tribunal
   #     agents PolitenessAgent, ConstructivenessAgent
   #     on(:after_agent) { |result| puts result.model }
-  #     process { |results| results.all? { |r| r.parsed["result"] == true } }
+  #     process { |results| results.all? { |r| r.processed["result"] == true } }
   #   end
   #   ContentQualityTribunal.new(input: "...").call
   #
@@ -89,6 +89,17 @@ module ActiveHarness
       @agent_execution_times = []
     end
 
+    # Returns a Result with processed: { "verdict" => @verdict } so the pipeline
+    # can handle agents and tribunals through the same interface.
+    def result
+      Result.new(
+        input:          @input,
+        output:         nil,
+        processed:      { "verdict" => @verdict },
+        execution_time: @execution_time
+      )
+    end
+
     # Run all agents in parallel, then compute the verdict.
     # Returns self so calls can be chained: tribunal.call.verdict
     #

data/lib/active_harness.rb

@@ -30,7 +30,7 @@ require_relative "active_harness/pipeline"
 require_relative "active_harness/railtie" if defined?(Rails::Railtie)
 
 module ActiveHarness
-  VERSION = "0.2.25"
+  VERSION = "0.2.26"
 
   class << self
     # Configure ActiveHarness.

data/lib/generators/active_harness/install/templates/tribunals/support_guard_tribunal.rb

@@ -6,6 +6,6 @@ class SupportGuardTribunal < ActiveHarness::Tribunal
   agents SupportGuardAgent
 
   process do |results|
-    results.none? { |r| r.parsed["spam"] == true }
+    results.none? { |r| r.processed["spam"] == true }
   end
 end

data/lib/generators/active_harness/tribunal/templates/tribunal.rb.tt

@@ -2,6 +2,6 @@ class <%= class_name %>Tribunal < ActiveHarness::Tribunal
   agents <%= class_name %>Agent
 
   process do |results|
-    results.all? { |r| r.parsed["result"] == true }
+    results.all? { |r| r.processed["result"] == true }
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: active_harness
 version: !ruby/object:Gem::Version
-  version: 0.2.25
+  version: 0.2.26
 platform: ruby
 authors:
 - the-teacher
@@ -54,6 +54,7 @@ files:
 - lib/active_harness/memory/adapter/postgresql.rb
 - lib/active_harness/memory/adapter/sqlite.rb
 - lib/active_harness/pipeline.rb
+- lib/active_harness/pipeline/README.md
 - lib/active_harness/pipeline/hooks.rb
 - lib/active_harness/pipeline/step.rb
 - lib/active_harness/providers/PROVIDER_CONTRACT.md