better-notion 1.5.4__py3-none-any.whl → 1.6.0__py3-none-any.whl

better_notion/plugins/official/agents_schema.py

@@ -0,0 +1,369 @@
+"""Agents plugin schema for AI agent documentation.
+
+This module provides comprehensive documentation about the agents workflow
+system that AI agents can consume to understand how to work with the system.
+
+This is the SINGLE SOURCE OF TRUTH for agents documentation. All other
+documentation (CLI help, website, etc.) should be derived from this schema.
+"""
+
+from better_notion._cli.docs.base import (
+    Command,
+    Concept,
+    Schema,
+    Workflow,
+    WorkflowStep,
+)
+
+# =============================================================================
+# CONCEPTS
+# =============================================================================
+
+WORKSPACE_CONCEPT = Concept(
+    name="workspace",
+    description=(
+        "A workspace is a collection of 8 interconnected databases that implement "
+        "a complete software development workflow management system. It provides "
+        "the structure for tracking organizations, projects, versions, tasks, ideas, "
+        "work issues, and incidents in a unified manner."
+    ),
+    properties={
+        "databases": [
+            "Organizations",
+            "Tags",
+            "Projects",
+            "Versions",
+            "Tasks",
+            "Ideas",
+            "Work Issues",
+            "Incidents",
+        ],
+        "initialization": "Created via 'agents init' command",
+        "detection": "Automatically detected by scanning for expected databases",
+        "uniqueness": "One workspace per Notion page",
+    },
+    relationships={
+        "Organizations → Projects": "Many-to-one (many projects belong to one organization)",
+        "Projects → Versions": "Many-to-one (many versions belong to one project)",
+        "Versions → Tasks": "Many-to-one (many tasks belong to one version)",
+        "Tasks → Tasks": "Self-referential (tasks can depend on other tasks)",
+    },
+)
+
+TASK_CONCEPT = Concept(
+    name="task",
+    description=(
+        "A task represents a unit of work that needs to be completed as part of "
+        "a project version. Tasks have states (Todo, In Progress, Done, Cancelled) "
+        "and can depend on other tasks."
+    ),
+    properties={
+        "required_properties": {
+            "Title": "Task name (title property)",
+            "Status": "Current state: Todo, In Progress, Done, Cancelled",
+            "Version": "Relation to Version database (required)",
+        },
+        "optional_properties": {
+            "Target Version": "Version where task should be implemented",
+            "Dependencies": "Other tasks this task depends on",
+            "Dependent Tasks": "Tasks that depend on this task",
+        },
+        "workflow": "Todo → In Progress → Done",
+    },
+    relationships={
+        "Version": "Required - each task must belong to one version",
+        "Dependencies": "Optional - tasks that must complete before this task",
+        "Dependent Tasks": "Inverse of dependencies - tasks blocked by this task",
+    },
+)
+
+PROJECT_CONCEPT = Concept(
+    name="project",
+    description=(
+        "A project represents a software project or product being developed. "
+        "Projects belong to organizations and contain multiple versions."
+    ),
+    properties={
+        "required_properties": {
+            "Title": "Project name",
+            "Organization": "Relation to organization (required)",
+        },
+        "contains": ["Versions", "Tasks", "Ideas", "Work Issues", "Incidents"],
+    },
+    relationships={
+        "Organization": "Required - each project belongs to one organization",
+        "Versions": "One-to-many - project contains multiple versions",
+    },
+)
+
+VERSION_CONCEPT = Concept(
+    name="version",
+    description=(
+        "A version represents a release or milestone of a project. Examples: "
+        "v1.0.0, v1.1.0, v2.0.0. Tasks are created within versions."
+    ),
+    properties={
+        "required_properties": {
+            "Title": "Version name (e.g., v1.0.0)",
+            "Project": "Relation to project (required)",
+        },
+        "contains": ["Tasks"],
+        "examples": ["v1.0.0", "v1.1.0", "v2.0.0-beta", "sprint-1"],
+    },
+    relationships={
+        "Project": "Required - each version belongs to one project",
+        "Tasks": "One-to-many - version contains multiple tasks",
+    },
+)
+
+# =============================================================================
+# WORKFLOWS
+# =============================================================================
+
+INITIALIZE_WORKSPACE = Workflow(
+    name="initialize_workspace",
+    description="Create a complete agents workflow management system with 8 databases",
+    steps=[
+        WorkflowStep(
+            description="Detect existing workspace in page",
+            purpose="Prevent duplicate workspace creation",
+        ),
+        WorkflowStep(
+            description="Create Organizations database",
+            command="notion databases create --parent PAGE_ID --title Organizations",
+        ),
+        WorkflowStep(
+            description="Create Tags database",
+            command="notion databases create --parent PAGE_ID --title Tags",
+        ),
+        WorkflowStep(
+            description="Create Projects database",
+            command="notion databases create --parent PAGE_ID --title Projects",
+        ),
+        WorkflowStep(
+            description="Create Versions database",
+            command="notion databases create --parent PAGE_ID --title Versions",
+        ),
+        WorkflowStep(
+            description="Create Tasks database",
+            command="notion databases create --parent PAGE_ID --title Tasks",
+        ),
+        WorkflowStep(
+            description="Create Ideas database",
+            command="notion databases create --parent PAGE_ID --title Ideas",
+        ),
+        WorkflowStep(
+            description="Create Work Issues database",
+            command="notion databases create --parent PAGE_ID --title 'Work Issues'",
+        ),
+        WorkflowStep(
+            description="Create Incidents database",
+            command="notion databases create --parent PAGE_ID --title Incidents",
+        ),
+        WorkflowStep(
+            description="Establish database relationships",
+            purpose="Create relations between databases (Projects→Organizations, etc.)",
+        ),
+        WorkflowStep(
+            description="Save workspace metadata",
+            command="agents info --parent-page PAGE_ID",
+            purpose="Verify setup and get database IDs",
+        ),
+    ],
+    commands=[
+        "agents init --parent-page PAGE_ID",
+        "agents info --parent-page PAGE_ID",
+    ],
+    prerequisites=["valid_page_id"],
+    error_recovery={
+        "workspace_exists": {
+            "message": "Detected 5+ expected databases in page",
+            "meaning": "Workspace already initialized in this page",
+            "solutions": [
+                {
+                    "flag": "--skip",
+                    "action": "use_existing_workspace",
+                    "description": "Skip initialization and use existing workspace",
+                    "when_to_use": "You want to keep existing data",
+                },
+                {
+                    "flag": "--reset",
+                    "action": "recreate_workspace",
+                    "description": "Delete all databases and recreate (WARNING: data loss)",
+                    "warning": "This will delete all existing databases and their content",
+                    "when_to_use": "You want to start completely fresh",
+                },
+            ],
+        }
+    },
+)
+
+CREATE_TASK_WORKFLOW = Workflow(
+    name="create_task",
+    description="Create a new task in the agents workflow system",
+    steps=[
+        WorkflowStep(
+            description="Verify workspace is initialized",
+            command="agents info --parent-page PAGE_ID",
+            purpose="Get database IDs and verify workspace exists",
+        ),
+        WorkflowStep(
+            description="Identify target Version",
+            purpose="Tasks must belong to a Version (required relation)",
+        ),
+        WorkflowStep(
+            description="Create task page with proper properties",
+            command="notion pages create --parent TASKS_DB_ID --title 'Task Name' --properties '{...}'",
+            purpose="Create task with Status and Version relation",
+        ),
+    ],
+    commands=[
+        "agents info --parent-page PAGE_ID",
+        "notion pages create --parent TASKS_DB_ID --title 'Task' --properties '{\"Status\": \"Todo\", \"Version\": \"VERSION_ID\"}'",
+    ],
+    prerequisites=["workspace_initialized"],
+    error_recovery={
+        "workspace_not_found": {
+            "message": "No workspace detected in page",
+            "solution": "Run 'agents init' first to create workspace",
+        },
+        "missing_version_relation": {
+            "message": "Task must have a Version relation",
+            "solution": "Always specify Version property when creating task",
+        },
+    },
+)
+
+QUERY_TASKS_WORKFLOW = Workflow(
+    name="query_tasks",
+    description="Query and filter tasks in the workspace",
+    steps=[
+        WorkflowStep(
+            description="Get workspace database IDs",
+            command="agents info --parent-page PAGE_ID",
+            purpose="Obtain tasks database ID",
+        ),
+        WorkflowStep(
+            description="Query tasks database",
+            command="notion databases query --database TASKS_DB_ID --filter '{...}'",
+            purpose="Retrieve tasks with optional filtering",
+        ),
+    ],
+    commands=[
+        "agents info --parent-page PAGE_ID",
+        "notion databases query --database TASKS_DB_ID",
+    ],
+    prerequisites=["workspace_initialized"],
+)
+
+# =============================================================================
+# COMMANDS
+# =============================================================================
+
+INIT_COMMAND = Command(
+    name="init",
+    purpose="Initialize a new agents workspace or manage existing one",
+    description=(
+        "Creates a complete workflow management system with 8 databases "
+        "and their relationships. Can detect existing workspaces to prevent duplicates."
+    ),
+    flags={
+        "--parent-page": "Parent page ID where workspace will be created",
+        "--workspace-name": "Name for the workspace (default: 'Agents Workspace')",
+        "--reset": "Force recreation (deletes existing databases and recreates)",
+        "--skip": "Skip initialization if workspace already exists",
+        "--debug": "Enable debug output",
+    },
+    workflow="initialize_workspace",
+    when_to_use=[
+        "First time setting up agents system in a page",
+        "Starting fresh in a new page",
+        "Recovering from corrupted workspace (use --reset)",
+        "Safely checking for existing workspace (use --skip)",
+    ],
+    error_recovery={
+        "workspace_exists": {
+            "solutions": [
+                {"flag": "--skip", "use_case": "Keep existing workspace"},
+                {"flag": "--reset", "use_case": "Delete and recreate (data loss)"},
+            ]
+        }
+    },
+)
+
+INFO_COMMAND = Command(
+    name="info",
+    purpose="Display workspace status and metadata",
+    description="Shows whether a workspace exists, database IDs, and workspace info",
+    flags={
+        "--parent-page": "Parent page ID to check for workspace",
+    },
+    workflow=None,
+    when_to_use=[
+        "Verify workspace initialization",
+        "Get database IDs for queries",
+        "Check workspace version and metadata",
+        "Debug workspace issues",
+    ],
+)
+
+# =============================================================================
+# COMPLETE SCHEMA
+# =============================================================================
+
+AGENTS_SCHEMA = Schema(
+    name="agents",
+    version="1.0.0",
+    description=(
+        "Workflow management system for software development. "
+        "Provides complete structure for tracking organizations, projects, "
+        "versions, tasks, ideas, work issues, and incidents."
+    ),
+    concepts=[
+        WORKSPACE_CONCEPT,
+        TASK_CONCEPT,
+        PROJECT_CONCEPT,
+        VERSION_CONCEPT,
+    ],
+    workflows=[
+        INITIALIZE_WORKSPACE,
+        CREATE_TASK_WORKFLOW,
+        QUERY_TASKS_WORKFLOW,
+    ],
+    commands={
+        "init": INIT_COMMAND,
+        "info": INFO_COMMAND,
+    },
+    best_practices=[
+        "Always run 'agents info' before database operations to verify workspace state",
+        "Use --skip flag to safely check for existing workspaces (prevents duplicates)",
+        "Use --reset flag only when you need to recreate workspace (causes data loss)",
+        "Tasks must have a Version relation - always specify Version property",
+        "Check task dependencies before marking tasks as complete",
+        "Projects belong to Organizations - create organization first",
+        "Versions belong to Projects - create project first",
+        "Query tasks by Status to find next available task",
+    ],
+    examples={
+        "initial_setup": """# First time setup
+notion agents init --parent-page PAGE_ID
+
+# Verify setup
+notion agents info --parent-page PAGE_ID""",
+
+        "safe_initialization": """# Check if workspace exists, use if found
+notion agents init --parent-page PAGE_ID --skip""",
+
+        "force_recreate": """# Delete existing workspace and recreate (WARNING: data loss)
+notion agents init --parent-page PAGE_ID --reset""",
+
+        "query_workspace": """# Get workspace info and database IDs
+notion agents info --parent-page PAGE_ID""",
+
+        "create_task": """# After workspace is initialized
+notion pages create \\
+  --parent TASKS_DB_ID \\
+  --title "Fix login bug" \\
+  --properties '{"Status": "Todo", "Version": "VERSION_ID"}'""",
+    },
+)

