mindX Augmentic Intelligence: Human-in-the-Loop (HITL) for Strategic Evolution Vision: The mindX system is designed for autonomous self-improvement and strategic evolution, driven by its MastermindAgent and CoordinatorAgent. However, true Augmentic Intelligence recognizes the value of human oversight, especially when dealing with critical system modifications or high-impact decisions. The Human-in-the-Loop (HITL) mechanism provides a crucial control point, balancing autonomy with safety and strategic alignment. Core Principle: HITL in mindX is not just a simple approval gate; it's an opportunity for human expertise to guide, validate, and course-correct the AI's evolutionary trajectory. It allows the system to operate autonomously for routine or well-understood improvements while escalating potentially high-risk or strategically ambiguous changes for human review.

HITL Trigger Points and Rationale

HITL is primarily invoked by the CoordinatorAgent during its autonomous improvement loop when processing its improvement_backlog. A backlog item is flagged for HITL under these conditions: Critical Component Modification: If the target_component_path of an improvement suggestion (either generated by the Coordinator's own analysis, Mastermind's directives, or other sources) matches an entry in the coordinator.autonomous_improvement.critical_components list defined in the system configuration (e.g., data/config/basegen_config.json). Rationale: Changes to core agents like SelfImprovementAgent, CoordinatorAgent, MastermindAgent, or critical utility/core modules can have system-wide, potentially destabilizing effects. Human review ensures these changes are sound before automated application.

Example Config:

// In data/config/basegen_config.json
"coordinator": {
  "autonomous_improvement": {
    "enabled": true,
    "critical_components": [
      "learning.self_improve_agent",      // The SIA itself
      "orchestration.coordinator_agent",  // The Coordinator
      "orchestration.mastermind_agent", // Mastermind is critical
      "core.bdi_agent",                 // Core reasoning engine
      "utils.config"                    // Central configuration loading
    ],
    "require_human_approval_for_critical": true // Master switch for HITL
  }
}

Explicit is_critical_target: true Flag: An improvement suggestion itself (e.g., generated by Mastermind's strategic assessment or Coordinator's LLM analysis) can be flagged with is_critical_target: true. Rationale: The AI, during its analysis, might determine that even if a component isn't on the global "critical" list, a specific proposed change to it carries high risk or strategic importance.

Example Backlog Item Snippet (Conceptual):

{
  "id": "suggestion_xyz",
  "target_component_path": "tools.experimental_new_tool",
  "suggestion": "Refactor tool to use a more efficient algorithm X, potentially impacting dependent services.",
  "priority": 8,
  "is_critical_target": true, // AI flagged this as needing review
  "status": "pending"
}

Low Confidence / Ambiguity (Future Extension): The system could be extended so that if an LLM (either in Mastermind, Coordinator, or SIA) generates a proposal or code modification with low confidence, or if multiple LLMs disagree on a course of action, it could automatically flag the item for HITL. The HITL Workflow within mindX Orchestration When the CoordinatorAgent._autonomous_improvement_worker() selects a backlog item that meets HITL criteria: Status Change: Instead of directly initiating a COMPONENT_IMPROVEMENT interaction with SIA, the Coordinator updates the backlog item's status from PENDING to PENDING_APPROVAL. logger.warning(f"Autonomous: CRITICAL improve for {target_path} (ID {item_id}) needs approval. Suggestion: {item_suggestion}") Notification (Conceptual): While not explicitly implemented in the current code, a production system would ideally trigger notifications to human operators (e.g., via email, Slack, dashboard alert) that an item requires review. Human Review & Action (via CLI): The human operator uses the mindX CLI to: View the backlog: coord_backlog (items needing approval will be evident by their status). Inspect the item: The backlog item contains the target_component_path, the suggestion (which is the context SIA will use), and potentially details from SIA if a change was already drafted but needs approval before application (see SIA's SUCCESS_NEEDS_APPROVAL output).

Make a decision:

