Download Latest Version ETE_V2.7z (374.4 kB)
Home
Name Modified Size InfoDownloads / Week
OVERVIEW_en.md 2026-11-14 5.8 kB
QA.md 2026-11-14 20.3 kB
README.md 2026-11-14 24.1 kB
USER_MANUAL_CS.md 2026-11-14 28.7 kB
USER_MANUAL_EN.md 2026-11-14 27.5 kB
USER_MANUAL_RU.md 2026-11-14 49.2 kB
ETE_V2.7z 2026-11-14 374.4 kB
Totals: 7 Items   529.8 kB 5

ETE: e-mails to events, tasks, notes and reply drafts

ETE reads e-mail accounts (IMAP, Gmail, Outlook) and lets a language model find appointments, tasks and information worth keeping. It writes them into calendars, task lists and notebooks (CalDAV, Google, Microsoft 365) and prepares a reply draft.

  • The model only analyses text and returns structured output. The application code decides what is written where.
  • ETE never sends e-mail. A reply is only saved as a draft (IMAP Drafts folder, Graph draft, Gmail draft). The user sends it from their own mail client.
  • The model can run in LM Studio on the user's own computer, so e-mails never have to leave it. OpenAI, Anthropic and Google models can be used as well.
  • Passwords, the OAuth client secret, OAuth sign-ins and API keys are stored in the system keyring, never in the configuration files.

Documentation

Document Content
README.md this file: installation, configuration, processing, limits
FILE_STRUCTURE.md folders and files of the project, configuration files field by field, runtime files
FILES_AND_FUNCTIONS.md every Python file with its constants, classes, methods and functions (generated from the source)
QA.md questions and answers: Google and Microsoft account setup, LM Studio, problems and their solutions
DESIGN.md design document: architecture, technical decisions and their reasons
OVERVIEW_en.md, OVERVIEW_cs.md, OVERVIEW_ru.md introduction of the application for new users
NAVOD_cs.md user guide in Czech
changes_debug.md, test_windows.md working lists of the debug phase (Czech)

Installation and start

Linux

Requirements: python3 with the venv module. ETE was tested with Python 3.13.

compile.sh always creates the environment venv_linux from scratch (--clear). An existing venv_linux is emptied first, so a damaged environment is repaired as well.

cd /path/to/ETE
# ⚠️ DESTRUCTIVE: empties and recreates venv_linux
sh compile.sh
sh run.sh

One processing run without the GUI (the schedule starts the same script):

sh /path/to/ETE/ghost_run.sh

ghost_run.sh returns 0 when the run finished without errors and 1 after an error. Details are in ete.log.

files/GUI.py cannot be started on its own. The button handlers are connected by main.py, so always start run.sh or venv_linux/bin/python main.py.

Windows (not tested)

Commands for the command prompt in the project folder:

cd C:\Users\user\ETE
py -m venv venv_windows
venv_windows\Scripts\python -m pip install -r requirements.txt
venv_windows\Scripts\python main.py

One processing run without the GUI:

venv_windows\Scripts\python main.py --no-gui

Command line

Command Effect
main.py starts the GUI
main.py --no-gui processes all enabled e-mail accounts once and exits
main.py --no-gui --once the same, then removes the schedule (used by the one-time schedule)

First configuration in the GUI

Every form field has an "i" icon before its label. It shows the help: what the field is for, whether it is required and what an empty value means, where to find the value, an example (prompts have none) and the internal parameter name. Warnings in the help are bold red. Fields that have no meaning for the selected account type or provider are greyed out. The width of the page list and of the profile list can be changed by dragging; the widths are not remembered.

Form changes are saved with the green Save button. Secrets have their own fields with the Store and Delete buttons and go directly into the keyring; they are never written to the CSV files. An action button (test, choose, sign in) works with the values in the form; when there are unsaved changes, ETE first offers to save them (Save, Ignore = continue without saving, Cancel).