better_notion/utils/agents/metadata.py

@@ -0,0 +1,185 @@
+"""Workspace metadata management for agents plugin.
+
+This module provides functionality to manage workspace metadata,
+including detecting duplicate workspaces and storing workspace information.
+"""
+
+import json
+import logging
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+from uuid import uuid4
+
+from better_notion._sdk.client import NotionClient
+from better_notion._sdk.models.page import Page
+
+logger = logging.getLogger(__name__)
+
+
+class WorkspaceMetadata:
+    """Manage workspace metadata for duplicate detection."""
+
+    # Property names used in Notion page
+    PROP_WORKSPACE_ID = "agents_workspace_id"
+    PROP_WORKSPACE_NAME = "agents_workspace_name"
+    PROP_INITIALIZED_AT = "agents_workspace_created"
+    PROP_VERSION = "agents_workspace_version"
+    PROP_DATABASE_IDS = "agents_workspace_databases"
+
+    @staticmethod
+    def generate_workspace_id() -> str:
+        """Generate a unique workspace ID.
+
+        Returns:
+            Unique workspace ID (UUID without hyphens for compactness)
+        """
+        return str(uuid4()).replace("-", "")
+
+    @staticmethod
+    def extract_metadata_from_page(page: Page) -> dict[str, Any]:
+        """Extract workspace metadata from page properties.
+
+        Args:
+            page: Page object to extract metadata from
+
+        Returns:
+            Dict with workspace metadata (empty if not initialized)
+
+        Example:
+            >>> metadata = WorkspaceMetadata.extract_metadata_from_page(page)
+            >>> if metadata.get("workspace_id"):
+            ...     print(f"Workspace: {metadata['workspace_name']}")
+        """
+        metadata = {}
+
+        # Try to get workspace ID from icon (stored as emoji)
+        # Notion doesn't support custom properties, so we use creative approaches
+
+        # Check if page icon contains our metadata marker
+        icon = page.icon
+        if icon and icon.startswith("🤖"):
+            metadata["is_agents_workspace"] = True
+            # Could encode data in icon, but keep it simple for now
+
+        return metadata
+
+    @staticmethod
+    async def detect_workspace(
+        page: Page,
+        client: NotionClient
+    ) -> dict[str, Any] | None:
+        """Detect if page already has an agents workspace.
+
+        Args:
+            page: Parent page to check
+            client: NotionClient instance
+
+        Returns:
+            Workspace metadata dict if found, None otherwise
+        """
+        # Primary detection: Scan for databases with expected names
+        expected_databases = [
+            "Organizations",
+            "Tags",
+            "Projects",
+            "Versions",
+            "Tasks",
+            "Ideas",
+            "Work Issues",
+            "Incidents"
+        ]
+
+        try:
+            # Search for databases in this page
+            results = await client.search(
+                query="",
+                filter={"value": "database", "property": "object"}
+            )
+
+            databases_found = []
+            database_ids = {}
+
+            for result in results:
+                if hasattr(result, 'title') and result.title in expected_databases:
+                    databases_found.append(result.title)
+                    # Extract the key name (lowercase with underscores)
+                    key = result.title.lower().replace(" ", "_")
+                    database_ids[key] = result.id
+
+            # Check if we have at least 5 of the expected databases
+            matches = len(databases_found)
+            if matches >= 5:
+                logger.info(f"Detected existing workspace with {matches}/{len(expected_databases)} databases in page {page.id}")
+
+                # Try to load workspace metadata from local config to get workspace_id
+                workspace_id = None
+                workspace_name = None
+                initialized_at = None
+
+                try:
+                    config_path = Path.home() / ".notion" / "workspace.json"
+                    if config_path.exists():
+                        with open(config_path, "r", encoding="utf-8") as f:
+                            config = json.load(f)
+                            # Only use config if it matches this page
+                            if config.get("parent_page") == page.id:
+                                workspace_id = config.get("workspace_id")
+                                workspace_name = config.get("workspace_name")
+                                initialized_at = config.get("initialized_at")
+                                logger.info(f"Config file matches this page, workspace_id: {workspace_id}")
+                except Exception as e:
+                    logger.debug(f"Could not load local config: {e}")
+
+                return {
+                    "workspace_id": workspace_id,
+                    "workspace_name": workspace_name,
+                    "initialized_at": initialized_at,
+                    "database_ids": database_ids,
+                    "detection_method": "database_scan",
+                    "databases_count": matches
+                }
+        except Exception as e:
+            logger.debug(f"Could not scan for databases: {e}")
+
+        return None
+
+    @staticmethod
+    def save_workspace_config(
+        page_id: str,
+        workspace_id: str,
+        workspace_name: str,
+        database_ids: dict[str, str],
+        path: Optional[Path] = None
+    ) -> Path:
+        """Save workspace configuration to local file.
+
+        Args:
+            page_id: Parent page ID
+            workspace_id: Unique workspace ID
+            workspace_name: Workspace name
+            database_ids: Dict of database name to ID
+            path: Optional custom path for config file
+
+        Returns:
+            Path to saved config file
+        """
+        if path is None:
+            path = Path.home() / ".notion" / "workspace.json"
+
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        config = {
+            "workspace_id": workspace_id,
+            "workspace_name": workspace_name,
+            "parent_page": page_id,
+            "initialized_at": datetime.now(timezone.utc).isoformat(),
+            "version": "1.5.4",  # Track version for migrations
+            "database_ids": database_ids
+        }
+
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(config, f, indent=2)
+
+        logger.info(f"Saved workspace config to {path}")
+        return path

