autobyteus 1.1.2__py3-none-any.whl → 1.1.4__py3-none-any.whl

examples/workflow/run_basic_research_workflow.py

@@ -0,0 +1,189 @@
+# file: autobyteus/examples/workflow/run_basic_research_workflow.py
+import asyncio
+import logging
+import argparse
+from pathlib import Path
+import sys
+import os
+
+# --- Boilerplate to make the script runnable from the project root ---
+SCRIPT_DIR = Path(__file__).resolve().parent.parent
+PACKAGE_ROOT = SCRIPT_DIR.parent
+if str(PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_ROOT))
+
+# Load environment variables from .env file in the project root
+try:
+    from dotenv import load_dotenv
+    env_file_path = PACKAGE_ROOT / ".env"
+    if env_file_path.exists():
+        load_dotenv(env_file_path)
+        print(f"Loaded environment variables from: {env_file_path}")
+    else:
+        print(f"Info: No .env file found at: {env_file_path}. Relying on exported environment variables.")
+except ImportError:
+    print("Warning: python-dotenv not installed. Cannot load .env file.")
+
+# --- Imports for the Workflow Example ---
+try:
+    from autobyteus.agent.context import AgentConfig
+    from autobyteus.llm.models import LLMModel
+    from autobyteus.llm.llm_factory import default_llm_factory, LLMFactory
+    from autobyteus.workflow.workflow_builder import WorkflowBuilder
+    from autobyteus.cli import workflow_cli
+except ImportError as e:
+    print(f"Error importing autobyteus components: {e}", file=sys.stderr)
+    print("Please ensure that the autobyteus library is installed and accessible.", file=sys.stderr)
+    sys.exit(1)
+
+# --- Logging Setup ---
+logger = logging.getLogger("basic_workflow_example")
+
+def setup_logging(args: argparse.Namespace):
+    """Configures logging for the interactive session."""
+    loggers_to_clear = [
+        logging.getLogger(),
+        logging.getLogger("autobyteus"),
+        logging.getLogger("autobyteus.cli"),
+    ]
+    for l in loggers_to_clear:
+        if l.hasHandlers():
+            for handler in l.handlers[:]:
+                l.removeHandler(handler)
+                if hasattr(handler, 'close'): handler.close()
+
+    script_log_level = logging.DEBUG if args.debug else logging.INFO
+
+    console_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(name)s - %(message)s')
+    formatted_console_handler = logging.StreamHandler(sys.stdout)
+    formatted_console_handler.setFormatter(console_formatter)
+    
+    root_logger = logging.getLogger()
+    root_logger.addHandler(formatted_console_handler)
+    root_logger.setLevel(script_log_level) 
+    
+    # Configure the main log file
+    log_file_path = Path(args.log_file).resolve()
+    log_file_path.parent.mkdir(parents=True, exist_ok=True)
+    agent_file_handler = logging.FileHandler(log_file_path, mode='w')  
+    agent_file_formatter = logging.Formatter('%(asctime)s - %(levelname)s - %(name)s:%(lineno)d - %(message)s')
+    agent_file_handler.setFormatter(agent_file_formatter)
+    file_log_level = logging.DEBUG if args.debug else logging.INFO
+
+    autobyteus_logger = logging.getLogger("autobyteus")
+    autobyteus_logger.addHandler(agent_file_handler)
+    autobyteus_logger.setLevel(file_log_level)
+    autobyteus_logger.propagate = True
+    
+    logger.info(f"Core library logs redirected to: {log_file_path} (level: {logging.getLevelName(file_log_level)})")
+
+
+async def main(args: argparse.Namespace):
+    """Main function to configure and run the research workflow."""
+    logger.info("--- Starting Basic Research Workflow Example ---")
+
+    # 1. Create LLM instance for the agents
+    try:
+        _ = LLMModel[args.llm_model]
+    except KeyError:
+        logger.error(f"LLM Model '{args.llm_model}' is not valid. Use --help-models to see available models.")
+        sys.exit(1)
+
+    logger.info(f"Creating LLM instance for model: {args.llm_model}")
+    llm_instance = default_llm_factory.create_llm(model_identifier=args.llm_model)
+
+    # 2. Define the Agent Configurations
+    
+    # The Coordinator/Manager Agent
+    research_manager_config = AgentConfig(
+        name="ResearchManager",
+        role="Coordinator",
+        description="A manager agent that receives research goals and delegates them to specialists.",
+        llm_instance=llm_instance,
+        # The prompt is now simpler, as the workflow builder will handle context.
+        # The {{tools}} placeholder is essential for tool injection.
+        system_prompt=(
+            "You are the manager of a research team. Your job is to understand the user's research goal and delegate it to the correct specialist agent on your team. "
+            "Do not answer questions yourself; always delegate. "
+            "You will be provided a manifest of your team members and available tools.\n\n"
+            "{{tools}}"
+        ),
+    )
+
+    # The Worker/Specialist Agent
+    fact_checker_config = AgentConfig(
+        name="FactChecker",
+        role="Specialist",
+        description="An agent with a limited, internal knowledge base for answering direct factual questions.",
+        llm_instance=llm_instance,
+        system_prompt=(
+            "You are a fact-checking bot. You have the following knowledge:\n"
+            "- The capital of France is Paris.\n"
+            "- The tallest mountain on Earth is Mount Everest.\n"
+            "- The primary programming language for AutoByteUs is Python.\n"
+            "You MUST ONLY answer questions based on this knowledge. If you are asked something you do not know, you MUST respond with 'I do not have information on that topic.'"
+        )
+    )
+
+    # 3. Define and Build the Workflow using WorkflowBuilder
+    
+    research_workflow = (
+        WorkflowBuilder(
+            name="BasicResearchWorkflow",
+            description="A simple two-agent workflow for delegating and answering research questions."
+        )
+        .set_coordinator(research_manager_config)
+        .add_agent_node(fact_checker_config, dependencies=[])
+        .build()
+    )
+    
+    # 4. Run the Workflow
+    
+    logger.info(f"Workflow instance '{research_workflow.name}' created with ID: {research_workflow.workflow_id}")
+
+    try:
+        logger.info("Starting interactive workflow session...")
+        await workflow_cli.run_workflow(
+            workflow=research_workflow, 
+            initial_prompt=args.initial_prompt
+        )
+        logger.info("Interactive workflow session finished.")
+    except Exception as e:
+        logger.error(f"An error occurred during the workflow execution: {e}", exc_info=True)
+    
+    logger.info("--- Basic Research Workflow Example Finished ---")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Run a basic two-agent research workflow.")
+    parser.add_argument("--llm-model", type=str, default="gpt-4o", help="The LLM model to use for the agents.")
+    parser.add_argument("--help-models", action="store_true", help="Display available LLM models and exit.")
+    parser.add_argument("--initial-prompt", type=str, help="An optional initial prompt to start the workflow automatically.")
+    parser.add_argument("--debug", action="store_true", help="Enable debug logging.")
+    parser.add_argument("--log-file", type=str, default="./workflow_logs.txt", 
+                       help="Path to the log file for autobyteus library logs.")
+
+    if "--help-models" in sys.argv:
+        try:
+            LLMFactory.ensure_initialized() 
+            print("Available LLM Models (you can use either name or value with --llm-model):")
+            all_models = sorted(list(LLMModel), key=lambda m: m.name)
+            if not all_models:
+                print("  No models found.")
+            for model in all_models:
+                print(f"  - Name: {model.name:<35} Value: {model.value}")
+        except Exception as e:
+            print(f"Error listing models: {e}")
+        sys.exit(0)
+
+    parsed_args = parser.parse_args()
+    
+    setup_logging(parsed_args)
+
+    try:
+        asyncio.run(main(parsed_args))
+    except (KeyboardInterrupt, SystemExit):
+        logger.info("Script interrupted by user. Exiting.")
+    except Exception as e:
+        logger.error(f"An unhandled error occurred at the top level: {e}", exc_info=True)
+    finally:
+        logger.info("Exiting script.")