The status bar shows background operations. The Cancel operations button at the bottom left offers to stop all or selected operations. A cancelled operation stops at the nearest safe point (between e-mails, before an e-mail is sent to the model, while waiting); an e-mail in progress is always finished. When the window is closed during an operation, ETE offers to quit the whole application or to stop selected operations only. An operation still running 5 seconds after quitting is abandoned.

On Linux, ETE uses the desktop file dialogs (KDE, GNOME) through xdg-desktop-portal when the portal is installed; a path can be typed or pasted there. Windows uses the system dialog.

  1. APP settings: language, theme (system follows the operating system, light, dark), font and window size, running in the background in the system tray, notifications and log level. A new language applies after the application is restarted.
  2. E-mail accounts: one profile per account.
  3. IMAP, example Seznam.cz: IMAP server imap.seznam.cz, port 993, login name = the whole e-mail address, the password is typed into "IMAP password" and stored with Store.
  4. The Drafts and Trash folders may stay empty. ETE then uses the folders the server marks as Drafts and Trash (RFC 6154). "Choose folder" lists the folders of the account; there is one such button before every folder field (read folder, move target, drafts, trash).
  5. Outlook: fill in the OAuth client ID of the app registration in Microsoft Entra ID and the tenant (common, consumers, organizations or the organization ID), then Sign in opens the sign-in in the web browser.
  6. Gmail: fill in the OAuth client ID and client secret of a "Desktop app" client from Google Cloud Console (the secret with Store), then Sign in. Until Google verifies the application, only test users entered in the OAuth consent screen can sign in. Google Keep works only with Google Workspace accounts.
  7. Step-by-step registration of both is in QA.md.
  8. Sign out deletes the stored sign-in. One sign-in covers e-mail, calendar, tasks and notes of the account.
  9. "After processing" decides what happens to a processed e-mail: keep, archive, delete (to trash), delete_permanent (permanently, irreversible) or move (to the given folder).
  10. "Without journal" is the recommended setting for a large mailbox, see Journal of processed e-mails.
  11. Check calendars of this account (Gmail, Outlook) lists the calendars, task lists and notebooks of the account (for Gmail also Google Keep when Keep access is on). The checked ones are created as new disabled targets; they are checked, enabled and saved on the Calendars and Notes and tasks pages. For an IMAP account the calendar is added manually as a CalDAV target.
  12. Calendars and Notes and tasks: targets for events, tasks and notes.
  13. CalDAV: server URL, login name and password (Store).
  14. Google and Microsoft: a reference to the e-mail account whose sign-in is used; only signed-in accounts of the same type are offered.
  15. The time zone is chosen from the system list (IANA names).
  16. The "Choose …" buttons list the calendars, task lists and notebooks on the server; "Test connection" checks the connection.
  17. Output routing: categories with a multi-line description for the model and with a target calendar, task list, notebook and an account for the reply draft. "Add from template" offers ready categories (personal, work, school, finance, family).
  18. AI services and models:
  19. provider lms (LM Studio), openai, anthropic or google;
  20. model ("Choose model" lists the available models);
  21. model parameters and the context range of the second pass;
  22. for LM Studio the server host and port (default localhost:1234), optionally the path to the lms program and the API token (Store) when authentication is on in LM Studio;
  23. for cloud providers the API key (Store).
  24. Prompts: instructions for the model. A prompt can have several lines. An empty prompt means the default prompt from config/prompt_default.csv; "Restore default" shows it for editing. "Test on sample" tries the prompt on a sample, which is pre-filled from config/test_prompts_examples.csv.
  25. Autoresponse: reply draft profiles: account, category, prompt, style, language, signature, name and gender of the writer. The language is free text (for example English, Deutsch, cs); a checked "auto" means the language of the e-mail.
  26. Automation: schedule of regular processing (see Scheduled runs), retry count, retry delay and request timeout.
  27. Hardware: detection of the processor, memory and graphics cards and a speed test of the selected model (tokens per second for LM Studio, response time for cloud models).
  28. Diagnostics and logs: tests of all connections and of the model, last errors and export of diagnostics. Passwords and keys are never shown.

The Overview page shows the state and starts processing manually. The Manual input page processes pasted text as the body of an e-mail; no reply draft is made and no post action is done.

