How I Pack Eleven Tool Domains into One PySide6 Window Without Spaghetti Wiring

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.

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. The trap with that many tools is wiring. If each tool is a one-off if tool name == "x" branch, the dispatcher becomes a 400-line switch from 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 . Every tool lives in a module under src/<domain / and exports a TOOLS list. The top-level TOOLS list 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 . python src/tools.py from browser.tools import BROWSER TOOLS from email agent.tools import EMAIL TOOLS from skills.tools import SKILLS TOOLS from memory.tools import MEMORY TOOLS from hosting.tools import HOSTING TOOLS from voice.tools import VOICE TOOLS from compression.tools import COMPRESSION TOOLS from oauth manager.tools import OAUTH TOOLS from terminal.tools import TERMINAL TOOLS from editor.tools import EDITOR TOOLS from file browser.tools import FILE TOOLS TOOLS = BROWSER TOOLS, EMAIL TOOLS, SKILLS TOOLS, MEMORY TOOLS, HOSTING TOOLS, VOICE TOOLS, COMPRESSION TOOLS, OAUTH TOOLS, TERMINAL TOOLS, EDITOR TOOLS, FILE TOOLS, That'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. Every tool function takes args: dict - dict and returns {"success": bool, "error": str | None, "result": Any} . Always. The dispatcher does not care whether the tool is a Playwright click or an SMTP send — it gets the same shape back. php src/browser/tools.py def browser navigate args: dict - dict: url = args.get "url" if not url or not isinstance url, str : return {"success": False, "error": "url is required and must be a string", "result": None} try: page = sync playwright .start .chromium.launch .new page page.goto url, timeout=8000 title = page.title return {"success": True, "error": None, "result": {"url": url, "title": title}} except Exception as e: return {"success": False, "error": f"navigation failed: {e}", "result": None} BROWSER TOOLS = { "name": "browser navigate", "description": "Navigate the Playwright browser to a URL and return the page title.", "parameters": { "type": "object", "properties": {"url": {"type": "string", "description": "Absolute URL to navigate to"}}, "required": "url" , }, "executor": browser navigate, }, Two things to notice. First, the dispatcher never sees the function's internals — it only ever reads .name , .description , .parameters , and .executor . 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. php src/agent.py def execute tool name: str, args: dict - dict: tool = TOOL REGISTRY.get name if tool is None: return {"success": False, "error": f"unknown tool: {name}", "result": None} try: return tool "executor" args except Exception as e: return {"success": False, "error": f"tool raised: {e r}", "result": None} TOOL REGISTRY = {t "name" : t for t in TOOLS} Twelve lines. It validates the name, calls the executor, catches anything that escapes the executor's own try/except defence in depth , and returns the same dict shape every other tool returns. The agent loop never branches on tool type. The registry itself is built at import time from the flat list, so len TOOL REGISTRY is 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. Three things I noticed during the v3 build that I did not notice in v2: terminal run tool 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 . The tool vanishes from the LLM's available list, the GUI stops autocompleting it, and execute tool returns unknown tool if anything still calls it. No leftover routes. browser click to browser press last week. The LLM started failing for a hot minute, but the failure was a clean unknown tool from the dispatcher, not a KeyError from 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 last month because both terminal/tools.py and editor/tools.py had 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. Streaming tool output is also not handled here — every tool buffers its full result and returns it once. That is fine for an email send but feels laggy for terminal run on a long compile. I plan to add a {"stream": True} flag to the return shape and a tool event signal the GUI can subscribe to. The dispatcher shape does not need to change; only the executors and the GUI do. Sentience v3 is MIT-licensed, the install is pip install -r requirements.txt && playwright install chromium && python sentience app.py , 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. If 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. GitHub: https://github.com/AmSach/sentience-v2 https://github.com/AmSach/sentience-v2 the v3.0 build lives on the master branch of this repo — the directory was renamed locally to Sentience-v3 in the workspace but the remote still points to the v2 repo Stack: PySide6 · Playwright · APScheduler · SQLite memory + RAG · imaplib/smtplib · SpeechRecognition + pyttsx3 · Python 3.10+