feat: Implement Agile Factory, Deep Agents, and Prompt Management enhancements

Author: gitwalter

.gitignore

@@ -170,6 +170,7 @@ test_results/
 
 # Generated project directories
 generated_projects/
+agile_factory_workspace/
 generated/
 output/
 temp/

agents/agile_factory/__init__.py

@@ -0,0 +1,8 @@
+"""
+Agile Software Factory Agent System
+
+A comprehensive multi-agent system for generating interactive websites and Streamlit apps.
+"""
+
+__version__ = "0.1.0"
+

agents/agile_factory/hitl/__init__.py

@@ -0,0 +1,2 @@
+"""Human-in-the-loop checkpoint implementations."""
+

agents/agile_factory/hitl/hitl_checkpoints.py

@@ -0,0 +1,164 @@
+"""
+Human-in-the-loop checkpoint implementations.
+
+Provides structured HITL checkpoints between workflow stages.
+"""
+
+import logging
+from typing import Dict, Any
+from agents.agile_factory.state.agile_state import AgileFactoryState
+
+logger = logging.getLogger(__name__)
+
+
+def create_checkpoint_summary(state: AgileFactoryState, checkpoint_name: str) -> Dict[str, Any]:
+    """
+    Create structured summary for human review at checkpoint.
+    
+    Args:
+        state: Current workflow state
+        checkpoint_name: Name of checkpoint
+        
+    Returns:
+        Structured summary dictionary
+    """
+    summary = {
+        "checkpoint": checkpoint_name,
+        "timestamp": None,  # Will be set by caller if needed
+        "status": state.get("status", "processing")
+    }
+    
+    if checkpoint_name == "story_review":
+        summary.update({
+            "what": "User Story Input",
+            "content": state.get("user_story", ""),
+            "project_type": state.get("project_type", "website")
+        })
+    
+    elif checkpoint_name == "requirements_review":
+        requirements = state.get("requirements", {})
+        summary.update({
+            "what": "Requirements Analysis",
+            "summary": requirements.get("summary", ""),
+            "functional_count": len(requirements.get("functional_requirements", [])),
+            "non_functional_count": len(requirements.get("non_functional_requirements", []))
+        })
+    
+    elif checkpoint_name == "architecture_review":
+        architecture = state.get("architecture", {})
+        summary.update({
+            "what": "Architecture Design",
+            "system_overview": architecture.get("system_overview", "")[:500],
+            "architecture_pattern": architecture.get("architecture_pattern", ""),
+            "components_count": len(architecture.get("components", [])),
+            "tech_stack": architecture.get("technology_stack", {})
+        })
+    
+    elif checkpoint_name == "code_generation_review":
+        code_files = state.get("code_files", {})
+        summary.update({
+            "what": "Code Generation",
+            "files_generated": len(code_files),
+            "file_list": list(code_files.keys())[:10],  # First 10 files
+            "total_size": sum(len(content) for content in code_files.values())
+        })
+    
+    elif checkpoint_name == "final_review":
+        summary.update({
+            "what": "Final Project Review",
+            "requirements_complete": bool(state.get("requirements")),
+            "architecture_complete": bool(state.get("architecture")),
+            "code_complete": bool(state.get("code_files")),
+            "tests_complete": bool(state.get("test_results")),
+            "docs_complete": bool(state.get("documentation_files"))
+        })
+    
+    return summary
+
+
+def print_summary(summary: Dict[str, Any]) -> None:
+    """
+    Print checkpoint summary to console.
+    
+    Args:
+        summary: Summary dictionary
+    """
+    print(f"\n{summary.get('what', 'Checkpoint')}:")
+    print("-" * 60)
+    
+    for key, value in summary.items():
+        if key not in ["checkpoint", "what", "timestamp"]:
+            if isinstance(value, dict):
+                print(f"{key}:")
+                for k, v in value.items():
+                    print(f"  {k}: {v}")
+            elif isinstance(value, list):
+                print(f"{key}: {len(value)} items")
+                if value and len(value) <= 5:
+                    for item in value:
+                        print(f"  - {item}")
+            else:
+                print(f"{key}: {value}")
+
+
+def hitl_checkpoint_node(state: AgileFactoryState, checkpoint_name: str) -> dict:
+    """
+    Generic HITL checkpoint node.
+    
+    This node presents a checkpoint summary to the human reviewer and
+    collects their decision (approve/reject/edit).
+    
+    Args:
+        state: Current workflow state
+        checkpoint_name: Name of checkpoint
+        
+    Returns:
+        Updates dict with HITL feedback (LangGraph will merge with state)
+    """
+    # Create structured summary
+    summary = create_checkpoint_summary(state, checkpoint_name)
+    
+    # Present to human (console for MVP, Streamlit UI later)
+    print("\n" + "="*60)
+    print(f"HITL CHECKPOINT: {checkpoint_name.upper().replace('_', ' ')}")
+    print("="*60)
+    print_summary(summary)
+    print("\nOptions:")
+    print("  [a]pprove - Continue to next step")
+    print("  [r]eject - Restart from beginning")
+    print("  [e]dit - Provide feedback for revision")
+    print("  [s]kip - Skip this checkpoint (not recommended)")
+    
+    # Get human input
+    # For LangGraph Studio, this will be handled via interrupt
+    # For now, we'll set a default and let Studio handle the interrupt
+    feedback = "approve"  # Default for automated testing
+    
+    # In LangGraph Studio, this will be an interrupt point
+    # The human will provide feedback through Studio UI
+    
+    # Build updates dict (correct LangGraph pattern - return only updates)
+    # Merge with existing hitl_approvals and hitl_feedback from state
+    existing_approvals = state.get("hitl_approvals", {}).copy()
+    existing_feedback = state.get("hitl_feedback", {}).copy()
+    
+    existing_approvals[checkpoint_name] = feedback == "approve"
+    existing_feedback[checkpoint_name] = feedback
+    
+    updates = {
+        "current_checkpoint": checkpoint_name,
+        "hitl_approvals": existing_approvals,
+        "hitl_feedback": existing_feedback
+    }
+    
+    if feedback == "approve":
+        updates["status"] = "approved"
+    elif feedback == "reject":
+        updates["status"] = "rejected"
+    elif feedback == "edit":
+        updates["status"] = "needs_revision"
+    
+    logger.info("HITL checkpoint %s: %s", checkpoint_name, feedback)
+    
+    return updates
+

