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