better-notion 1.5.5__py3-none-any.whl → 1.6.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.
@@ -0,0 +1,369 @@
1
+ """Agents plugin schema for AI agent documentation.
2
+
3
+ This module provides comprehensive documentation about the agents workflow
4
+ system that AI agents can consume to understand how to work with the system.
5
+
6
+ This is the SINGLE SOURCE OF TRUTH for agents documentation. All other
7
+ documentation (CLI help, website, etc.) should be derived from this schema.
8
+ """
9
+
10
+ from better_notion._cli.docs.base import (
11
+ Command,
12
+ Concept,
13
+ Schema,
14
+ Workflow,
15
+ WorkflowStep,
16
+ )
17
+
18
+ # =============================================================================
19
+ # CONCEPTS
20
+ # =============================================================================
21
+
22
+ WORKSPACE_CONCEPT = Concept(
23
+ name="workspace",
24
+ description=(
25
+ "A workspace is a collection of 8 interconnected databases that implement "
26
+ "a complete software development workflow management system. It provides "
27
+ "the structure for tracking organizations, projects, versions, tasks, ideas, "
28
+ "work issues, and incidents in a unified manner."
29
+ ),
30
+ properties={
31
+ "databases": [
32
+ "Organizations",
33
+ "Tags",
34
+ "Projects",
35
+ "Versions",
36
+ "Tasks",
37
+ "Ideas",
38
+ "Work Issues",
39
+ "Incidents",
40
+ ],
41
+ "initialization": "Created via 'agents init' command",
42
+ "detection": "Automatically detected by scanning for expected databases",
43
+ "uniqueness": "One workspace per Notion page",
44
+ },
45
+ relationships={
46
+ "Organizations → Projects": "Many-to-one (many projects belong to one organization)",
47
+ "Projects → Versions": "Many-to-one (many versions belong to one project)",
48
+ "Versions → Tasks": "Many-to-one (many tasks belong to one version)",
49
+ "Tasks → Tasks": "Self-referential (tasks can depend on other tasks)",
50
+ },
51
+ )
52
+
53
+ TASK_CONCEPT = Concept(
54
+ name="task",
55
+ description=(
56
+ "A task represents a unit of work that needs to be completed as part of "
57
+ "a project version. Tasks have states (Todo, In Progress, Done, Cancelled) "
58
+ "and can depend on other tasks."
59
+ ),
60
+ properties={
61
+ "required_properties": {
62
+ "Title": "Task name (title property)",
63
+ "Status": "Current state: Todo, In Progress, Done, Cancelled",
64
+ "Version": "Relation to Version database (required)",
65
+ },
66
+ "optional_properties": {
67
+ "Target Version": "Version where task should be implemented",
68
+ "Dependencies": "Other tasks this task depends on",
69
+ "Dependent Tasks": "Tasks that depend on this task",
70
+ },
71
+ "workflow": "Todo → In Progress → Done",
72
+ },
73
+ relationships={
74
+ "Version": "Required - each task must belong to one version",
75
+ "Dependencies": "Optional - tasks that must complete before this task",
76
+ "Dependent Tasks": "Inverse of dependencies - tasks blocked by this task",
77
+ },
78
+ )
79
+
80
+ PROJECT_CONCEPT = Concept(
81
+ name="project",
82
+ description=(
83
+ "A project represents a software project or product being developed. "
84
+ "Projects belong to organizations and contain multiple versions."
85
+ ),
86
+ properties={
87
+ "required_properties": {
88
+ "Title": "Project name",
89
+ "Organization": "Relation to organization (required)",
90
+ },
91
+ "contains": ["Versions", "Tasks", "Ideas", "Work Issues", "Incidents"],
92
+ },
93
+ relationships={
94
+ "Organization": "Required - each project belongs to one organization",
95
+ "Versions": "One-to-many - project contains multiple versions",
96
+ },
97
+ )
98
+
99
+ VERSION_CONCEPT = Concept(
100
+ name="version",
101
+ description=(
102
+ "A version represents a release or milestone of a project. Examples: "
103
+ "v1.0.0, v1.1.0, v2.0.0. Tasks are created within versions."
104
+ ),
105
+ properties={
106
+ "required_properties": {
107
+ "Title": "Version name (e.g., v1.0.0)",
108
+ "Project": "Relation to project (required)",
109
+ },
110
+ "contains": ["Tasks"],
111
+ "examples": ["v1.0.0", "v1.1.0", "v2.0.0-beta", "sprint-1"],
112
+ },
113
+ relationships={
114
+ "Project": "Required - each version belongs to one project",
115
+ "Tasks": "One-to-many - version contains multiple tasks",
116
+ },
117
+ )
118
+
119
+ # =============================================================================
120
+ # WORKFLOWS
121
+ # =============================================================================
122
+
123
+ INITIALIZE_WORKSPACE = Workflow(
124
+ name="initialize_workspace",
125
+ description="Create a complete agents workflow management system with 8 databases",
126
+ steps=[
127
+ WorkflowStep(
128
+ description="Detect existing workspace in page",
129
+ purpose="Prevent duplicate workspace creation",
130
+ ),
131
+ WorkflowStep(
132
+ description="Create Organizations database",
133
+ command="notion databases create --parent PAGE_ID --title Organizations",
134
+ ),
135
+ WorkflowStep(
136
+ description="Create Tags database",
137
+ command="notion databases create --parent PAGE_ID --title Tags",
138
+ ),
139
+ WorkflowStep(
140
+ description="Create Projects database",
141
+ command="notion databases create --parent PAGE_ID --title Projects",
142
+ ),
143
+ WorkflowStep(
144
+ description="Create Versions database",
145
+ command="notion databases create --parent PAGE_ID --title Versions",
146
+ ),
147
+ WorkflowStep(
148
+ description="Create Tasks database",
149
+ command="notion databases create --parent PAGE_ID --title Tasks",
150
+ ),
151
+ WorkflowStep(
152
+ description="Create Ideas database",
153
+ command="notion databases create --parent PAGE_ID --title Ideas",
154
+ ),
155
+ WorkflowStep(
156
+ description="Create Work Issues database",
157
+ command="notion databases create --parent PAGE_ID --title 'Work Issues'",
158
+ ),
159
+ WorkflowStep(
160
+ description="Create Incidents database",
161
+ command="notion databases create --parent PAGE_ID --title Incidents",
162
+ ),
163
+ WorkflowStep(
164
+ description="Establish database relationships",
165
+ purpose="Create relations between databases (Projects→Organizations, etc.)",
166
+ ),
167
+ WorkflowStep(
168
+ description="Save workspace metadata",
169
+ command="agents info --parent-page PAGE_ID",
170
+ purpose="Verify setup and get database IDs",
171
+ ),
172
+ ],
173
+ commands=[
174
+ "agents init --parent-page PAGE_ID",
175
+ "agents info --parent-page PAGE_ID",
176
+ ],
177
+ prerequisites=["valid_page_id"],
178
+ error_recovery={
179
+ "workspace_exists": {
180
+ "message": "Detected 5+ expected databases in page",
181
+ "meaning": "Workspace already initialized in this page",
182
+ "solutions": [
183
+ {
184
+ "flag": "--skip",
185
+ "action": "use_existing_workspace",
186
+ "description": "Skip initialization and use existing workspace",
187
+ "when_to_use": "You want to keep existing data",
188
+ },
189
+ {
190
+ "flag": "--reset",
191
+ "action": "recreate_workspace",
192
+ "description": "Delete all databases and recreate (WARNING: data loss)",
193
+ "warning": "This will delete all existing databases and their content",
194
+ "when_to_use": "You want to start completely fresh",
195
+ },
196
+ ],
197
+ }
198
+ },
199
+ )
200
+
201
+ CREATE_TASK_WORKFLOW = Workflow(
202
+ name="create_task",
203
+ description="Create a new task in the agents workflow system",
204
+ steps=[
205
+ WorkflowStep(
206
+ description="Verify workspace is initialized",
207
+ command="agents info --parent-page PAGE_ID",
208
+ purpose="Get database IDs and verify workspace exists",
209
+ ),
210
+ WorkflowStep(
211
+ description="Identify target Version",
212
+ purpose="Tasks must belong to a Version (required relation)",
213
+ ),
214
+ WorkflowStep(
215
+ description="Create task page with proper properties",
216
+ command="notion pages create --parent TASKS_DB_ID --title 'Task Name' --properties '{...}'",
217
+ purpose="Create task with Status and Version relation",
218
+ ),
219
+ ],
220
+ commands=[
221
+ "agents info --parent-page PAGE_ID",
222
+ "notion pages create --parent TASKS_DB_ID --title 'Task' --properties '{\"Status\": \"Todo\", \"Version\": \"VERSION_ID\"}'",
223
+ ],
224
+ prerequisites=["workspace_initialized"],
225
+ error_recovery={
226
+ "workspace_not_found": {
227
+ "message": "No workspace detected in page",
228
+ "solution": "Run 'agents init' first to create workspace",
229
+ },
230
+ "missing_version_relation": {
231
+ "message": "Task must have a Version relation",
232
+ "solution": "Always specify Version property when creating task",
233
+ },
234
+ },
235
+ )
236
+
237
+ QUERY_TASKS_WORKFLOW = Workflow(
238
+ name="query_tasks",
239
+ description="Query and filter tasks in the workspace",
240
+ steps=[
241
+ WorkflowStep(
242
+ description="Get workspace database IDs",
243
+ command="agents info --parent-page PAGE_ID",
244
+ purpose="Obtain tasks database ID",
245
+ ),
246
+ WorkflowStep(
247
+ description="Query tasks database",
248
+ command="notion databases query --database TASKS_DB_ID --filter '{...}'",
249
+ purpose="Retrieve tasks with optional filtering",
250
+ ),
251
+ ],
252
+ commands=[
253
+ "agents info --parent-page PAGE_ID",
254
+ "notion databases query --database TASKS_DB_ID",
255
+ ],
256
+ prerequisites=["workspace_initialized"],
257
+ )
258
+
259
+ # =============================================================================
260
+ # COMMANDS
261
+ # =============================================================================
262
+
263
+ INIT_COMMAND = Command(
264
+ name="init",
265
+ purpose="Initialize a new agents workspace or manage existing one",
266
+ description=(
267
+ "Creates a complete workflow management system with 8 databases "
268
+ "and their relationships. Can detect existing workspaces to prevent duplicates."
269
+ ),
270
+ flags={
271
+ "--parent-page": "Parent page ID where workspace will be created",
272
+ "--workspace-name": "Name for the workspace (default: 'Agents Workspace')",
273
+ "--reset": "Force recreation (deletes existing databases and recreates)",
274
+ "--skip": "Skip initialization if workspace already exists",
275
+ "--debug": "Enable debug output",
276
+ },
277
+ workflow="initialize_workspace",
278
+ when_to_use=[
279
+ "First time setting up agents system in a page",
280
+ "Starting fresh in a new page",
281
+ "Recovering from corrupted workspace (use --reset)",
282
+ "Safely checking for existing workspace (use --skip)",
283
+ ],
284
+ error_recovery={
285
+ "workspace_exists": {
286
+ "solutions": [
287
+ {"flag": "--skip", "use_case": "Keep existing workspace"},
288
+ {"flag": "--reset", "use_case": "Delete and recreate (data loss)"},
289
+ ]
290
+ }
291
+ },
292
+ )
293
+
294
+ INFO_COMMAND = Command(
295
+ name="info",
296
+ purpose="Display workspace status and metadata",
297
+ description="Shows whether a workspace exists, database IDs, and workspace info",
298
+ flags={
299
+ "--parent-page": "Parent page ID to check for workspace",
300
+ },
301
+ workflow=None,
302
+ when_to_use=[
303
+ "Verify workspace initialization",
304
+ "Get database IDs for queries",
305
+ "Check workspace version and metadata",
306
+ "Debug workspace issues",
307
+ ],
308
+ )
309
+
310
+ # =============================================================================
311
+ # COMPLETE SCHEMA
312
+ # =============================================================================
313
+
314
+ AGENTS_SCHEMA = Schema(
315
+ name="agents",
316
+ version="1.0.0",
317
+ description=(
318
+ "Workflow management system for software development. "
319
+ "Provides complete structure for tracking organizations, projects, "
320
+ "versions, tasks, ideas, work issues, and incidents."
321
+ ),
322
+ concepts=[
323
+ WORKSPACE_CONCEPT,
324
+ TASK_CONCEPT,
325
+ PROJECT_CONCEPT,
326
+ VERSION_CONCEPT,
327
+ ],
328
+ workflows=[
329
+ INITIALIZE_WORKSPACE,
330
+ CREATE_TASK_WORKFLOW,
331
+ QUERY_TASKS_WORKFLOW,
332
+ ],
333
+ commands={
334
+ "init": INIT_COMMAND,
335
+ "info": INFO_COMMAND,
336
+ },
337
+ best_practices=[
338
+ "Always run 'agents info' before database operations to verify workspace state",
339
+ "Use --skip flag to safely check for existing workspaces (prevents duplicates)",
340
+ "Use --reset flag only when you need to recreate workspace (causes data loss)",
341
+ "Tasks must have a Version relation - always specify Version property",
342
+ "Check task dependencies before marking tasks as complete",
343
+ "Projects belong to Organizations - create organization first",
344
+ "Versions belong to Projects - create project first",
345
+ "Query tasks by Status to find next available task",
346
+ ],
347
+ examples={
348
+ "initial_setup": """# First time setup
349
+ notion agents init --parent-page PAGE_ID
350
+
351
+ # Verify setup
352
+ notion agents info --parent-page PAGE_ID""",
353
+
354
+ "safe_initialization": """# Check if workspace exists, use if found
355
+ notion agents init --parent-page PAGE_ID --skip""",
356
+
357
+ "force_recreate": """# Delete existing workspace and recreate (WARNING: data loss)
358
+ notion agents init --parent-page PAGE_ID --reset""",
359
+
360
+ "query_workspace": """# Get workspace info and database IDs
361
+ notion agents info --parent-page PAGE_ID""",
362
+
363
+ "create_task": """# After workspace is initialized
364
+ notion pages create \\
365
+ --parent TASKS_DB_ID \\
366
+ --title "Fix login bug" \\
367
+ --properties '{"Status": "Todo", "Version": "VERSION_ID"}'""",
368
+ },
369
+ )
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: better-notion
3
- Version: 1.5.5
3
+ Version: 1.6.0
4
4
  Summary: A high-level Python SDK for the Notion API with developer experience in mind.
