Practice

Writing tools with an AI assistant

The Ask AI panel, what it sends and what it writes, and how to get the same result from any chatbot you already use.

pyNavis ships an AI (beta) panel whose Ask AI dock panel writes bundles from a plain-words request. It is a convenience over the same contract this guide describes, not a different way of building tools: what comes back is a bundle.yaml, a script.py and sometimes a config.py, written into an ordinary *.pushbutton folder you can open and edit. This page explains the mechanism so you can trust it, tune it, or reproduce it elsewhere.

The panel is a beta, and not the only way#

The panel is new and lightly tested. Read every script it proposes before you click Create. And you do not need it at all: any assistant that can read a long document will write pyNavis tools once it has the authoring guide. The panel's footer has a Copy authoring guide button that puts that exact guide on the clipboard, and the rest of this page tells you what to do with it.

What the model is given#

Every request carries a system prompt made of two parts:

• The output rules. Answer with one bundle; a Title: line; an Icon: line naming one or two letters and a colour; one fenced block per file with the file name in the fence's info string; no other files or paths; no __main__ guard; toasts, never print(); ask a question instead of guessing a property name.
• The authoring guide. A generated document, authoring-pack.md, shipped beside the runtime: what a pushbutton is, the hard rules, the silent failure modes, the script templates, the design rules and the full pynavis API reference. It is built from the same sources as this site.

Then the conversation so far. When you tick Attach selection, the newest message also carries the schema of the current selection: the item count, the category names and the property names under each, capped at about four kilobytes. Never a value. A value is project data, a source file name, a client, a project number in a custom tab, and this text leaves the machine, so the reader in SelectionReader does not read values at all and SelectionSummary would drop one if it were handed it. Nothing else about the document goes: no file name, no path, no geometry. When the conversation is revising a tool, the newest message also carries that tool's files exactly as they are on disk, so the model edits what exists rather than what it remembers.

What comes back, and what is written#

The reply is parsed for fenced blocks named bundle.yaml, script.py or config.py. Any other name is refused and listed in the transcript, never written. A reply with no script.py is a question, not a proposal. A complete proposal shows a card: Create tool the first time, Update tool afterwards.

Create writes the bundle into the per-user extension root, which pyNavis always scans:

%APPDATA%\pyNavis\extensions\AI.extension\
    extension.yaml                       name: AI
    AI.tab\Generated.panel\
        Isolate_Level.pushbutton\
            bundle.yaml
            script.py
            config.py                    only when proposed
            icon.png  icon.dark.png  icon.small.png  icon.small.dark.png

The folder name is the title with everything but letters, digits and underscores removed, numbered if it already exists. The four icons are painted in-app: a rounded square in violet, teal, amber, rose or green with the letters from the Icon: line. Blue is deliberately not in that set, so a tool the assistant wrote never passes for a shipped one. The files are written to a staging folder and moved into place in one step, then the ribbon reloads. Update rewrites the same folder, so the bundle key, and any shortcut bound to it, survive.

Coming back to a tool#

The panel header has a dropdown of every tool in AI.extension. Picking one starts a fresh conversation that is already editing that tool: its files ride on your next message, and the card reads Update tool. Nothing is sent until you type.

The fix loop#

Every script that fails records its traceback per bundle for the session. When the tool the conversation is editing has one, the transcript offers Send last error to AI, which pastes the traceback as the next message and asks for complete revised files. Creating or updating the tool clears the recorded error.

Doing the same with any assistant#

1. In the Ask AI panel, click Copy authoring guide. No key is needed for that button. The clipboard now holds the output rules and the guide, about thirty thousand tokens.
2. Paste it into your chatbot as the first message, or as a project or custom instruction if it supports one, then describe the tool.
3. Save what comes back as files: make a folder <Name>.pushbutton under a panel in one of your extensions, put script.py and bundle.yaml in it, and click Reload. See Your first button for the folder chain and Icons for the art; without an icon the button still works, it just has none.
4. If it fails, copy the traceback from the output window or the log at %APPDATA%\pyNavis\logs\pyNavis.log back into the chat.

The guide is what makes this work. A model that has not read it will happily wrap the code in if __name__ == '__main__': (which never runs in pyNavis), print() its result (which opens an empty output window) and invent library functions. With it, the answer usually runs first time.

Settings and privacy#

Provider, base URL, model and the longest answer are the ai section of config.json, edited from AI Settings or the AI section of the Settings window. The API key is not there: it is in secrets.json beside it, encrypted with Windows DPAPI for the current user, so a shared or screenshotted config.json never carries a key. Two providers are supported, Anthropic and any OpenAI-compatible endpoint, which also covers a local server with no key at all. Requests go from Navisworks straight to that endpoint; pyNavis runs no service in between and keeps no copy of the conversation.