better-notion 1.5.5__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

@@ -162,6 +162,29 @@ class AgentsPlugin(CombinedPluginInterface):
                                         "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:
@@ -181,6 +204,48 @@ class AgentsPlugin(CombinedPluginInterface):
                             "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\"}}'",
+                                    ],
+                                },
+                            ],
                         }
                     )
 
@@ -234,6 +299,32 @@ class AgentsPlugin(CombinedPluginInterface):
                                 "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:
@@ -256,6 +347,25 @@ class AgentsPlugin(CombinedPluginInterface):
                                 "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",
+                                },
                             }
                         )
 
@@ -266,6 +376,52 @@ class AgentsPlugin(CombinedPluginInterface):
             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(