coord_approve : The CoordinatorAgent._process_backlog_approval() method changes the item's status back to PENDING and records the approval. The autonomous loop can now pick up this item in its next cycle and proceed with tasking SIA. coord_reject : The CoordinatorAgent._process_backlog_approval() method changes the item's status to rejected_manual (or a similar terminal state). The autonomous loop will ignore this item. Mastermind or other strategic processes might later re-evaluate why it was rejected. SIA Execution & Post-Approval: If approved, the Coordinator tasks SIA as usual. SIA's SUCCESS_NEEDS_APPROVAL Output: The SelfImprovementAgent itself can be designed to make a change, test it, but not automatically promote it if it deems the change critical (e.g., modifying its own core logic or a sensitive file). In such cases, SIA would output a status like SUCCESS_NEEDS_APPROVAL along with paths to the diff and the proposed new code. The CoordinatorAgent (in _process_component_improvement_cli) recognizes this SIA output. If the target was a critical component, it would then update the original backlog item (or create a new one) with status PENDING_APPROVAL and include the diff/new code paths in the approval_details. This allows the human to review the actual proposed code change before it's applied.

Setting Up for Autonomous Augmentic Intelligence with HITL

To configure mindX for autonomous operation with HITL safeguards: Configuration (data/config/basegen_config.json):

{
  // ... other configurations ...
  "coordinator": {
    "llm": {
      "provider": "gemini", // Or your preferred LLM for Coordinator
      "model": "gemini-1.5-flash-latest"
    },
    "autonomous_improvement": {
      "enabled": true, // ** KEY: Set to true to enable autonomous loop **
      "interval_seconds": 3600, // How often the Coordinator checks the backlog (e.g., 1 hour)
      "cooldown_seconds_after_failure": 7200, // How long to wait before retrying a failed item on the same component
      "max_cpu_before_sia": 85.0, // Don't start SIA tasks if system CPU is above this
      "critical_components": [ // List of Python module paths (package.module_stem)
        "learning.self_improve_agent",
        "orchestration.coordinator_agent",
        "orchestration.mastermind_agent",
        "core.bdi_agent",
        "core.belief_system",
        "utils.config",
        "utils.logging_config",
        "llm.llm_factory"
        // Add any other components considered critical
      ],
      "require_human_approval_for_critical": true // ** KEY: Set to true for HITL on criticals **
    },
    "max_concurrent_sia_tasks": 1, // How many SIA processes can run at once
    "sia_cli_timeout_seconds": 600, // Timeout for SIA operations (e.g., 10 minutes)
    "sia_rollback_timeout_seconds": 120
  },
  "mastermind_agent": {
    "autonomous_loop": {
        "enabled": true, // ** Enable Mastermind's own strategic loop **
        "interval_seconds": 14400, // e.g., every 4 hours
        "default_directive": "Proactively monitor mindX, assess tool suite effectiveness, identify strategic evolutionary opportunities for components and tools, and initiate campaigns to enhance overall system health, capabilities, and efficiency based on current state and long-term goals."
    }
  }
  // ... other configurations ...
}

Workflow for the Human Operator:

Start the System:

python3 scripts/run_mindx.py

