Summary Views Documentation

[bsbodden]

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:

Missing Detail	Code Location	Suggested Action
Task TTL is 7 days (auto-expiry)	tasks.py:13 _TASK_TTL_SECONDS = 604800	Add to "Task Polling" section
Max 200 memories inlined in LLM prompt	summary_views.py:46 _MAX_MEMORIES_FOR_LLM_PROMPT = 200	Add to "Token-Aware Summarization"
Large memory set warning at 5,000+ memories	summary_views.py:580	Add to "Configuration Options"
Fallback when no LLM API keys configured	summary_views.py:434-443 (concatenates up to 50 memories)	Add as a note under "Custom Prompts"
No MCP tools for summary views	mcp.py has zero summary view references	Mention in overview or "Related Documentation"
Storage uses plain Redis strings (not RedisJSON)	summary_views.py:99-163	Consider noting for operators
time_window_days minimum value is 1	models.py:974 ge=1	Add to the fields table
View IDs are ULIDs (not UUIDs)	api.py:1126 str(ULID())	Clarify in create response example