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

better_notion/utils/agents/state_machine.py

@@ -0,0 +1,216 @@
+"""State machine for managing task status transitions.
+
+This module provides the state machine logic for task workflow transitions,
+ensuring that tasks only move through valid states.
+"""
+
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+
+class TaskStatus(Enum):
+    """Task status values following the workflow.
+
+    The typical workflow is:
+        Backlog → Claimed → In Progress → In Review → Completed
+
+    Tasks can be Cancelled from most states.
+    """
+
+    BACKLOG = "Backlog"
+    CLAIMED = "Claimed"
+    IN_PROGRESS = "In Progress"
+    IN_REVIEW = "In Review"
+    COMPLETED = "Completed"
+    CANCELLED = "Cancelled"
+
+
+class TaskStateMachine:
+    """Manages valid task status transitions.
+
+    This state machine enforces the workflow rules for task status changes.
+    It prevents invalid transitions and provides helpers for querying
+    possible next states.
+
+    Example:
+        >>> # Check if a transition is valid
+        >>> is_valid = TaskStateMachine.can_transition(
+        ...     TaskStatus.BACKLOG,
+        ...     TaskStatus.CLAIMED
+        ... )
+        >>> print(is_valid)  # True
+
+        >>> # Get next possible states
+        >>> next_states = TaskStateMachine.get_next_statuses("Backlog")
+        >>> print(next_states)  # ["Claimed", "Cancelled"]
+
+        >>> # Validate transition
+        >>> is_valid, error = TaskStateMachine.validate_transition(
+        ...     "Backlog",
+        ...     "Completed"
+        ... )
+        >>> print(error)  # "Invalid transition: Backlog → Completed"
+    """
+
+    # Define valid state transitions
+    TRANSITIONS: Dict[TaskStatus, List[TaskStatus]] = {
+        TaskStatus.BACKLOG: [
+            TaskStatus.CLAIMED,
+            TaskStatus.CANCELLED,
+        ],
+        TaskStatus.CLAIMED: [
+            TaskStatus.IN_PROGRESS,
+            TaskStatus.BACKLOG,  # Unclaim and return to backlog
+            TaskStatus.CANCELLED,
+        ],
+        TaskStatus.IN_PROGRESS: [
+            TaskStatus.IN_REVIEW,
+            TaskStatus.COMPLETED,  # Skip review if not needed
+            TaskStatus.CANCELLED,
+        ],
+        TaskStatus.IN_REVIEW: [
+            TaskStatus.COMPLETED,
+            TaskStatus.IN_PROGRESS,  # Request changes during review
+            TaskStatus.CANCELLED,
+        ],
+        TaskStatus.COMPLETED: [
+            # Terminal state - no transitions out
+        ],
+        TaskStatus.CANCELLED: [
+            # Terminal state - no transitions out
+        ],
+    }
+
+    @classmethod
+    def can_transition(
+        cls,
+        from_status: TaskStatus,
+        to_status: TaskStatus,
+    ) -> bool:
+        """Check if a transition between two states is valid.
+
+        Args:
+            from_status: Current state
+            to_status: Desired next state
+
+        Returns:
+            True if the transition is valid, False otherwise
+
+        Example:
+            >>> TaskStateMachine.can_transition(
+            ...     TaskStatus.BACKLOG,
+            ...     TaskStatus.CLAIMED
+            ... )
+            True
+        """
+        allowed = cls.TRANSITIONS.get(from_status, [])
+        return to_status in allowed
+
+    @classmethod
+    def validate_transition(
+        cls,
+        from_status: str,
+        to_status: str,
+    ) -> Tuple[bool, Optional[str]]:
+        """Validate a transition and return (is_valid, error_message).
+
+        This is a convenience method that handles string status values
+        and returns a detailed error message if the transition is invalid.
+
+        Args:
+            from_status: Current status as string
+            to_status: Desired next status as string
+
+        Returns:
+            Tuple of (is_valid, error_message):
+            - is_valid: True if transition is valid
+            - error_message: None if valid, error description if invalid
+
+        Example:
+            >>> is_valid, error = TaskStateMachine.validate_transition(
+            ...     "Backlog",
+            ...     "Claimed"
+            ... )
+            >>> print(is_valid)  # True
+            >>> print(error)  # None
+
+            >>> is_valid, error = TaskStateMachine.validate_transition(
+            ...     "Completed",
+            ...     "In Progress"
+            ... )
+            >>> print(is_valid)  # False
+            >>> print(error)  # "Invalid transition: Completed → In Progress"
+        """
+        try:
+            from_enum = TaskStatus(from_status)
+            to_enum = TaskStatus(to_status)
+        except ValueError as e:
+            return False, f"Invalid status values: {from_status} → {to_status}"
+
+        if not cls.can_transition(from_enum, to_enum):
+            return False, f"Invalid transition: {from_status} → {to_status}"
+
+        return True, None
+
+    @classmethod
+    def get_next_statuses(cls, current_status: str) -> List[str]:
+        """Get list of valid next statuses from current status.
+
+        Args:
+            current_status: Current status as string
+
+        Returns:
+            List of valid next status values as strings
+
+        Example:
+            >>> TaskStateMachine.get_next_statuses("Backlog")
+            ["Claimed", "Cancelled"]
+
+            >>> TaskStateMachine.get_next_statuses("Completed")
+            []
+        """
+        try:
+            current_enum = TaskStatus(current_status)
+            next_enums = cls.TRANSITIONS.get(current_enum, [])
+            return [e.value for e in next_enums]
+        except ValueError:
+            return []
+
+    @classmethod
+    def is_terminal_state(cls, status: str) -> bool:
+        """Check if a status is a terminal state (no transitions out).
+
+        Terminal states are Completed and Cancelled.
+
+        Args:
+            status: Status to check
+
+        Returns:
+            True if status is terminal, False otherwise
+
+        Example:
+            >>> TaskStateMachine.is_terminal_state("Completed")
+            True
+
+            >>> TaskStateMachine.is_terminal_state("In Progress")
+            False
+        """
+        try:
+            status_enum = TaskStatus(status)
+            allowed = cls.TRANSITIONS.get(status_enum, [])
+            return len(allowed) == 0
+        except ValueError:
+            return False
+
+    @classmethod
+    def get_initial_state(cls) -> str:
+        """Get the initial state for new tasks.
+
+        Returns:
+            The initial task status (Backlog)
+
+    Example:
+        >>> TaskStateMachine.get_initial_state()
+        "Backlog"
+        """
+        return TaskStatus.BACKLOG.value

