ai-consultants 2.10.1

package/scripts/debate_round.sh

@@ -0,0 +1,421 @@
+#!/bin/bash
+# debate_round.sh - Multi-Agent Debate (MAD) implementation for AI Consultants
+#
+# Implements deliberation rounds where consultants can see and
+# respond to each other's responses.
+#
+# Usage: ./debate_round.sh <responses_dir> <round_number> <output_dir>
+#
+# Round 1: Initial responses (handled by consult_all.sh)
+# Round 2: Cross-critique - each consultant sees other responses
+# Round 3: Final stance - final position after seeing critiques
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/lib/common.sh"
+source "$SCRIPT_DIR/lib/personas.sh"
+source "$SCRIPT_DIR/config.sh" 2>/dev/null || log_warn "config.sh not loaded (using defaults)"
+
+# =============================================================================
+# DEBATE OPTIMIZATION (v2.3)
+# =============================================================================
+
+# Check if category requires mandatory debate (v2.3 Quality Review)
+# Usage: is_mandatory_debate_category <category>
+is_mandatory_debate_category() {
+    local category="${1:-GENERAL}"
+    case "$category" in
+        SECURITY|ARCHITECTURE)
+            return 0  # Mandatory debate
+            ;;
+        *)
+            return 1  # Not mandatory
+            ;;
+    esac
+}
+
+# Check if debate should be skipped based on confidence spread
+# Usage: should_skip_debate <responses_dir> [category]
+should_skip_debate() {
+    local responses_dir="$1"
+    local category="${2:-GENERAL}"
+
+    # SECURITY and ARCHITECTURE always require debate (v2.3 Quality Review)
+    if is_mandatory_debate_category "$category"; then
+        return 1  # Don't skip - mandatory categories always debate
+    fi
+
+    # Skip if debate optimization is not enabled
+    if [[ "${ENABLE_DEBATE_OPTIMIZATION:-false}" != "true" ]]; then
+        return 1  # Don't skip
+    fi
+
+    local threshold="${DEBATE_CONFIDENCE_SPREAD_THRESHOLD:-3}"
+    local min_confidence=10
+    local max_confidence=0
+    local count=0
+
+    for f in "$responses_dir"/*.json; do
+        if [[ -f "$f" && "$f" != *"summary"* && "$f" != *"round_"* ]]; then
+            local confidence
+            confidence=$(jq -r '.confidence.score // 5' "$f" 2>/dev/null)
+            if [[ "$confidence" =~ ^[0-9]+$ ]]; then
+                [[ $confidence -lt $min_confidence ]] && min_confidence=$confidence
+                [[ $confidence -gt $max_confidence ]] && max_confidence=$confidence
+                ((count++)) || true
+            fi
+        fi
+    done
+
+    if [[ $count -lt 2 ]]; then
+        return 1  # Not enough responses to evaluate
+    fi
+
+    local spread=$((max_confidence - min_confidence))
+    if [[ $spread -lt $threshold ]]; then
+        log_debug "Debate optimization: Skipping debate (confidence spread: $spread < threshold: $threshold)"
+        return 0  # Skip debate
+    fi
+
+    return 1  # Don't skip
+}
+
+# Extract compact summary for token-optimized debate
+# Usage: extract_compact_summary <response_file>
+extract_compact_summary() {
+    local response_file="$1"
+
+    if [[ "${DEBATE_USE_SUMMARIES:-true}" == "true" ]]; then
+        # Use only summary field (compact)
+        local consultant=$(jq -r '.consultant // "Unknown"' "$response_file" 2>/dev/null)
+        local summary=$(jq -r '.response.summary // "No summary"' "$response_file" 2>/dev/null | head -c 300)
+        local approach=$(jq -r '.response.approach // "unknown"' "$response_file" 2>/dev/null)
+        local confidence=$(jq -r '.confidence.score // 5' "$response_file" 2>/dev/null)
+
+        echo "**$consultant** ($approach, conf:$confidence): $summary"
+    else
+        # Use full extract_summary (original behavior)
+        extract_summary "$response_file"
+    fi
+}
+
+# --- Parameters ---
+RESPONSES_DIR="${1:-}"
+ROUND_NUMBER="${2:-2}"
+OUTPUT_DIR="${3:-}"
+QUESTION_CATEGORY="${4:-GENERAL}"  # v2.3: Category for mandatory debate check
+
+if [[ ! "$ROUND_NUMBER" =~ ^[0-9]+$ ]] || [[ "$ROUND_NUMBER" -lt 1 ]]; then
+    log_error "Invalid round number: $ROUND_NUMBER (must be a positive integer)"
+    exit 1
+fi
+
+if [[ -z "$RESPONSES_DIR" || ! -d "$RESPONSES_DIR" ]]; then
+    log_error "Usage: $0 <responses_dir> <round_number> [output_dir] [category]"
+    exit 1
+fi
+
+if [[ -z "$OUTPUT_DIR" ]]; then
+    OUTPUT_DIR="$RESPONSES_DIR/round_${ROUND_NUMBER}"
+fi
+
+mkdir -p "$OUTPUT_DIR"
+
+log_info "=== Multi-Agent Debate - Round $ROUND_NUMBER ==="
+
+# =============================================================================
+# HELPER FUNCTIONS
+# =============================================================================
+
+# Extract summary from a response for the debate prompt
+extract_summary() {
+    local response_file="$1"
+    local consultant=$(jq -r '.consultant // "Unknown"' "$response_file" 2>/dev/null)
+    local summary=$(jq -r '.response.summary // .response.detailed[:500] // "No summary"' "$response_file" 2>/dev/null)
+    local approach=$(jq -r '.response.approach // "unknown"' "$response_file" 2>/dev/null)
+    local confidence=$(jq -r '.confidence.score // 5' "$response_file" 2>/dev/null)
+
+    echo "**$consultant** (Approach: $approach, Confidence: $confidence/10):
+$summary"
+}
+
+# Build prompt for debate round
+build_debate_prompt() {
+    local consultant="$1"
+    local my_response_file="$2"
+    local responses_dir="$3"
+
+    local my_response=$(cat "$my_response_file" 2>/dev/null)
+
+    # Validate response JSON before using in debate prompt
+    if [[ -z "$my_response" ]] || ! echo "$my_response" | jq -e '.' > /dev/null; then
+        log_warn "Invalid or empty previous response for $consultant, using fallback"
+        my_response='{"response":{"summary":"No summary","approach":"unknown"},"confidence":{"score":5}}'
+    fi
+
+    local other_summaries=""
+
+    # Collect summaries from other consultants (using compact summaries when optimized)
+    for f in "$responses_dir"/*.json; do
+        if [[ -f "$f" && "$f" != *"summary"* && "$f" != *"round_"* ]]; then
+            local other_consultant=$(jq -r '.consultant // "Unknown"' "$f" 2>/dev/null)
+            if [[ "$other_consultant" != "$consultant" ]]; then
+                other_summaries+="
+$(extract_compact_summary "$f")
+---
+"
+            fi
+        fi
+    done
+
+    cat << EOF
+# Round $ROUND_NUMBER - Cross-Critique
+
+## Your Previous Response (Round $((ROUND_NUMBER - 1)))
+$(echo "$my_response" | jq -r '.response.summary // "No summary"' 2>/dev/null)
+
+Approach: $(echo "$my_response" | jq -r '.response.approach // "unknown"' 2>/dev/null)
+Confidence: $(echo "$my_response" | jq -r '.confidence.score // 5' 2>/dev/null)/10
+
+## Other Consultants' Responses
+$other_summaries
+
+## Instructions
+
+After seeing the opinions of other consultants, respond in JSON:
+
+{
+  "debate": {
+    "round": $ROUND_NUMBER,
+    "position_changed": <true if you changed your mind, false otherwise>,
+    "original_stance": "<your original position>",
+    "updated_stance": "<your new position or confirmation of previous>",
+    "confidence_delta": <confidence change: -3 to +3>,
+    "critiques": [
+      {
+        "target": "<consultant name>",
+        "critique": "<your critique>",
+        "severity": "<minor|moderate|major>"
+      }
+    ],
+    "incorporated_from": [
+      {
+        "source": "<consultant name>",
+        "idea": "<what you incorporated>"
+      }
+    ],
+    "areas_of_agreement": ["<points you agree with others on>"],
+    "areas_of_disagreement": ["<points you disagree on>"]
+  },
+  "response": {
+    "summary": "<updated summary if position_changed, otherwise confirmation>",
+    "detailed": "<updated details>",
+    "approach": "<updated or confirmed approach>",
+    "pros": ["<updated pros>"],
+    "cons": ["<updated cons>"]
+  },
+  "confidence": {
+    "score": <new score 1-10>,
+    "reasoning": "<why this confidence level after debate>"
+  }
+}
+
+IMPORTANT: Respond ONLY with valid JSON. Be honest - if others have valid points, acknowledge them.
+EOF
+}
+
+# =============================================================================
+# MAIN DEBATE EXECUTION
+# =============================================================================
+
+run_debate_round() {
+    # Use shared function to get enabled consultants
+    local consultants_str
+    consultants_str=$(get_enabled_consultants)
+    # shellcheck disable=SC2206
+    local consultants=($consultants_str)
+
+    local pids=()
+    local output_files=()
+    local consultant_names=()
+
+    log_info "Starting debate round $ROUND_NUMBER for ${#consultants[@]} consultants..."
+
+    for consultant in "${consultants[@]}"; do
+        local consultant_lower
+        consultant_lower=$(to_lower "$consultant")
+        local response_file="$RESPONSES_DIR/${consultant_lower}.json"
+
+        # Skip if no previous round response
+        if [[ ! -f "$response_file" || ! -s "$response_file" ]]; then
+            log_warn "$consultant: no previous response, skipping"
+            continue
+        fi
+
+        local output_file="$OUTPUT_DIR/${consultant_lower}.json"
+        output_files+=("$output_file")
+
+        # Build debate prompt
+        local debate_prompt=$(build_debate_prompt "$consultant" "$response_file" "$RESPONSES_DIR")
+
+        # Execute query in background
+        (
+            local start_time
+            start_time=$(get_timestamp_ms)
+
+            # Route to appropriate query script based on consultant
+            case "$consultant" in
+                Gemini)
+                    echo "$debate_prompt" | "$SCRIPT_DIR/query_gemini.sh" "" "" "$output_file" > /dev/null
+                    ;;
+                Codex)
+                    "$SCRIPT_DIR/query_codex.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Mistral)
+                    "$SCRIPT_DIR/query_mistral.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Kilo)
+                    "$SCRIPT_DIR/query_kilo.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Cursor)
+                    "$SCRIPT_DIR/query_cursor.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Aider)
+                    "$SCRIPT_DIR/query_aider.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Claude)
+                    "$SCRIPT_DIR/query_claude.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Qwen3)
+                    "$SCRIPT_DIR/query_qwen3.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                GLM)
+                    "$SCRIPT_DIR/query_glm.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Grok)
+                    "$SCRIPT_DIR/query_grok.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                DeepSeek)
+                    "$SCRIPT_DIR/query_deepseek.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Ollama)
+                    "$SCRIPT_DIR/query_ollama.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Amp)
+                    "$SCRIPT_DIR/query_amp.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                Kimi)
+                    "$SCRIPT_DIR/query_kimi.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                MiniMax)
+                    "$SCRIPT_DIR/query_minimax.sh" "$debate_prompt" "" "$output_file" > /dev/null
+                    ;;
+                *)
+                    log_error "Unknown consultant in debate round: $consultant (no query script mapped)"
+                    exit 1
+                    ;;
+            esac
+
+            local end_time
+            end_time=$(get_timestamp_ms)
+            local latency=$((end_time - start_time))
+
+            # Add debate metadata to result
+            if [[ -f "$output_file" && -s "$output_file" ]]; then
+                local temp_file=$(mktemp)
+                if jq --argjson round "$ROUND_NUMBER" \
+                      --argjson latency "$latency" \
+                      '. + {debate_round: $round, debate_latency_ms: $latency}' \
+                      "$output_file" > "$temp_file"; then
+                    mv "$temp_file" "$output_file"
+                else
+                    log_warn "Failed to add debate metadata for $consultant"
+                    rm -f "$temp_file"
+                fi
+            fi
+        ) 2>"$OUTPUT_DIR/${consultant_lower}.err" &
+
+        pids+=($!)
+        consultant_names+=("$consultant")
+    done
+
+    # Wait for all jobs
+    local success_count=0
+    for i in "${!pids[@]}"; do
+        local cname="${consultant_names[$i]}"
+        local cname_lower
+        cname_lower=$(to_lower "$cname")
+        local err_file="$OUTPUT_DIR/${cname_lower}.err"
+        if wait "${pids[$i]}" 2>/dev/null; then
+            ((success_count++)) || true
+        else
+            log_warn "Debate round $ROUND_NUMBER: $cname failed"
+            if [[ -s "$err_file" ]]; then
+                log_debug "  Error details: $(head -c 200 "$err_file")"
+            fi
+        fi
+        # Clean up empty error logs
+        [[ -f "$err_file" && ! -s "$err_file" ]] && rm -f "$err_file"
+    done
+
+    log_success "Debate round $ROUND_NUMBER completed: $success_count/${#pids[@]} responses"
+
+    # Generate round summary
+    generate_round_summary
+}
+
+# Generate debate round summary
+generate_round_summary() {
+    local summary_file="$OUTPUT_DIR/round_summary.json"
+
+    local position_changes=0
+    local total_critiques=0
+    local consultants_responded=0
+
+    for f in "$OUTPUT_DIR"/*.json; do
+        if [[ -f "$f" && "$f" != *"summary"* ]]; then
+            ((consultants_responded++)) || true
+
+            local changed=$(jq -r '.debate.position_changed // false' "$f" 2>/dev/null)
+            if [[ "$changed" == "true" ]]; then
+                ((position_changes++)) || true
+            fi
+
+            local critiques=$(jq -r '.debate.critiques | length // 0' "$f" 2>/dev/null)
+            total_critiques=$((total_critiques + critiques))
+        fi
+    done
+
+    jq -n \
+        --argjson round "$ROUND_NUMBER" \
+        --argjson responded "$consultants_responded" \
+        --argjson changes "$position_changes" \
+        --argjson critiques "$total_critiques" \
+        --arg timestamp "$(date -Iseconds)" \
+        '{
+            round: $round,
+            timestamp: $timestamp,
+            consultants_responded: $responded,
+            position_changes: $changes,
+            total_critiques: $critiques,
+            stability: (if $changes == 0 then "stable" elif $changes <= 1 then "mostly_stable" else "volatile" end)
+        }' > "$summary_file"
+
+    log_info "Round summary saved: $summary_file"
+}
+
+# =============================================================================
+# ENTRY POINT
+# =============================================================================
+
+# Check if debate should be skipped based on confidence spread (v2.3)
+if [[ "$ROUND_NUMBER" == "2" ]] && should_skip_debate "$RESPONSES_DIR" "$QUESTION_CATEGORY"; then
+    log_info "Debate skipped: confidence spread below threshold (all consultants agree)"
+    echo '{"skipped": true, "reason": "confidence_spread_below_threshold"}' > "$OUTPUT_DIR/round_summary.json"
+    echo "$OUTPUT_DIR"
+    exit 0
+fi
+
+run_debate_round
+echo "$OUTPUT_DIR"