better-notion 1.5.5__py3-none-any.whl → 1.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,6 +21,7 @@ def format_response(
21
21
  data: Any = None,
22
22
  error: dict[str, Any] | None = None,
23
23
  rate_limit: dict[str, Any] | None = None,
24
+ meta: dict[str, Any] | None = None,
24
25
  ) -> str:
25
26
  """
26
27
  Format CLI response as JSON.
@@ -33,6 +34,7 @@ def format_response(
33
34
  data: Response data (for successful operations)
34
35
  error: Error information (for failed operations)
35
36
  rate_limit: Rate limit information from API response
37
+ meta: Additional metadata for AI agents (context, next_steps, etc.)
36
38
 
37
39
  Returns:
38
40
  JSON-formatted response string
@@ -50,6 +52,28 @@ def format_response(
50
52
  }
51
53
  }
52
54
 
55
+ Response with AI metadata:
56
+ >>> format_response(
57
+ ... success=True,
58
+ ... data={"workspace_id": "abc123"},
59
+ ... meta={
60
+ ... "command": "agents init",
61
+ ... "context": {"state": "initialized"},
62
+ ... "next_steps": [{"command": "agents info"}]
63
+ ... }
64
+ ... )
65
+ {
66
+ "success": true,
67
+ "data": {"workspace_id": "abc123"},
68
+ "meta": {
69
+ "version": "0.4.0",
70
+ "timestamp": "2025-01-26T10:00:00Z",
71
+ "command": "agents init",
72
+ "context": {"state": "initialized"},
73
+ "next_steps": [{"command": "agents info"}]
74
+ }
75
+ }
76
+
53
77
  Error response:
54
78
  >>> format_response(
55
79
  ... success=False,
@@ -58,11 +82,7 @@ def format_response(
58
82
  {
59
83
  "success": false,
60
84
  "error": {"code": "NOT_FOUND", "message": "Page not found", "retry": false},
61
- "meta": {
62
- "version": "0.4.0",
63
- "timestamp": "2025-01-26T10:00:00Z",
64
- "rate_limit": {"remaining": null, "reset_at": null}
65
- }
85
+ "meta": {...}
66
86
  }
67
87
  """
