Inside ThunderbirdAI: From Raw Email to a Grounded AI Answer

Suppose this message exists in a banking folder:

Subject: Debit Card transaction of INR 805 at Book Nook
From: Aster Bank Alerts <alerts@asterbank.test>
Date: 24 Aug 2026

INR 805.00 was debited from account ending 1842 at Book Nook.
Reference: TXN-HC-100005

Later, the user asks:

Find transaction TXN-HC-100005. Give me its amount and source message.

The desired answer looks small: INR 805.00 plus a link to the email. Producing it safely requires a chain of different jobs:

1. Read and interpret the message correctly.
2. Preserve where the readable body came from.
3. Extract useful fields without turning derived metadata into source truth.
4. Decide what text may remain local or cross an endpoint boundary.
5. Persist a canonical analysis record.
6. Build searchable child passages with parent-message identity.
7. freeze the user’s selected scope.
8. recognize the transaction ID as an exact constraint.
9. retrieve a bounded evidence card.
10. render it locally or let a configured model synthesize an answer.
11. map the citation back to the source message.

Each step has a different correctness condition. MIME parsing can fail while retrieval is perfect. Retrieval can succeed while synthesis invents a number. The final prose can be correct while its citation points to the wrong message. Calling the whole chain “the AI” makes those failures harder to locate.

An analysis request can originate from new mail, a folder or message change, a background backfill, a forced reanalysis, or a targeted refresh of one artifact such as summaries or embeddings.

Those requests enter a bounded queue. They are deduplicated by stable message identity, so the same message does not need parallel copies of the same job. An explicit user request can promote work that was already waiting as background work. Background work may be paused without making a force-reanalyse command meaningless.

Workers consume bounded batches:

queue
  → worker batch
  → per-message analysis
  → changed-row checkpoint
  → observer and UI update
  → next batch

This scheduling layer is not glamorous, but it determines whether a mail client stays usable while thousands of existing messages are analysed. Unlimited parallelism would fight for CPU, memory, storage, and any local model endpoint. A one-message-at-a-time design would make a large backfill unnecessarily slow. ThunderbirdAI exposes an effective worker limit and uses bounded checkpoints instead of treating concurrency as an accident of promises or threads.

“Local AI” can mean several different things. Rules and SQLite running inside Thunderbird are local. Ollama listening on 127.0.0.1 is also local to the machine, but it is still a separate process receiving a request. A public OpenAI-compatible endpoint crosses a different trust boundary again.

ThunderbirdAI therefore computes a policy decision before endpoint work. The record may contain separate representations:

localRawText    exact locally available analysis text
redactedText    text after policy-driven replacements
externalSafeText
                the bounded representation permitted for the chosen endpoint

Deterministic PII rules recognize forms such as email addresses, phone numbers, UPI IDs, PAN-like tokens, Aadhaar-like numbers, API keys, JWTs, and payment-card candidates. Shape matching alone is not enough for every type; card candidates, for example, receive a Luhn check. Policy can allow, redact, or block endpoint text according to sensitivity and destination.

The key boundary is not “did we use an LLM?” It is:

Which exact representation left Thunderbird, for which operation, under which permission?

Metadata-only traces should not preserve raw bodies, bearer tokens, API keys, or unredacted evidence. A loopback endpoint reduces network exposure, but it does not erase the boundary between the mail client and the model server.

ThunderbirdAI keeps two profile-local databases:

This distinction turns cache invalidation into an explicit contract. When a canonical record changes, the affected RAG rows become dirty. A small change can replace a few records and chunks. A schema mismatch, reset, or missed generation can request a lazy rebuild. An interrupted rebuild does not claim to be current until its covered generation commits.

Canonical storage uses changed-row transactions and SQLite write-ahead logging. Bulk analysis suppresses a save after every message and checkpoints after bounded counts, elapsed time, errors, or session completion. This replaced the much less attractive shape of repeatedly serializing one large JSON document while a mailbox was changing.

The architectural lesson is broader than SQLite:

Name the canonical state, name the derived state, and make rebuildability directional.

If both databases appear equally authoritative, recovery becomes guesswork.

The Assistant supports scopes such as selected messages, the current folder, an account, or All Mail. Scope is not a helpful hint to the model. It is a data-access boundary enforced before candidate ranking.

