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

better_notion/_cli/response.py

@@ -21,6 +21,7 @@ def format_response(
     data: Any = None,
     error: dict[str, Any] | None = None,
     rate_limit: dict[str, Any] | None = None,
+    meta: dict[str, Any] | None = None,
 ) -> str:
     """
     Format CLI response as JSON.
@@ -33,6 +34,7 @@ def format_response(
         data: Response data (for successful operations)
         error: Error information (for failed operations)
         rate_limit: Rate limit information from API response
+        meta: Additional metadata for AI agents (context, next_steps, etc.)
 
     Returns:
         JSON-formatted response string
@@ -50,6 +52,28 @@ def format_response(
           }
         }
 
+        Response with AI metadata:
+        >>> format_response(
+        ...     success=True,
+        ...     data={"workspace_id": "abc123"},
+        ...     meta={
+        ...         "command": "agents init",
+        ...         "context": {"state": "initialized"},
+        ...         "next_steps": [{"command": "agents info"}]
+        ...     }
+        ... )
+        {
+          "success": true,
+          "data": {"workspace_id": "abc123"},
+          "meta": {
+            "version": "0.4.0",
+            "timestamp": "2025-01-26T10:00:00Z",
+            "command": "agents init",
+            "context": {"state": "initialized"},
+            "next_steps": [{"command": "agents info"}]
+          }
+        }
+
         Error response:
         >>> format_response(
         ...     success=False,
@@ -58,11 +82,7 @@ def format_response(
         {
           "success": false,
           "error": {"code": "NOT_FOUND", "message": "Page not found", "retry": false},
-          "meta": {
-            "version": "0.4.0",
-            "timestamp": "2025-01-26T10:00:00Z",
-            "rate_limit": {"remaining": null, "reset_at": null}
-          }
+          "meta": {...}
         }
     """
     response: dict[str, Any] = {
@@ -81,6 +101,10 @@ def format_response(
         if error is not None:
             response["error"] = error
 
+    # Add custom metadata for AI agents
+    if meta:
+        response["meta"].update(meta)
+
     return json.dumps(response, indent=2)
 
 
@@ -90,6 +114,7 @@ def format_error(
     *,
     retry: bool = False,
     details: dict[str, Any] | None = None,
+    meta: dict[str, Any] | None = None,
 ) -> str:
     """
     Format an error response.
@@ -101,6 +126,7 @@ def format_error(
         message: Human-readable error message
         retry: Whether the operation should be retried
         details: Additional error details
+        meta: Additional metadata for AI agents (recovery strategies, etc.)
 
     Returns:
         JSON-formatted error response string
@@ -116,6 +142,20 @@ def format_error(
           },
           "meta": {...}
         }
+
+        With error recovery metadata:
+        >>> format_error(
+        ...     "WORKSPACE_EXISTS",
+        ...     "Workspace already initialized",
+        ...     meta={
+        ...         "error_recovery": {
+        ...             "solutions": [
+        ...                 {"flag": "--skip", "action": "use_existing"},
+        ...                 {"flag": "--reset", "action": "recreate"}
+        ...             ]
+        ...         }
+        ...     }
+        ... )
     """
     error_info: dict[str, Any] = {
         "code": code,
@@ -126,10 +166,15 @@ def format_error(
     if details:
         error_info["details"] = details
 
-    return format_response(success=False, error=error_info)
+    return format_response(success=False, error=error_info, meta=meta)
 
 
-def format_success(data: Any, *, rate_limit: dict[str, Any] | None = None) -> str:
+def format_success(
+    data: Any,
+    *,
+    rate_limit: dict[str, Any] | None = None,
+    meta: dict[str, Any] | None = None,
+) -> str:
     """
     Format a success response.
 
@@ -138,6 +183,7 @@ def format_success(data: Any, *, rate_limit: dict[str, Any] | None = None) -> st
     Args:
         data: Response data
         rate_limit: Rate limit information from API response
+        meta: Additional metadata for AI agents (context, next_steps, etc.)
 
     Returns:
         JSON-formatted success response string
@@ -149,5 +195,15 @@ def format_success(data: Any, *, rate_limit: dict[str, Any] | None = None) -> st
           "data": {"id": "page_123", "title": "My Page"},
           "meta": {...}
         }
+
+        With contextual metadata:
+        >>> format_success(
+        ...     {"workspace_id": "abc123"},
+        ...     meta={
+        ...         "command": "agents init",
+        ...         "context": {"state": "initialized"},
+        ...         "next_steps": [{"command": "agents info"}]
+        ...     }
+        ... )
     """
-    return format_response(success=True, data=data, rate_limit=rate_limit)
+    return format_response(success=True, data=data, rate_limit=rate_limit, meta=meta)

better_notion/plugins/official/agents.py

@@ -86,6 +86,18 @@ class AgentsPlugin(CombinedPluginInterface):
                 "-n",
                 help="Name for the workspace",
             ),
+            reset: bool = typer.Option(
+                False,
+                "--reset",
+                "-r",
+                help="Reset workspace (delete existing databases and recreate)",
+            ),
+            skip: bool = typer.Option(
+                False,
+                "--skip",
+                "-s",
+                help="Skip if workspace already exists (return existing databases)",
+            ),
             debug: bool = typer.Option(
                 False,
                 "--debug",
@@ -106,8 +118,13 @@ class AgentsPlugin(CombinedPluginInterface):
             - Incidents
             - Tags
 
+            If a workspace already exists in the page, use --reset to recreate
+            or --skip to keep the existing one.
+
             Example:
                 $ notion agents init --parent-page page123 --name "My Workspace"
+                $ notion agents init --parent-page page123 --reset  # Recreate
+                $ notion agents init --parent-page page123 --skip    # Keep existing
             """
             import asyncio
             import logging
@@ -128,19 +145,107 @@ class AgentsPlugin(CombinedPluginInterface):
                     client = get_client()
                     initializer = WorkspaceInitializer(client)
 
+                    # Handle --skip flag
+                    if skip:
+                        from better_notion._sdk.models.page import Page
+                        from better_notion.utils.agents.metadata import WorkspaceMetadata
+
+                        try:
+                            page = await Page.get(parent_page_id, client=client)
+                            existing = await WorkspaceMetadata.detect_workspace(page, client)
+
+                            if existing:
+                                database_ids = existing.get("database_ids", {})
+                                return format_success(
+                                    {
+                                        "message": "Workspace already exists, skipping initialization",
+                                        "workspace_id": existing.get("workspace_id"),
+                                        "databases_found": len(database_ids),
+                                        "database_ids": database_ids,
+                                    },
+                                    meta={
+                                        "command": "agents init",
+                                        "context": {
+                                            "state": "already_initialized",
+                                            "description": "Agents workspace already exists in this page",
+                                        },
+                                        "next_steps": [
+                                            {
+                                                "action": "query_tasks",
+                                                "command": f"notion databases query --database {database_ids.get('tasks', 'TASKS_DB_ID')}",
+                                                "purpose": "List all tasks in workspace",
+                                            },
+                                            {
+                                                "action": "create_task",
+                                                "description": "To create a new task, use pages create with Version relation",
+                                            },
+                                        ],
+                                        "capabilities": [
+                                            "create_tasks",
+                                            "manage_versions",
+                                            "track_projects",
+                                        ],
+                                    }
+                                )
+                        except Exception:
+                            # If detection fails, proceed with normal init
+                            pass
+
+                    # Initialize workspace (with skip_detection=True if --reset)
                     database_ids = await initializer.initialize_workspace(
                         parent_page_id=parent_page_id,
                         workspace_name=workspace_name,
+                        skip_detection=reset,  # Skip detection if resetting
                     )
 
-                    # Save database IDs
-                    initializer.save_database_ids()
-
                     return format_success(
                         {
                             "message": "Workspace initialized successfully",
+                            "workspace_id": initializer._workspace_id,
                             "databases_created": len(database_ids),
                             "database_ids": database_ids,
+                        },
+                        meta={
+                            "command": "agents init",
+                            "context": {
+                                "state": "initialized",
+                                "description": "Agents workspace ready for task management",
+                                "workspace_name": workspace_name,
+                            },
+                            "next_steps": [
+                                {
+                                    "command": "agents info --parent-page " + parent_page_id,
+                                    "purpose": "View workspace status and database IDs",
+                                    "when": "To verify workspace setup",
+                                },
+                                {
+                                    "command": f"notion databases query --database {database_ids.get('tasks', 'TASKS_DB_ID')}",
+                                    "purpose": "List all tasks in workspace",
+                                    "when": "To see existing tasks",
+                                },
+                            ],
+                            "capabilities": [
+                                "create_tasks",
+                                "manage_versions",
+                                "track_projects",
+                                "manage_ideas",
+                                "track_incidents",
+                            ],
+                            "common_workflows": [
+                                {
+                                    "name": "create_organization",
+                                    "description": "Create a new organization in the workspace",
+                                    "command": f"notion pages create --parent {database_ids.get('organizations', 'ORGANIZATIONS_DB_ID')} --title 'Organization Name'",
+                                },
+                                {
+                                    "name": "create_task",
+                                    "description": "Create a task in the workspace",
+                                    "steps": [
+                                        f"agents info --parent-page {parent_page_id}",
+                                        f"notion pages create --parent {database_ids.get('tasks', 'TASKS_DB_ID')} --title 'Task Name' --properties '{{\"Status\": \"Todo\", \"Version\": \"VERSION_ID\"}}'",
+                                    ],
+                                },
+                            ],
                         }
                     )
 
@@ -151,6 +256,172 @@ class AgentsPlugin(CombinedPluginInterface):
             result = asyncio.run(_init())
             typer.echo(result)
 
+        @agents_app.command("info")
+        def workspace_info(
+            parent_page_id: str = typer.Option(
+                ...,
+                "--parent-page",
+                "-p",
+                help="ID of the parent page to check",
+            ),
+        ) -> None:
+            """
+            Show workspace information for a page.
+
+            Displays whether a workspace is initialized in the given page,
+            along with workspace metadata and database information.
+
+            Example:
+                $ notion agents info --parent-page page123
+            """
+            import asyncio
+
+            async def _info() -> str:
+                try:
+                    client = get_client()
+                    from better_notion._sdk.models.page import Page
+                    from better_notion.utils.agents.metadata import WorkspaceMetadata
+
+                    page = await Page.get(parent_page_id, client=client)
+                    existing = await WorkspaceMetadata.detect_workspace(page, client)
+
+                    if existing:
+                        database_ids = existing.get("database_ids", {})
+
+                        return format_success(
+                            {
+                                "message": "Workspace found in this page",
+                                "parent_page": parent_page_id,
+                                "parent_title": page.title,
+                                "workspace_id": existing.get("workspace_id"),
+                                "workspace_name": existing.get("workspace_name"),
+                                "initialized_at": existing.get("initialized_at"),
+                                "databases_count": len(database_ids),
+                                "database_ids": database_ids,
+                                "detection_method": existing.get("detection_method", "config_file"),
+                            },
+                            meta={
+                                "command": "agents info",
+                                "context": {
+                                    "state": "workspace_found",
+                                    "description": "Workspace is ready for use",
+                                },
+                                "available_databases": list(database_ids.keys()),
+                                "next_steps": [
+                                    {
+                                        "action": "query_tasks",
+                                        "command": f"notion databases query --database {database_ids.get('tasks', 'TASKS_DB_ID')}",
+                                        "purpose": "List all tasks in workspace",
+                                    },
+                                    {
+                                        "action": "create_task",
+                                        "command": f"notion pages create --parent {database_ids.get('tasks', 'TASKS_DB_ID')} --title 'Task Name' --properties '{{\"Status\": \"Todo\"}}'",
+                                        "purpose": "Create a new task",
+                                        "note": "Make sure to set Version relation",
+                                    },
+                                    {
+                                        "action": "list_projects",
+                                        "command": f"notion databases query --database {database_ids.get('projects', 'PROJECTS_DB_ID')}",
+                                        "purpose": "List all projects",
+                                    },
+                                ],
+                            }
+                        )
+                    else:
+                        # Search for any databases in the page
+                        results = await client.search(
+                            query="",
+                            filter={"value": "database", "property": "object"}
+                        )
+
+                        # Count databases in this page
+                        databases_in_page = []
+                        for result in results:
+                            if hasattr(result, 'title'):
+                                databases_in_page.append(result.title)
+
+                        return format_success(
+                            {
+                                "message": "No agents workspace found in this page",
+                                "parent_page": parent_page_id,
+                                "parent_title": page.title,
+                                "workspace_initialized": False,
+                                "other_databases": len(databases_in_page),
+                            },
+                            meta={
+                                "command": "agents info",
+                                "context": {
+                                    "state": "no_workspace",
+                                    "description": "No agents workspace detected in this page",
+                                },
+                                "next_steps": [
+                                    {
+                                        "action": "initialize_workspace",
+                                        "command": f"notion agents init --parent-page {parent_page_id}",
+                                        "purpose": "Initialize a new agents workspace",
+                                        "note": "This will create 8 databases for workflow management",
+                                    },
+                                ],
+                                "error_recovery": {
+                                    "message": "Workspace must be initialized before managing tasks",
+                                    "solution": "Run 'agents init' to create the workspace",
+                                },
+                            }
+                        )
+
+                except Exception as e:
+                    result = format_error("INFO_ERROR", str(e), retry=False)
+                    return result
+
+            result = asyncio.run(_info())
+            typer.echo(result)
+
+        @agents_app.command("schema")
+        def agents_schema(
+            format: str = typer.Option(
+                "json",
+                "--format",
+                "-f",
+                help="Output format (json, yaml, pretty)",
+            ),
+        ) -> None:
+            """
+            Get agents plugin schema for AI agents.
+
+            Returns comprehensive documentation about the agents system including:
+            - Concepts (workspace, task, project, version)
+            - Workflows (initialize, create_task, query_tasks)
+            - Commands documentation (init, info)
+            - Best practices and usage examples
+
+            Example:
+                $ notion agents schema
+                $ notion agents schema --format json
+                $ notion agents schema --format yaml
+                $ notion agents schema --format pretty
+            """
+            from better_notion.plugins.official.agents_schema import AGENTS_SCHEMA
+            from better_notion._cli.docs.formatters import (
+                format_schema_json,
+                format_schema_yaml,
+                format_schema_pretty,
+            )
+
+            if format == "json":
+                typer.echo(format_schema_json(AGENTS_SCHEMA))
+            elif format == "yaml":
+                typer.echo(format_schema_yaml(AGENTS_SCHEMA))
+            elif format == "pretty":
+                typer.echo(format_schema_pretty(AGENTS_SCHEMA))
+            else:
+                result = format_error(
+                    "INVALID_FORMAT",
+                    f"Unknown format: {format}. Supported formats: json, yaml, pretty",
+                    retry=False,
+                )
+                typer.echo(result)
+                raise typer.Exit(code=1)
+
         @agents_app.command("init-project")
         def init_project(
             project_id: str = typer.Option(