Processing

A run goes through all enabled e-mail accounts and processes the e-mails in the read folder of each account that are not yet in processed_emails.csv (for an account without journal: all e-mails in the folder). Only one run can work at a time; a second one (from the GUI or the schedule) ends with the error "Processing is already running".

  1. Attachments: converted to text and at most 4 images (PDF, DOCX, ODT, DOC, HTML, text files and images). DOC is converted through LibreOffice when it is installed, otherwise its text is read with olefile. An unreadable attachment never stops the run: the model gets a note in the text and the user a warning (a message box in the GUI, a log entry without the GUI). Images are sent to the model only when the model is marked as able to process images.
  2. First pass (prompt main): the model returns events, tasks and notes. Every item has its own category, and the whole e-mail has one more category for the reply draft. An invalid answer is retried like a failed request. After the first pass the e-mail is written to processed_emails.csv (not for an account without journal).
  3. Routing: the category of an item decides its target.
  4. Without a category, or when the category names no target of that kind, the first enabled target of that kind is used.
  5. When the category names a target that is disabled or does not exist, the item is skipped with a warning.
  6. Second pass (prompts calendar, todo, note): the item is compared with the existing items of the target and the model decides create, update (with the uid of an existing item) or skip. "Context of the check" sets what is compared:
  7. single (also empty): no existing items;
  8. date: events of the same day and open tasks due on the same day;
  9. all: events of the same day, all open tasks of the list and all notes of the notebook.

An empty prompt means the default from config/prompt_default.csv. When the model returns update with a uid that was not among the offered items, the item is created as new.

  1. Writing and update rules:
  2. Events and tasks: only the fields ETE fills in are changed (title, description, location, start, end, due date, priority, reminder). An empty value from the model never deletes an existing value. Attendees, recurrence, attachments and subtasks stay unchanged.
  3. An event with attendees is never changed, because the change could send notifications to the attendees. A new short event "title (update)" with the new time is created instead; its description refers to the original event.
  4. Notes: the new text is appended to the end of the note with today's date; nothing is deleted. OneNote appends the text to the end of the first block of the page. Google Keep cannot change a note: a new note with the appended text is created and the original is deleted. A Keep checklist gets the text as a new item; a Keep note with attachments is not changed.
  5. A whole-day event gets its end according to iCalendar (the day after the last day). A timed event without an end lasts the default duration of the calendar.
  6. An error of one item does not stop the other items. It is logged and the user gets a warning.
  7. Reply draft: the category of the whole e-mail selects the account for the draft (the reply account of the category, otherwise the account the e-mail came to).
  8. The first enabled Autoresponse profile whose account and category match is used (an empty field means any).
  9. The name and gender of the writer are taken from the e-mail account when they are empty in the profile.
  10. An empty language means the language of the e-mail.
  11. In the account the e-mail came to, the draft joins the conversation of the original e-mail. In another account, a separate draft addressed to the sender is created.
  12. Post action: according to "After processing" of the account. With the journal, the action is also applied to e-mails processed earlier that are still in the folder, so it is repeated after an earlier error. Without the journal, it is applied only to e-mails processed without any error.

Reading an account and the first pass are retried on errors according to "Retries on failure" and "Delay between retries (s)" on the Automation page. An e-mail whose first pass fails is not written to processed_emails.csv and is processed again in the next run.

The key of an e-mail in processed_emails.csv is account name;Message-ID; the UID is used for an e-mail without Message-ID.

Journal of processed e-mails

  • With the journal (default): ETE writes processed e-mails to processed_emails.csv. E-mails in the journal are not downloaded again; only their Message-ID is read and they get the post action again. Each run still has to wait for the list of all e-mails in the folder, which is slow for a large folder (for example the Inbox).
  • Without the journal ("Without journal"): ETE processes every e-mail in the folder and applies the post action after successful processing. Turning it on selects the action delete_permanent. An e-mail whose processing failed stays in the folder and is processed again in the next run.
  • Recommended setup: create a folder in the mailbox (for example ETE) and a rule that copies all incoming e-mails into it. In ETE choose this folder for reading, "Without journal" and delete_permanent. The originals in the Inbox stay unchanged.
  • Warning: the copy rule must be created by the user in the mailbox settings. Never choose the Inbox for reading together with a deleting action; the processed e-mails would be deleted from it irreversibly.

