028 Agents 935be579

Supervertaler - AI Agent Documentation (Compact)

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

⚡ 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.241
• Main app: Supervertaler.py (large monolithic PyQt6 file)
• Latest major completed work:
  • 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/
• Tests: tests/
• Changelog: CHANGELOG.md
• Version source: pyproject.toml
• Website version mention: docs/index.html
• Unified settings: settings/settings.json
• 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).

🔌 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. Keep unified settings and migration stable.
2. Continue reducing monolith pressure in Supervertaler.py.
3. Maintain release reliability (PyPI + Windows core/full artifacts).
4. 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.