GENA Help

Install Ollama directly on the machine running Thunderbird/Betterbird.

1. Download and install from ollama.com/download.
2. Pull a chat model (for summarisation, compose, AutoTag, etc.):

   ollama pull llama3.1:8b

3. Pull an embedding model (for Semantic Search):

   ollama pull snowflake-arctic-embed2

4. Verify the models are available:

   ollama list

Allowing API access from other machines

By default, Ollama only listens on 127.0.0.1:11434. If Thunderbird runs on a different machine to Ollama, you need to bind to all interfaces:

macOS / Linux:

OLLAMA_HOST=0.0.0.0 ollama serve

Or set OLLAMA_HOST=0.0.0.0 as a persistent environment variable before starting the Ollama service.

systemd (Linux):

sudo systemctl edit ollama

Add under [Service]:

[Service]
Environment="OLLAMA_HOST=0.0.0.0"

Then reload and restart:

sudo systemctl daemon-reload
sudo systemctl restart ollama

Running Ollama in Docker is ideal for a dedicated server or NAS. The container exposes the API on port 11434.

CPU only:

docker run -d \
  --name ollama \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama

With NVIDIA GPU:

docker run -d \
  --name ollama \
  --gpus all \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama

After the container is running, pull your models into it:

docker exec ollama ollama pull llama3.1:8b
docker exec ollama ollama pull snowflake-arctic-embed2

For full Docker documentation including AMD GPU support, see the Ollama Docker guide.

Before configuring GENA, confirm that Ollama is responding. Replace localhost with your server's hostname or IP if running remotely.

Test the LLM (generate endpoint)

curl http://localhost:11434/api/generate \
  -d '{
    "model": "llama3.1:8b",
    "prompt": "Say hello in one sentence.",
    "stream": false
  }'

You should receive a JSON response containing a "response" field with the model's reply.

Test the embedding endpoint

curl http://localhost:11434/api/embed \
  -d '{
    "model": "snowflake-arctic-embed2",
    "input": "This is a test sentence."
  }'

You should receive a JSON response containing an "embeddings" array of numerical vectors.

Test the OpenAI-compatible endpoint

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.1:8b",
    "messages": [{"role": "user", "content": "Say hello."}],
    "stream": false
  }'

If any of these return a connection error, Ollama is not running or is not listening on the expected address. See Troubleshooting.

docker run -d \
  --name qdrant \
  -p 6333:6333 \
  -p 6334:6334 \
  -v qdrant_data:/qdrant/storage \
  qdrant/qdrant

This starts Qdrant with its REST API on port 6333 and gRPC on port 6334. GENA uses the REST API (port 6333). Data is persisted in a Docker volume so it survives container restarts.

If you want to run both Ollama and Qdrant together, here is an example compose.yml:

services:
  ollama:
    image: ollama/ollama
    container_name: ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    restart: unless-stopped
    # Uncomment the following for NVIDIA GPU support:
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: all
    #           capabilities: [gpu]

  qdrant:
    image: qdrant/qdrant
    container_name: qdrant
    ports:
      - "6333:6333"
      - "6334:6334"
    volumes:
      - qdrant_data:/qdrant/storage
    restart: unless-stopped

volumes:
  ollama_data:
  qdrant_data:

Start both services with:

docker compose up -d

Then pull your models into the Ollama container as described in the Ollama setup section above.

If Qdrant is exposed to a network (not just localhost), you should enable API key authentication. Add an environment variable to your Docker run command or compose file:

environment:
  - QDRANT__SERVICE__API_KEY=your-secret-key-here

Then enter the same key in the Qdrant API Key field in GENA settings.

Confirm Qdrant is running before configuring GENA:

Health check

curl http://localhost:6333/healthz

Should return: {"title":"qdrant - vectorass engine","version":"..."} (or similar with a 200 status).

List collections

curl http://localhost:6333/collections

Should return a JSON response with a "collections" array (empty until GENA creates its first collection).

If using an API key

curl http://localhost:6333/collections \
  -H "api-key: your-secret-key-here"

If these return connection errors or timeouts, check that Docker is running and the port mapping is correct. See Troubleshooting.

This is the simplest configuration for vLLM, LM Studio, text-generation-webui OpenAI mode, or other compatible servers.

{
  "Content-Type": "application/json"
}