68
88
  response: dict[str, Any] = {
@@ -81,6 +101,10 @@ def format_response(
81
101
  if error is not None:
82
102
  response["error"] = error
83
103
 
104
+ # Add custom metadata for AI agents
105
+ if meta:
106
+ response["meta"].update(meta)
107
+
84
108
  return json.dumps(response, indent=2)
85
109
 
86
110
 
@@ -90,6 +114,7 @@ def format_error(
90
114
  *,
91
115
  retry: bool = False,
92
116
  details: dict[str, Any] | None = None,
117
+ meta: dict[str, Any] | None = None,
93
118
  ) -> str:
94
119
  """
95
120
  Format an error response.
@@ -101,6 +126,7 @@ def format_error(
101
126
  message: Human-readable error message
102
127
  retry: Whether the operation should be retried
103
128
  details: Additional error details
129
+ meta: Additional metadata for AI agents (recovery strategies, etc.)
104
130
 
105
131
  Returns:
106
132
  JSON-formatted error response string
@@ -116,6 +142,20 @@ def format_error(
116
142
  },
117
143
  "meta": {...}
118
144
  }
145
+
146
+ With error recovery metadata:
147
+ >>> format_error(
148
+ ... "WORKSPACE_EXISTS",
149
+ ... "Workspace already initialized",
150
+ ... meta={
151
+ ... "error_recovery": {
152
+ ... "solutions": [
153
+ ... {"flag": "--skip", "action": "use_existing"},
154
+ ... {"flag": "--reset", "action": "recreate"}
155
+ ... ]
156
+ ... }
157
+ ... }
158
+ ... )
119
159
  """
120
160
  error_info: dict[str, Any] = {
121
161
  "code": code,
@@ -126,10 +166,15 @@ def format_error(
126
166
  if details:
127
167
  error_info["details"] = details
128
168
 
129
- return format_response(success=False, error=error_info)
169
+ return format_response(success=False, error=error_info, meta=meta)
130
170
 
131
171
 
132
- def format_success(data: Any, *, rate_limit: dict[str, Any] | None = None) -> str:
172
+ def format_success(
173
+ data: Any,
174
+ *,
175
+ rate_limit: dict[str, Any] | None = None,
176
+ meta: dict[str, Any] | None = None,
177
+ ) -> str:
133
178
  """
134
179
  Format a success response.
135
180
 
@@ -138,6 +183,7 @@ def format_success(data: Any, *, rate_limit: dict[str, Any] | None = None) -> st
138
183
  Args:
139
184
  data: Response data
140
185
  rate_limit: Rate limit information from API response
186
+ meta: Additional metadata for AI agents (context, next_steps, etc.)
141
187
 
142
188
  Returns:
143
189
  JSON-formatted success response string
@@ -149,5 +195,15 @@ def format_success(data: Any, *, rate_limit: dict[str, Any] | None = None) -> st
149
195
  "data": {"id": "page_123", "title": "My Page"},
150
196
  "meta": {...}
151
197
  }
198
+
199
+ With contextual metadata:
200
+ >>> format_success(
201
+ ... {"workspace_id": "abc123"},
202
+ ... meta={
203
+ ... "command": "agents init",
204
+ ... "context": {"state": "initialized"},
205
+ ... "next_steps": [{"command": "agents info"}]
206
+ ... }
207
+ ... )
152
208
  """
153
- return format_response(success=True, data=data, rate_limit=rate_limit)
209
+ return format_response(success=True, data=data, rate_limit=rate_limit, meta=meta)
@@ -162,6 +162,100 @@ class AgentsPlugin(CombinedPluginInterface):
162
162
  "workspace_id": existing.get("workspace_id"),
163
163
  "databases_found": len(database_ids),
164
164
  "database_ids": database_ids,
165
+ },
166
+ meta={
167
+ "command": "agents init",
168
+ "context": {
169
+ "state": "already_initialized",
170
+ "description": "Agents workspace already exists in this page",
171
+ },
172
+ "hierarchy": {
173
+ "description": "Agents workflow hierarchy",
174
+ "levels": [
175
+ {
176
+ "level": 1,
177
+ "entity": "Organization",
178
+ "database": "organizations",
179
+ "required_before": ["Projects"]
180
+ },
181
+ {
182
+ "level": 2,
183
+ "entity": "Project",
184
+ "database": "projects",
185
+ "required_before": ["Versions", "Tasks"],
186
+ "requires": ["Organization"]
187
+ },
188
+ {
189
+ "level": 3,
190
+ "entity": "Version",
191
+ "database": "versions",
192
+ "required_before": ["Tasks"],
193
+ "requires": ["Project"]
194
+ },
195
+ {
196
+ "level": 4,
197
+ "entity": "Task",
198
+ "database": "tasks",
199
+ "requires": ["Version"]
200
+ }
201
+ ]
202
+ },
203
+ "next_steps": [
204
+ {
205
+ "action": "check_organizations",
206
+ "command": "notion agents orgs list",
207
+ "purpose": "Check if organizations exist",
208
+ "why": "Organizations are the starting point - create them first"
209
+ },
210
+ {
211
+ "action": "create_organization",
212
+ "command": "notion agents orgs create --name 'Organization Name'",
213
+ "purpose": "Create a new organization",
214
+ "when": "If no organizations exist",
215
+ "examples": [
216
+ "notion agents orgs create --name 'WareflowX'",
217
+ "notion agents orgs create --name 'WareflowX' --slug 'wareflowx'"
218
+ ]
219
+ },
220
+ {
221
+ "action": "create_project",
222
+ "command": "notion agents projects create --org 'Org Name' --name 'Project Name'",
223
+ "purpose": "Create a project in an organization",
224
+ "requires": ["organization_exists"],
225
+ "examples": [
226
+ "notion agents projects create --org 'WareflowX' --name 'Website Redesign'"
227
+ ]
228
+ },
229
+ {
230
+ "action": "create_version",
231
+ "command": "notion agents versions create --project 'Project' --name 'v1.0.0'",
232
+ "purpose": "Create a version in a project",
233
+ "requires": ["project_exists"],
234
+ },
235
+ {
236
+ "action": "create_task",
237
+ "command": "notion agents tasks create --version 'v1.0.0' --name 'Task Name'",
238
+ "purpose": "Create a task in a version",
239
+ "requires": ["version_exists"],
240
+ },
241
+ ],
242
+ "capabilities": [
243
+ "create_organizations",
244
+ "create_projects",
245
+ "create_versions",
246
+ "create_tasks",
247
+ "manage_ideas",
248
+ "track_work_issues",
249
+ "manage_incidents",
250
+ ],
251
+ "quick_reference": {
252
+ "lifecycle": "Organization → Project → Version → Task",
253
+ "create_org": "notion agents orgs create --name NAME",
254
+ "list_orgs": "notion agents orgs list",
255
+ "create_project": "notion agents projects create --org ORG --name NAME",
256
+ "create_version": "notion agents versions create --project PROJECT --name VERSION",
257
+ "create_task": "notion agents tasks create --version VERSION --name TASK",
258
+ }
165
259
  }
166
260
  )
167
261
  except Exception:
@@ -181,6 +275,115 @@ class AgentsPlugin(CombinedPluginInterface):
181
275
  "workspace_id": initializer._workspace_id,
182
276
  "databases_created": len(database_ids),
183
277
  "database_ids": database_ids,
278
+ },
279
+ meta={
280
+ "command": "agents init",
281
+ "context": {
282
+ "state": "initialized",
283
+ "description": "Agents workspace ready for task management",
284
+ "workspace_name": workspace_name,
285
+ },
286
+ "hierarchy": {
287
+ "description": "Agents workflow hierarchy - follow this order",
288
+ "lifecycle": "Organization → Project → Version → Task",
289
+ "levels": [
290
+ {
291
+ "level": 1,
292
+ "entity": "Organization",
293
+ "database": "organizations",
294
+ "command": "notion agents orgs create --name 'Org Name'",
295
+ "next": "Projects"
296
+ },
297
+ {
298
+ "level": 2,
299
+ "entity": "Project",
300
+ "database": "projects",
301
+ "command": "notion agents projects create --org 'Org' --name 'Project'",
302
+ "requires": ["Organization"],
303
+ "next": "Versions"
304
+ },
305
+ {
306
+ "level": 3,
307
+ "entity": "Version",
308
+ "database": "versions",
309
+ "command": "notion agents versions create --project 'Project' --name 'v1.0.0'",
310
+ "requires": ["Project"],
311
+ "next": "Tasks"
312
+ },
313
+ {
314
+ "level": 4,
315
+ "entity": "Task",
316
+ "database": "tasks",
317
+ "command": "notion agents tasks create --version 'v1.0.0' --name 'Task'",
318
+ "requires": ["Version"]
319
+ }
320
+ ]
321
+ },
322
+ "next_steps": [
323
+ {
324
+ "action": "first_create_organization",
325
+ "priority": 1,
326
+ "command": "notion agents orgs create --name 'Your Organization Name'",
327
+ "purpose": "Create your first organization (required before projects)",
328
+ "why": "Organizations are the top-level entity - all projects belong to an organization",
329
+ "examples": [
330
+ "notion agents orgs create --name 'WareflowX'",
331
+ "notion agents orgs create --name 'WareflowX' --slug 'wareflowx'"
332
+ ]
333
+ },
334
+ {
335
+ "action": "then_create_project",
336
+ "priority": 2,
337
+ "command": "notion agents projects create --org 'Org Name' --name 'Project Name'",
338
+ "purpose": "Create a project in the organization",
339
+ "requires": ["organization_exists"],
340
+ },
341
+ {
342
+ "action": "then_create_version",
343
+ "priority": 3,
344
+ "command": "notion agents versions create --project 'Project' --name 'v1.0.0'",
345
+ "purpose": "Create a version in the project",
346
+ "requires": ["project_exists"],
347
+ },
348
+ {
349
+ "action": "then_create_tasks",
350
+ "priority": 4,
351
+ "command": "notion agents tasks create --version 'v1.0.0' --name 'Task Name'",
352
+ "purpose": "Create tasks in the version",
353
+ "requires": ["version_exists"],
354
+ },
355
+ {
356
+ "action": "verify_setup",
357
+ "command": "agents info --parent-page " + parent_page_id,
358
+ "purpose": "View workspace status and database IDs",
359
+ "when": "Anytime to verify setup",
360
+ },
361
+ ],
362
+ "capabilities": [
363
+ "create_organizations",
364
+ "create_projects",
365
+ "create_versions",
366
+ "create_tasks",
367
+ "manage_ideas",
368
+ "track_work_issues",
369
+ "manage_incidents",
370
+ ],
371
+ "quick_start": {
372
+ "description": "Quick start guide - create your first workflow",
373
+ "steps": [
374
+ "1. Create organization: notion agents orgs create --name 'WareflowX'",
375
+ "2. Create project: notion agents projects create --org 'WareflowX' --name 'Website Redesign'",
376
+ "3. Create version: notion agents versions create --project 'Website Redesign' --name 'v1.0.0'",
377
+ "4. Create task: notion agents tasks create --version 'v1.0.0' --name 'Fix login bug'"
378
+ ]
379
+ },
380
+ "quick_reference": {
381
+ "list_orgs": "notion agents orgs list",
382
+ "list_projects": "notion agents projects list",
383
+ "list_versions": "notion agents versions list --project 'Project'",
384
+ "list_tasks": "notion agents tasks list --version 'v1.0.0'",
385
+ "find_next_task": "notion agents tasks next --version 'v1.0.0'"
386
+ }
184
387
  }
185
388
  )