LM Studio

  • When the LM Studio server does not answer on the given host and port and the host is localhost, 127.0.0.1 or ::1, ETE starts it with lms server start. "Choose model" and "Test backend" ask before they start the server or load a model.
  • After the start ETE waits at most 60 s (LMS_STARTUP_TIMEOUT) for the server to answer. A server that does not answer in time during its start counts as not running, and ETE keeps waiting. When it does not answer within the limit, ETE reports that the server did not start.
  • The lms program is looked for in "Path to lms (LM Studio CLI)", then in PATH and in ~/.lmstudio/bin (Windows %USERPROFILE%\.lmstudio\bin). When it is not found, ETE on Linux offers to search the whole computer (find, can be cancelled) and stores the chosen path in "Path to lms (LM Studio CLI)". The search can also be started any time with "Find lms" in the row of "Path to lms (LM Studio CLI)".
  • API token authentication (LM Studio 0.4.0 and newer, Developer > Server Settings, "Require authentication", token from "Manage Tokens"): the token is typed into the API key field and stored with Store. ETE passes it to the lmstudio SDK 1.6.0b1 and to the requests to /api/v1/chat (header Authorization: Bearer). Without a stored token nothing is passed. Authentication does not work with older LM Studio versions.
  • A remote server (also over LM Link) must already run and allow network access in the LM Studio settings.
  • The model is loaded with the configured context length and GPU options. Model reasoning is removed from the answer.
  • The model is unloaded when the application quits and after a run without the GUI.

Secrets

  • The secret storage is files/secret_store.py; the keyring service is named ETE.
  • A secret is stored under the profile name and a key name:
  • e-mail: email_password, oauth_client_secret and the Outlook (msal_token_cache) or Gmail (google_credentials) sign-in;
  • calendars: calendar_password;
  • tasks: todo_password;
  • notes: notes_password.

Profiles of different kinds with the same name therefore do not share a password.

  • The profile name of e-mail, calendar, task and notes profiles is converted: trimmed, diacritics removed and spaces between words replaced by one underscore (Jan Píša → Jan_Pisa). The converted name is shown after editing of the field ends, and it is stored in the configuration and used as the keyring key. Characters without a diacritic decomposition (for example ł, ß) stay. Names saved earlier are converted only when the field is edited.
  • Two profiles of the same kind must not have the same name; Save refuses such a configuration.
  • Every value is stored in the keyring encoded in Base64 with the prefix ETE-B64:, because the KDE keyring (SecretService) returned a value containing a backslash as empty in a new process. Base64 is not encryption; the keyring provides the protection. Long values are split into parts (ETE-CHUNKS:). Values stored by an older ETE version (without the prefix) are reported as not stored and have to be entered again. An empty value is also reported as not stored.
  • API keys of cloud providers and the LM Studio token are stored under the name engine with the key api_key_<provider> (LM Studio api_key_lms). Without a stored key, the provider library uses its environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or GOOGLE_API_KEY).
  • When a profile is renamed, its secrets are moved to the new name after Save (a missing or empty secret is not moved). When a profile is removed, its secrets are deleted from the keyring after Save.
  • SECRET_BACKEND = "keyring" in files/secret_store.py must stay in production. The value "csv" stores secrets in config/secrets.csv and is meant for debugging only. While debugging, a password written directly into the password field of the account CSV is read as well.

Scheduled runs

The schedule is set on the Automation page:

  • Write schedule first shows the current ETE entry and the entry that will be written, and after confirmation writes it and checks it.
  • Remove schedule removes the schedule after confirmation.
  • Show schedule shows the current entry.

Disabled automation or an empty start time means that the schedule is removed.