5
5
  Project-URL: Homepage, https://github.com/nesalia-inc/better-notion
6
6
  Project-URL: Documentation, https://github.com/nesalia-inc/better-notion#readme
@@ -33,9 +33,9 @@ better_notion/_cli/async_typer.py,sha256=0GlE9G84FAFxBEtaunL3PrCxGx4m70SuwYrTeI8
33
33
  better_notion/_cli/config.py,sha256=2D7z50yY4k3EoJNcd6EIUyy5uyIulbr6PzTub2mDmqg,3176
34
34
  better_notion/_cli/display.py,sha256=ROQsc4RwNuoXaHx0dfFlQ0A8WTCScmD855XwB9vHjeY,8480
35
35
  better_notion/_cli/errors.py,sha256=p1H_Vik-DnNX1dY1lg9xsKKW9p6gHEwKw7zcgG6vM-A,5328
36
- better_notion/_cli/main.py,sha256=AAl7ibN5p6RncmfN0HZQK3ZK5etLA3WKgO2xQ7uMsXc,4297
36
+ better_notion/_cli/main.py,sha256=Av8iadXtQGl7wJCZRoeAyMuu3HQwXpyiXIV92ea_MYw,11192
37
37
  better_notion/_cli/markdown.py,sha256=MgCxrxKf4iGkiLjgeWk7dMAk9NljYBaAJ2mvUE59KKM,10446
