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

> Source: <https://dev.to/aman_sachan_126d19c4a2773/how-i-pack-eleven-tool-domains-into-one-pyside6-window-without-spaghetti-wiring-1e7b>
> Published: 2026-06-18 01:51:17+00:00

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+