better-notion 0.9.9__py3-none-any.whl → 1.0.1__py3-none-any.whl

better_notion/utils/agents/dependency_resolver.py

@@ -0,0 +1,368 @@
+"""Dependency resolution for task management in the agents workflow system.
+
+This module provides functionality to resolve task dependencies, determine
+execution order, and find tasks that are ready to start.
+"""
+
+from collections import deque
+from typing import Any, AsyncIterator, Dict, List, Set, Tuple
+
+
+class DependencyResolver:
+    """Resolves task dependencies and determines execution order.
+
+    This class provides methods to:
+    - Build dependency graphs from tasks
+    - Perform topological sorting to find execution order
+    - Detect circular dependencies
+    - Find tasks that are ready to start (all dependencies completed)
+    - Find tasks that are blocked by incomplete dependencies
+
+    Example:
+        >>> # Build dependency graph
+        >>> graph = {
+        ...     "task-a": ["task-b"],  # A depends on B
+        ...     "task-b": [],           # B has no dependencies
+        ... }
+        >>>
+        >>> # Get execution order
+        >>> order = DependencyResolver.topological_sort(graph)
+        >>> print(order)  # ["task-b", "task-a"]
+    """
+
+    @staticmethod
+    def build_dependency_graph(
+        tasks: List[Any],
+        get_task_id: callable,
+        get_dependency_ids: callable,
+    ) -> Dict[str, List[str]]:
+        """Build dependency graph (adjacency list) from tasks.
+
+        Args:
+            tasks: List of task objects
+            get_task_id: Function to extract task ID from task object
+            get_dependency_ids: Function to extract dependency IDs from task object
+
+        Returns:
+            Dict mapping task_id → list of task_ids it depends on
+
+        Example:
+            >>> tasks = [task1, task2, task3]
+            >>> graph = DependencyResolver.build_dependency_graph(
+            ...     tasks,
+            ...     lambda t: t.id,
+            ...     lambda t: t.dependencies
+            ... )
+        """
+        graph: Dict[str, List[str]] = {}
+
+        for task in tasks:
+            task_id = get_task_id(task)
+            deps = get_dependency_ids(task)
+
+            # Ensure deps is a list
+            if deps is None:
+                deps = []
+            elif isinstance(deps, str):
+                deps = [deps]
+            elif not isinstance(deps, list):
+                deps = list(deps)
+
+            graph[task_id] = deps
+
+        return graph
+
+    @staticmethod
+    def topological_sort(graph: Dict[str, List[str]]) -> List[str]:
+        """Perform topological sort to find execution order.
+
+        Args:
+            graph: Dependency graph (task_id → list of dependencies)
+
+        Returns:
+            List of task IDs in dependency order (dependencies before dependents)
+
+        Raises:
+            ValueError: If graph contains circular dependencies
+
+        Example:
+            >>> graph = {
+            ...     "A": ["B"],
+            ...     "B": ["C"],
+            ...     "C": [],
+            ... }
+            >>> order = DependencyResolver.topological_sort(graph)
+            >>> print(order)  # ["C", "B", "A"]
+        """
+        # Calculate in-degrees
+        in_degree: Dict[str, int] = {node: 0 for node in graph}
+
+        for node in graph:
+            for dep in graph[node]:
+                # Only count dependencies that are in our graph
+                if dep in in_degree:
+                    in_degree[node] += 1
+
+        # Start with nodes that have no dependencies
+        queue = deque([node for node, degree in in_degree.items() if degree == 0])
+        result: List[str] = []
+
+        while queue:
+            node = queue.popleft()
+            result.append(node)
+
+            # Reduce in-degree for dependent nodes
+            for dependent, deps in graph.items():
+                if node in deps:
+                    in_degree[dependent] -= 1
+                    if in_degree[dependent] == 0:
+                        queue.append(dependent)
+
+        # Check for cycles
+        if len(result) != len(graph):
+            # Find which nodes are in the cycle
+            processed = set(result)
+            cycle_nodes = [node for node in graph if node not in processed]
+
+            if cycle_nodes:
+                raise ValueError(
+                    f"Circular dependency detected involving tasks: {', '.join(cycle_nodes[:3])}"
+                )
+
+            raise ValueError("Circular dependency detected in task graph")
+
+        return result
+
+    @staticmethod
+    def detect_cycles(graph: Dict[str, List[str]]) -> List[List[str]]:
+        """Detect circular dependencies in the graph.
+
+        Args:
+            graph: Dependency graph
+
+        Returns:
+            List of cycles (each cycle is a list of task IDs)
+
+        Example:
+            >>> graph = {
+            ...     "A": ["B"],
+            ...     "B": ["C"],
+            ...     "C": ["A"],  # Circular!
+            ... }
+            >>> cycles = DependencyResolver.detect_cycles(graph)
+            >>> print(len(cycles))  # 1
+        """
+        cycles: List[List[str]] = []
+        visited: Set[str] = set()
+        rec_stack: Set[str] = set()
+        path: List[str] = []
+
+        def dfs(node: str) -> None:
+            """Depth-first search to detect cycles."""
+            visited.add(node)
+            rec_stack.add(node)
+            path.append(node)
+
+            for neighbor in graph.get(node, []):
+                if neighbor not in visited:
+                    dfs(neighbor)
+                elif neighbor in rec_stack:
+                    # Found a cycle
+                    cycle_start = path.index(neighbor)
+                    cycle = path[cycle_start:] + [neighbor]
+                    cycles.append(cycle)
+
+            path.pop()
+            rec_stack.remove(node)
+
+        for node in graph:
+            if node not in visited:
+                dfs(node)
+
+        return cycles
+
+    @staticmethod
+    def get_ready_tasks(
+        tasks: List[Any],
+        get_task_id: callable,
+        get_dependency_ids: callable,
+        get_task_status: callable,
+        completed_status: str = "Completed",
+    ) -> List[Any]:
+        """Find tasks that can be started (all dependencies completed).
+
+        Args:
+            tasks: List of task objects
+            get_task_id: Function to extract task ID
+            get_dependency_ids: Function to extract dependency IDs
+            get_task_status: Function to extract task status
+            completed_status: Status that means dependencies are satisfied
+
+        Returns:
+            List of tasks that are ready to start
+
+        Example:
+            >>> ready = DependencyResolver.get_ready_tasks(
+            ...     tasks,
+            ...     lambda t: t.id,
+            ...     lambda t: t.depends_on,
+            ...     lambda t: t.status
+            ... )
+        """
+        # Build task map for O(1) lookups
+        task_map = {get_task_id(t): t for t in tasks}
+
+        ready_tasks: List[Any] = []
+
+        for task in tasks:
+            task_id = get_task_id(task)
+            deps = get_dependency_ids(task)
+
+            if deps is None:
+                deps = []
+            elif isinstance(deps, str):
+                deps = [deps]
+            elif not isinstance(deps, list):
+                deps = list(deps)
+
+            # Check if all dependencies are satisfied
+            all_complete = True
+
+            for dep_id in deps:
+                dep_task = task_map.get(dep_id)
+
+                if dep_task is None:
+                    # Dependency doesn't exist in our task list
+                    # Assume it's not completed
+                    all_complete = False
+                    break
+
+                dep_status = get_task_status(dep_task)
+
+                if dep_status != completed_status:
+                    all_complete = False
+                    break
+
+            if all_complete and len(deps) > 0:
+                # Task has dependencies and all are complete
+                ready_tasks.append(task)
+            elif len(deps) == 0:
+                # Task has no dependencies - also ready
+                task_status = get_task_status(task)
+                # Only include if not already completed
+                if task_status != completed_status:
+                    ready_tasks.append(task)
+
+        return ready_tasks
+
+    @staticmethod
+    def get_blocked_tasks(
+        tasks: List[Any],
+        get_task_id: callable,
+        get_dependency_ids: callable,
+        get_task_status: callable,
+        completed_status: str = "Completed",
+    ) -> List[Tuple[Any, List[Any]]]:
+        """Find tasks that are blocked by incomplete dependencies.
+
+        Args:
+            tasks: List of task objects
+            get_task_id: Function to extract task ID
+            get_dependency_ids: Function to extract dependency IDs
+            get_task_status: Function to extract task status
+            completed_status: Status that means dependencies are satisfied
+
+        Returns:
+            List of (task, blocking_tasks) tuples where blocking_tasks
+            are the incomplete dependencies
+
+        Example:
+            >>> blocked = DependencyResolver.get_blocked_tasks(
+            ...     tasks,
+            ...     lambda t: t.id,
+            ...     lambda t: t.depends_on,
+            ...     lambda t: t.status
+            ... )
+            >>> for task, blockers in blocked:
+            ...     print(f"{task.id} blocked by {[b.id for b in blockers]}")
+        """
+        # Build task map
+        task_map = {get_task_id(t): t for t in tasks}
+
+        blocked: List[Tuple[Any, List[Any]]] = []
+
+        for task in tasks:
+            task_id = get_task_id(task)
+            deps = get_dependency_ids(task)
+
+            if deps is None:
+                deps = []
+            elif isinstance(deps, str):
+                deps = [deps]
+            elif not isinstance(deps, list):
+                deps = list(deps)
+
+            if not deps:
+                # No dependencies = not blocked
+                continue
+
+            # Check for incomplete dependencies
+            blocking: List[Any] = []
+
+            for dep_id in deps:
+                dep_task = task_map.get(dep_id)
+
+                if dep_task is None:
+                    # Dependency doesn't exist - treat as blocker
+                    continue
+
+                dep_status = get_task_status(dep_task)
+
+                if dep_status != completed_status:
+                    blocking.append(dep_task)
+
+            if blocking:
+                blocked.append((task, blocking))
+
+        return blocked
+
+    @staticmethod
+    def get_execution_order(
+        tasks: List[Any],
+        get_task_id: callable,
+        get_dependency_ids: callable,
+    ) -> List[Any]:
+        """Get tasks in dependency execution order.
+
+        Args:
+            tasks: List of task objects
+            get_task_id: Function to extract task ID
+            get_dependency_ids: Function to extract dependency IDs
+
+        Returns:
+            List of tasks in execution order
+
+        Raises:
+            ValueError: If circular dependencies are detected
+
+        Example:
+            >>> ordered = DependencyResolver.get_execution_order(
+            ...     tasks,
+            ...     lambda t: t.id,
+            ...     lambda t: t.depends_on
+            ... )
+        """
+        # Build dependency graph
+        graph = DependencyResolver.build_dependency_graph(
+            tasks,
+            get_task_id,
+            get_dependency_ids,
+        )
+
+        # Get execution order
+        order = DependencyResolver.topological_sort(graph)
+
+        # Build task map and return in order
+        task_map = {get_task_id(t): t for t in tasks}
+
+        return [task_map[task_id] for task_id in order if task_id in task_map]