38
- better_notion/_cli/response.py,sha256=fVzpD2wuoZI2vk4ozVWsNE-QArEXOHGWRdayz68F230,4177
38
+ better_notion/_cli/response.py,sha256=7y49EbQ15HvKd4j2Focf0XTi3VGqHc_oHZ8g3FJdSxs,6074
39
39
  better_notion/_cli/commands/__init__.py,sha256=hxoUYPXalRT123fITkPirs03nzCfD9YAGd8ac3bQY9w,112
40
40
  better_notion/_cli/commands/auth.py,sha256=d1-g8SKCrC8Di4yM36hafVlF9YZQ9pypRYU9IQoaZOo,3663
41
41
  better_notion/_cli/commands/blocks.py,sha256=ErcR-SHhPoz6B9uy0xOG6CGZB-bhvny5lxBYufmYHbw,15711
@@ -48,6 +48,10 @@ better_notion/_cli/commands/search.py,sha256=JM20W5TiohsOKLyEUABEaWr0yB82W2_qAGQ
48
48
  better_notion/_cli/commands/update.py,sha256=NfmijzTpCbVTEY2h0QdcJZXEiGmWkk-iyEtZCqrgmAk,4997
49
49
  better_notion/_cli/commands/users.py,sha256=wpjKCo-HHfpiGsjvLSs8nb2MjZ8nxtppCC0N_OCkz9M,4890