Request template

{
  "model": "{{model}}",
  "messages": [
    {
      "role": "user",
      "content": "{{content}}"
    }
  ],
  "temperature": 0.2,
  "stream": false
}

If your Ollama build exposes OpenAI-compatible chat completions, you can use the same pattern as vLLM.

• Endpoint URL: http://localhost:11434/v1/chat/completions
• Model: llama3.1:8b
• Response path: choices.0.message.content

Headers template

{
  "Content-Type": "application/json"
}

Request template

{
  "model": "{{model}}",
  "messages": [
    {
      "role": "user",
      "content": "{{content}}"
    }
  ],
  "stream": false,
  "temperature": 0.2
}

If you prefer Ollama's native API, use this configuration instead.

• Endpoint URL: http://localhost:11434/api/generate
• Model: llama3.1:8b
• Response path: response

Headers template

{
  "Content-Type": "application/json"
}

Request template

{
  "model": "{{model}}",
  "prompt": "{{content}}",
  "stream": false,
  "options": {
    "temperature": 0.2
  }
}

Replace YOUR_OPENAI_API_KEY with your actual key.

• Endpoint URL: https://api.openai.com/v1/chat/completions
• Model: gpt-4o-mini or another supported model
• Response path: choices.0.message.content

Headers template

{
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_OPENAI_API_KEY"
}

Request template

{
  "model": "{{model}}",
  "messages": [
    {
      "role": "user",
      "content": "{{content}}"
    }
  ],
  "temperature": 0.2
}

Anthropic's response shape is different, so the response path must also change.

• Endpoint URL: https://api.anthropic.com/v1/messages
• Model: claude-3-5-sonnet-latest or another supported model
• Response path: content.0.text

Headers template

{
  "Content-Type": "application/json",
  "x-api-key": "YOUR_ANTHROPIC_API_KEY",
  "anthropic-version": "2023-06-01"
}

Request template

{
  "model": "{{model}}",
  "max_tokens": 1200,
  "messages": [
    {
      "role": "user",
      "content": "{{content}}"
    }
  ]
}

DeepSeek uses an OpenAI-compatible chat completions endpoint. Replace YOUR_DEEPSEEK_API_KEY with your actual key.

• Endpoint URL: https://api.deepseek.com/chat/completions
• Model: deepseek-v4-flash (fast chat model) or deepseek-v4-pro (higher quality)
• Response path: choices.0.message.content

Headers template

{
  "Content-Type": "application/json",
  "Authorization": "Bearer YOUR_DEEPSEEK_API_KEY"
}

Request template

{
  "model": "{{model}}",
  "messages": [
    {
      "role": "user",
      "content": "{{content}}"
    }
  ],
  "temperature": 0.2,
  "stream": false
}

Many providers expose an OpenAI-compatible endpoint. If so, start with the vLLM/OpenAI-compatible example and only change:

• Endpoint URL
• Model
• Authentication headers

This is a complete, real-world configuration using three services on a local network: a vLLM server for the chat LLM, Ollama for embeddings, and Qdrant for vector storage. All features are enabled — summarisation, compose rewriting, inbox digest, AutoTag, and semantic search.

Replace the hostnames below with your own server addresses.

Headers template

{
  "Content-Type": "application/json"
}

Request template

{
  "model": "{{model}}",
  "messages": [
    {
      "role": "user",
      "content": "{{content}}"
    }
  ],
  "temperature": 0.2,
  "stream": false
}

Displayed message prompt

Summarise this email chain for me and return ONLY a clean HTML fragment suitable for display in a small summary panel.
Use clear section headings and spacing.
Format it as: an optional short overview paragraph, then headings for Key Request, Current Status, Actions Required, Deadlines, and Risks.
Use <h3>, <p>, <ul>, <li>, <strong>, and <br> where appropriate.
Do not return markdown.
Do not return a full HTML document.

Email content:

Compose prompt

Please rewrite this selected email-compose HTML fragment to be more professional and correct any spelling and grammar.
Preserve the intent.
Preserve the HTML structure, paragraph breaks, repeated line breaks, bullet or numbered lists, links, and inline formatting such as bold, italic, and colours where possible.
Return only the rewritten HTML fragment, with no markdown fences and no explanation.

HTML fragment:

AutoTag rules