better_notion/utils/agents/workspace.py

@@ -6,12 +6,14 @@ required databases for the workflow management system.
 
 import json
 import logging
+from datetime import datetime, timezone
 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.metadata import WorkspaceMetadata
 from better_notion.utils.agents.schemas import (
     IncidentSchema,
     IdeaSchema,
@@ -48,11 +50,15 @@ class WorkspaceInitializer:
         """
         self._client = client
         self._database_ids: Dict[str, str] = {}
+        self._workspace_id: Optional[str] = None
+        self._parent_page_id: Optional[str] = None
+        self._workspace_name: Optional[str] = None
 
     async def initialize_workspace(
         self,
         parent_page_id: str,
         workspace_name: str = "Agents Workspace",
+        skip_detection: bool = False,
     ) -> Dict[str, str]:
         """Initialize a complete workspace with all databases.
 
@@ -62,15 +68,22 @@ class WorkspaceInitializer:
         Args:
             parent_page_id: ID of the parent page where databases will be created
             workspace_name: Name for the workspace (used for database titles)
+            skip_detection: If True, skip duplicate detection (for reset operation)
 
         Returns:
             Dict mapping database names to their IDs
 
         Raises:
             Exception: If database creation fails with detailed error message
+            Exception: If workspace already exists (and skip_detection is False)
         """
         logger.info(f"Initializing workspace '{workspace_name}' in page {parent_page_id}")
 
+        # Store workspace info
+        self._parent_page_id = parent_page_id
+        self._workspace_name = workspace_name
+        self._workspace_id = WorkspaceMetadata.generate_workspace_id()
+
         # Get parent page
         try:
             parent = await Page.get(parent_page_id, client=self._client)
@@ -80,6 +93,26 @@ class WorkspaceInitializer:
             logger.error(error_msg)
             raise Exception(error_msg) from e
 
+        # Check for existing workspace unless skipped
+        if not skip_detection:
+            existing = await WorkspaceMetadata.detect_workspace(parent, self._client)
+            if existing:
+                workspace_info = {
+                    "workspace_id": existing.get("workspace_id", "unknown"),
+                    "workspace_name": existing.get("workspace_name", workspace_name),
+                    "initialized_at": existing.get("initialized_at", "unknown"),
+                    "databases": existing.get("database_ids", {})
+                }
+                error_msg = (
+                    f"Workspace already initialized in this page\n"
+                    f"Workspace ID: {workspace_info['workspace_id']}\n"
+                    f"Initialized: {workspace_info['initialized_at']}\n"
+                    f"Databases: {len(workspace_info.get('databases', {}))} created\n"
+                    f"Use --reset to reinitialize or --skip to keep existing"
+                )
+                logger.error(error_msg)
+                raise Exception(error_msg) from None
+
         # Create databases in order (independent first, then dependent)
         self._database_ids = {}
         databases_order = [
@@ -108,7 +141,11 @@ class WorkspaceInitializer:
                 logger.error(error_msg)
                 raise Exception(error_msg) from e
 
+        # Save workspace metadata
+        self.save_database_ids()
+
         logger.info(f"Workspace initialization complete. Created {len(self._database_ids)} databases")
+        logger.info(f"Workspace ID: {self._workspace_id}")
         return self._database_ids
 
     async def _create_organizations_db(self, parent: Page) -> None:
@@ -312,7 +349,7 @@ class WorkspaceInitializer:
         pass
 
     def save_database_ids(self, path: Optional[Path] = None) -> None:
-        """Save database IDs to a config file.
+        """Save workspace metadata (database IDs and workspace info) to config file.
 
         Args:
             path: Path to save config file (default: ~/.notion/workspace.json)
@@ -322,8 +359,18 @@ class WorkspaceInitializer:
 
         path.parent.mkdir(parents=True, exist_ok=True)
 
+        # Save full workspace metadata
+        config = {
+            "workspace_id": self._workspace_id,
+            "workspace_name": self._workspace_name,
+            "parent_page": self._parent_page_id,
+            "initialized_at": datetime.now(timezone.utc).isoformat(),
+            "version": "1.5.4",
+            "database_ids": self._database_ids
+        }
+
         with open(path, "w", encoding="utf-8") as f:
-            json.dump(self._database_ids, f, indent=2)
+            json.dump(config, f, indent=2)
 
     @classmethod
     def load_database_ids(cls, path: Optional[Path] = None) -> Dict[str, str]:

{better_notion-1.5.4.dist-info → better_notion-1.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: better-notion
-Version: 1.5.4
+Version: 1.6.0
 Summary: A high-level Python SDK for the Notion API with developer experience in mind.
 Project-URL: Homepage, https://github.com/nesalia-inc/better-notion
 Project-URL: Documentation, https://github.com/nesalia-inc/better-notion#readme