50
50
  better_notion/_cli/commands/workspace.py,sha256=f3VQcXZ6lu2QrAxkQyFVb3FVU7LYC8kag6VOUvVEu-c,3671
51
+ better_notion/_cli/docs/__init__.py,sha256=NQ2Wt18dVEE43hw2XZtdM8S3OJ5DHzLTKW20byxxYng,415
52
+ better_notion/_cli/docs/base.py,sha256=xESWiLIaNqK8jCs34_jM1E33oaIv4lwmhJkJh3Lf4RQ,6538
53
+ better_notion/_cli/docs/formatters.py,sha256=bFZ2WOr7Q1O-Q2uUXWki_88jciqHU39wJeaOc_QqSGc,4261
54
+ better_notion/_cli/docs/registry.py,sha256=D1AyQoUITrs-8r_hP72C6ef1vsEQhOEqV13oBuv3pK0,2281
51
55
  better_notion/_cli/utils/__init__.py,sha256=VV2SaZnclN-HMMRIsqgxlBNL2HB4n1AvAfMJJWCoTxo,29
52
56
  better_notion/_sdk/__init__.py,sha256=oTo9qHSrRBRqPw-2ZHU5TR4erVZTf9IzYRFP8ju9H5U,210
53
57
  better_notion/_sdk/client.py,sha256=1XKpMLNesCNi4xq6zi__qgh02SLcB3ZwWM-gG-7PAUQ,13660