Important: The email is urgent and requires action, can be an urgent or critical request or a failure notification, complaint or action.
To Do: A real person is directly asking me to do something, reply, confirm, or provide information
Appointment: The email specifically requests or sets an appointment for a meeting optionally with Teams, Zoom, Webex or Phone.

AutoTag prompt

You are an email triage assistant. Your default answer is NONE — most emails do not need a tag.

Only apply a tag when the email clearly matches one of these criteria. Reply NONE if none clearly fit.

{{tags}}

Do NOT tag: marketing, spam, sales pitches, unsolicited email, newsletters, automated notifications, or anything where no direct personal action or reply is needed.

Reply with ONE tag name exactly as listed, or the word NONE. Do not explain.

Email:

Inbox Digest prompt

You are an email triage assistant. Review the emails below and identify ONLY those that need attention.
Ignore routine successes, confirmations, newsletters, marketing, and automated notifications where nothing has gone wrong.

Flag emails in these categories only:
- Failures, errors, warnings, or alerts (systems, jobs, deployments, monitors)
- Requests for information, decisions, approvals, or replies from a real person
- Deadlines or time-sensitive items
- Anything marked urgent or high priority
- Anything that requires an action or response

For each flagged item give: sender, subject, and one sentence on why it needs attention.

If nothing in this folder requires attention, return exactly: <p>Nothing requiring your attention today.</p>

Return ONLY a clean HTML fragment.
Use <h3> for category headings, <ul> and <li> for items, <strong> for sender and subject.
Do not summarise every email.
Do not return markdown or a full HTML document.

Emails:

Search prompt

You are an email search assistant. The user has asked a question and the system has found potentially relevant emails from their mailbox.

Analyse the emails below and answer the user's question directly and confidently.
Lead with a clear, specific answer. If you can identify who, when, and what, state it plainly.

Then provide a table of the relevant emails as evidence.

Return ONLY a clean HTML fragment:
- Start with a <p> answering the question directly
- Follow with a <table> with columns: Date, From, Subject, Relevance (one sentence)
- Style the table with <thead> and <tbody>
- If no emails are relevant, say so clearly in a <p>

Do not return markdown. Do not return a full HTML document.

User question:
{{query}}

Relevant emails:
{{results}}

Each rule is one line: the Thunderbird tag name, a colon, and a plain-English description of when to apply it.

Important: The email is urgent or requires my immediate personal attention or decision
To Do: A real person is directly asking me to do something, reply, confirm, or provide information
Appointment: The email requests or confirms a specific meeting, call, or appointment

The tag name must match the Thunderbird tag exactly (same capitalisation). These descriptions are passed directly to the LLM as its criteria — write them as instructions to the model, not as labels.

• Be concrete, not abstract. "A real person is directly asking me to do something" works better than "requires action" — the latter is too broad and matches spam.
• Avoid "by name" qualifiers. Small local models do not reliably infer that they are acting as you. "Asking me personally" is sufficient.
• Describe what it IS, not just what it is not. Save exclusions for the prompt, not the rules.

The prompt controls how the LLM approaches the tagging decision. Use {{tags}} as a placeholder — GENA replaces it with the tag names and their criteria from your rules. Alternatively, use {{tag_rules}} to insert just the rules block in a location you control.

The most important things for reliable tagging:

• State that the default answer is NONE — most emails should not be tagged.
• Explicitly exclude marketing, spam, sales pitches, newsletters, and automated notifications.
• Ask for exactly ONE tag or NONE — asking for "up to three" causes small models to fill all available slots regardless of fit.
• Do not say "if in doubt, reply NONE" — small local models are always somewhat uncertain and will use this as a standing instruction to return NONE for anything borderline, including legitimate emails.

Recommended prompt (local/small models)

You are an email triage assistant. Your default answer is NONE — most emails do not need a tag.

Only apply a tag when the email clearly matches one of these criteria. Reply NONE if none clearly fit.

{{tags}}

Do NOT tag: marketing, spam, sales pitches, unsolicited email, newsletters, automated notifications, or anything where no direct personal action or reply is needed.

Reply with ONE tag name exactly as listed, or the word NONE. Do not explain.

Email:

Alternative prompt using {{tag_rules}}

If you want full control over the layout of the criteria block, use {{tag_rules}} instead. GENA inserts the rules in - Tag: criteria format at that position.