better_notion/utils/agents/workspace.py

@@ -0,0 +1,371 @@
+"""Workspace initializer for the agents workflow system.
+
+This module provides functionality to initialize a new workspace with all
+required databases for the workflow management system.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from better_notion._cli.config import Config
+from better_notion._sdk.client import NotionClient
+from better_notion._sdk.models.page import Page
+from better_notion.utils.agents.schemas import (
+    IncidentSchema,
+    IdeaSchema,
+    OrganizationSchema,
+    ProjectSchema,
+    TagSchema,
+    TaskSchema,
+    VersionSchema,
+    WorkIssueSchema,
+)
+
+
+class WorkspaceInitializer:
+    """Initialize a new workspace with workflow databases.
+
+    This class handles the creation of all required databases and their
+    relationships for the agents workflow system.
+
+    Example:
+        >>> initializer = WorkspaceInitializer(client)
+        >>> database_ids = await initializer.initialize_workspace(
+        ...     parent_page_id="page123",
+        ...     workspace_name="My Workspace"
+        ... )
+    """
+
+    def __init__(self, client: NotionClient) -> None:
+        """Initialize the workspace initializer.
+
+        Args:
+            client: Authenticated NotionClient instance
+        """
+        self._client = client
+        self._database_ids: Dict[str, str] = {}
+
+    async def initialize_workspace(
+        self,
+        parent_page_id: str,
+        workspace_name: str = "Agents Workspace",
+    ) -> Dict[str, str]:
+        """Initialize a complete workspace with all databases.
+
+        Creates all 8 databases in the correct order, establishing
+        relationships between them.
+
+        Args:
+            parent_page_id: ID of the parent page where databases will be created
+            workspace_name: Name for the workspace (used for database titles)
+
+        Returns:
+            Dict mapping database names to their IDs
+
+        Raises:
+            Exception: If database creation fails
+        """
+        # Get parent page
+        parent = await Page.get(parent_page_id, client=self._client)
+
+        # Create databases in order (independent first, then dependent)
+        self._database_ids = {}
+
+        # 1. Organizations (independent)
+        await self._create_organizations_db(parent)
+
+        # 2. Tags (independent)
+        await self._create_tags_db(parent)
+
+        # 3. Projects (depends on Organizations)
+        await self._create_projects_db(parent)
+
+        # 4. Versions (depends on Projects)
+        await self._create_versions_db(parent)
+
+        # 5. Tasks (depends on Versions)
+        await self._create_tasks_db(parent)
+
+        # 6. Ideas (depends on Projects)
+        await self._create_ideas_db(parent)
+
+        # 7. Work Issues (depends on Projects, Tasks, Ideas)
+        await self._create_work_issues_db(parent)
+
+        # 8. Incidents (depends on Projects, Versions, Tasks)
+        await self._create_incidents_db(parent)
+
+        return self._database_ids
+
+    async def _create_organizations_db(self, parent: Page) -> None:
+        """Create Organizations database."""
+        schema = OrganizationSchema.get_schema()
+
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Organizations",
+            schema=schema,
+        )
+
+        self._database_ids["organizations"] = db.id
+
+    async def _create_tags_db(self, parent: Page) -> None:
+        """Create Tags database."""
+        schema = TagSchema.get_schema()
+
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Tags",
+            schema=schema,
+        )
+
+        self._database_ids["tags"] = db.id
+
+    async def _create_projects_db(self, parent: Page) -> None:
+        """Create Projects database with relation to Organizations."""
+        schema = ProjectSchema.get_schema()
+
+        # Update relation with Organizations database ID
+        if "organizations" in self._database_ids:
+            schema["Organization"]["relation"]["database_id"] = self._database_ids[
+                "organizations"
+            ]
+
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Projects",
+            schema=schema,
+        )
+
+        self._database_ids["projects"] = db.id
+
+        # Update Organizations database with reverse relation
+        await self._add_reverse_relation(
+            self._database_ids["organizations"],
+            db.id,
+            "Projects",
+        )
+
+    async def _create_versions_db(self, parent: Page) -> None:
+        """Create Versions database with relation to Projects."""
+        schema = VersionSchema.get_schema()
+
+        # Update relation with Projects database ID
+        if "projects" in self._database_ids:
+            schema["Project"]["relation"]["database_id"] = self._database_ids["projects"]
+
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Versions",
+            schema=schema,
+        )
+
+        self._database_ids["versions"] = db.id
+
+        # Update Projects database with reverse relation
+        await self._add_reverse_relation(
+            self._database_ids["projects"],
+            db.id,
+            "Versions",
+        )
+
+    async def _create_tasks_db(self, parent: Page) -> None:
+        """Create Tasks database with relations to Versions (self-referencing for dependencies)."""
+        schema = TaskSchema.get_schema()
+
+        # Update relations with Versions database ID
+        if "versions" in self._database_ids:
+            schema["Version"]["relation"]["database_id"] = self._database_ids["versions"]
+            schema["Target Version"]["relation"]["database_id"] = self._database_ids[
+                "versions"
+            ]
+
+        # Tasks reference themselves for dependencies
+        # Will be updated after database creation
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Tasks",
+            schema=schema,
+        )
+
+        self._database_ids["tasks"] = db.id
+
+        # Update self-referential relations
+        await self._update_self_relations(db.id)
+
+        # Update Versions database with reverse relation
+        await self._add_reverse_relation(
+            self._database_ids["versions"],
+            db.id,
+            "Tasks",
+        )
+
+    async def _create_ideas_db(self, parent: Page) -> None:
+        """Create Ideas database with relations to Projects and Tasks."""
+        schema = IdeaSchema.get_schema()
+
+        # Update relations
+        if "projects" in self._database_ids:
+            schema["Project"]["relation"]["database_id"] = self._database_ids["projects"]
+
+        # Related Task will be updated after Tasks DB creation
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Ideas",
+            schema=schema,
+        )
+
+        self._database_ids["ideas"] = db.id
+
+        # Update Projects database with reverse relation
+        await self._add_reverse_relation(
+            self._database_ids["projects"],
+            db.id,
+            "Ideas",
+        )
+
+    async def _create_work_issues_db(self, parent: Page) -> None:
+        """Create Work Issues database with relations."""
+        schema = WorkIssueSchema.get_schema()
+
+        # Update relations
+        if "projects" in self._database_ids:
+            schema["Project"]["relation"]["database_id"] = self._database_ids["projects"]
+        if "tasks" in self._database_ids:
+            schema["Task"]["relation"]["database_id"] = self._database_ids["tasks"]
+        if "ideas" in self._database_ids:
+            schema["Related Idea"]["relation"]["database_id"] = self._database_ids["ideas"]
+
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Work Issues",
+            schema=schema,
+        )
+
+        self._database_ids["work_issues"] = db.id
+
+    async def _create_incidents_db(self, parent: Page) -> None:
+        """Create Incidents database with relations."""
+        schema = IncidentSchema.get_schema()
+
+        # Update relations
+        if "projects" in self._database_ids:
+            schema["Project"]["relation"]["database_id"] = self._database_ids["projects"]
+        if "versions" in self._database_ids:
+            schema["Affected Version"]["relation"][
+                "database_id"
+            ] = self._database_ids["versions"]
+        if "tasks" in self._database_ids:
+            schema["Fix Task"]["relation"]["database_id"] = self._database_ids["tasks"]
+
+        db = await self._client.databases.create(
+            parent=parent,
+            title="Incidents",
+            schema=schema,
+        )
+
+        self._database_ids["incidents"] = db.id
+
+    async def _add_reverse_relation(
+        self,
+        database_id: str,
+        related_db_id: str,
+        property_name: str,
+    ) -> None:
+        """Add reverse relation to a database.
+
+        Note: This is a placeholder. The actual Notion API creates
+        dual_property relations automatically. This method exists
+        for documentation purposes.
+        """
+        # Notion API handles dual_property relations automatically
+        # This is a no-op but documents the intent
+        pass
+
+    async def _update_self_relations(self, database_id: str) -> None:
+        """Update self-referential relations in Tasks database.
+
+        Note: The database was created with placeholder relations.
+        This method updates them to point to themselves.
+        """
+        # Get the database
+        db = await self._client.databases.get(database_id)
+
+        # Update Dependencies and Dependent Tasks to point to self
+        # Note: This would require updating the database schema
+        # via the Notion API, which may not support all updates
+        pass
+
+    def save_database_ids(self, path: Optional[Path] = None) -> None:
+        """Save database IDs to a config file.
+
+        Args:
+            path: Path to save config file (default: ~/.notion/workspace.json)
+        """
+        if path is None:
+            path = Path.home() / ".notion" / "workspace.json"
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(self._database_ids, f, indent=2)
+
+    @classmethod
+    def load_database_ids(cls, path: Optional[Path] = None) -> Dict[str, str]:
+        """Load database IDs from config file.
+
+        Args:
+            path: Path to config file (default: ~/.notion/workspace.json)
+
+        Returns:
+            Dict mapping database names to IDs
+
+        Raises:
+            FileNotFoundError: If config file doesn't exist
+        """
+        if path is None:
+            path = Path.home() / ".notion" / "workspace.json"
+
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+
+
+async def initialize_workspace_command(
+    parent_page_id: str,
+    workspace_name: str = "Agents Workspace",
+) -> Dict[str, str]:
+    """Convenience function to initialize a workspace.
+
+    Args:
+        parent_page_id: ID of parent page
+        workspace_name: Name for the workspace
+
+    Returns:
+        Dict mapping database names to IDs
+
+    Example:
+        >>> from better_notion._cli.config import Config
+        >>> from better_notion._sdk.client import NotionClient
+        >>>
+        >>> config = Config.load()
+        >>> client = NotionClient(auth=config.token)
+        >>>
+        >>> db_ids = await initialize_workspace_command(
+        ...     parent_page_id="page123",
+        ...     workspace_name="My Workspace"
+        ... )
+    """
+    from better_notion._cli.config import Config
+    from better_notion._sdk.client import NotionClient
+
+    config = Config.load()
+    client = NotionClient(auth=config.token)
+
+    initializer = WorkspaceInitializer(client)
+    database_ids = await initializer.initialize_workspace(parent_page_id, workspace_name)
+
+    # Save to config file
+    initializer.save_database_ids()
+
+    return database_ids

{better_notion-0.9.9.dist-info → better_notion-1.0.1.dist-info}/METADATA

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: better-notion
-Version: 0.9.9
-Summary: A high-level Python SDK for the Notion API with developer experience in mind.
+Version: 1.0.1
+Summary: A high-level Python SDK for the Notion API with developer experience in mind. Now with AI agents workflow management system!
 Project-URL: Homepage, https://github.com/nesalia-inc/better-notion
 Project-URL: Documentation, https://github.com/nesalia-inc/better-notion#readme
 Project-URL: Repository, https://github.com/nesalia-inc/better-notion

{better_notion-0.9.9.dist-info → better_notion-1.0.1.dist-info}/RECORD

@@ -105,13 +105,22 @@ better_notion/plugins/__init__.py,sha256=ZbaLy0BS4_zWfEyCW0Xv9EhK427cEhrKIap_8DR
 better_notion/plugins/base.py,sha256=G2asUEvQXWIiyWvNtB1hgg9JXZhDayi7Jvfq15FeQWY,5255
 better_notion/plugins/loader.py,sha256=ewCG_Thv7Khh8IsHLB17U1Hi0cWpq0YG3w37hrpbeRk,7710
 better_notion/plugins/state.py,sha256=jH_tZWvC35hqLO4qwl2Kwq9ziWVavwCEUcCqy3s5wMY,3780
-better_notion/plugins/official/__init__.py,sha256=4c0kaPLOqUQ7vIISgCm4Y9TG306Vew5A8dfDrLsAGwc,327
+better_notion/plugins/official/__init__.py,sha256=rPg5vdk1cEANVstMPzxcWmImtsOpdSR40JSml7h1uUk,426
+better_notion/plugins/official/agents.py,sha256=8Cwx5fkNMaYc1bavS48jyvaXCTMYWgCaIMZH0y9YSbM,12696
 better_notion/plugins/official/productivity.py,sha256=_-whP4pYA4HufE1aUFbIdhrjU-O9njI7xUO_Id2M1J8,8726
 better_notion/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 better_notion/utils/helpers.py,sha256=HgFuUQlG_HzBOB0z2GA9RxPLoXgwRc0DIxa9Fg6C-Jk,2337
 better_notion/utils/retry.py,sha256=9WJDNitiIfVTL18hIlipvOKn41ukePrOwtAwx-LevpQ,7479
-better_notion-0.9.9.dist-info/METADATA,sha256=Dr3EAgGQk505eplEDCEObHyv1bf81bkjjWNI9d6cPOQ,11096
-better_notion-0.9.9.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-better_notion-0.9.9.dist-info/entry_points.txt,sha256=D0bUcP7Z00Zyjxw7r2p29T95UrwioDO0aGDoHe9I6fo,55
-better_notion-0.9.9.dist-info/licenses/LICENSE,sha256=BAdN3JpgMY_y_fWqZSCFSvSbC2mTHP-BKDAzF5FXQAI,1069
-better_notion-0.9.9.dist-info/RECORD,,
+better_notion/utils/agents/__init__.py,sha256=Zu32q0abbimrJY5dczjWNEastE-IrtGPQjpxD4JS4IU,1715
+better_notion/utils/agents/auth.py,sha256=_SBcqBjXmX8CJMCPpRWM-UuaDg7-OOtMWbhnYEiIBTs,6568
+better_notion/utils/agents/dependency_resolver.py,sha256=PfHHDIQztGih4LwylMb0_MyhDFbOYPjvUxcxY52mSEs,12033
+better_notion/utils/agents/project_context.py,sha256=aJlzy5H2rL4sAfW2jHL_3K2VkBJ4ihUhCRVolkpuO78,7477
+better_notion/utils/agents/rbac.py,sha256=8ZA8Y7wbOiVZDbpjpH7iC35SZrZ0jl4fcJ3xWCm3SsE,11820
+better_notion/utils/agents/schemas.py,sha256=e_lpGGO12FXtfqFyI91edj9xc5RUtuA6pU7Sk6ip7xg,21784
+better_notion/utils/agents/state_machine.py,sha256=xUBEeDTbU1Xq-rsRo2sbr6AUYpYrV9DTHOtZT2cWES8,6699
+better_notion/utils/agents/workspace.py,sha256=T8mP_DNIWhI1-k6UydJINsEJ6kQxQ6_Pa44ul58k088,12370
+better_notion-1.0.1.dist-info/METADATA,sha256=twwihoncbT6FKJ_VmFtC_5g2zXSY12q-YAWFm4hLaqQ,11143
+better_notion-1.0.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+better_notion-1.0.1.dist-info/entry_points.txt,sha256=D0bUcP7Z00Zyjxw7r2p29T95UrwioDO0aGDoHe9I6fo,55
+better_notion-1.0.1.dist-info/licenses/LICENSE,sha256=BAdN3JpgMY_y_fWqZSCFSvSbC2mTHP-BKDAzF5FXQAI,1069
+better_notion-1.0.1.dist-info/RECORD,,