186
389
 
@@ -234,6 +437,32 @@ class AgentsPlugin(CombinedPluginInterface):
234
437
  "databases_count": len(database_ids),
235
438
  "database_ids": database_ids,
236
439
  "detection_method": existing.get("detection_method", "config_file"),
440
+ },
441
+ meta={
442
+ "command": "agents info",
443
+ "context": {
444
+ "state": "workspace_found",
445
+ "description": "Workspace is ready for use",
446
+ },
447
+ "available_databases": list(database_ids.keys()),
448
+ "next_steps": [
449
+ {
450
+ "action": "query_tasks",
451
+ "command": f"notion databases query --database {database_ids.get('tasks', 'TASKS_DB_ID')}",
452
+ "purpose": "List all tasks in workspace",
453
+ },
454
+ {
455
+ "action": "create_task",
456
+ "command": f"notion pages create --parent {database_ids.get('tasks', 'TASKS_DB_ID')} --title 'Task Name' --properties '{{\"Status\": \"Todo\"}}'",
457
+ "purpose": "Create a new task",
458
+ "note": "Make sure to set Version relation",
459
+ },
460
+ {
461
+ "action": "list_projects",
462
+ "command": f"notion databases query --database {database_ids.get('projects', 'PROJECTS_DB_ID')}",
463
+ "purpose": "List all projects",
464
+ },
465
+ ],
237
466
  }
