Supervertaler - AI Agent Documentation (Compact)

Supervertaler - AI Agent Documentation (Compact)

Purpose: Fast, reliable handoff when context is low or chats reset. Last Updated: February 9, 2026 | Version: v1.9.246

⚡ 60-Second Resume Checklist

1. Read CHANGELOG.md top entry (latest release context).
2. Check git status --short (do not revert unrelated user changes).
3. Confirm version in pyproject.toml.
4. Confirm unified settings in settings/settings.json.
5. If deeper context is needed, open:
   • docs/agent-archive/AGENTS_FULL_REFERENCE_v1.9.240_2026-02-08.md

🎯 Current State

• Current version: v1.9.246
• Main app: Supervertaler.py (large monolithic PyQt6 file)
• Latest major completed work:
  • Cross-platform support: macOS/Linux via modules/platform_helpers.py (v1.9.246)
  • Native global hotkey system replacing AHK-only approach (v1.9.246)
  • Unified settings system in settings/settings.json
  • Inline API key editing in Settings UI
  • One-time migration from legacy settings files (.migrated)
  • Custom OpenAI-compatible provider (custom_openai)

📁 Key Paths (Source of Truth)

• Main app: Supervertaler.py
• Modules: modules/
• Platform helpers: modules/platform_helpers.py
• Tests: tests/
• Changelog: CHANGELOG.md
• Version source: pyproject.toml
• Dependencies: requirements.txt (includes pynput>=1.7.6)
• Website version mention: docs/index.html
• Unified settings: settings/settings.json
• AHK hotkey script (Windows fallback): supervertaler_hotkeys.ahk
• Archived full agent reference:
  • docs/agent-archive/AGENTS_FULL_REFERENCE_v1.9.240_2026-02-08.md

🏗️ Settings Architecture (v1.9.240+)

Primary config:

• settings/settings.json

Top-level sections:

• api_keys
• general
• ui
• features

Satellite files under settings/:

• themes.json
• shortcuts.json
• recent_projects.json
• find_replace_history.json
• superlookup_history.json
• voice_commands.json
• model_version_cache.json

Migration behavior:

• Legacy settings files are migrated at startup and renamed to .migrated.

🔑 API Keys

Primary storage:

• settings/settings.json under api_keys

Compatibility:

• Legacy api_keys.txt remains supported as fallback input.

Common key names:

• openai, claude, google, gemini, custom_openai, deepl, google_translate, ollama_endpoint

Notes:

• google and gemini are aliases.
• custom_openai supports OpenAI-compatible endpoints (endpoint/model configured in Settings > AI Settings).

🌐 Cross-Platform Architecture (v1.9.246+)

Central module: modules/platform_helpers.py

Constants:

• IS_WINDOWS, IS_MACOS, IS_LINUX

Utilities:

• open_file(path) / open_folder(path) — replaces os.startfile()
• get_hidden_subprocess_flags() — CREATE_NO_WINDOW on Windows, empty dict elsewhere

Global hotkeys (GlobalHotkeyManager):

• Windows: RegisterHotKey API (background thread with GetMessageW loop)
• macOS/Linux: pynput GlobalHotKeys (requires Accessibility permission on macOS)
• Callbacks do zero work in the background thread — only signal Qt main thread via QMetaObject.invokeMethod
• Main thread handles: send Cmd/Ctrl+C → wait 250ms → read clipboard → dispatch

Keystroke injection (CrossPlatformKeySender):

• Windows: AHK subprocess (Send "^c" via temp .ahk file), PowerShell SendKeys fallback
• macOS: osascript (tell application "System Events" to keystroke "c" using command down)
• Linux: pynput Controller

Hotkey callback flow:

pynput/WinAPI thread → QMetaObject.invokeMethod (QueuedConnection)
  → @pyqtSlot _handle_superlookup_hotkey (main thread)
    → CrossPlatformKeySender.send_copy()
    → QTimer.singleShot(250ms) → read clipboard → on_ahk_capture(text)

🍎 macOS Hotkey Status — Pending Fixes

Working:

• pynput GlobalHotKeys registers successfully (shows "Active via PYNPUT")
• Accessibility permission grant flow works
• Crash fixed (was caused by doing pyperclip/pynput work in background thread)

Known issues:

1. osascript Cmd+C deletes selected text in source app (likely stray modifier keys from hotkey)
2. Cmd+C doesn't actually copy selections — only reads existing clipboard content
3. Reliability: sometimes works, sometimes doesn't

Planned fixes:

• Debug osascript keystroke injection (may need modifier release delay before sending)
• Consider using pbcopy via AppleScript instead of keystroke simulation
• Change macOS shortcuts: ⌃⌥L/M → ⌃⌘L/M (Ctrl+Cmd, user-requested — easier to reach)

🔌 LLM Providers

Supported providers:

• openai
• claude
• gemini
• ollama
• custom_openai

Relevant implementation files:

• modules/llm_clients.py
• Supervertaler.py (settings UI and provider wiring)

🧪 Testing Quick Start

Run:

pytest tests/

Manual smoke test checklist:

• Import DOCX, translate, export
• Save/load .svproj
• TM and termbase behavior
• AI translation with configured keys
• SDLPPX round-trip

📦 Release Checklist

1. Update version in pyproject.toml.
2. Update release notes in CHANGELOG.md.
3. Update version mention in docs/index.html.
4. Validate main workflows.
5. Build and upload:

python -m build
python -m twine upload dist/supervertaler-<version>*

Windows EXE packaging:

• build_windows_release.ps1 (core/full)

⚠️ High-Value Pitfalls

1. Supervertaler.py is large: read/edit by line range, not full-file stream.
2. Qt table access: use cellWidget() for editors and item() for plain items.
3. Block signals during programmatic text updates to avoid cascades.
4. Style issues can be timing-related (hidden widgets, deferred visibility).
5. XML namespace formats (SDLXLIFF): always use namespace dicts.

📌 Active Priorities

1. Fix macOS global hotkey Cmd+C issues (deletes selection, doesn't copy).
2. Make macOS shortcuts configurable (⌃⌘L/M instead of ⌃⌥L/M).
3. Test Linux global hotkeys (pynput backend, untested).
4. Keep unified settings and migration stable.
5. Continue reducing monolith pressure in Supervertaler.py.
6. Maintain release reliability (PyPI + Windows core/full artifacts).
7. Keep this file short and operationally focused.

📚 Archived Reference

The full historical/long-form agent document is preserved at:

• docs/agent-archive/AGENTS_FULL_REFERENCE_v1.9.240_2026-02-08.md

When context is limited, use this compact file first and open the archive only when needed.