Summary Views Documentation

1. Documentation Audit: docs/summary-views.md

1.1 Discrepancies

D1: Task ID prefix in example (cosmetic but misleading)

• Doc (line 158): "id": "task_01J5X..." suggests a task_ prefix
• Code (api.py:1273): task_id = payload.task_id or str(ULID()) generates a raw ULID without prefix
• Impact: Low - example-only, but could confuse someone parsing or matching IDs
• Fix: Change the example ID to "01J5X..." (plain ULID format)

D2: DELETE response body not documented

• Doc (lines 115-116): Shows only the HTTP method and path, no response body
• Code (api.py:1166): Returns AckResponse(status="ok") with HTTP 200
• Impact: Low - API consumers won't know what to expect from the response
• Fix: Add response example: {"status": "ok"}

D3: Partition results survive view deletion (undocumented)

• Doc: No mention of what happens to stored partition results when a view is deleted
• Code (summary_views.py:147-148): Explicitly states in a comment: "Stored partition summaries are left as-is for now; they can be cleaned up in a later pass if needed."
• Impact: Medium - orphaned data accumulates in Redis with no API to clean it up
• Fix: Add a note under "Delete a Summary View" explaining this behavior

D4: Missing error response documentation

• Doc: No mention of 400, 404, or 422 error responses for any endpoint
• Code produces these errors:
  • 404 for non-existent views (api.py:1162, 1200, 1241, 1271)
  • 404 for non-existent tasks (api.py:1297)
  • 400 for invalid group_by/filter keys (api.py:1098-1109)
  • 400 for group keys mismatch in partition run (api.py:1206-1212)
  • 400 for source != "long_term" (api.py:1080-1087)
  • 422 for validation errors (e.g., time_window_days: 0 violates ge=1)
• Impact: Medium - developers will encounter undocumented error cases
• Fix: Add an "Error Responses" section

D5: Group key validation for partition runs not documented

• Doc (line 127-129): Shows running a partition with {"group": {"user_id": "alice"}} but doesn't mention the constraint
• Code (api.py:1203-1212): Validates that set(payload.group.keys()) == set(view.group_by) and returns 400 if they don't match exactly
• Impact: Medium - developers will hit unexpected 400s if they provide extra or missing keys
• Fix: Add a note under "Run a Single Partition" explaining the group keys must exactly match view.group_by

D6: Authentication requirement not mentioned

• Doc: No mention that all endpoints require authentication
• Code: Every endpoint has current_user: UserInfo = Depends(get_current_user)
• Impact: Medium - API consumers need auth headers (or DISABLE_AUTH=true in development)
• Fix: Add an authentication note at the top or link to the auth docs

1.3 Missing Information

These are not inaccuracies but notable omissions that would improve the documentation: