{"slug": "how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring", "title": "How I Pack Eleven Tool Domains into One PySide6 Window Without Spaghetti Wiring", "summary": "A developer built Sentience v3, a 100% local desktop AI assistant with 60 tools across 11 domains, using a flat registry pattern to avoid spaghetti wiring. The system uses a strict executor signature and a single dispatcher that knows nothing about individual tools, ensuring maintainability and preventing silent failures.", "body_md": "Sentience v3 is a 100% local desktop AI assistant — think \"Cursor, but it also handles your email, your browser, your memory, and your voice.\" It runs on PySide6, talks to Groq / OpenAI / Anthropic / Ollama, and ships ~60 tools across eleven domains: code editor, file browser, integrated terminal, browser automation, memory, RAG, context compression, email, voice, local hosting, and OAuth.\n\nThe trap with that many tools is wiring. If each tool is a one-off `if tool_name == \"x\"`\n\nbranch, the dispatcher becomes a 400-line `switch`\n\nfrom hell, and a typo in one name silently disables a feature. I spent two evenings on that mistake in v2. v3 fixes it with a pattern I'd describe as: **a flat registry, a strict executor signature, and one dispatcher that knows nothing about any individual tool**.\n\nEvery tool lives in a module under `src/<domain>/`\n\nand exports a `*_TOOLS`\n\nlist. The top-level `TOOLS`\n\nlist is literally a `[*BROWSER_TOOLS, *EMAIL_TOOLS, *SKILLS_TOOLS, *MEMORY_TOOLS, *HOSTING_TOOLS, *VOICE_TOOLS, *COMPRESSION_TOOLS, *OAUTH_TOOLS, *TERMINAL_TOOLS, *EDITOR_TOOLS, *FILE_TOOLS]`\n\n.\n\n``` python\n# src/tools.py\nfrom browser.tools import BROWSER_TOOLS\nfrom email_agent.tools import EMAIL_TOOLS\nfrom skills.tools import SKILLS_TOOLS\nfrom memory.tools import MEMORY_TOOLS\nfrom hosting.tools import HOSTING_TOOLS\nfrom voice.tools import VOICE_TOOLS\nfrom compression.tools import COMPRESSION_TOOLS\nfrom oauth_manager.tools import OAUTH_TOOLS\nfrom terminal.tools import TERMINAL_TOOLS\nfrom editor.tools import EDITOR_TOOLS\nfrom file_browser.tools import FILE_TOOLS\n\nTOOLS = [\n    *BROWSER_TOOLS,\n    *EMAIL_TOOLS,\n    *SKILLS_TOOLS,\n    *MEMORY_TOOLS,\n    *HOSTING_TOOLS,\n    *VOICE_TOOLS,\n    *COMPRESSION_TOOLS,\n    *OAUTH_TOOLS,\n    *TERMINAL_TOOLS,\n    *EDITOR_TOOLS,\n    *FILE_TOOLS,\n]\n```\n\nThat's the whole list. No nested groups, no \"categories with priorities\", no clever merging logic — eleven flat spreads. If you add a tool, you add a constant. If you remove a domain, you delete one spread. There is no other place to edit.\n\nEvery tool function takes `(args: dict) -> dict`\n\nand returns `{\"success\": bool, \"error\": str | None, \"result\": Any}`\n\n. Always. The dispatcher does not care whether the tool is a Playwright click or an SMTP send — it gets the same shape back.\n\n``` php\n# src/browser/tools.py\ndef browser_navigate(args: dict) -> dict:\n    url = args.get(\"url\")\n    if not url or not isinstance(url, str):\n        return {\"success\": False, \"error\": \"url is required and must be a string\", \"result\": None}\n    try:\n        page = sync_playwright().start().chromium.launch().new_page()\n        page.goto(url, timeout=8000)\n        title = page.title()\n        return {\"success\": True, \"error\": None, \"result\": {\"url\": url, \"title\": title}}\n    except Exception as e:\n        return {\"success\": False, \"error\": f\"navigation failed: {e}\", \"result\": None}\n\nBROWSER_TOOLS = [\n    {\n        \"name\": \"browser_navigate\",\n        \"description\": \"Navigate the Playwright browser to a URL and return the page title.\",\n        \"parameters\": {\n            \"type\": \"object\",\n            \"properties\": {\"url\": {\"type\": \"string\", \"description\": \"Absolute URL to navigate to\"}},\n            \"required\": [\"url\"],\n        },\n        \"executor\": browser_navigate,\n    },\n]\n```\n\nTwo things to notice. First, **the dispatcher never sees the function's internals** — it only ever reads `.name`\n\n, `.description`\n\n, `.parameters`\n\n, and `.executor`\n\n. Second, **the executor is a real function reference**, not a string. That means the GUI's autocomplete, the LLM's tool description, and the dispatcher's lookup all read from the same dict — they cannot drift.\n\n``` php\n# src/agent.py\ndef execute_tool(name: str, args: dict) -> dict:\n    tool = TOOL_REGISTRY.get(name)\n    if tool is None:\n        return {\"success\": False, \"error\": f\"unknown tool: {name}\", \"result\": None}\n    try:\n        return tool[\"executor\"](args)\n    except Exception as e:\n        return {\"success\": False, \"error\": f\"tool raised: {e!r}\", \"result\": None}\n\nTOOL_REGISTRY = {t[\"name\"]: t for t in TOOLS}\n```\n\nTwelve lines. It validates the name, calls the executor, catches anything that escapes the executor's own `try/except`\n\n(defence in depth), and returns the same dict shape every other tool returns. The agent loop never branches on tool type.\n\nThe registry itself is built at import time from the flat list, so `len(TOOL_REGISTRY)`\n\nis the number of tools the LLM is told about, the number the GUI autocompletes from, and the number the dispatcher can route to. One source of truth.\n\nThree things I noticed during the v3 build that I did not notice in v2:\n\n`terminal_run`\n\ntool last weekend and zero other files needed editing. The dispatcher, the registry, the LLM tool list, and the GUI autocomplete all picked it up automatically.`tools.py`\n\n. The tool vanishes from the LLM's available list, the GUI stops autocompleting it, and `execute_tool`\n\nreturns `unknown tool`\n\nif anything still calls it. No leftover routes.`browser_click`\n\nto `browser_press`\n\nlast week. The LLM started failing for a hot minute, but the failure was a clean `unknown tool`\n\nfrom the dispatcher, not a `KeyError`\n\nfrom somewhere in the GUI. I could grep for the old name, see every callsite, and decide on each one.The flat list is not free. If two tools in different domains want the same name, the later spread silently wins, and there is no warning. I almost shipped a duplicate `terminal_run`\n\nlast month because both `terminal/tools.py`\n\nand `editor/tools.py`\n\nhad local helper modules that exported a function with that name — neither was a registered tool, but the import collision was loud enough to catch it. A real registry should probably check for name collisions at startup. I have not added that yet.\n\nStreaming tool output is also not handled here — every tool buffers its full result and returns it once. That is fine for an `email_send`\n\nbut feels laggy for `terminal_run`\n\non a long compile. I plan to add a `{\"stream\": True}`\n\nflag to the return shape and a `tool_event`\n\nsignal the GUI can subscribe to. The dispatcher shape does not need to change; only the executors and the GUI do.\n\nSentience v3 is MIT-licensed, the install is `pip install -r requirements.txt && playwright install chromium && python sentience_app.py`\n\n, and the only API key you need is a free Groq key. The repo, the build script, and the v2→v3 changelog are at the GitHub link below.\n\nIf you ship a tool dispatcher that does this differently — eager grouping, priority routing, dynamic tool loading — I'd genuinely like to hear what pushed you away from the flat approach. I am one bad experience away from complicating this.\n\nGitHub: [https://github.com/AmSach/sentience-v2](https://github.com/AmSach/sentience-v2) (the v3.0 build lives on the `master`\n\nbranch of this repo — the directory was renamed locally to Sentience-v3 in the workspace but the remote still points to the v2 repo)\n\nStack: PySide6 · Playwright · APScheduler · SQLite (memory + RAG) · imaplib/smtplib · SpeechRecognition + pyttsx3 · Python 3.10+", "url": "https://wpnews.pro/news/how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring", "canonical_source": "https://dev.to/aman_sachan_126d19c4a2773/how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring-1e7b", "published_at": "2026-06-18 01:51:17+00:00", "updated_at": "2026-06-18 02:21:34.251378+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models", "ai-products"], "entities": ["Sentience v3", "PySide6", "Groq", "OpenAI", "Anthropic", "Ollama", "Playwright"], "alternates": {"html": "https://wpnews.pro/news/how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring", "markdown": "https://wpnews.pro/news/how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring.md", "text": "https://wpnews.pro/news/how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring.txt", "jsonld": "https://wpnews.pro/news/how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring.jsonld"}}