![logo](/resources/img/full-logo-white.png)

# Sortana

Sortana is an experimental Thunderbird add-on that integrates an AI-powered filter rule. 
It allows you to classify email messages by sending their contents to a configurable
HTTP endpoint. The endpoint should respond with JSON indicating whether the
message meets a specified criterion.

## Features

- **AI classification rule** – adds the "AI classification" term with
  `matches` and `doesn't match` operators.
- **Configurable endpoint** – set the classification service URL on the options page.
- **Prompt templates** – choose between several model formats or provide your own custom template.
- **Custom system prompts** – tailor the instructions sent to the model for more precise results.
- **Filter editor integration** – patches Thunderbird's filter editor to accept
  text criteria for AI classification.
- **Persistent result caching** – classification results are saved to disk so messages aren't re-evaluated across restarts.
- **Advanced parameters** – tune generation settings like temperature, top‑p and more from the options page.
- **Debug logging** – optional colorized logs help troubleshoot interactions with the AI service.
- **Automatic rules** – create rules that tag or move new messages based on AI classification.
- **Packaging script** – `build-xpi.ps1` builds an XPI ready for installation.

## Architecture Overview

The extension relies on both WebExtension scripts and Thunderbird's experiment
APIs:

- `background.js` loads the saved endpoint, registers the UI patching script,
  and listens for test messages.
- `experiment/api.js` exposes the `aiFilter` namespace. It loads
  `modules/ExpressionSearchFilter.jsm` which implements the custom filter term
  and performs the HTTP request.
- `experiment/DomContentScript/` registers content scripts for Thunderbird
  windows; `content/filterEditor.js` modifies the filter editor UI.
- `options/` contains the HTML and JavaScript for the options page.
- `_locales/` holds localized strings used throughout the UI.

### Key Files

| Path                                    | Purpose                                        |
| --------------------------------------- | ---------------------------------------------- |
| `manifest.json`                         | Extension manifest and entry points.           |
| `background.js`                         | Startup tasks and message handling.            |
| `modules/ExpressionSearchFilter.jsm`    | Custom filter term and AI request logic.       |
| `experiment/api.js`                     | Bridges WebExtension code with privileged APIs.|
| `content/filterEditor.js`               | Patches the filter editor interface.           |
| `options/options.html` and `options.js` | Endpoint and rule configuration UI. |
| `logger.js` and `modules/logger.jsm`    | Colorized logging with optional debug mode.    |

## Building

1. Ensure PowerShell is available (for Windows) or adapt the script for other
   environments.
2. Run `powershell ./build-xpi.ps1` from the repository root. The script reads
the version from `manifest.json` and creates an XPI in the `release` folder.
3. Install the generated XPI in Thunderbird via the Add-ons Manager. During
   development you can also load the directory as a temporary add-on.

## Usage

1. Open the add-on's options and set the URL of your classification service.
2. Create or edit a filter in Thunderbird and choose the **AI classification**
   term. Enter the desired criterion (for example, a short description of the
   messages you want to match).
3. When the filter runs, the add-on sends the message text to the service and
   checks the JSON response for a match.

### Example Filters

Here are some useful and fun example criteria you can use in your filters. Filters should be able to be answered as either `true` or `false`.

- **"Does this message require my attention, response, or decision soon?"**  
  Identify emails with deadlines, requests, or actionable items.

- **"Is this message spam, phishing, or irrelevant bulk mail?"**  
  Catch low-value or deceptive messages and sweep them into the junk folder.

- **"Is this email promotional, advertising a product or service, or part of a mass mailing?"**  
  Great for filtering out newsletters, deals, and marketing campaigns.

- **"Is this a personal message from a friend or family member?"**  
  Keep emotionally meaningful or social emails from getting lost.

- **"Is this message a receipt, invoice, or shipping notification?"**  
  Automatically tag or file transactional messages for easy lookup.

- **"Does this message relate to one of my current work projects?"**  
  Focus your inbox around what matters right now.

- **"Would I roll my eyes reading this email?"**  
  For when you're ready to filter based on vibes.

You can define as many filters as you'd like, each using a different prompt and triggering tags, moves, or actions based on the model's classification.

## License

This project is licensed under the terms of the GNU General Public License
version 3. See `LICENSE` for the full text.

## Acknowledgments

Sortana builds upon knowledge gained from open-source projects. In particular,
[FiltaQuilla](https://github.com/RealRaven2000/FiltaQuilla) and
[Expression-Search-NG](https://github.com/opto/expression-search-NG) clarified
how Thunderbird's WebExtension and experiment APIs can be extended. Their code
provided invaluable guidance during development.