@@ -107,8 +111,9 @@ better_notion/plugins/base.py,sha256=3h9jOZzS--UqmVW3RREtcQ2h1GTWWPUryTencsJKhTM
107
111
  better_notion/plugins/loader.py,sha256=zCWsMdJyvZs1IHFm0zjEiqm_l_5jB1Uw4x30Kq8rLS4,9527
108
112
  better_notion/plugins/state.py,sha256=jH_tZWvC35hqLO4qwl2Kwq9ziWVavwCEUcCqy3s5wMY,3780
109
113
  better_notion/plugins/official/__init__.py,sha256=rPg5vdk1cEANVstMPzxcWmImtsOpdSR40JSml7h1uUk,426
110
- better_notion/plugins/official/agents.py,sha256=Sa_Yxsj9CG3gULVLGJOrpIcdX9Tp4afi3nsCNQ-dwCU,32023
114
+ better_notion/plugins/official/agents.py,sha256=Wc3EK934GEbD3lGrU2ZuVW8K5bNVA1BIGqttk52wIno,40859
111
115
  better_notion/plugins/official/agents_cli.py,sha256=8l6e1zJCAT4DdAO-QfdjK_vrrrik3pmrojwakE32ZNY,53048
116
+ better_notion/plugins/official/agents_schema.py,sha256=QDMGzOUEtH2QShIig8g6pS8veeZz6x034RXm6MU2PJQ,14136
112
117
  better_notion/plugins/official/productivity.py,sha256=_-whP4pYA4HufE1aUFbIdhrjU-O9njI7xUO_Id2M1J8,8726
113
118
  better_notion/plugins/official/agents_sdk/__init__.py,sha256=luQBzZLsJ7fC5U0jFu8dfzMviiXj2SBZXcTohM53wkQ,725
114
119
  better_notion/plugins/official/agents_sdk/managers.py,sha256=0zMZPu63zhdyqiudO2gKsmM3YOJh0nFAR9FrMlwkV2A,31186
@@ -127,8 +132,8 @@ better_notion/utils/agents/rbac.py,sha256=8ZA8Y7wbOiVZDbpjpH7iC35SZrZ0jl4fcJ3xWC
127
132
  better_notion/utils/agents/schemas.py,sha256=eHfGhY90FAPXA3E8qE6gP75dgNzn-9z5Ju1FMwBKnQQ,22120
128
133
  better_notion/utils/agents/state_machine.py,sha256=xUBEeDTbU1Xq-rsRo2sbr6AUYpYrV9DTHOtZT2cWES8,6699
129
134
  better_notion/utils/agents/workspace.py,sha256=nS7BNa0-RFCxeAKa0inmBZcPfRKTMB11pi9OW4WzvQ4,15915
130
- better_notion-1.5.5.dist-info/METADATA,sha256=NwV0BcDdFVCjqHh7JbBZJechiXP_0YubbMlQPk9nTqU,11096
131
- better_notion-1.5.5.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
132
- better_notion-1.5.5.dist-info/entry_points.txt,sha256=D0bUcP7Z00Zyjxw7r2p29T95UrwioDO0aGDoHe9I6fo,55
133
- better_notion-1.5.5.dist-info/licenses/LICENSE,sha256=BAdN3JpgMY_y_fWqZSCFSvSbC2mTHP-BKDAzF5FXQAI,1069
134
- better_notion-1.5.5.dist-info/RECORD,,
135
+ better_notion-1.6.0.dist-info/METADATA,sha256=leiPUN0D9auHnDVpw5hos7gPAoxwsEwJVp4xv8vVunk,11096
136
+ better_notion-1.6.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
137
+ better_notion-1.6.0.dist-info/entry_points.txt,sha256=D0bUcP7Z00Zyjxw7r2p29T95UrwioDO0aGDoHe9I6fo,55
138
+ better_notion-1.6.0.dist-info/licenses/LICENSE,sha256=BAdN3JpgMY_y_fWqZSCFSvSbC2mTHP-BKDAzF5FXQAI,1069
139
+ better_notion-1.6.0.dist-info/RECORD,,