238
467
  )
239
468
  else:
@@ -256,6 +485,25 @@ class AgentsPlugin(CombinedPluginInterface):
256
485
  "parent_title": page.title,
257
486
  "workspace_initialized": False,
258
487
  "other_databases": len(databases_in_page),
488
+ },
489
+ meta={
490
+ "command": "agents info",
491
+ "context": {
492
+ "state": "no_workspace",
493
+ "description": "No agents workspace detected in this page",
494
+ },
495
+ "next_steps": [
496
+ {
497
+ "action": "initialize_workspace",
498
+ "command": f"notion agents init --parent-page {parent_page_id}",
499
+ "purpose": "Initialize a new agents workspace",
500
+ "note": "This will create 8 databases for workflow management",
501
+ },
502
+ ],
503
+ "error_recovery": {
504
+ "message": "Workspace must be initialized before managing tasks",
505
+ "solution": "Run 'agents init' to create the workspace",
506
+ },
259
507
  }
260
508
  )
261
509
 
@@ -266,6 +514,52 @@ class AgentsPlugin(CombinedPluginInterface):
266
514
  result = asyncio.run(_info())
267
515
  typer.echo(result)
268
516
 
517
+ @agents_app.command("schema")
518
+ def agents_schema(
519
+ format: str = typer.Option(
520
+ "json",
521
+ "--format",
522
+ "-f",
523
+ help="Output format (json, yaml, pretty)",
524
+ ),
525
+ ) -> None:
526
+ """
527
+ Get agents plugin schema for AI agents.
528
+
529
+ Returns comprehensive documentation about the agents system including:
530
+ - Concepts (workspace, task, project, version)
531
+ - Workflows (initialize, create_task, query_tasks)
532
+ - Commands documentation (init, info)
533
+ - Best practices and usage examples
534
+
535
+ Example:
536
+ $ notion agents schema
537
+ $ notion agents schema --format json
538
+ $ notion agents schema --format yaml
539
+ $ notion agents schema --format pretty
540
+ """
541
+ from better_notion.plugins.official.agents_schema import AGENTS_SCHEMA
542
+ from better_notion._cli.docs.formatters import (
543
+ format_schema_json,
544
+ format_schema_yaml,
545
+ format_schema_pretty,
546
+ )
547
+
548
+ if format == "json":
549
+ typer.echo(format_schema_json(AGENTS_SCHEMA))
550
+ elif format == "yaml":
551
+ typer.echo(format_schema_yaml(AGENTS_SCHEMA))
552
+ elif format == "pretty":
553
+ typer.echo(format_schema_pretty(AGENTS_SCHEMA))
554
+ else:
555
+ result = format_error(
556
+ "INVALID_FORMAT",
557
+ f"Unknown format: {format}. Supported formats: json, yaml, pretty",
558
+ retry=False,
559
+ )
560
+ typer.echo(result)
561
+ raise typer.Exit(code=1)
562
+
269
563
  @agents_app.command("init-project")
270
564
  def init_project(
271
565
  project_id: str = typer.Option(