If the user selects five office messages and asks for banking transaction TXN-HC-100005, the correct pipeline is:

five selected message identities
  → zero in-scope transaction matches
  → no banking evidence card
  → not found or insufficient evidence

It must not silently search All Mail because that would produce a more satisfying answer. Relevance cannot grant access. Reranking cannot grant access. A tool request emitted by a model cannot grant access. The user may choose a wider scope and submit a new turn; the current turn remains bound to the scope with which it began.

This is one of the most reusable lessons from the project. Authorization belongs outside the probabilistic layer. The best-ranked forbidden record is still forbidden.

After retrieval, ThunderbirdAI can take two routes.

With Direct RAG on:

scope → local retrieval → evidence cards → deterministic rendering

No answer model is called. This is useful for exact lookups, auditing, and diagnosing whether retrieval itself works. The output may be less conversational, but endpoint synthesis cannot alter it.

With Direct RAG off:

scope → local retrieval → bounded evidence cards
      → policy-safe endpoint request → citation URI mapping → rendered answer

The endpoint sees a small evidence pack, not a Thunderbird profile or an open mailbox handle. Email bodies remain untrusted data even if they contain imperative text such as “ignore prior instructions.” The model is asked to answer from supplied evidence and acknowledge absent facts.

Citation mapping checks whether emitted source identifiers correspond to retrieved records. That is valuable, but it is not an independent fact verifier. A mapped citation can still fail to support a particular sentence. The current pipeline does not hide a second model judge or claim that every answer has passed a repair loop. Debug output should say what happened rather than upgrading citation plumbing into a stronger guarantee.

We can now replay the small question from the beginning.

Now change one condition at a time:

• If the banking message is outside a Selected Messages scope, it is not retrieved.
• If the RAG index is stale, the canonical store can drive a rebuild.
• If the optional summary endpoint fails, local analysis can still complete.
• If Direct RAG is enabled, answer synthesis does not contact the endpoint.
• If the exact identifier is absent, the result should preserve that uncertainty.
• If a citation ID does not map to retrieved evidence, it must not become an openable source.

This is why end-to-end tests are more informative than asking whether “the model works.” The same final symptom can originate in parsing, policy, persistence, indexing, scope, planning, ranking, packing, synthesis, or citation mapping.

The public bundle is designed to reproduce a patched Thunderbird tree from pinned Gecko and comm revisions rather than uploading two enormous upstream working trees. It contains patches, overlays for new files, deletion manifests, hashes, a tested mozconfig, and scripts that verify and apply the export.

The exported state reports a successful Thunderbird build on 6 September 2026 with Python 3.12 and zero compiler warnings. Its GitHub bundle-validation workflow also completed successfully. Those facts establish that the exported bundle verifies and that the reconstructed source compiled in the recorded environment. They do not establish production security, perfect mail compatibility, or model quality for every inbox.

The repository keeps the evidence boundaries visible:

• Building from source describes the pinned reconstruction and build.
• Testing and smoke checks separates bundle validation, compilation, smoke testing, and focused suites.
• AI Mail Pipeline: Deep Dive provides the source-level pipeline reference behind this article.
• Pipeline and Evaluation Reference records guarantees, evaluation entry points, and outstanding evidence.

An experiment is more trustworthy when its negative space is documented. “Built successfully” is a build claim. “Retrieved the right message in this frozen corpus” is an evaluation claim. Neither should quietly become “safe and correct for all mail.”

ThunderbirdAI first makes a message locally searchable and auditable. It stores canonical AI records separately from its disposable retrieval index. When a question arrives, Thunderbird freezes the user’s scope, plans exact and semantic retrieval inside that boundary, and packs a small evidence set.

Direct RAG renders that evidence locally. Synthesized RAG sends only permitted, bounded evidence to the configured endpoint. An exhaustive digest is a separate, explicit and checkpointed workflow whose coverage is reported. In every route, the parent email remains the source that the user can inspect.

The result is less mysterious than “an AI that knows your inbox,” and that is a feature. A mailbox assistant should be explainable as a sequence of bounded transformations:

mail
  → canonical local record
  → rebuildable evidence index
  → frozen scope
  → exact and semantic retrieval
  → bounded evidence
  → local rendering or optional synthesis
  → source-linked answer

Once those boundaries are explicit, model improvements become upgrades to particular stages rather than excuses to blur the whole system.