scopemate 0.1.0__py3-none-any.whl

scopemate/engine.py

@@ -0,0 +1,226 @@
+#!/usr/bin/env python3
+"""
+scopemate Engine - Main application logic for scopemate
+
+This module contains the TaskEngine class which coordinates all the functionality
+of scopemate, handling the workflow for creating, breaking down, and saving tasks.
+"""
+import os
+from typing import List, Optional, Dict, Any
+
+from .models import ScopeMateTask
+from .storage import (
+    save_checkpoint, save_plan, load_plan, 
+    checkpoint_exists, delete_checkpoint, CHECKPOINT_FILE
+)
+from .task_analysis import (
+    check_and_update_parent_estimates, find_long_duration_leaf_tasks,
+    should_decompose_task, _initialize_task_depths,
+    get_task_depth, is_leaf_task
+)
+from .breakdown import suggest_breakdown
+from .interaction import prompt_user, build_root_task, print_summary
+
+
+class TaskEngine:
+    """
+    Main engine for scopemate that coordinates task creation, breakdown, and management.
+    """
+    
+    def __init__(self):
+        """Initialize the TaskEngine."""
+        self.tasks: List[ScopeMateTask] = []
+        self.task_depths: Dict[str, int] = {}
+        self.max_depth: int = 5  # Maximum depth of task hierarchy
+        
+    def load_from_checkpoint(self) -> bool:
+        """
+        Load tasks from checkpoint file if it exists.
+        
+        Returns:
+            True if checkpoint was loaded, False otherwise
+        """
+        if checkpoint_exists():
+            resume = prompt_user(
+                f"Found checkpoint '{CHECKPOINT_FILE}'. Resume?", 
+                default="y", 
+                choices=["y","n"]
+            )
+            if resume.lower() == "y":
+                self.tasks = load_plan(CHECKPOINT_FILE)
+                return True
+            else:
+                delete_checkpoint()
+        
+        return False
+    
+    def load_from_file(self, default_filename: str = "scopemate_plan.json") -> bool:
+        """
+        Load tasks from a user-specified file.
+        
+        Args:
+            default_filename: Default filename to suggest
+            
+        Returns:
+            True if file was loaded, False otherwise
+        """
+        choice = prompt_user("Load existing plan?", default="n", choices=["y","n"])
+        if choice.lower() == "y":
+            fname = prompt_user("Enter filename to load", default=default_filename)
+            try:
+                self.tasks = load_plan(fname)
+                return True
+            except FileNotFoundError:
+                print(f"File not found: {fname}")
+        
+        return False
+    
+    def create_new_task(self) -> None:
+        """Create a new root task interactively."""
+        self.tasks.append(build_root_task())
+        save_checkpoint(self.tasks)
+    
+    def breakdown_complex_tasks(self) -> None:
+        """Process all tasks and break down complex ones."""
+        # Initialize depth tracking
+        self.task_depths = _initialize_task_depths(self.tasks)
+        
+        # Maintain a list of tasks to process (for recursive handling)
+        tasks_to_process = list(self.tasks)
+        
+        # Process tasks with checkpointing
+        while tasks_to_process:
+            # Get the next task to process
+            current_task = tasks_to_process.pop(0)
+            
+            # Calculate depth for this task if not already tracked
+            current_depth = get_task_depth(current_task, self.task_depths, self.tasks)
+            
+            # Check if this task is a leaf (has no children)
+            is_leaf = is_leaf_task(current_task.id, self.tasks)
+            
+            # Only decompose if criteria met
+            if should_decompose_task(current_task, current_depth, self.max_depth, is_leaf):
+                print(f"\nDecomposing task {current_task.id} at depth {current_depth}...")
+                print(f"  Size: {current_task.scope.size}, Time: {current_task.scope.time_estimate}")
+                
+                # Get subtask breakdown from LLM with user interaction
+                subtasks = suggest_breakdown(current_task)
+                
+                if subtasks:
+                    # Set depth for new subtasks
+                    for sub in subtasks:
+                        self.task_depths[sub.id] = current_depth + 1
+                        
+                    # Add subtasks to the task list
+                    self.tasks.extend(subtasks)
+                    
+                    # Add the newly created subtasks to the processing queue
+                    tasks_to_process.extend(subtasks)
+                    
+                    save_checkpoint(self.tasks)
+                    
+                    print(f"Created {len(subtasks)} subtasks for {current_task.id}")
+                    
+                    # Check and update parent estimates if needed
+                    self.tasks = check_and_update_parent_estimates(self.tasks)
+                    save_checkpoint(self.tasks)
+    
+    def handle_long_duration_tasks(self) -> None:
+        """Find and handle long duration leaf tasks."""
+        # Find long duration leaf tasks
+        long_duration_leaf_tasks = find_long_duration_leaf_tasks(self.tasks)
+        
+        if long_duration_leaf_tasks:
+            print("\n=== Found Long-Duration Leaf Tasks ===")
+            print("These tasks have long durations but no subtasks:")
+            
+            for i, task in enumerate(long_duration_leaf_tasks):
+                print(f"{i+1}. [{task.id}] {task.title} - {task.scope.time_estimate}")
+            
+            print("\nDo you want to break down any of these tasks?")
+            choice = prompt_user("Enter task numbers to break down (comma-separated) or 'n' to skip", default="n")
+            
+            if choice.lower() != "n":
+                try:
+                    # Parse the choices
+                    selected_indices = [int(idx.strip()) - 1 for idx in choice.split(",")]
+                    for idx in selected_indices:
+                        if 0 <= idx < len(long_duration_leaf_tasks):
+                            task_to_breakdown = long_duration_leaf_tasks[idx]
+                            print(f"\nBreaking down: [{task_to_breakdown.id}] {task_to_breakdown.title}")
+                            
+                            # Get subtask suggestions
+                            suggested_subtasks = suggest_breakdown(task_to_breakdown)
+                            
+                            if suggested_subtasks:
+                                # Set depth for new subtasks
+                                for sub in suggested_subtasks:
+                                    if task_to_breakdown.id in self.task_depths:
+                                        self.task_depths[sub.id] = self.task_depths[task_to_breakdown.id] + 1
+                                    else:
+                                        self.task_depths[sub.id] = 1
+                                    
+                                self.tasks.extend(suggested_subtasks)
+                                save_checkpoint(self.tasks)
+                                print(f"Created {len(suggested_subtasks)} subtasks for {task_to_breakdown.id}")
+                                
+                                # Check and update parent estimates
+                                self.tasks = check_and_update_parent_estimates(self.tasks)
+                                save_checkpoint(self.tasks)
+                except ValueError:
+                    print("Invalid selection, skipping breakdown.")
+    
+    def finalize_plan(self) -> None:
+        """Review and save the final plan."""
+        # Final check of parent-child estimate consistency
+        self.tasks = check_and_update_parent_estimates(self.tasks)
+        
+        # Review and final save
+        print_summary(self.tasks)
+        proceed = prompt_user("Save final plan?", default="y", choices=["y","n"])
+        if proceed.lower() == 'y':
+            fname = prompt_user("Save plan to file", default="scopemate_plan.json")
+            save_plan(self.tasks, fname)
+            delete_checkpoint()
+        else:
+            print(f"Plan left in checkpoint '{CHECKPOINT_FILE}'. Run again to resume.")
+    
+    def run(self) -> None:
+        """Run the full interactive workflow."""
+        # Display introduction
+        print("=== scopemate Action Plan Builder ===")
+        print("This tool helps break down complex tasks and maintain consistent time estimates.")
+        print("Now with interactive task breakdown - choose from alternative approaches and customize subtasks!")
+        print("Note: Parent tasks will be automatically adjusted if child tasks take longer.\n")
+        
+        # Try to load existing checkpoint
+        if not self.load_from_checkpoint():
+            # If no checkpoint, try loading from file or create new
+            if not self.load_from_file():
+                self.create_new_task()
+        
+        # Process the tasks
+        self.breakdown_complex_tasks()
+        
+        # Check for leaf tasks with long durations
+        self.handle_long_duration_tasks()
+        
+        # Finalize the plan
+        self.finalize_plan()
+
+    def run_interactive(self) -> None:
+        """Run the interactive mode of the application."""
+        print("=== scopemate Action Plan Builder ===")
+
+
+def interactive_builder():
+    """
+    Legacy function for backward compatibility that runs the TaskEngine.
+    """
+    engine = TaskEngine()
+    try:
+        engine.run()
+    except KeyboardInterrupt:
+        print("\nOperation cancelled. Progress saved in checkpoint.")
+        save_checkpoint(engine.tasks) 