Monitor Logs: Keep an eye on the console output or the log file (data/logs/mindx_debug.log if configured) for: Coordinator: Autonomous improvement loop started. Mastermind: Autonomous loop started. Messages from _autonomous_improvement_worker indicating it's analyzing the system or processing backlog items. Crucially, warnings like: Autonomous: CRITICAL improvement for 'learning.self_improve_agent' (ID abcdef12) requires human approval. Suggestion: Enhance self-test coverage. Check Backlog Regularly: mindX (Mastermind) > coord_backlog Look for items with status PENDING_APPROVAL. Review Pending Approvals: Note the id, target_component_path, and suggestion. If the suggestion came from an SIA run that produced code but held back promotion (due to SUCCESS_NEEDS_APPROVAL), the backlog item (or a linked interaction) should contain paths to the diff file or the proposed new code. The human operator would then manually inspect these files. Decision Criteria: Does the suggested improvement align with strategic goals? Is the target component indeed critical? Is the proposed change (if a diff is available) understandable, safe, and likely to achieve the desired outcome? What are the potential risks if this change is applied incorrectly? Approve or Reject: mindX (Mastermind) > coord_approve mindX (Mastermind) > coord_reject Observe Post-Approval: If approved, the Coordinator's autonomous loop should pick up the item in a subsequent cycle and initiate the SIA task. Monitor the logs for the outcome of that SIA task. Example Scenario: Autonomous Augmentic Intelligence with HITL Mastermind's autonomous loop runs ASSESS_TOOL_SUITE_EFFECTIVENESS. Its LLM identifies that the BaseGenAgent tool, while useful, could be enhanced to support PlantUML diagram generation from code structure. It creates a high-priority "ENHANCE_EXISTING_TOOL" recommendation for tools.base_gen_agent. Mastermind's BDI then creates a goal to "Enhance BaseGenAgent with PlantUML generation." Its plan involves: CONCEPTUALIZE_NEW_TOOL (but focused on enhancing BaseGenAgent): Generates a detailed spec for the PlantUML feature, including required new methods in BaseGenAgent, and how its CLI might be extended. The LLM marks this as is_critical_target: true because BaseGenAgent is now considered important for Mastermind's own analysis. INITIATE_TOOL_CODING_CAMPAIGN: Mastermind tasks Coordinator to improve tools.base_gen_agent.py based on this spec. Coordinator's autonomous loop picks up this task from Mastermind (which would appear as a high-priority item in its backlog, perhaps added via an internal add_to_improvement_backlog call made by Mastermind via a BDI action that interacts with Coordinator). Coordinator sees target_component_path: "tools.base_gen_agent" and the (hypothetical) is_critical_target: true flag from the Mastermind-generated suggestion. Because require_human_approval_for_critical is true, Coordinator sets the backlog item for "Enhance BaseGenAgent with PlantUML" to PENDING_APPROVAL. Logs a warning. Human operator sees the warning/checks coord_backlog. Reviews the specification (which was the suggestion / analysis_context for the backlog item). Decides it's a good idea. Human operator types: coord_approve Coordinator's autonomous loop now sees the item as PENDING. It tasks SIA: python learning/self_improve_agent.py /path/to/tools/base_gen_agent.py --context "Add PlantUML generation capability based on this spec: {spec_json}" --output-json SIA works on base_gen_agent.py. If it modifies a core part of its own logic or the change is complex, its internal evaluation might decide the change is SUCCESS_NEEDS_APPROVAL. It outputs JSON indicating this, along with the path to the modified code and diff. Coordinator receives SIA's response. Sees SUCCESS_NEEDS_APPROVAL. It updates the backlog item's status again to PENDING_APPROVAL, this time adding the diff/new code path information to the item's approval_details. Human operator is notified again (or checks coord_backlog). Now they can review the actual code changes proposed by SIA. If the code looks good, human operator types: coord_approve again. Coordinator now needs a mechanism to tell SIA to apply the previously generated and now approved changes. This might involve SIA having a mode to apply a change from a specific iteration directory, or Coordinator managing the file promotion. (This detail needs refinement in SIA/Coordinator interaction for "approve after code review".) Alternative: If SIA's initial SUCCESS_NEEDS_APPROVAL means "I've made the change in a temp location, human must manually copy it", then the human's coord_approve simply marks the backlog item as COMPLETED_SUCCESS (from HITL perspective), assuming the human did the manual promotion. The system needs clarity on who does the final code promotion after HITL code review. Ideally, SIA can be re-invoked to promote an approved change. This detailed HITL workflow allows mindX to leverage powerful autonomous capabilities while retaining human strategic control and safety, truly aiming for an "Augmentic" form of intelligence. This INSTRUCTIONS.md provides a conceptual and practical guide to the HITL mechanism. The key is the configuration in basegen_config.json and the PENDING_APPROVAL status in the CoordinatorAgent's backlog flow.

---

Referenced in this document

INSTRUCTIONS

---

All DocumentsDocument IndexThe Book of mindXImprovement JournalAPI Reference