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

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.

The flat registry

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].

# 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.

The strict executor signature

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.

# 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.

The dispatcher that knows nothing

# 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.

What this buys you in practice

Three things I noticed during the v3 build that I did not notice in v2:

Adding a tool is a one-file change. I added a 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.
Disabling a tool is a one-line change. Comment out the spread in 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.
Refactoring is safe. I renamed 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 honest limitations

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.

Try it

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 (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+

推荐订阅源

DEV Community