examples/workflow/run_code_review_workflow.py

@@ -0,0 +1,269 @@
+# file: autobyteus/examples/workflow/run_code_review_workflow.py
+"""
+This example script demonstrates a simple software development workflow
+with a coordinator, an engineer, a code reviewer, a test writer, and a tester.
+"""
+import asyncio
+import logging
+import argparse
+from pathlib import Path
+import sys
+import os
+
+# --- Boilerplate to make the script runnable from the project root ---
+SCRIPT_DIR = Path(__file__).resolve().parent.parent
+PACKAGE_ROOT = SCRIPT_DIR.parent
+if str(PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_ROOT))
+
+# Load environment variables from .env file
+try:
+    from dotenv import load_dotenv
+    load_dotenv(PACKAGE_ROOT / ".env")
+except ImportError:
+    pass
+
+# --- Imports for the Workflow TUI Example ---
+try:
+    from autobyteus.agent.context import AgentConfig
+    from autobyteus.llm.models import LLMModel
+    from autobyteus.llm.llm_factory import default_llm_factory, LLMFactory
+    from autobyteus.workflow.workflow_builder import WorkflowBuilder
+    from autobyteus.cli.workflow_tui.app import WorkflowApp
+    from autobyteus.tools import file_writer, file_reader, bash_executor
+    from autobyteus.agent.workspace import BaseAgentWorkspace, WorkspaceConfig
+    from autobyteus.tools.parameter_schema import ParameterSchema, ParameterDefinition, ParameterType
+except ImportError as e:
+    print(f"Error importing autobyteus components: {e}", file=sys.stderr)
+    sys.exit(1)
+
+# --- A simple, self-contained workspace for this example ---
+class SimpleLocalWorkspace(BaseAgentWorkspace):
+    """A minimal workspace for local file system access."""
+
+    def __init__(self, config: WorkspaceConfig):
+        super().__init__(config)
+        self.root_path: str = config.get("root_path")
+        if not self.root_path:
+            raise ValueError("SimpleLocalWorkspace requires a 'root_path' in its config.")
+
+    def get_base_path(self) -> str:
+        return self.root_path
+
+    @classmethod
+    def get_workspace_type_name(cls) -> str:
+        return "simple_local_workspace_for_review"
+
+    @classmethod
+    def get_description(cls) -> str:
+        return "A basic workspace for local file access for the code review workflow."
+
+    @classmethod
+    def get_config_schema(cls) -> ParameterSchema:
+        schema = ParameterSchema()
+        schema.add_parameter(ParameterDefinition(
+            name="root_path",
+            param_type=ParameterType.STRING,
+            description="The absolute local file path for the workspace root.",
+            required=True
+        ))
+        return schema
+
+
+# --- Logging Setup ---
+def setup_file_logging() -> Path:
+    log_dir = PACKAGE_ROOT / "logs"
+    log_dir.mkdir(exist_ok=True)
+    log_file_path = log_dir / "code_review_workflow_tui_app.log"
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", filename=log_file_path, filemode="w")
+    logging.getLogger("asyncio").setLevel(logging.WARNING)
+    logging.getLogger("textual").setLevel(logging.WARNING)
+    return log_file_path
+
+def create_code_review_workflow(
+    coordinator_model: str, 
+    engineer_model: str, 
+    reviewer_model: str, 
+    test_writer_model: str,
+    tester_model: str,
+    workspace: BaseAgentWorkspace,
+    use_xml_tool_format: bool = True
+):
+    """Creates the code review workflow."""
+    
+    # --- AGENT CONFIGURATIONS ---
+
+    # Coordinator Agent
+    coordinator_config = AgentConfig(
+        name="ProjectManager", role="Coordinator", description="Manages the development process, assigning tasks to the team.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=coordinator_model),
+        system_prompt=(
+            "You are the project manager for a software team. Your role is to manage a strict, sequential code development, review, and testing process. Your team consists of a SoftwareEngineer, a CodeReviewer, a TestWriter, and a Tester.\n\n"
+            "### Your Workflow\n"
+            "You must follow this workflow precisely:\n"
+            "1.  **Delegate to Engineer:** Receive a request from the user to write code to a specific filename. Instruct the `SoftwareEngineer` to write the code and save it.\n"
+            "2.  **Delegate to Reviewer:** After the engineer confirms completion, instruct the `CodeReviewer` to review the code. You must provide the filename to the reviewer.\n"
+            "3.  **Delegate to Test Writer:** After the review is complete, instruct the `TestWriter` to write pytest tests for the code. Provide the original source filename and tell them to save the tests in a new file, like `test_FILENAME.py`.\n"
+            "4.  **Delegate to Tester:** After the tests are written, instruct the `Tester` to run the tests. You must provide the filename of the test file.\n"
+            "5.  **Report to User:** Once you receive the test results, present the final status (code written, reviewed, and tests passed/failed) to the user.\n\n"
+            "**CRITICAL RULE:** This is a sequential process. You must wait for one agent to finish before contacting the next. You are the central point of communication.\n\n"
+            "{{tools}}"
+        ),
+        use_xml_tool_format=use_xml_tool_format
+    )
+
+    # Software Engineer Agent
+    engineer_config = AgentConfig(
+        name="SoftwareEngineer", role="Developer", description="Writes Python code based on instructions and saves it to a file.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=engineer_model),
+        system_prompt=(
+            "You are a skilled Python software engineer. You receive tasks from your ProjectManager. "
+            "Your job is to write high-quality Python code to fulfill the request. "
+            "After writing the code, you MUST save it to the specified filename using the `FileWriter` tool. "
+            "Confirm completion once the file is saved.\n\n{{tools}}"
+        ),
+        tools=[file_writer],
+        workspace=workspace,
+        use_xml_tool_format=use_xml_tool_format
+    )
+    
+    # Code Reviewer Agent
+    reviewer_config = AgentConfig(
+        name="CodeReviewer", role="Senior Developer", description="Reads and reviews Python code from files for quality and correctness.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=reviewer_model),
+        system_prompt=(
+            "You are a senior software engineer acting as a code reviewer. You will be given a file path to review. "
+            "You MUST use the `FileReader` tool to read the code from the file. "
+            "After reading the code, provide a constructive review, identifying any potential bugs, style issues, or areas for improvement.\n\n{{tools}}"
+        ),
+        tools=[file_reader],
+        workspace=workspace,
+        use_xml_tool_format=use_xml_tool_format
+    )
+
+    # Test Writer Agent
+    test_writer_config = AgentConfig(
+        name="TestWriter", role="QA Engineer", description="Writes pytest tests for Python code.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=test_writer_model),
+        system_prompt=(
+            "You are a QA engineer specializing in testing. You will be given the path to a Python source file. "
+            "Your task is to read that file, write comprehensive tests for it using the `pytest` framework, and save the tests to a new file. "
+            "The test filename MUST start with `test_`. For example, if you are testing `code.py`, you should save the tests in `test_code.py`.\n\n{{tools}}"
+        ),
+        tools=[file_reader, file_writer],
+        workspace=workspace,
+        use_xml_tool_format=use_xml_tool_format
+    )
+
+    # Tester Agent
+    tester_config = AgentConfig(
+        name="Tester", role="QA Automation", description="Executes pytest tests and reports results.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=tester_model),
+        system_prompt=(
+            "You are a QA automation specialist. Your job is to run tests. You will be given a test file to execute. "
+            "You MUST use the `BashExecutor` tool to run the command `pytest` on the given test file. "
+            "Report the full output from the command back to the Project Manager.\n\n{{tools}}"
+        ),
+        tools=[bash_executor],
+        workspace=workspace,
+        use_xml_tool_format=use_xml_tool_format
+    )
+
+
+    # --- BUILD THE WORKFLOW ---
+    
+    code_review_workflow = (
+        WorkflowBuilder(name="SoftwareDevWorkflow", description="A workflow for writing, reviewing, and testing code.")
+        .set_coordinator(coordinator_config)
+        .add_agent_node(engineer_config)
+        .add_agent_node(reviewer_config)
+        .add_agent_node(test_writer_config)
+        .add_agent_node(tester_config)
+        .build()
+    )
+
+    return code_review_workflow
+
+async def main(args: argparse.Namespace, log_file: Path):
+    """Main async function to create the workflow and run the TUI app."""
+    print("Setting up software development workflow...")
+    print(f"--> Logs will be written to: {log_file.resolve()}")
+
+    workspace_path = Path(args.output_dir).resolve()
+    workspace_path.mkdir(parents=True, exist_ok=True)
+    print(f"--> Agent workspace (output directory) is set to: {workspace_path}")
+    
+    workspace_config = WorkspaceConfig(params={"root_path": str(workspace_path)})
+    workspace = SimpleLocalWorkspace(config=workspace_config)
+
+    # Resolve models
+    coordinator_model = args.coordinator_model or args.llm_model
+    engineer_model = args.engineer_model or args.llm_model
+    reviewer_model = args.reviewer_model or args.llm_model
+    test_writer_model = args.test_writer_model or args.llm_model
+    tester_model = args.tester_model or args.llm_model
+    
+    print(f"--> Coordinator Model: {coordinator_model}")
+    print(f"--> Engineer Model: {engineer_model}")
+    print(f"--> Reviewer Model: {reviewer_model}")
+    print(f"--> Test Writer Model: {test_writer_model}")
+    print(f"--> Tester Model: {tester_model}")
+
+    use_xml_tool_format = not args.no_xml_tools
+    print(f"--> Using XML Tool Format: {use_xml_tool_format}")
+
+    try:
+        workflow = create_code_review_workflow(
+            coordinator_model=coordinator_model,
+            engineer_model=engineer_model,
+            reviewer_model=reviewer_model,
+            test_writer_model=test_writer_model,
+            tester_model=tester_model,
+            workspace=workspace,
+            use_xml_tool_format=use_xml_tool_format
+        )
+        app = WorkflowApp(workflow=workflow)
+        await app.run_async()
+    except Exception as e:
+        logging.critical(f"Failed to create or run workflow TUI: {e}", exc_info=True)
+        print(f"\nCRITICAL ERROR: {e}\nCheck log file for details: {log_file.resolve()}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Run a software development workflow with a Textual TUI.",
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+    parser.add_argument("--llm-model", type=str, default="kimi-latest", help="The default LLM model for all agents.")
+    parser.add_argument("--coordinator-model", type=str, help="Specific LLM model for the ProjectManager. Defaults to --llm-model.")
+    parser.add_argument("--engineer-model", type=str, help="Specific LLM model for the SoftwareEngineer. Defaults to --llm-model.")
+    parser.add_argument("--reviewer-model", type=str, help="Specific LLM model for the CodeReviewer. Defaults to --llm-model.")
+    parser.add_argument("--test-writer-model", type=str, help="Specific LLM model for the TestWriter. Defaults to --llm-model.")
+    parser.add_argument("--tester-model", type=str, help="Specific LLM model for the Tester. Defaults to --llm-model.")
+    parser.add_argument("--output-dir", type=str, default="./code_review_output", help="Directory for the shared workspace.")
+    parser.add_argument("--no-xml-tools", action="store_true", help="Disable XML-based tool formatting.")
+    parser.add_argument("--help-models", action="store_true", help="Display available LLM models and exit.")
+    
+    if "--help-models" in sys.argv:
+        try:
+            LLMFactory.ensure_initialized()
+            print("Available LLM Models (you can use either name or value with model arguments):")
+            all_models = sorted(list(LLMModel), key=lambda m: m.name)
+            if not all_models:
+                print("  No models found.")
+            for model in all_models:
+                print(f"  - Name: {model.name:<35} Value: {model.value}")
+        except Exception as e:
+            print(f"Error listing models: {e}")
+        sys.exit(0)
+
+    parsed_args = parser.parse_args()
+
+    log_file_path = setup_file_logging()
+    try:
+        asyncio.run(main(parsed_args, log_file_path))
+    except KeyboardInterrupt:
+        print("\nExiting application.")
+    except Exception as e:
+        logging.critical(f"Top-level application error: {e}", exc_info=True)
+        print(f"\nUNHANDLED ERROR: {e}\nCheck log file for details: {log_file_path.resolve()}")
+

examples/workflow/run_debate_workflow.py

@@ -0,0 +1,212 @@
+# file: autobyteus/examples/workflow/run_debate_workflow.py
+"""
+This example script demonstrates a hierarchical workflow.
+A parent workflow (The Debate) manages two sub-workflows (Debating Teams).
+"""
+import asyncio
+import logging
+import argparse
+from pathlib import Path
+import sys
+import os
+
+# --- Boilerplate to make the script runnable from the project root ---
+SCRIPT_DIR = Path(__file__).resolve().parent.parent
+PACKAGE_ROOT = SCRIPT_DIR.parent
+if str(PACKAGE_ROOT) not in sys.path:
+    sys.path.insert(0, str(PACKAGE_ROOT))
+
+# Load environment variables from .env file
+try:
+    from dotenv import load_dotenv
+    load_dotenv(PACKAGE_ROOT / ".env")
+except ImportError:
+    pass
+
+# --- Imports for the Workflow TUI Example ---
+try:
+    from autobyteus.agent.context import AgentConfig
+    from autobyteus.llm.models import LLMModel
+    from autobyteus.llm.llm_factory import default_llm_factory, LLMFactory
+    from autobyteus.workflow.workflow_builder import WorkflowBuilder
+    from autobyteus.cli.workflow_tui.app import WorkflowApp
+    from autobyteus.workflow.context.workflow_config import WorkflowConfig
+except ImportError as e:
+    print(f"Error importing autobyteus components: {e}", file=sys.stderr)
+    sys.exit(1)
+
+# --- Logging Setup ---
+def setup_file_logging() -> Path:
+    log_dir = PACKAGE_ROOT / "logs"
+    log_dir.mkdir(exist_ok=True)
+    log_file_path = log_dir / "debate_workflow_tui_app.log"
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s [%(levelname)s] %(name)s: %(message)s", filename=log_file_path, filemode="w")
+    logging.getLogger("asyncio").setLevel(logging.WARNING)
+    logging.getLogger("textual").setLevel(logging.WARNING)
+    return log_file_path
+
+def create_debate_workflow(moderator_model: str, affirmative_model: str, negative_model: str, use_xml_tool_format: bool = True):
+    """Creates a hierarchical debate workflow for the TUI demonstration."""
+    # Validate models
+    def _validate_model(model_name: str):
+        try:
+            _ = LLMModel[model_name]
+        except KeyError:
+            logging.critical(f"LLM Model '{model_name}' is not valid. Use --help-models to see available models.")
+            print(f"\nCRITICAL ERROR: LLM Model '{model_name}' is not valid. Use --help-models to see available models.\nCheck log file for details.")
+            sys.exit(1)
+
+    for model in [moderator_model, affirmative_model, negative_model]:
+        _validate_model(model)
+    
+    logging.info(f"Using models -> Moderator: {moderator_model}, Affirmative: {affirmative_model}, Negative: {negative_model}")
+    logging.info(f"Using XML tool format: {use_xml_tool_format}")
+
+    # --- AGENT CONFIGURATIONS ---
+
+    # Parent-Level Agents
+    moderator_config = AgentConfig(
+        name="DebateModerator", role="Coordinator", description="Manages the debate, gives turns, and summarizes.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=moderator_model),
+        system_prompt=(
+            "You are the impartial moderator of a debate between two teams. Your goal is to facilitate a structured, turn-by-turn debate on a user's topic.\n"
+            "Your team consists of Team_Affirmative and Team_Negative. You will delegate tasks to them using their unique names.\n"
+            "Responsibilities: 1. Announce the topic. 2. Ask Team_Affirmative for an opening statement. 3. Ask Team_Negative for a rebuttal. "
+            "4. Facilitate a structured flow of arguments. 5. Conclude the debate.\n"
+            "CRITICAL RULE: You must enforce a strict turn-based system. Only communicate with ONE team at a time using the `SendMessageTo` tool. After sending a message, you must wait for a response before messaging the other team.\n"
+            "Do not debate yourself. Your role is to moderate.\n\n{{tools}}"
+        ),
+        use_xml_tool_format=use_xml_tool_format
+    )
+
+    # Team Affirmative Agents
+    lead_affirmative_config = AgentConfig(
+        name="Lead_Affirmative", role="Coordinator", description="Leads the team arguing FOR the motion.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=affirmative_model),
+        system_prompt=(
+            "You are the lead of the Affirmative team. You receive high-level instructions from the DebateModerator (e.g., 'prepare opening statement').\n"
+            "Your job is to delegate this task to your team member, the Proponent, by giving them a specific instruction.\n\n{{tools}}"
+        ),
+        use_xml_tool_format=use_xml_tool_format
+    )
+    proponent_config = AgentConfig(
+        name="Proponent", role="Debater", description="Argues in favor of the debate topic.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=affirmative_model),
+        system_prompt="You are a Proponent. You will receive instructions from your team lead. Your role is to argue STRONGLY and PERSUASIVELY IN FAVOR of the motion.",
+        use_xml_tool_format=use_xml_tool_format
+    )
+
+    # Team Negative Agents
+    lead_negative_config = AgentConfig(
+        name="Lead_Negative", role="Coordinator", description="Leads the team arguing AGAINST the motion.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=negative_model),
+        system_prompt=(
+            "You are the lead of the Negative team. You receive high-level instructions from the DebateModerator (e.g., 'prepare your rebuttal').\n"
+            "Your job is to delegate this task to your team member, the Opponent, by giving them a specific instruction.\n\n{{tools}}"
+        ),
+        use_xml_tool_format=use_xml_tool_format
+    )
+    opponent_config = AgentConfig(
+        name="Opponent", role="Debater", description="Argues against the debate topic.",
+        llm_instance=default_llm_factory.create_llm(model_identifier=negative_model),
+        system_prompt="You are an Opponent. You will receive instructions from your team lead. Your role is to argue STRONGLY and PERSUASIVELY AGAINST the motion.",
+        use_xml_tool_format=use_xml_tool_format
+    )
+
+    # --- BUILD SUB-WORKFLOWS ---
+    
+    # Build Team Affirmative
+    team_affirmative_workflow: WorkflowConfig = (
+        WorkflowBuilder(name="Team_Affirmative", description="A two-agent team that argues in favor of a proposition.", role="Argues FOR the motion")
+        .set_coordinator(lead_affirmative_config)
+        .add_agent_node(proponent_config)
+        .build()._runtime.context.config # Build to get the config object
+    )
+    
+    # Build Team Negative
+    team_negative_workflow: WorkflowConfig = (
+        WorkflowBuilder(name="Team_Negative", description="A two-agent team that argues against a proposition.", role="Argues AGAINST the motion")
+        .set_coordinator(lead_negative_config)
+        .add_agent_node(opponent_config)
+        .build()._runtime.context.config # Build to get the config object
+    )
+
+    # --- BUILD PARENT WORKFLOW ---
+    
+    debate_workflow = (
+        WorkflowBuilder(name="Grand_Debate", description="A hierarchical workflow for a moderated debate between two teams.")
+        .set_coordinator(moderator_config)
+        .add_workflow_node(team_affirmative_workflow)
+        .add_workflow_node(team_negative_workflow)
+        .build()
+    )
+
+    return debate_workflow
+
+async def main(args: argparse.Namespace, log_file: Path):
+    """Main async function to create the workflow and run the TUI app."""
+    print("Setting up hierarchical debate workflow...")
+    print(f"--> Logs will be written to: {log_file.resolve()}")
+
+    # Resolve model for each role, falling back to the default --llm-model
+    moderator_model = args.moderator_model or args.llm_model
+    affirmative_model = args.affirmative_model or args.llm_model
+    negative_model = args.negative_model or args.llm_model
+    print(f"--> Moderator Model: {moderator_model}")
+    print(f"--> Affirmative Team Model: {affirmative_model}")
+    print(f"--> Negative Team Model: {negative_model}")
+
+    # Determine tool format setting from args
+    use_xml_tool_format = not args.no_xml_tools
+    print(f"--> Using XML Tool Format: {use_xml_tool_format}")
+
+    try:
+        workflow = create_debate_workflow(
+            moderator_model=moderator_model,
+            affirmative_model=affirmative_model,
+            negative_model=negative_model,
+            use_xml_tool_format=use_xml_tool_format,
+        )
+        app = WorkflowApp(workflow=workflow)
+        await app.run_async()
+    except Exception as e:
+        logging.critical(f"Failed to create or run debate workflow TUI: {e}", exc_info=True)
+        print(f"\nCRITICAL ERROR: {e}\nCheck log file for details: {log_file.resolve()}")
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Run a hierarchical 2-team debate workflow with a Textual TUI.",
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+    parser.add_argument("--llm-model", type=str, default="kimi-latest", help="The default LLM model for all agents. Can be overridden by other arguments.")
+    parser.add_argument("--moderator-model", type=str, help="Specific LLM model for the Moderator. Defaults to --llm-model.")
+    parser.add_argument("--affirmative-model", type=str, help="Specific LLM model for the Affirmative Team. Defaults to --llm-model.")
+    parser.add_argument("--negative-model", type=str, help="Specific LLM model for the Negative Team. Defaults to --llm-model.")
+    parser.add_argument("--no-xml-tools", action="store_true", help="Disable XML-based tool formatting. Recommended for models that struggle with XML.")
+    parser.add_argument("--help-models", action="store_true", help="Display available LLM models and exit.")
+    
+    if "--help-models" in sys.argv:
+        try:
+            LLMFactory.ensure_initialized()
+            print("Available LLM Models (you can use either name or value with model arguments):")
+            all_models = sorted(list(LLMModel), key=lambda m: m.name)
+            if not all_models:
+                print("  No models found.")
+            for model in all_models:
+                print(f"  - Name: {model.name:<35} Value: {model.value}")
+        except Exception as e:
+            print(f"Error listing models: {e}")
+        sys.exit(0)
+
+    parsed_args = parser.parse_args()
+
+    log_file_path = setup_file_logging()
+    try:
+        asyncio.run(main(parsed_args, log_file_path))
+    except KeyboardInterrupt:
+        print("\nExiting application.")
+    except Exception as e:
+        # This catches errors during asyncio.run, which might not be logged otherwise
+        logging.critical(f"Top-level application error: {e}", exc_info=True)
+        print(f"\nUNHANDLED ERROR: {e}\nCheck log file for details: {log_file_path.resolve()}")
+