better_notion/utils/agents/project_context.py

@@ -0,0 +1,232 @@
+"""Project context management for agents workflow system.
+
+This module provides the ProjectContext class for managing project context
+stored in .notion files. Each project directory contains a .notion file
+that identifies the project, organization, and role for that directory.
+"""
+
+from dataclasses import dataclass, asdict
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+
+@dataclass
+class ProjectContext:
+    """Project context stored in .notion file.
+
+    The .notion file identifies which project the current directory belongs to,
+    allowing CLI commands to know which Notion database to query and what
+    permissions the current role has.
+
+    Attributes:
+        project_id: Notion page ID for the project
+        project_name: Human-readable project name
+        org_id: Notion page ID for the organization
+        role: Current role for this project context (default: Developer)
+
+    Example:
+        >>> context = ProjectContext.create(
+        ...     project_id="abc123",
+        ...     project_name="my-project",
+        ...     org_id="org789",
+        ...     role="Developer"
+        ... )
+        >>> print(context.project_id)
+        'abc123'
+
+        >>> # Load from current directory
+        >>> context = ProjectContext.from_current_directory()
+        >>> if context:
+        ...     print(f"Working on {context.project_name} as {context.role}")
+    """
+
+    project_id: str
+    project_name: str
+    org_id: str
+    role: str = "Developer"
+
+    @classmethod
+    def from_current_directory(cls) -> Optional["ProjectContext"]:
+        """Load .notion file from current directory or parent directories.
+
+        This method searches up the directory tree from the current working
+        directory until it finds a .notion file. This allows commands to work
+        from any subdirectory within a project.
+
+        Returns:
+            ProjectContext if .notion file is found, None otherwise
+
+        Example:
+            >>> # In /Users/dev/projects/my-project/src
+            >>> # .notion is in /Users/dev/projects/my-project
+            >>> context = ProjectContext.from_current_directory()
+            >>> # Will find and load the .notion file from parent directory
+        """
+        cwd = Path.cwd()
+
+        # Search up the directory tree
+        for parent in [cwd, *cwd.parents]:
+            notion_file = parent / ".notion"
+
+            if notion_file.exists() and notion_file.is_file():
+                try:
+                    with open(notion_file, encoding="utf-8") as f:
+                        data = yaml.safe_load(f)
+
+                    if data and isinstance(data, dict):
+                        return cls(**data)
+
+                except (yaml.YAMLError, TypeError, ValueError) as e:
+                    # Invalid YAML or data structure
+                    # Log and continue searching
+                    continue
+
+        return None
+
+    @classmethod
+    def from_path(cls, path: Path) -> Optional["ProjectContext"]:
+        """Load .notion file from specific path.
+
+        Args:
+            path: Path to directory containing .notion file
+
+        Returns:
+            ProjectContext if .notion file exists and is valid, None otherwise
+
+        Example:
+            >>> path = Path("/Users/dev/projects/my-project")
+            >>> context = ProjectContext.from_path(path)
+        """
+        notion_file = path / ".notion"
+
+        if not notion_file.exists() or not notion_file.is_file():
+            return None
+
+        try:
+            with open(notion_file, encoding="utf-8") as f:
+                data = yaml.safe_load(f)
+
+            if data and isinstance(data, dict):
+                return cls(**data)
+
+        except (yaml.YAMLError, TypeError, ValueError):
+            return None
+
+    @classmethod
+    def create(
+        cls,
+        project_id: str,
+        project_name: str,
+        org_id: str,
+        role: str = "Developer",
+        path: Optional[Path] = None,
+    ) -> "ProjectContext":
+        """Create new .notion file with project context.
+
+        Args:
+            project_id: Notion page ID for the project
+            project_name: Human-readable project name
+            org_id: Notion page ID for the organization
+            role: Role for this project context (default: Developer)
+            path: Directory where to create .notion file (default: cwd)
+
+        Returns:
+            New ProjectContext instance
+
+        Raises:
+            IOError: If unable to write to the .notion file
+
+        Example:
+            >>> context = ProjectContext.create(
+            ...     project_id="abc123def456",
+            ...     project_name="my-awesome-project",
+            ...     org_id="org789xyz012",
+            ...     role="Developer",
+            ...     path=Path.cwd()
+            ... )
+        """
+        if path is None:
+            path = Path.cwd()
+
+        context = cls(
+            project_id=project_id,
+            project_name=project_name,
+            org_id=org_id,
+            role=role,
+        )
+
+        notion_file = path / ".notion"
+
+        with open(notion_file, "w", encoding="utf-8") as f:
+            yaml.dump(asdict(context), f, default_flow_style=False, sort_keys=False)
+
+        return context
+
+    def save(self, path: Optional[Path] = None) -> None:
+        """Save context to .notion file.
+
+        Args:
+            path: Directory where to save .notion file (default: cwd)
+
+        Raises:
+            IOError: If unable to write to the .notion file
+
+        Example:
+            >>> context.role = "PM"
+            >>> context.save()
+        """
+        if path is None:
+            path = Path.cwd()
+
+        notion_file = path / ".notion"
+
+        with open(notion_file, "w", encoding="utf-8") as f:
+            yaml.dump(asdict(self), f, default_flow_style=False, sort_keys=False)
+
+    def update_role(self, new_role: str, path: Optional[Path] = None) -> None:
+        """Update project role and save to .notion file.
+
+        Args:
+            new_role: New role value
+            path: Directory where .notion file is located (default: cwd)
+
+        Example:
+            >>> context.update_role("PM")
+            >>> print(context.role)
+            'PM'
+        """
+        self.role = new_role
+        self.save(path)
+
+    def has_permission(self, permission: str) -> bool:
+        """Check if current role has a specific permission.
+
+        This is a convenience method that will integrate with the
+        RoleManager class. For now, it returns True for all permissions.
+
+        Args:
+            permission: Permission string (e.g., "tasks:claim")
+
+        Returns:
+            True if role has permission, False otherwise
+
+        Example:
+            >>> if context.has_permission("tasks:claim"):
+            ...     # Claim the task
+        """
+        # TODO: Integrate with RoleManager
+        # For now, allow all permissions
+        return True
+
+    def __repr__(self) -> str:
+        """String representation of project context."""
+        return (
+            f"ProjectContext("
+            f"project_id={self.project_id!r}, "
+            f"project_name={self.project_name!r}, "
+            f"org_id={self.org_id!r}, "
+            f"role={self.role!r}"
+            f")"
+        )