Addon:GrampsAssistant

This is a Third-party Addon. The Addon/Plugin system is controlled by the Plugin Manager. Please use carefully on data that is backed up, and help make it better by reporting any issues to the bug tracker. Unless otherwise stated on this page, you can download this addon by following these instructions. Please note that some Addons have prerequisites that need to be installed before they can be used.

The Gramps Assistant adds a chat panel to Gramps where you can ask questions about your family tree in plain English — things like "How many people were born before 1900?", "How am I related to I0042?", or "Who are Anna Larsson's grandchildren?" — and get answers pulled straight from your open family tree. It can also drive Gramps on your behalf: switching views, applying filters so results appear on screen, opening the editor for a person, and navigating to someone by name.

Your family tree data leaves your computer To answer a question, the AI provider you choose (OpenAI, Anthropic, Google, or another) is sent whatever information from your tree is needed to answer it. If that's a concern, run a model on your own computer instead — see Using a local, private model below — so nothing goes out over the internet.

Cloud AI providers usually charge money Unless you use a local model, each question costs a small amount of money, billed to the API key you provide. Costs are normally tiny (fractions of a cent to a few cents per question), but check your provider's pricing page if you plan to use it heavily.

The assistant can make changes, and not everything is confirmed first Most questions only read data. But the assistant can also write and run small pieces of code against your tree (through the Gram.py Script addon it relies on for advanced lookups) to have the same permissions as Gramps itself. Full scripts are shown to you in the Grampy Script panel and wait for you to press Execute before anything runs; but quick one-line lookups the assistant uses to answer a question can run immediately, without a confirmation step. Anything it changes goes through Gramps' normal Undo history (Edit -> Undo), so it can always be reverted. Only connect this addon to AI providers/models you trust, and consider testing on a backup copy of your tree first.

Contents

Usage

Open it from Tools -> Utilities -> Gramps Assistant. It opens as a persistent panel that you can leave open alongside the rest of Gramps while you work — closing its window just hides it, and your conversation is still there when you reopen it.

The panel has three parts:

• A scrolling chat display at the top, showing your questions and the assistant's answers, with headings, bullet lists, tables, links, and code formatted for easy reading.
• A text box where you type your question. Press ↵ Enter to send it, or ⇧ Shift+↵ Enter to start a new line without sending.
• A row of controls below the text box: a ⚙ (gear) button for Settings, a Clear button, an approximate token-count label, and a Send button (which becomes Cancel while the assistant is replying, so you can stop a response in progress).

Before you can chat, click ⚙ and choose an AI model — see Settings below. Until a model is chosen, the Send button will just remind you to configure one.

Following what you're looking at

The assistant automatically knows which person is currently selected elsewhere in Gramps (the "active person"), and updates that awareness whenever you navigate to someone else. This means you can ask things like "How old was she when she died?" or "Who are his parents?" right after clicking on a person, without needing to repeat their name or ID. This can be turned off in Settings if you'd rather it not add that information to every question.

Starting over

Click Clear to erase the conversation and start fresh. This is also a good way to reduce the token count shown next to the buttons (an estimate of how much text is being sent to the AI provider with every question) if a long conversation is getting expensive or slow.

Settings

Click the ⚙ button to open the settings dialog:

• System Prompt — the instructions given to the AI before every conversation, describing its role and how it should behave. The default asks it to answer genealogy questions using only real data from tools, never invented answers. Advanced users can customize this; most people can leave it as-is.
• Simplify tools — when enabled, the assistant only mentions the specific capabilities relevant to your current question (based on keywords and the Gramps view you have open) instead of all of them at once. Turn this on if you're using a smaller or local model that gets confused by too many options at once; leave it off for the best results with a capable cloud model.
• Use Local Model — see below.
• Use Foundational Model — pick a well-known cloud AI model from the Model dropdown (OpenAI, Anthropic Claude, and Google Gemini presets are included), and enter the name of the environment variable holding your API key for that provider (e.g. OPENAI_API_KEY). Choosing Custom lets you point at any OpenAI-compatible or Anthropic-compatible service by URL.

Getting an API key

Cloud providers require you to sign up on their website and create an API key, a long secret code that authorizes billing to your account. Once you have one, make it available to Gramps by setting an environment variable with that name before starting Gramps, for example (Linux/macOS):

   export OPENAI_API_KEY=your-key-here
   gramps

On Windows, set it as a System Environment Variable instead. Never share your API key or paste it directly into the chat — Settings only asks for the name of the variable, not the key itself.

Using a local, private model

If you'd rather nothing about your family ever leaves your computer (and pay nothing per question), you can run an AI model locally with free software such as Ollama, LM Studio, or llama.cpp, then point Gramps Assistant at it:

1. Install and start one of those programs, and load a model that supports "tool calling" / "function calling" (check the model's description).
2. In Settings, select Use Local Model and enter its URL (Ollama's default is http://localhost:11434) and, for Ollama, the model's name.
3. No API key is needed for local models.

Local models are typically less capable than the latest cloud models, especially at following complex multi-step instructions, so turning on Simplify tools is recommended in this mode.

What you can ask

Some examples to get a feel for it:

• "How many people are in this tree?"
• "Tell me about I0001." / "Tell me about the active person."
• "Is I0042 still alive?"
• "How is I0010 related to I0025?"
• "List the children of I0007." / "Who are her siblings?"
• "Show me his ancestors back 6 generations."
• "What events do we have recorded for I0003, not just birth and death?"
• "Switch to the Places view." / "Find everyone with the surname Larsson."
• "Open the editor for the active person."
• "Look up 'Ellis Island' on Wikipedia."

For questions that don't fit a specific built-in capability — custom counts, breakdowns, or reports — the assistant can write and run a short Gram.py Script on the fly (the Grampy Script addon must be installed; see Prerequisites).

Prerequisites

• The Gram.py Script gramplet, which Gramps Assistant relies on for advanced lookups and for running any code it writes. It is installed automatically as a dependency when you install Gramps Assistant through the Addon Manager.
• An internet connection, if you're using a cloud AI provider — none is needed for a local model.
• An account and API key with whichever cloud AI provider you choose, unless you're using a local model.

Credits

Gramps Assistant was built by Doug Blank.

See also

• Gram.py Script — the scripting gramplet that powers Gramps Assistant's advanced lookups.
• GrampsAssistant source on GitHub.