You are a strict email triage assistant. Your default answer is NONE.

Only apply a tag if the email clearly and specifically matches one of these rules:
{{tag_rules}}

Do NOT tag: automated notifications, newsletters, marketing, sales pitches, spam, or anything where no direct personal action is required. Reply with ONE tag name exactly as listed, or NONE. Do not explain.

Email:

Tips for large hosted models (GPT-4, Claude, etc.)

Larger models are better at following nuanced instructions and are less likely to over-tag. With a capable model you can use more detailed criteria and ask for up to two tags if useful. The recommended prompt above still works well, but you have more headroom.

Enable LLM Debug in settings, then run AutoTag. Each email produces a console entry like:

GENA AutoTag | Subject line here | tags: To Do    {prompt: "…", response: "…"}

The label shows the subject and the applied tag (or NONE) at a glance. Expand the object to see the exact prompt sent and the raw LLM response. This makes it easy to spot whether the model is seeing the right criteria and whether its response is being parsed correctly.

Common causes of wrong tags:

• Model returns all tags every time — your prompt says "up to three" or similar. Change it to ask for ONE tag only.
• Model returns NONE for obvious emails — your criteria are too restrictive, or your prompt has an unconditional "if in doubt, reply NONE" instruction. Soften the criteria and remove the "if in doubt" phrase.
• Model invents tag names — the LLM is not seeing the available tag list. Check that your prompt contains {{tags}} or {{tag_rules}} and that at least one rule is configured.
• Quoted reply content confuses the result — GENA strips standard Outlook-style reply separators and common quoted-message headers before sending. If your mail client uses an unusual format, check the debug prompt to see what the model actually received.

Semantic Search requires two external services:

• An embedding model — converts email text and search queries into numerical vectors that capture semantic meaning. Recommended: snowflake-arctic-embed2. GENA supports local Ollama (/api/embed) and any OpenAI-compatible embedding endpoint such as LiteLLM (/v1/embeddings), including those requiring a Bearer API key.
• Qdrant — a vector database that stores these embeddings and performs fast similarity searches across hundreds of thousands of emails.

Both services must be running and accessible from the machine running Thunderbird/Betterbird.

1. GENA iterates every account and folder in your mail client.
2. For each email, it reads the full body text, combines it with the subject, sender, recipients, and date, and generates an embedding vector.
3. The vector is stored in Qdrant along with metadata (subject, sender, date, folder) used for display and for locating the email in Thunderbird when you click a search result.
4. Each email is identified by a deterministic UUID derived from its RFC Message-ID header. This means two Thunderbird/Betterbird clients with the same email account share the same Qdrant collection — both can index and search without duplicating data.

Collection naming

Each email account gets its own Qdrant collection, named after the account's email address with @ replaced by _. For example, dave@example.com becomes collection dave_example.com.

Background indexing

When Auto-index on startup is enabled (the default), GENA runs a full background scan every time Thunderbird starts:

• New emails that are not yet in Qdrant are read, embedded, and added.
• Already-indexed emails are skipped.
• Deleted emails — vectors in Qdrant for emails that no longer exist in the mailbox are pruned automatically.

Additionally, new emails arriving via IMAP trigger immediate incremental indexing regardless of the auto-index setting.

The current indexing status is shown in the GENA launcher popup under the Semantic Search button. You can also manually trigger indexing using the Index Mailbox button in the Semantic Search window, with an option to index only the current account.

1. Your question is converted into an embedding vector using the same model.
2. Qdrant returns the most similar emails across all account collections.
3. The matching emails (with body snippets and metadata) are sent to the LLM along with your question using the configured search prompt.
4. The LLM analyses the evidence and returns a confident answer — for example, “Fred from WaterCo asked about purchasing water on 2025-03-15” — along with a table of supporting emails.
5. Clicking a row in the results table opens the email in Thunderbird by searching the mail index for the matching sender, subject, and date.

Search prompt

The search prompt controls how the LLM interprets and presents results. It uses two placeholders:

• {{query}} — replaced with the user's question
• {{results}} — replaced with the matching emails from Qdrant, including subject, sender, date, folder, and a body snippet for each

The default prompt asks for a direct, confident answer followed by an HTML evidence table. You can customise this in GENA Settings.

