rcrewai 0.6.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32edcb190b0d85db67d404b260fbb86d9b2821d6a89adf350d792b60a0e21a06
-  data.tar.gz: 46d061ecebca5a67714a6a8139d41bf9d20ce60d4eb5f0a1505d965defffaeb8
+  metadata.gz: '0024080cd05b151b653bcedb4b29afea563e149f9d68dce1662d636a919020a9'
+  data.tar.gz: 53bb6b1376f88d1379cb0f877eeaa35aed0822f08df5f76d482e28d55101efe6
 SHA512:
-  metadata.gz: a77a41b7fa6dad5de896c7b635777ee5f2429eb826e65516b2d3a5b2d9e9446ca8de0bf6fd0fd94f9efd4159c5080a94d534aa6c65447abd4d781b8d05a63ff4
-  data.tar.gz: a65c248d53e9f346cd88c4f9f8e04280e89d67d5bf9695ff252ca14ee270864f23ee1f64395831ce7f2be95d682fc54ecb655d64a8c2b09b99800dcd561d3524
+  metadata.gz: b7923adbf161caa5361568268306513c92e5ffbddc3736cd91cd0fbccedd8cdd4230854f8310cf358964c7ccea09b1e43040e944f4c5472b0f5e58983bf37aaf
+  data.tar.gz: e4c9426c4e948fca50c3708a8a0e57588b4b18c51a5ac8df0bd2dd902aa2440a20d8d1f6a464333bb9c3244d5ff6901070645bb932fd5fb6e77f3d3f82ff9f83

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-07
+
+Turns the `:consensual` crew process from a stub into a real multi-agent
+consensus (propose → vote → pick). This is a behavior change to an existing
+process type — see `docs/upgrading-to-0.7.md`.
+
+### Changed
+- The `:consensual` crew process now performs real multi-agent consensus instead of silently running sequentially. For each task, up to `consensus_agents` agents (default 3) propose candidate answers, all participants score each candidate 0–10, and the highest-scored candidate wins (ties break toward the task's assigned agent). Configure via `Crew.new(process: :consensual, consensus_agents: N)`. A proposer that errors is dropped; if all proposals fail the task is marked failed. **Behavior change:** code relying on `:consensual`'s previous (accidental) sequential behavior should switch to `process: :sequential`. See `docs/upgrading-to-0.7.md`.
+
 ## [0.6.1] - 2026-07-06
 
 Follow-ups to the 0.6.0 Cognitive Memory release, deepening the areas that
@@ -208,7 +217,8 @@ output, guardrails, planning, and training/testing. See `ROADMAP.md`.
 - CLI usage documentation
 - Real-world use cases and examples
 
-[Unreleased]: https://github.com/gkosmo/rcrewAI/compare/v0.6.1...HEAD
+[Unreleased]: https://github.com/gkosmo/rcrewAI/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/gkosmo/rcrewAI/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/gkosmo/rcrewAI/compare/v0.6.0...v0.6.1
 [0.6.0]: https://github.com/gkosmo/rcrewAI/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/gkosmo/rcrewAI/compare/v0.4.0...v0.5.0

data/README.md

@@ -445,6 +445,26 @@ flow.state.id          # => automatic UUID
   or your own `#save`/`#load`) and call `flow.restore(id)` to resume.
 - Invoke a `Crew` inside any step, or pause with `human_feedback('Approve?')`.
 
