Dsblank: Created page with "{{Third-party addon}} The {{man label|Gramps Assistant}} adds a chat panel to Gramps where you can ask questions about your family tree in plain English — things like "How m..."

2026-07-07T16:45:11Z

Created page with "{{Third-party addon}} The {{man label|Gramps Assistant}} adds a chat panel to Gramps where you can ask questions about your family tree in plain English — things like "How m..."

New page

{{Third-party addon}}
The {{man label|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.

{{man warn|1=Your family tree data leaves your computer|2=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|Using a local, private model]] below — so nothing goes out over the internet.}}

{{man warn|1=Cloud AI providers usually charge money|2=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.}}

{{man warn|1=The assistant can make changes, and not everything is confirmed first|2=Most questions only read data. But the assistant can also write and run small pieces of code against your tree (through the [[Addon:GrampyScript|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 {{man label|Grampy Script}} panel and wait for you to press {{man button|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 ({{man menu|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.}}

== Usage ==

Open it from {{man menu|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 {{man key press|Enter}} to send it, or {{man key press|Shift|Enter}} to start a new line without sending.
* A row of controls below the text box: a {{man button|⚙}} (gear) button for [[#Settings|Settings]], a {{man button|Clear}} button, an approximate token-count label, and a {{man button|Send}} button (which becomes {{man button|Cancel}} while the assistant is replying, so you can stop a response in progress).

Before you can chat, click {{man button|⚙}} and choose an AI model — see [[#Settings|Settings]] below. Until a model is chosen, the {{man button|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 {{man button|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 {{man button|⚙}} button to open the settings dialog:

* {{man label|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.
* {{man label|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.
* {{man label|Use Local Model}} — see [[#Using a local, private model|below]].
* {{man label|Use Foundational Model}} — pick a well-known cloud AI model from the {{man label|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. <code>OPENAI_API_KEY</code>). Choosing {{man label|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 [https://ollama.com/ Ollama], [https://lmstudio.ai/ LM Studio], or [https://github.com/ggml-org/llama.cpp llama.cpp], then point {{man label|Gramps Assistant}} at it:
# Install and start one of those programs, and load a model that supports "tool calling" / "function calling" (check the model's description).
# In Settings, select {{man label|Use Local Model}} and enter its URL (Ollama's default is <code>http://localhost:11434</code>) and, for Ollama, the model's name.
# 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 {{man label|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 [[Addon:GrampyScript|Gram.py Script]] on the fly (the {{man label|Grampy Script}} addon must be installed; see [[#Prerequisites|Prerequisites]]).

== Prerequisites ==
* The [[Addon:GrampyScript|Gram.py Script]] gramplet, which {{man label|Gramps Assistant}} relies on for advanced lookups and for running any code it writes. It is installed automatically as a dependency when you install {{man label|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 ==
{{man label|Gramps Assistant}} was built by Doug Blank.

== See also ==
* [[Addon:GrampyScript|Gram.py Script]] — the scripting gramplet that powers {{man label|Gramps Assistant}}'s advanced lookups.
* [https://github.com/gramps-project/addons-source/tree/maintenance/gramps61/GrampsAssistant GrampsAssistant source] on GitHub.

[[Category:Addons]]
[[Category:Plugins]]
[[Category:Tools]]

Addon:GrampsAssistant - Revision history

Dsblank: Created page with "{{Third-party addon}} The {{man label|Gramps Assistant}} adds a chat panel to Gramps where you can ask questions about your family tree in plain English — things like "How m..."