1. Install and start Qdrant (default port 6333).
2. Install and start Ollama with an embedding model: ollama pull snowflake-arctic-embed2
3. In GENA Settings, set the Qdrant URL and the Embedding endpoint URL (full URL, e.g. http://localhost:11434/api/embed).
4. Optionally set the Qdrant API Key and Embedding API key if your instances require authentication.
5. Restart Thunderbird or click Index Mailbox in the Semantic Search window to start the initial indexing.
6. The initial index of a large mailbox may take some time as it reads the body of every email. Subsequent starts only process new and deleted emails.

GENA logs debug information to the Thunderbird/Betterbird extension console. To access it:

1. In Thunderbird or Betterbird, open the menu and go to Tools → Developer Tools → Debug Add-ons (or press Ctrl+Shift+I on some builds, though the menu route is more reliable).
2. This opens the about:debugging page. Find GENA in the list of installed extensions.
3. Click the Inspect button next to GENA. This opens a developer tools window connected to GENA's background script.
4. Switch to the Console tab. All GENA debug output appears here.

To enable debug output, go to GENA Settings and tick LLM Debug. Once enabled, every LLM request and response is logged to this console, including the full prompt, the raw JSON response, and any errors.

If GENA is not working, the first step is always to confirm that the underlying services are reachable from the machine running Thunderbird. Open a terminal on that machine and run:

LLM (Ollama native)

curl http://localhost:11434/api/generate \
  -d '{"model":"llama3.1:8b","prompt":"Say hello.","stream":false}'

LLM (OpenAI-compatible)

curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.1:8b","messages":[{"role":"user","content":"Say hello."}],"stream":false}'

Embedding (Ollama)

curl http://localhost:11434/api/embed \
  -H "Content-Type: application/json" \
  -d '{"model":"snowflake-arctic-embed2","input":"test"}'

Embedding (LiteLLM / OpenAI-compatible)

curl https://your-litellm-host/v1/embeddings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model":"snowflake-arctic-embed2","input":"test"}'

Qdrant

curl http://localhost:6333/healthz
curl http://localhost:6333/collections

Replace localhost with the actual hostname or IP if your services run on a different machine. If any of these fail, fix the connectivity issue before trying to configure GENA — the extension uses the same HTTP calls internally.

Ollama's default CORS (Cross-Origin Resource Sharing) policy can block requests from browser-based extensions. Thunderbird extensions run in a browser-like environment, so CORS rules apply.

Symptoms: curl works perfectly, but GENA shows a network error or the extension console logs a CORS-related message such as Cross-Origin Request Blocked.

Fix: Set the OLLAMA_ORIGINS environment variable to allow all origins:

OLLAMA_ORIGINS="*" ollama serve

For a persistent fix on Linux with systemd:

sudo systemctl edit ollama

Add:

[Service]
Environment="OLLAMA_ORIGINS=*"

Then:

sudo systemctl daemon-reload
sudo systemctl restart ollama

For Docker, pass it as an environment variable:

docker run -d \
  --name ollama \
  -e OLLAMA_ORIGINS="*" \
  -p 11434:11434 \
  -v ollama_data:/root/.ollama \
  ollama/ollama

Or in your compose.yml:

services:
  ollama:
    image: ollama/ollama
    environment:
      - OLLAMA_ORIGINS=*
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama

• Ports not published: docker run does not expose ports by default. You must use -p 11434:11434 (Ollama) and -p 6333:6333 (Qdrant) to make the services reachable from outside the container.
• Port conflicts: If another service is already using port 11434 or 6333, Docker will fail to start the container. Check with lsof -i :11434 (macOS/Linux) or netstat -an | findstr 11434 (Windows) and stop the conflicting service, or remap the port (e.g. -p 11435:11434) and update your GENA settings accordingly.
• Binding to localhost only: By default, Docker publishes ports on 0.0.0.0 (all interfaces). If you want to restrict access to the local machine only, use -p 127.0.0.1:6333:6333.
• Firewall: On Linux, ufw or firewalld may block the published port even though Docker is running. Test from the Thunderbird machine with curl. If it works locally but not remotely, check your firewall rules.
• Container-to-container communication: If Ollama and Qdrant are both in Docker and you want them to talk to each other (not required by GENA, but useful for other tools), put them on the same Docker network or use the compose.yml approach shown in the Qdrant setup section.