Create a specialist

Combine a tool, a focused assistant and a page into a mini-app.

Create a specialist

A specialist is a mini-app: a tool, an assistant with one job, and a page in the sidebar. People can use it on its page, or just ask Tallgeese's main chat, which hands the question over. The Financial Advisor is built this way: it keeps a watch list, fetches prices and news, and shows them on a page.

Four files make a specialist

1. item.toml: the parts

[[provides]]
kind = "sandboxedServer"
server = "finance"
grants = ["storage"]                       # lets the tool keep a database
allow = { http = ["https://www.sec.gov:443"] }
tools = { ask = ["record_trade", "delete_account"] }

[[provides]]
kind = "agent"
role = "tg_financial_advisor"
# When should the main chat hand a question over?
area = "their investments, portfolio or watch list, or prices or news about a stock or fund"

[[provides]]
kind = "page"
id = "financial-advisor"
glyph = "chart"
calls = ["list_portfolio", "watch", "delete_account"]   # what the page may do itself
confirms = ["delete_account"]                           # the page asks "are you sure?" first
actions = ["review", "news"]                            # buttons that start a chat message

2. agent/agent.toml: the assistant's job

name = "tg_financial_advisor"
description = "The person's investments: holdings, a watch list, prices and news."
developer_instructions = """
You are the Financial Advisor. Your only job is the person's investments.
- Always use your tools. Never estimate a number yourself.
- Say "as of" with the time and source for any price.
- Don't recommend buying or selling particular securities.
"""

The instructions can be up to 16 KB. Say what the job is, which tool answers which question, what to do when nothing is set up yet, and what never to do.

3. plugin.toml: settings and permissions

[[settings]]
id = "price_key"
kind = "secret"           # typed in the app's settings and kept safely; the page never sees it
group = "prices"

[[permissions]]
id = "trades"
default = "ask"           # the person can change this to "allow"
tools = ["record_trade"]

[data]
storage = true
export = ["json", "csv"]  # lets people export their own data

4. page/: your screen

A normal web page (HTML, CSS, JavaScript) that you build into a single file. It talks to Tallgeese through a small helper called host:

import { host } from "@tallgeese/plugin-page";

const info = await host.init();                    // always first: language, theme, settings
const result = await host.call("list_portfolio");  // run one of the tools you listed in "calls"
host.onChanged(() => refresh());                   // data changed (even if the assistant changed it)
host.onTheme((t) => applyTheme(t));                // follow the app's light or dark mode
host.ask("Review my mix");                         // start a chat message when the person clicks
host.openSettings("prices");                       // send them to settings to type a key

The page runs in a sealed frame: no network, no files, no access to the conversation. It can only do what the helper allows.

Design rules that keep people safe

• Consequences are confirmed in the chat. Recording a trade isn't something the page can do. The person confirms it in the conversation, where they can see exactly what's being asked.
• If the page can call something that asks first, it must ask too. That's what confirms is for.
• The tool does the work. The page draws, the assistant follows instructions, and only the tool computes, stores data or goes online.
• Return data for the page separately. A tool can answer in text for the assistant and also in structured data for the page.
• Ask for only what you need. List only the addresses you really reach, and only the tools the page really needs.
• Make your own data last. Data stays on the person's computer when your item updates. If you change your database layout, upgrade it the first time the new version starts.

Using Python in your skills

Skills are only text, but Tallgeese can supply a ready-made Python for them. Add one line to your item and, when someone gets it, Tallgeese offers to download Python once (they see how large it is first).

[[provides]]
kind = "skillPack"
skills = ["python-scripts"]

[[provides]]
kind = "runtime"
family = "python"

• It includes numpy, pandas, matplotlib, openpyxl, python-docx, python-pptx, reportlab, pypdf, pillow and lxml. Nothing else can be installed, so design around those.
• In your skill, tell the assistant to check Python is there first, write scripts to files, never overwrite the person's files, and never try to install packages.
• Reading a Word or PDF file is easier with the built-in document reader. Use Python to make files.
• It isn't available on every kind of computer yet. People on an unsupported one see that the item is for another computer.