scopemate/interaction.py

@@ -0,0 +1,292 @@
+#!/usr/bin/env python3
+"""
+scopemate Interaction - Functions for user interaction
+
+This module handles all interactive aspects of scopemate, including
+collecting user input and displaying information.
+"""
+from typing import List, Optional, Dict, Any
+
+from .models import (
+    ScopeMateTask, Purpose, Scope, Outcome, Meta,
+    get_utc_now, VALID_URGENCY_TYPES, VALID_OUTCOME_TYPES,
+    VALID_SIZE_TYPES, VALID_TIME_ESTIMATES, VALID_CONFIDENCE_LEVELS,
+    VALID_TEAMS
+)
+
+# -------------------------------
+# User Input Functions
+# -------------------------------
+def prompt_user(
+    prompt: str, 
+    default: Optional[str] = None, 
+    choices: Optional[List[str]] = None
+) -> str:
+    """
+    Prompt user for input with optional default and choices validation.
+    
+    Args:
+        prompt: The prompt text to display
+        default: Optional default value if user enters nothing
+        choices: Optional list of valid choices
+        
+    Returns:
+        User's validated input as a string
+    """
+    while True:
+        suffix = f" [{default}]" if default is not None else ""
+        resp = input(f"{prompt}{suffix}: ").strip()
+        
+        if not resp and default is not None:
+            resp = default
+            
+        if choices:
+            low = resp.lower()
+            if low not in [c.lower() for c in choices]:
+                print(f"Please choose from {choices}.")
+                continue
+                
+        if resp:
+            return resp
+        
+        # If we get here with an empty response and no default, loop again
+
+
+def generate_concise_title(parent_title: str, subtask_title: str) -> str:
+    """
+    Generate a concise subtask title without repeating the parent title.
+    
+    Args:
+        parent_title: The title of the parent task
+        subtask_title: The proposed title for the subtask
+        
+    Returns:
+        A concise title for the subtask
+    """
+    # If subtask title already contains parent title, extract the unique part
+    if parent_title and parent_title.lower() in subtask_title.lower():
+        # Try to find the part after the parent title
+        suffix = subtask_title[subtask_title.lower().find(parent_title.lower()) + len(parent_title):].strip()
+        if suffix:
+            # Remove any leading separators like "-" or ":"
+            return suffix.lstrip(" -:").strip()
+    
+    # If parent title isn't in subtask or couldn't extract suffix, use the subtask title directly
+    return subtask_title
+
+
+def build_custom_subtask(parent_task: ScopeMateTask) -> ScopeMateTask:
+    """
+    Interactively gather information to create a custom subtask.
+    
+    Args:
+        parent_task: The parent ScopeMateTask
+        
+    Returns:
+        A new ScopeMateTask object as a subtask of the parent
+    """
+    # This is a simplified version - the full version should include all the prompts
+    # from the original code in core.py
+    
+    import uuid
+    
+    print(f"\n=== Creating Custom Subtask for: {parent_task.title} ===")
+    
+    title = prompt_user("Give a short TITLE for this subtask")
+    title = generate_concise_title(parent_task.title, title)
+    
+    summary = prompt_user("What is the primary PURPOSE of this subtask?")
+    outcome_def = prompt_user("Define the desired OUTCOME")
+    
+    # Ask for team assignment
+    print("\nTEAM options:")
+    print("- Product: Product management team")
+    print("- Design: Design and user experience team")
+    print("- Frontend: Frontend development team")
+    print("- Backend: Backend development team")
+    print("- ML: Machine learning team")
+    print("- Infra: Infrastructure and DevOps team")
+    print("- Testing: QA and testing team")
+    print("- Other: Any other team")
+    team = prompt_user(
+        "TEAM responsible", 
+        default=parent_task.meta.team, 
+        choices=VALID_TEAMS
+    )
+    
+    # Create the subtask with sensible defaults inheriting from parent
+    subtask = ScopeMateTask(
+        id=f"TASK-{uuid.uuid4().hex[:6]}",
+        title=title,
+        purpose=Purpose(
+            detailed_description=summary, 
+            alignment=parent_task.purpose.alignment.copy(), 
+            urgency=parent_task.purpose.urgency
+        ),
+        scope=Scope(
+            size="straightforward", 
+            time_estimate="days", 
+            dependencies=[], 
+            risks=[]
+        ),
+        outcome=Outcome(
+            type=parent_task.outcome.type,
+            detailed_outcome_definition=outcome_def,
+            acceptance_criteria=[],
+            metric=None,
+            validation_method=None
+        ),
+        meta=Meta(
+            status="backlog", 
+            priority=None, 
+            created=get_utc_now(), 
+            updated=get_utc_now(), 
+            due_date=None, 
+            confidence="medium",
+            team=team
+        ),
+        parent_id=parent_task.id
+    )
+    
+    return subtask
+
+
+def build_root_task() -> ScopeMateTask:
+    """
+    Interactively gather information to create a new root task.
+    
+    Returns:
+        A new ScopeMateTask object
+    """
+    # This is a simplified version - the full version should include all the prompts
+    # from the original code in core.py
+    
+    import uuid
+    from .llm import estimate_scope
+    
+    print("=== scopemate Action Plan Builder ===")
+    
+    title = prompt_user("Give a short TITLE for this task")
+    summary = prompt_user("What is the primary PURPOSE of this task?")
+    outcome_def = prompt_user("Define the desired OUTCOME")
+    
+    # Ask for team assignment
+    print("\nTEAM options:")
+    print("- Product: Product management team")
+    print("- Design: Design and user experience team")
+    print("- Frontend: Frontend development team")
+    print("- Backend: Backend development team")
+    print("- ML: Machine learning team")
+    print("- Infra: Infrastructure and DevOps team")
+    print("- Testing: QA and testing team")
+    print("- Other: Any other team")
+    team = prompt_user(
+        "TEAM responsible", 
+        default="Product", 
+        choices=VALID_TEAMS
+    )
+    
+    # Create root task with sensible defaults
+    root = ScopeMateTask(
+        id=f"TASK-{uuid.uuid4().hex[:6]}",
+        title=title,
+        purpose=Purpose(
+            detailed_description=summary, 
+            alignment=[], 
+            urgency="strategic"
+        ),
+        scope=Scope(
+            size="straightforward", 
+            time_estimate="week", 
+            dependencies=[], 
+            risks=[]
+        ),
+        outcome=Outcome(
+            type="customer-facing",
+            detailed_outcome_definition=outcome_def,
+            acceptance_criteria=[],
+            metric=None,
+            validation_method=None
+        ),
+        meta=Meta(
+            status="backlog", 
+            priority=None, 
+            created=get_utc_now(), 
+            updated=get_utc_now(), 
+            due_date=None, 
+            confidence="medium",
+            team=team
+        )
+    )
+    
+    # Use LLM to estimate scope
+    root.scope = estimate_scope(root)
+    return root
+
+
+def print_summary(tasks: List[ScopeMateTask]) -> None:
+    """
+    Print a hierarchical summary of tasks with complexity indicators and statistics.
+    
+    Args:
+        tasks: List of ScopeMateTask objects to summarize
+    """
+    print("\n=== Task Summary ===")
+    
+    # Build hierarchy maps
+    task_map = {t.id: t for t in tasks}
+    children_map = {}
+    
+    for t in tasks:
+        if t.parent_id:
+            if t.parent_id not in children_map:
+                children_map[t.parent_id] = []
+            children_map[t.parent_id].append(t.id)
+    
+    # Find root tasks (those without parents or with unknown parents)
+    root_tasks = [t.id for t in tasks if not t.parent_id or t.parent_id not in task_map]
+    
+    # Print the hierarchy starting from root tasks
+    for root_id in root_tasks:
+        _print_task_hierarchy(root_id, task_map, children_map)
+        
+    # Print some statistics about task complexity
+    complex_count = sum(1 for t in tasks if t.scope.size in ["complex", "uncertain", "pioneering"])
+    long_tasks = sum(1 for t in tasks if t.scope.time_estimate in ["sprint", "multi-sprint"])
+    leaf_tasks = sum(1 for t_id in task_map if t_id not in children_map)
+    
+    print("\n=== Task Statistics ===")
+    print(f"Total tasks: {len(tasks)}")
+    print(f"Leaf tasks (no subtasks): {leaf_tasks}")
+    print(f"Complex+ tasks: {complex_count} ({(complex_count/len(tasks))*100:.1f}%)")
+    print(f"Sprint+ duration tasks: {long_tasks} ({(long_tasks/len(tasks))*100:.1f}%)")
+
+
+def _print_task_hierarchy(
+    task_id: str, 
+    task_map: Dict[str, ScopeMateTask], 
+    children_map: Dict[str, List[str]], 
+    level: int = 0
+) -> None:
+    """
+    Recursively print a task and its children with hierarchical indentation.
+    
+    Args:
+        task_id: ID of the task to print
+        task_map: Dictionary mapping task IDs to tasks
+        children_map: Dictionary mapping task IDs to lists of child IDs
+        level: Current indentation level
+    """
+    if task_id not in task_map:
+        return
+        
+    t = task_map[task_id]
+    indent = "  " * level
+    
+    print(f"{indent}{'└─' if level > 0 else ''} [{t.id}] {t.title}")
+    print(f"{indent}   Scope: {t.scope.size} | Est: {t.scope.time_estimate} | Team: {t.meta.team or 'Not assigned'}")
+    
+    # Print children recursively
+    if task_id in children_map:
+        for child_id in children_map[task_id]:
+            _print_task_hierarchy(child_id, task_map, children_map, level + 1)