agents/agile_factory/nodes/__init__.py

@@ -0,0 +1,2 @@
+"""Agent nodes for Agile Factory workflow."""
+

agents/agile_factory/nodes/architecture_node.py

@@ -0,0 +1,167 @@
+"""
+Architecture Designer Node for Agile Factory workflow.
+
+Uses existing architecture_designer agent with prompt loader.
+"""
+
+import logging
+import os
+import re
+from typing import Dict, Any
+from agents.agile_factory.state.agile_state import AgileFactoryState
+from agents.agile_factory.utils.safe_prompt_formatting import safe_format_prompt, safe_format_prompt_with_validation
+from agents.agile_factory.utils.llm_config import get_llm_model
+from prompts import get_agent_prompt_loader
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_core.messages import SystemMessage, HumanMessage
+
+logger = logging.getLogger(__name__)
+
+
+def architecture_node(state: AgileFactoryState) -> dict:
+    """
+    Architecture Designer Node using existing agent with prompt loader.
+    
+    This node:
+    1. Loads prompt using existing get_agent_prompt_loader system
+    2. Creates LLM with Gemini 2.5 Flash
+    3. Executes architecture design
+    4. Returns updates dict with architecture (LangGraph will merge with state)
+    
+    Args:
+        state: Current workflow state
+        
+    Returns:
+        Updates dict with architecture design (LangGraph will merge with state)
+    """
+    try:
+        # Get API key
+        api_key = os.environ.get('GEMINI_API_KEY') or os.environ.get('GOOGLE_API_KEY')
+        if not api_key:
+            raise ValueError("GEMINI_API_KEY or GOOGLE_API_KEY environment variable must be set")
+        
+        # Prepare context for architecture design
+        user_story = state.get("user_story", "")
+        requirements = state.get("requirements", {})
+        project_type = state.get("project_type", "website")
+        
+        # Load prompt using existing system and inject dynamic context
+        prompt_loader = get_agent_prompt_loader("architecture_designer_v1")
+        system_prompt_template = prompt_loader.get_system_prompt()
+        
+        # Ensure prompt is a string (not PromptTemplate object)
+        if not isinstance(system_prompt_template, str):
+            logger.warning(f"Prompt is not a string (type: {type(system_prompt_template)}), converting...")
+            if hasattr(system_prompt_template, 'template'):
+                system_prompt_template = system_prompt_template.template
+            else:
+                system_prompt_template = str(system_prompt_template)
+        
+        # Validate prompt was loaded
+        if not system_prompt_template or len(system_prompt_template.strip()) == 0:
+            error_msg = "Failed to load system prompt template - prompt is empty"
+            logger.error(error_msg)
+            return {
+                "errors": state.get("errors", []) + [error_msg],
+                "status": "error",
+                "current_node": "architecture_designer"
+            }
+        
+        logger.info(f"Loaded prompt template: {len(system_prompt_template)} characters (type: {type(system_prompt_template).__name__})")
+        
+        # Format system prompt with dynamic context using safe formatting
+        try:
+            # Convert requirements dict to string for formatting
+            requirements_str = str(requirements) if isinstance(requirements, dict) else requirements
+            system_prompt, missing_placeholders = safe_format_prompt_with_validation(
+                system_prompt_template,
+                user_story=user_story,
+                requirements=requirements_str,
+                project_type=project_type
+            )
+            
+            if missing_placeholders:
+                logger.warning(f"Some placeholders not replaced: {missing_placeholders}")
+            
+            logger.info(f"Formatted prompt: {len(system_prompt)} characters")
+        except Exception as e:
+            error_msg = f"Prompt formatting failed: {e}"
+            logger.error(error_msg, exc_info=True)
+            return {
+                "errors": state.get("errors", []) + [error_msg],
+                "status": "error",
+                "current_node": "architecture_designer"
+            }
+        
+        # Create LLM with configurable model
+        model_name = get_llm_model(state)
+        logger.info(f"Using LLM model: {model_name}")
+        llm = ChatGoogleGenerativeAI(
+            model=model_name,
+            google_api_key=api_key,
+            temperature=0,
+            convert_system_message_to_human=True
+        )
+        
+        # Task message is now embedded in the system prompt, so we use a simple instruction
+        task = "Design the architecture for the project based on the requirements provided."
+        
+        # Execute architecture design
+        messages = [
+            SystemMessage(content=system_prompt),
+            HumanMessage(content=task)
+        ]
+        
+        logger.info("Calling LLM for architecture design...")
+        result = llm.invoke(messages)
+        logger.info(f"LLM response received: {len(result.content) if hasattr(result, 'content') else 'N/A'} characters")
+        output = result.content.strip()
+        
+        # Parse JSON response (architecture_designer outputs JSON)
+        import json
+        import re
+        
+        # Extract JSON from markdown code block if present
+        json_match = re.search(r'```json\s*(\{.*\})\s*```', output, re.DOTALL)
+        if json_match:
+            json_str = json_match.group(1)
+        else:
+            # Try to find JSON object boundaries
+            first_brace = output.find('{')
+            if first_brace != -1:
+                brace_count = 0
+                json_start = first_brace
+                for i, char in enumerate(output[first_brace:], start=first_brace):
+                    if char == '{':
+                        brace_count += 1
+                    elif char == '}':
+                        brace_count -= 1
+                        if brace_count == 0:
+                            json_str = output[json_start:i+1]
+                            break
+                else:
+                    json_str = output[first_brace:]
+            else:
+                json_str = output
+        
+        # Clean trailing commas
+        json_str = re.sub(r',(\s*[}\]])', r'\1', json_str)
+        
+        architecture = json.loads(json_str)
+        
+        logger.info(f"Architecture design complete: {len(architecture.get('components', []))} components")
+        
+        # Return updates dict (correct LangGraph pattern)
+        return {
+            "architecture": architecture,
+            "current_node": "architecture_designer"
+        }
+        
+    except Exception as e:
+        logger.error(f"Architecture design failed: {e}")
+        return {
+            "errors": state.get("errors", []) + [f"Architecture design error: {str(e)}"],
+            "status": "error",
+            "current_node": "architecture_designer"
+        }
+