+## 🗳️ Consensual Process
+
+For decisions where multiple perspectives matter, the `:consensual` process has
+several agents propose competing answers and vote to pick the best:
+
+```ruby
+crew = RCrewAI::Crew.new('panel', process: :consensual, consensus_agents: 3)
+crew.add_agent(junior)
+crew.add_agent(senior)
+crew.add_task(task)
+
+crew.execute   # each task: agents propose → all score 0–10 → highest wins
+```
+
+For every task, up to `consensus_agents` agents (default 3) propose a candidate
+answer, all participants score each candidate, and the highest-scored candidate
+becomes the result (ties break toward the task's assigned agent). A proposer that
+errors is dropped; if all proposals fail the task is marked failed. Consensus
+multiplies LLM calls, so `consensus_agents` bounds the cost on larger crews.
+
 ## 💡 Examples
 
 ### Hierarchical Team with Human Oversight

data/docs/superpowers/specs/2026-07-07-consensual-process-design.md

@@ -0,0 +1,82 @@
+# Consensual Process: propose → vote → pick
+
+**Date:** 2026-07-07
+**Status:** Approved design (pending implementation)
+**Target version:** `rcrewai` 0.7.0 (current is 0.6.1)
+**Scope:** Replace the stubbed `Process::Consensual` (which silently runs tasks sequentially) with a real multi-agent consensus: agents propose candidate answers, score each other's candidates, and the highest-scored candidate wins.
+
+---
+
+## Motivation
+
+`Crew.new('c', process: :consensual)` is a public, validated, documented process type. But `Process::Consensual#execute` currently just runs each task once (`execute_with_consensus` calls `task.execute` with a "for now, just execute normally" comment). A user selecting `:consensual` silently gets sequential behavior — the feature is advertised but not implemented. This is a latent honesty gap: fix the code to do what its name and comments promise ("agent voting/discussion").
+
+## Behavior
+
+For each task in the crew, instead of a single execution:
+
+1. **Propose** — up to `consensus_agents` agents (default 3, capped from the crew) each independently produce a candidate answer for the task.
+2. **Vote** — each participating agent scores every candidate 0–10 for how well it satisfies the task's description and expected output.
+3. **Pick** — the candidate with the highest total score wins. Ties break toward the task's assigned agent's candidate (or the first proposer if the assigned agent didn't propose).
+
+## Components
+
+All within `Process::Consensual`, replacing the stub. Result shape is unchanged
+(`{ task:, result:, status: }`) so `Crew#format_execution_results` needs no changes.
+
+- `execute` — iterate tasks, call `execute_with_consensus(task)`, log, return results.
+- `select_participants(task)` — first N agents (`consensus_agents`), always including the task's assigned agent if present and not already in the first N.
+- `gather_proposals(task, participants)` — each agent runs the task; returns `[{ agent:, content: }]`. A proposer that raises is dropped (logged), not fatal.
+- `score_candidates(task, candidates, participants)` — each participant scores each candidate via an LLM call; returns per-candidate total. Non-numeric / failed scores count as 0.
+- `pick_winner(task, scored)` — highest total; deterministic tie-break toward the task's assigned agent, else first proposer.
+
+## Configuration
+
+```ruby
+Crew.new('c', process: :consensual, consensus_agents: 3)
+```
+
+`consensus_agents` (default 3) caps how many agents propose and vote, bounding
+cost regardless of crew size. Read by the process from the crew.
+
+## Cost
+
+Bounded per task: N proposals + N×N scoring calls, N defaulting to 3
+(≈ 3 + 9 = 12 LLM calls/task worst case), independent of crew size.
+
+## Edge cases
+
+- **1 participant** → a single proposal, no meaningful vote; returns a valid result.
+- **A proposer errors** → that candidate is dropped; consensus continues with the rest.
+- **All proposals fail** → task marked `:failed` with the error, matching Sequential's rescue behavior.
+- **No agents in crew** → task `:failed` (nothing can propose).
+
+## Scoring mechanism
+
+Each participant is prompted: given the task (description + expected output) and a
+candidate answer, return a single integer 0–10. The response is parsed with a
+tolerant integer extraction (first integer in the text; clamp to 0–10; default 0
+on failure). Scores are summed across participants per candidate.
+
+## Backward compatibility
+
+`:consensual` already exists and validates. This changes only runtime behavior
+(from "silently sequential" to "actual consensus"). The async consensual path
+(`Crew#execute_consensual_async`, parallel aggregation) is intentionally left
+unchanged for this pass and noted in docs; expanding it is a possible follow-up.
+
+## Testing (TDD)
+
+Fake agents returning canned proposals and scores (no live LLM) prove:
+- highest-scored candidate wins
+- deterministic tie-break toward the task's assigned agent
+- `consensus_agents` cap respected on a larger crew
+- single-agent degradation returns a valid result
+- a proposer raising is dropped, consensus still completes
+- all-proposals-fail marks the task `:failed`
+
+## Rollout
+
+Ship in `0.7.0` (behavior change to an existing feature warrants a minor bump).
+`docs/upgrading-to-0.7.md` notes the behavior change; README documents the
+consensus flow and `consensus_agents`.

data/docs/upgrading-to-0.7.md

@@ -0,0 +1,36 @@
+# Upgrading to RCrewAI 0.7
+
+RCrewAI 0.7 makes the `:consensual` crew process do what its name promises.
+
+## Behavior change: `:consensual` process
+
+Previously, `Crew.new('c', process: :consensual)` was a stub — it silently ran
+tasks **sequentially**. As of 0.7 it performs real multi-agent consensus:
+
+1. **Propose** — up to `consensus_agents` agents (default 3) each produce a
+   candidate answer for the task.
+2. **Vote** — every participant scores each candidate 0–10.
+3. **Pick** — the highest-scored candidate wins (ties break toward the task's
+   assigned agent).
+
+### What you must do
+
+Nothing to keep your code running — the API is unchanged. But be aware:
+
+- If you were using `process: :consensual` and relying on its (accidental)
+  sequential behavior, switch to `process: :sequential` explicitly.
+- Consensus multiplies LLM calls (≈ N proposals + N×N scoring per task, N=3 by
+  default). Tune or bound it with `consensus_agents:`.
+
+```ruby
+crew = RCrewAI::Crew.new('panel', process: :consensual, consensus_agents: 3)
+```
+
+### Edge cases
+
+- One agent → a single proposal (no real vote), still a valid result.
+- A proposer that errors is dropped; consensus continues with the rest.
+- If every proposal fails, the task is marked failed.
+
+The async consensual path (`crew.execute(async: true)` with `:consensual`) is
+unchanged in this release (parallel aggregation).

data/examples/consensual_process_example.rb

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Consensual process — agents propose competing answers and vote to pick one.
+#
+# For each task: up to `consensus_agents` agents each produce a candidate
+# answer, every participant scores each candidate 0-10, and the highest-scored
+# candidate wins (ties break toward the task's assigned agent).
+#
+# This example stubs the agents so it runs WITHOUT an API key. In real use each
+# agent calls your configured LLM to propose and to score.
+#
+# Run:
+#   ruby examples/consensual_process_example.rb
+
+require_relative '../lib/rcrewai'
+
+RCrewAI.configure(validate: false) do |c|
+  c.llm_provider = :openai
+  c.api_key = 'demo-key'
+end
+
+# A stand-in agent: proposes a fixed answer, and scores candidates by a simple
+# rubric (here: answers mentioning "trade-offs" are judged higher). A real
+# Agent proposes via execute_task and scores via its llm_client.
+class PanelAgent
+  attr_reader :name
+
+  def initialize(name, answer)
+    @name = name
+    @answer = answer
+  end
+
+  def execute_task(_task)
+    { content: @answer }
+  end
+
+  def llm_client
+    self
+  end
+
+  def chat(messages:, **)
+    candidate = messages.first[:content]
+    score = candidate.include?('trade-offs') ? 9 : 5
+    { content: score.to_s }
+  end
+end
+
+junior = PanelAgent.new('junior', 'Use PostgreSQL.')
+senior = PanelAgent.new('senior', 'Use PostgreSQL, but weigh the trade-offs vs. DynamoDB for scale.')
+
+crew = RCrewAI::Crew.new('architecture_panel', process: :consensual, consensus_agents: 3)
+crew.add_agent(junior)
+crew.add_agent(senior)
+
+task = RCrewAI::Task.new(name: 'db_choice', description: 'Recommend a database', agent: junior)
+crew.add_task(task)
+
+result = crew.execute
+
+puts "process: #{result[:process]}"
+puts "consensus winner: #{result[:results].first[:result].inspect}"
+puts '(the answer weighing trade-offs scored higher and won)'

data/lib/rcrewai/crew.rb

@@ -22,6 +22,7 @@ module RCrewAI
       @planning = options.fetch(:planning, false)
       @planning_llm = options[:planning_llm]
       @planned = false
+      @consensus_agents = options.fetch(:consensus_agents, 3)
       @knowledge = build_knowledge(options[:knowledge], options[:knowledge_sources])
       @before_kickoff_hooks = []
       @after_kickoff_hooks = []
@@ -30,7 +31,7 @@ module RCrewAI
       validate_process_type!
     end
 
-    attr_reader :knowledge, :stream_sink, :last_inputs
+    attr_reader :knowledge, :stream_sink, :last_inputs, :consensus_agents
 
     def planning?
       @planning

data/lib/rcrewai/process.rb

@@ -373,23 +373,16 @@ module RCrewAI
       end
     end
 
+    # Multi-agent consensus: for each task, several agents propose candidate
+    # answers, all participants score each candidate, and the highest-scored
+    # candidate wins (ties break toward the task's assigned agent).
     class Consensual < Base
+      DEFAULT_CONSENSUS_AGENTS = 3
+
       def execute
         log_execution_start
-        @logger.info 'Consensual execution - agents collaborate on decisions'
-
-        # For now, implement as enhanced sequential with collaboration
-        # Full consensual process would involve agent voting/discussion
-        results = []
-
-        crew.tasks.each do |task|
-          @logger.info "Collaborative execution of task: #{task.name}"
-
-          # Simple consensus: let multiple agents provide input
-          consensus_result = execute_with_consensus(task)
-          results << consensus_result
-        end
-
+        @logger.info 'Consensual execution - agents propose, vote, and pick'
+        results = crew.tasks.map { |task| execute_with_consensus(task) }
         log_execution_end(results)
         results
       end
@@ -397,14 +390,89 @@ module RCrewAI
       private
 
       def execute_with_consensus(task)
-        # For now, just execute normally
-        # Future: implement actual consensus mechanisms
+        @logger.info "Consensus for task: #{task.name}"
+        participants = select_participants(task)
+        candidates = gather_proposals(task, participants)
 
-        result = task.execute
-        { task: task, result: result, status: :completed }
+        if candidates.empty?
+          return { task: task, result: 'All agents failed to produce a proposal', status: :failed }
+        end
+
+        scored = score_candidates(task, candidates, participants)
+        winner = pick_winner(task, scored)
+        task.result = winner[:content] if task.respond_to?(:result=)
+
+        { task: task, result: winner[:content], status: :completed }
       rescue StandardError => e
+        @logger.error "Consensus failed for #{task.name}: #{e.message}"
         { task: task, result: e.message, status: :failed }
       end
+
+      # First N agents, always including the task's assigned agent if present.
+      def select_participants(task)
+        cap = consensus_agent_cap
+        chosen = crew.agents.first(cap)
+        assigned = task.respond_to?(:agent) ? task.agent : nil
+        if assigned && crew.agents.include?(assigned) && !chosen.include?(assigned)
+          chosen = ([assigned] + chosen).first(cap)
+        end
+        chosen
+      end
+
+      def gather_proposals(task, participants)
+        participants.filter_map do |agent|
+          content = extract_content(agent.execute_task(task))
+          { agent: agent, content: content }
+        rescue StandardError => e
+          @logger.warn "Agent #{agent.name} failed to propose: #{e.message}"
+          nil
+        end
+      end
+
+      def score_candidates(task, candidates, participants)
+        candidates.map do |candidate|
+          total = participants.sum { |voter| score(voter, task, candidate[:content]) }
+          candidate.merge(score: total)
+        end
+      end
+
+      def score(voter, task, candidate_content)
+        prompt = <<~PROMPT
+          Score how well the following answer satisfies the task, from 0 to 10.
+          Reply with just the integer.
+
+          Task: #{task.description}
+          Expected output: #{task.respond_to?(:expected_output) ? task.expected_output : 'n/a'}
+
+          Answer:
+          #{candidate_content}
+        PROMPT
+        response = voter.llm_client.chat(messages: [{ role: 'user', content: prompt }])
+        parse_score(response.is_a?(Hash) ? response[:content] : response)
+      rescue StandardError
+        0
+      end
+
+      def pick_winner(task, scored)
+        assigned = task.respond_to?(:agent) ? task.agent : nil
+        scored.max_by { |c| [c[:score], c[:agent] == assigned ? 1 : 0] }
+      end
+
+      def parse_score(text)
+        match = text.to_s[/-?\d+/]
+        return 0 unless match
+
+        match.to_i.clamp(0, 10)
+      end
+
+      def extract_content(agent_result)
+        agent_result.is_a?(Hash) ? agent_result[:content].to_s : agent_result.to_s
+      end
+
+      def consensus_agent_cap
+        cap = crew.respond_to?(:consensus_agents) ? crew.consensus_agents : nil
+        [(cap || DEFAULT_CONSENSUS_AGENTS).to_i, 1].max
+      end
     end
 
     class ProcessError < RCrewAI::Error; end

data/lib/rcrewai/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RCrewAI
-  VERSION = '0.6.1'
+  VERSION = '0.7.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rcrewai
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.0
 platform: ruby
 authors:
 - gkosmo
@@ -357,6 +357,7 @@ files:
 - docs/superpowers/plans/2026-05-11-llm-modernization.md
 - docs/superpowers/specs/2026-05-11-llm-modernization-design.md
 - docs/superpowers/specs/2026-07-06-cognitive-memory-design.md
+- docs/superpowers/specs/2026-07-07-consensual-process-design.md
 - docs/tutorials/advanced-agents.md
 - docs/tutorials/custom-tools.md
 - docs/tutorials/deployment.md
@@ -366,8 +367,10 @@ files:
 - docs/upgrading-to-0.3.md
 - docs/upgrading-to-0.4.md
 - docs/upgrading-to-0.6.md
+- docs/upgrading-to-0.7.md
 - examples/async_execution_example.rb
 - examples/cognitive_memory_example.rb
+- examples/consensual_process_example.rb
 - examples/flow_example.rb
 - examples/hierarchical_crew_example.rb
 - examples/human_in_the_loop_example.rb