Frequency Start
hourly every hour at the minute of the given time
daily every day at the given time
weekly every Monday at the given time
monthly on the 1st day of every month at the given time
once once, at the nearest occurrence of the given time
  • Linux: one line in the crontab of the logged-in user, marked with the comment # ETE-schedule. The other crontab entries stay unchanged and no duplicate ETE entry is created. The line starts ghost_run.sh and sets DBUS_SESSION_BUS_ADDRESS, so that the run can read the keyring and show a notification (notify-send). With once the run removes its entry when it ends.
  • Windows (not tested): the task ETE in Task Scheduler, which starts main.py --no-gui with the same Python the application runs with.

Languages

  • GUI texts are in files/locales/<code>.json (en, cs, de, es, fr, pl, ru). The default and fallback language is English: a text missing in another language is taken from en.json.
  • The translations into de, es, fr, pl and ru should be checked by native speakers.
  • The log is always in English. Error details returned by services stay in English.

Configuration files

Every configuration class has its own file in config/. One line is one profile, fields are separated by ;, the file is UTF-8 without a header. The fields of every file are listed in FILE_STRUCTURE.md.

File Fields
ConfigAutomation.csv 8
ConfigUI.csv 9
ConfigEngine.csv 16
ConfigAutoresponse.csv 9
RoutingCategory.csv 6
EmailAccount.csv 20
CalendarAccount.csv 11
TODOAccount.csv 10
NotesAccount.csv 9
Prompt.csv 5
  • Prompts, the Autoresponse prompt and signature and the routing category description can have several lines and contain ;. In the file they are encoded: \n is a line break, \s a semicolon and \\ a backslash.
  • The delivered Prompt.csv contains the prompts in the same wording as the defaults; the other configuration files are empty.
  • prompt_default.csv and test_prompts_examples.csv have lines name;encoded text (names main, calendar, todo, note, custom, autoresponse). They are not configuration classes and the GUI does not change them.
  • Configuration from older versions is not converted. Older files have to be created again in the GUI. A file with a different number of fields is not loaded (error "expected N fields") and the GUI then refuses to save, so that the valid files are not overwritten with empty content.

Known limitations

  • Tests on Windows are listed separately in DOC/test_windows.md.
  • Not tested:
  • Windows;
  • real Microsoft Graph and Google servers;
  • real IMAP servers other than the connection test to Seznam.cz;
  • DOC conversion through LibreOffice;
  • the run lock on Windows (msvcrt.locking).

Tested: desktop file dialogs through xdg-desktop-portal in KDE, the LM Studio API token against LM Studio 0.4 and the Seznam.cz folders (verified by John), the GUI in English, Czech, Russian, French and Polish, completeness of all seven translations, the whole flow with a stand-in model against a CalDAV server (Radicale), processing with and without the journal, the run lock and cancelling on Linux, the lms search, writing the schedule to cron, the shape of the requests to cloud models and the run without the GUI.

  • The "Time limit of a request (s)" on the Automation page applies to one request to a cloud model. Requests to LM Studio through the SDK have no time limit.
  • "After processing" and "Move to folder" on the Automation page are not used; the settings of each e-mail account apply.
  • "Open app when scheduler starts" has no effect yet. "Keep running in background" means that closing the window only hides the application into the system tray.
  • The fields model_path, model_ability_reasoning and model_ability_tools of ConfigEngine are not used. The processing never asks for a reasoning level, so generate_lms always uses the SDK path with an enforced JSON schema.
  • The task and note category of a target is free text and is not checked against the categories of the service.
  • After a profile is renamed, the secret state shows "not stored" until the change is saved with Save.
  • The GUI always runs one operation at a time. The dialog for stopping operations therefore lists one running operation and possibly cancelled operations that are still stopping.
  • Gmail: for an account with the journal, the Message-ID of every e-mail in the folder is read with a separate metadata request (without downloading the content).

License

ETE is free software under the GNU General Public License version 3 or (at your option) any later version (GPL-3.0-or-later). The full text is in the file LICENSE. The components used and their licenses are listed on the About page.

Source: README.md, updated 2026-11-14