Ability Name: community/notion-quick-capture

[azazrashid]

Add notion-quick-capture community ability

Voice inbox for Notion: capture tasks and notes, search pages, read content, and query databases by voice via the Notion API.

Deliverables:

• community/notion-quick-capture/main.py — ability logic (quick add to database, quick note to page, search, read page, query database; first-run setup with token validation and database discovery; handling for multi-data-source DBs and invalid tokens)
• community/notion-quick-capture/config.json — unique_name and matching_hotwords for trigger registration
• community/notion-quick-capture/init.py — package marker
• community/notion-quick-capture/README.md — setup (integration creation, sharing with OpenHome), trigger words, example flows, API usage, limitations

Behavior:

• Uses Notion API 2022-06-28; internal integration token (no OAuth).
• Persists integration_token, databases (nickname + schema cache), notes_page_id in notion_capture_prefs.json (delete-then-write).
• Validates token on startup; re-runs setup if invalid.
• Skips/removes databases that use multiple data sources (unsupported).
• Quick add/query fall back to title-only or no filter when schema fetch fails.
• Exit words and resume_normal_flow() on all paths; editor_logging_handler only; no blocked imports.

Suggested Trigger Words
"notion",
"add to my tasks",
"new task",
"add a note",
"add to notion",
"notion note",
"search notion",
"find in notion",
"read from notion",
"notion tasks",
"what tasks",
"capture to notion"

Demo:
https://www.loom.com/share/8b19595010914807a8ec50da118bb8b5 https://www.loom.com/share/ce9d7c49a9a64556919c9684555323e8

Type

• New community Ability
• Improvement to existing Ability
• Bug fix
• Documentation update

Checklist

• Files are in community/my-ability-name/
• main.py follows SDK pattern (extends MatchingCapability, has register_capability + call)
• README.md included with description, suggested triggers, and setup
• resume_normal_flow() called on every exit path
• No print() — using editor_logging_handler
• No hardcoded API keys — using placeholders
• No blocked imports (redis, connection_manager, user_config)
• No asyncio.sleep() or asyncio.create_task() — using session_tasks
• Error handling on all external calls
• Tested in OpenHome Live Editor

[github-actions]

🔀 Branch Merge Check

PR direction: add-notion-quick-capture → dev

✅ Passed — add-notion-quick-capture → dev is a valid merge direction

[github-actions]

✅ Ability Validation Passed

📋 Validating: community/notion-quick-capture
  ✅ All checks passed!

[github-actions]

✅ Community PR Path Check — Passed

All changed files are inside the community/ folder. Looks good!

[github-actions]

🔍 Lint Results

✅ __init__.py — Empty as expected

Files linted: community/notion-quick-capture/main.py

✅ Flake8 — Passed

✅ All checks passed!

[abubakar4360]

I checked the setup on the link, and I did not get the ntn... token. Can you please check again if there are changes on Notion's site?

[azazrashid]

@abubakar4360 I checked and it's there. You have to go to the notion.so/profile url and create an internal integration.

[abubakar4360]

Hello @azazrashid, I checked the demo, great work on the notion ability. The schema caching design is smart — fetching and storing Notion property types once and reusing them across the session keeps the LLM property-mapping prompt accurate without hammering the API on every command. A few things to fix before this can go through:

1. EXIT_WORDS is missing natural spoken exits. {"stop", "exit", "quit", "done", "cancel", "bye", "goodbye", "never mind", "no thanks", "that's all", "that is all"} misses: "forget it", "leave it", "I'm good", "that's it", "all done", "actually", "close", "end". Long-term fix: replace the _is_exit check with a single LLM classifier call — "Is the user trying to stop or exit? Return YES or NO."

2. The _query_database spoken summary goes directly from LLM output into speak() with no length cap or format guardrails. The prompt says "1-2 sentences per item" for up to 8 items — that's up to 16 sentences read aloud in one go. Add to the prompt: "Total response under 40 words. Plain spoken English only, no markdown, no bullet points, no lists. Lead with the most important item."

3. _read_page also pipes LLM output straight into speak(). The summary prompt says "3-5 sentences" with no word limit — a dense Notion page could produce 80+ words of spoken output. Add to the system prompt: "Maximum 40 words. Plain spoken English, no markdown, no lists."

4. "Adding that now." fires for both quick_add and quick_note before the API call completes. On a slow connection this means the user hears confirmation before anything has actually happened, then potentially a second error message. Move the confirmation speak to after the successful API call inside _quick_add and _quick_note, or change the filler to something non-committal: "On it." or "One sec."

5. "No database configured. Run Notion setup first." appears twice — in _quick_add and _query_database. "Run Notion setup" is implementation language. Change to: "I don't have a database set up yet. Say Notion setup to get started."

6. "Your Notion integration token is invalid. Please run setup again and paste a new token." — 23 words, and "paste a new token" assumes the user knows what a token is. Change to: "Your Notion connection isn't working. Let's set it up again."

7. "I didn't find anything matching that. Make sure the page is shared with the OpenHome integration, or try different keywords." — 23 words of troubleshooting instructions. On a voice device this is too much. Change to: "Nothing came up for that. Try different keywords or check your Notion sharing settings."

8. _first_run_setup contains at least six sequential speak() + user_response() or run_io_loop() calls with no LLM routing between them. Per the QA guide this warrants a manual voice test before approval — run through the full setup flow out loud and confirm it doesn't feel like a phone tree. Several of the setup speak strings are also very long (the three-step token walkthrough, the database share instructions) and should be considered for partial deferral to logs rather than TTS.

[uzair401]

Hi @azazrashid, Please address the issues highlighted by @abubakar4360, and then we will proceed further.