{html_escape(tb)}"
+
+ # Colour scheme
+ if dark_mode:
+ bg_color = "#1e1e1e"
+ fg_color = "#dcdcdc"
+ code_bg = "#2d2d2d"
+ code_fg = "#dcdcdc"
+ table_header_bg = "#2a2a2a"
+ table_header_fg = "#ccc"
+ table_alt_bg = "#252525"
+ border_color = "#444"
+ else:
+ bg_color = "#ffffff"
+ fg_color = "#1a1a1a"
+ code_bg = "#f4f4f4"
+ code_fg = "#000000"
+ table_header_bg = "#f3f3f3"
+ table_header_fg = "#333"
+ table_alt_bg = "#fafafa"
+ border_color = "#ccc"
+
+ h1 = font_size + 18
+ h2 = font_size + 12
+ h3 = font_size + 8
+ h4 = font_size + 4
+ h5 = font_size + 2
+ h6 = font_size + 1
+ base = font_size + 2
+
+ return f"""
+
+
+
+
+
+
+ {_get_mathjax_script()}
+
+
+ {html_content}
+
+"""
diff --git a/backend/routers/__init__.py b/backend/routers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/backend/routers/ai.py b/backend/routers/ai.py
new file mode 100644
index 0000000..834da80
--- /dev/null
+++ b/backend/routers/ai.py
@@ -0,0 +1,234 @@
+"""
+backend/routers/ai.py
+=====================
+AI provider configuration and chat / automation endpoints.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if _ROOT not in sys.path:
+ sys.path.insert(0, _ROOT)
+
+from markdown_reader.logic import (
+ AI_PROVIDER_PRIORITY,
+ TranslationConfigError,
+ delete_secure_ai_api_key,
+ fetch_available_models,
+ get_ai_automation_task_templates,
+ get_ai_provider_display_name,
+ get_ai_provider_env_var,
+ get_ai_provider_model,
+ get_openai_compatible_base_url_choice,
+ get_openai_compatible_base_url_options,
+ get_openai_compatible_storage_key_name,
+ get_provider_default_models,
+ get_secure_ai_api_key,
+ load_ai_automation_logs,
+ load_ai_chat_histories,
+ load_persisted_ai_settings,
+ request_ai_agent_response,
+ save_ai_chat_histories,
+ set_ai_provider_model,
+ set_current_ai_provider,
+ set_openai_compatible_base_url_choice,
+ set_secure_ai_api_key,
+ translate_markdown_with_ai,
+)
+
+router = APIRouter()
+
+
+# ── Models ────────────────────────────────────────────────────────────────────
+
+
+class ApiKeyPayload(BaseModel):
+ provider: str
+ api_key: str
+
+
+class ProviderModelPayload(BaseModel):
+ provider: str
+ model: str
+
+
+class BaseUrlChoicePayload(BaseModel):
+ choice_key: str
+
+
+class AgentChatPayload(BaseModel):
+ message: str
+ document_text: str = ""
+ selected_text: str = ""
+ chat_history: list[dict[str, Any]] = []
+
+
+class TranslatePayload(BaseModel):
+ content: str
+ source_language: str
+ target_language: str
+
+
+# ── Settings endpoints ─────────────────────────────────────────────────────────
+
+
+@router.get("/settings")
+def get_ai_settings():
+ """Return all persisted AI provider settings."""
+ settings = load_persisted_ai_settings()
+ # Augment with display names and env var names
+ for provider in AI_PROVIDER_PRIORITY:
+ settings.setdefault("providers", {})
+ settings["providers"][provider] = {
+ "display_name": get_ai_provider_display_name(provider),
+ "env_var": get_ai_provider_env_var(provider),
+ "model": get_ai_provider_model(provider),
+ "default_models": get_provider_default_models(provider),
+ }
+ return settings
+
+
+@router.post("/settings/provider")
+def set_provider(provider: str):
+ """Set the active AI provider."""
+ if provider not in AI_PROVIDER_PRIORITY:
+ raise HTTPException(status_code=400, detail=f"Unknown provider: {provider}")
+ set_current_ai_provider(provider)
+ return {"provider": provider}
+
+
+@router.post("/settings/model")
+def set_model(payload: ProviderModelPayload):
+ """Set the model for a given provider."""
+ set_ai_provider_model(payload.provider, payload.model)
+ return {"provider": payload.provider, "model": payload.model}
+
+
+@router.post("/settings/apikey")
+def save_api_key(payload: ApiKeyPayload):
+ """Store an API key securely for the given provider."""
+ set_secure_ai_api_key(payload.provider, payload.api_key)
+ return {"provider": payload.provider, "saved": True}
+
+
+@router.delete("/settings/apikey/{provider}")
+def remove_api_key(provider: str):
+ """Delete the stored API key for the given provider."""
+ delete_secure_ai_api_key(provider)
+ return {"provider": provider, "deleted": True}
+
+
+@router.get("/settings/openai-compatible/base-url-options")
+def openai_compatible_base_url_options():
+ return get_openai_compatible_base_url_options()
+
+
+@router.get("/settings/openai-compatible/base-url-choice")
+def openai_compatible_base_url_choice():
+ return {"choice": get_openai_compatible_base_url_choice()}
+
+
+@router.post("/settings/openai-compatible/base-url-choice")
+def set_openai_compatible_base_url(payload: BaseUrlChoicePayload):
+ set_openai_compatible_base_url_choice(payload.choice_key)
+ return {"choice": payload.choice_key}
+
+
+@router.get("/models/{provider}")
+def get_models(provider: str, base_url_override: str = ""):
+ """Fetch available models for a provider (live API call)."""
+ api_key = get_secure_ai_api_key(
+ get_openai_compatible_storage_key_name()
+ if provider == "openai_compatible"
+ else provider
+ )
+ try:
+ models = fetch_available_models(
+ provider, api_key, base_url_override=base_url_override
+ )
+ except Exception:
+ # Fall back to default list when the API is unreachable
+ models = get_provider_default_models(provider)
+ return {"provider": provider, "models": models}
+
+
+# ── Chat / automation endpoints ────────────────────────────────────────────────
+
+
+@router.post("/chat")
+def ai_chat(payload: AgentChatPayload):
+ """Send a message to the AI agent and return a structured response."""
+ try:
+ result = request_ai_agent_response(
+ payload.message,
+ document_text=payload.document_text,
+ selected_text=payload.selected_text,
+ chat_history=payload.chat_history,
+ )
+ except TranslationConfigError as exc:
+ raise HTTPException(
+ status_code=422,
+ detail={
+ "message": str(exc),
+ "provider": getattr(exc, "provider_name", None),
+ "env_var": getattr(exc, "env_var", None),
+ },
+ )
+ except RuntimeError as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+ return result
+
+
+@router.get("/chat/history")
+def get_chat_history():
+ """Load all persisted AI chat histories."""
+ return {"histories": load_ai_chat_histories()}
+
+
+@router.post("/chat/history")
+def save_chat_history(histories: list[dict[str, Any]]):
+ """Persist AI chat histories."""
+ save_ai_chat_histories(histories)
+ return {"saved": True}
+
+
+@router.get("/automation/templates")
+def automation_templates():
+ """Return built-in AI automation task templates."""
+ return {"templates": get_ai_automation_task_templates()}
+
+
+@router.get("/automation/logs")
+def automation_logs(limit: int = 100):
+ """Return AI automation audit log entries."""
+ return {"logs": load_ai_automation_logs(limit=limit)}
+
+
+# ── Translation endpoint ───────────────────────────────────────────────────────
+
+
+@router.post("/translate")
+def translate(payload: TranslatePayload):
+ """Translate Markdown content via AI."""
+ try:
+ result = translate_markdown_with_ai(
+ payload.content, payload.source_language, payload.target_language
+ )
+ except TranslationConfigError as exc:
+ raise HTTPException(
+ status_code=422,
+ detail={
+ "message": str(exc),
+ "provider": getattr(exc, "provider_name", None),
+ },
+ )
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+ return {"translated": result}
diff --git a/backend/routers/export.py b/backend/routers/export.py
new file mode 100644
index 0000000..15087a0
--- /dev/null
+++ b/backend/routers/export.py
@@ -0,0 +1,136 @@
+"""
+backend/routers/export.py
+=========================
+File export endpoints (HTML, DOCX, PDF).
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if _ROOT not in sys.path:
+ sys.path.insert(0, _ROOT)
+
+router = APIRouter()
+
+
+class ExportPayload(BaseModel):
+ content: str # Markdown source
+ output_path: str | None = None # Optional explicit output path
+ base_dir: str | None = None # For resolving relative image paths
+ dark_mode: bool = False
+ font_family: str = "system-ui, sans-serif"
+ font_size: int = 14
+
+
+def _make_output_path(suggested: str | None, suffix: str) -> str:
+ if suggested:
+ return suggested
+ _, path = tempfile.mkstemp(suffix=suffix)
+ return path
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+
+@router.post("/html")
+def export_html(payload: ExportPayload):
+ """Export Markdown to a self-contained HTML file, return its path."""
+ from backend.renderer import render_markdown
+
+ html = render_markdown(
+ payload.content,
+ base_dir=payload.base_dir,
+ dark_mode=payload.dark_mode,
+ font_family=payload.font_family,
+ font_size=payload.font_size,
+ )
+ out_path = _make_output_path(payload.output_path, ".html")
+ parent = os.path.dirname(out_path)
+ if parent:
+ os.makedirs(parent, exist_ok=True)
+ with open(out_path, "w", encoding="utf-8") as f:
+ f.write(html)
+ return {"path": out_path}
+
+
+@router.post("/html/download")
+def download_html(payload: ExportPayload):
+ """Export Markdown to HTML and stream the file for download."""
+ from backend.renderer import render_markdown
+
+ html = render_markdown(
+ payload.content,
+ base_dir=payload.base_dir,
+ dark_mode=payload.dark_mode,
+ font_family=payload.font_family,
+ font_size=payload.font_size,
+ )
+ _, tmp = tempfile.mkstemp(suffix=".html")
+ with open(tmp, "w", encoding="utf-8") as f:
+ f.write(html)
+ return FileResponse(tmp, media_type="text/html", filename="export.html")
+
+
+@router.post("/docx")
+def export_docx(payload: ExportPayload):
+ """Export Markdown to DOCX and return the output file path."""
+ # We use a minimal stub that shells out to the existing logic. The legacy
+ # export_to_docx() function requires a MarkdownReader 'app' object, so we
+ # create a lightweight adapter.
+ from markdown_reader.logic import export_to_docx
+
+ out_path = _make_output_path(payload.output_path, ".docx")
+ parent = os.path.dirname(out_path)
+ if parent:
+ os.makedirs(parent, exist_ok=True)
+
+ # Build a minimal duck-typed adapter the legacy function can use
+ class _AppAdapter:
+ editors = [None]
+ notebook = type(
+ "NB", (), {"index": lambda self, _: 0, "select": lambda self: None}
+ )()
+ file_paths = [payload.base_dir]
+ current_font_family = payload.font_family
+ current_font_size = payload.font_size
+ dark_mode = payload.dark_mode
+ _markdown_content = payload.content
+
+ adapter = _AppAdapter()
+
+ # Monkey-patch the text area to return our content
+ class _FakeTextArea:
+ def get(self, *_):
+ return payload.content
+
+ adapter.editors = [_FakeTextArea()]
+
+ try:
+ export_to_docx(adapter, out_path)
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+ return {"path": out_path}
+
+
+@router.post("/pdf")
+def export_pdf(payload: ExportPayload):
+ """Export Markdown to PDF via WeasyPrint and return the output file path."""
+ from markdown_reader.plugins.pdf_exporter import export_markdown_to_pdf
+
+ out_path = _make_output_path(payload.output_path, ".pdf")
+ parent = os.path.dirname(out_path)
+ if parent:
+ os.makedirs(parent, exist_ok=True)
+ try:
+ export_markdown_to_pdf(payload.content, out_path, base_dir=payload.base_dir)
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+ return {"path": out_path}
diff --git a/backend/routers/files.py b/backend/routers/files.py
new file mode 100644
index 0000000..e6d6872
--- /dev/null
+++ b/backend/routers/files.py
@@ -0,0 +1,139 @@
+"""
+backend/routers/files.py
+========================
+File system CRUD endpoints + recent-files management.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if _ROOT not in sys.path:
+ sys.path.insert(0, _ROOT)
+
+from markdown_reader.logic import APP_SETTINGS_FILE_PATH
+from markdown_reader.recent_files import RecentFilesManager
+
+router = APIRouter()
+
+# Singleton recent-files manager (shared across requests)
+_recent: RecentFilesManager | None = None
+
+
+def _get_recent() -> RecentFilesManager:
+ global _recent
+ if _recent is None:
+ _recent = RecentFilesManager(str(APP_SETTINGS_FILE_PATH))
+ return _recent
+
+
+# ── Models ────────────────────────────────────────────────────────────────────
+
+
+class WritePayload(BaseModel):
+ path: str
+ content: str
+
+
+class FileEntry(BaseModel):
+ name: str
+ path: str
+ is_dir: bool
+ extension: str
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+
+@router.get("/read")
+def read_file(path: str = Query(..., description="Absolute path to the file")):
+ """Read a file and return its content."""
+ if not os.path.isfile(path):
+ raise HTTPException(status_code=404, detail=f"File not found: {path}")
+ try:
+ with open(path, encoding="utf-8", errors="replace") as f:
+ content = f.read()
+ return {"path": path, "content": content}
+ except OSError as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.post("/write")
+def write_file(payload: WritePayload):
+ """Write (or overwrite) a file with the provided content."""
+ path = payload.path
+ parent = os.path.dirname(path)
+ if parent:
+ os.makedirs(parent, exist_ok=True)
+ try:
+ with open(path, "w", encoding="utf-8") as f:
+ f.write(payload.content)
+ return {"path": path, "written": True}
+ except OSError as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+
+
+@router.get("/list")
+def list_files(
+ path: str = Query(..., description="Directory to list"),
+ extensions: str | None = Query(
+ None,
+ description="Comma-separated list of file extensions to include (e.g. md,txt)",
+ ),
+):
+ """List entries in a directory (non-recursive, sorted: dirs first)."""
+ if not os.path.isdir(path):
+ raise HTTPException(status_code=404, detail=f"Directory not found: {path}")
+
+ allowed_exts: set[str] | None = None
+ if extensions:
+ allowed_exts = {e.strip().lower().lstrip(".") for e in extensions.split(",")}
+
+ entries: list[dict] = []
+ try:
+ with os.scandir(path) as it:
+ for entry in sorted(it, key=lambda e: (not e.is_dir(), e.name.lower())):
+ if entry.name.startswith("."):
+ continue
+ is_dir = entry.is_dir()
+ ext = Path(entry.name).suffix.lstrip(".").lower()
+ if not is_dir and allowed_exts and ext not in allowed_exts:
+ continue
+ entries.append(
+ {
+ "name": entry.name,
+ "path": entry.path,
+ "is_dir": is_dir,
+ "extension": ext,
+ }
+ )
+ except PermissionError:
+ raise HTTPException(status_code=403, detail="Permission denied")
+
+ return {"path": path, "entries": entries}
+
+
+@router.get("/recent")
+def get_recent_files():
+ """Return the most-recently-opened file paths."""
+ return {"entries": _get_recent().entries}
+
+
+@router.post("/recent")
+def add_recent_file(path: str = Query(...)):
+ """Record a file as most-recently-opened."""
+ _get_recent().push(path)
+ return {"entries": _get_recent().entries}
+
+
+@router.delete("/recent")
+def clear_recent_files():
+ """Clear all recent-file entries."""
+ _get_recent().clear()
+ return {"entries": []}
diff --git a/backend/routers/markdown.py b/backend/routers/markdown.py
new file mode 100644
index 0000000..85eb5dd
--- /dev/null
+++ b/backend/routers/markdown.py
@@ -0,0 +1,105 @@
+"""
+backend/routers/markdown.py
+============================
+Markdown rendering and conversion endpoints.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+if _ROOT not in sys.path:
+ sys.path.insert(0, _ROOT)
+
+from backend.renderer import render_markdown
+from markdown_reader.logic import (
+ convert_html_to_markdown,
+ convert_pdf_to_markdown,
+ convert_pdf_to_markdown_docling,
+)
+from markdown_reader.word_count_bar import _count_words, _reading_time, _strip_markdown
+
+router = APIRouter()
+
+
+# ── Models ────────────────────────────────────────────────────────────────────
+
+
+class RenderPayload(BaseModel):
+ content: str
+ base_dir: str | None = None
+ dark_mode: bool = False
+ font_family: str = "system-ui, sans-serif"
+ font_size: int = 14
+
+
+class HtmlToMarkdownPayload(BaseModel):
+ html: str
+
+
+class PdfToMarkdownPayload(BaseModel):
+ path: str
+ use_docling: bool = False
+
+
+# ── Endpoints ─────────────────────────────────────────────────────────────────
+
+
+@router.post("/render")
+def render(payload: RenderPayload):
+ """Render Markdown text to a full HTML document string."""
+ html = render_markdown(
+ payload.content,
+ base_dir=payload.base_dir,
+ dark_mode=payload.dark_mode,
+ font_family=payload.font_family,
+ font_size=payload.font_size,
+ )
+ return {"html": html}
+
+
+@router.post("/convert/html")
+def html_to_markdown(payload: HtmlToMarkdownPayload):
+ """Convert an HTML string to Markdown."""
+ try:
+ result = convert_html_to_markdown(payload.html)
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+ return {"markdown": result}
+
+
+@router.post("/convert/pdf")
+def pdf_to_markdown(payload: PdfToMarkdownPayload):
+ """Convert a local PDF file to Markdown."""
+ if not os.path.isfile(payload.path):
+ raise HTTPException(status_code=404, detail=f"File not found: {payload.path}")
+ try:
+ if payload.use_docling:
+ result = convert_pdf_to_markdown_docling(payload.path)
+ else:
+ result = convert_pdf_to_markdown(payload.path)
+ except Exception as exc:
+ raise HTTPException(status_code=500, detail=str(exc))
+ return {"markdown": result}
+
+
+@router.post("/wordcount")
+def word_count(payload: RenderPayload):
+ """Return word count statistics for the given Markdown text."""
+ stripped = _strip_markdown(payload.content)
+ words = _count_words(stripped)
+ chars_with = len(payload.content)
+ chars_without = len(
+ payload.content.replace(" ", "").replace("\n", "").replace("\t", "")
+ )
+ return {
+ "words": words,
+ "chars_with_spaces": chars_with,
+ "chars_without_spaces": chars_without,
+ "reading_time": _reading_time(words),
+ }
diff --git a/docs/PrepareForMacUser.md b/docs/PrepareForMacUser.md
index 58b29ca..00e617b 100644
--- a/docs/PrepareForMacUser.md
+++ b/docs/PrepareForMacUser.md
@@ -6,7 +6,7 @@ brew install cairo pango gdk-pixbuf libffi
Then reactivate your virtual environment:
```bash
deactivate
-source venv/bin/activate
+source .venv/bin/activate
```
#### If you are using Apple Silicon (M1/M2/M3/M4)
diff --git a/docs/PrepareForWindowsUser.md b/docs/PrepareForWindowsUser.md
index b604709..0ae1a2f 100644
--- a/docs/PrepareForWindowsUser.md
+++ b/docs/PrepareForWindowsUser.md
@@ -31,7 +31,7 @@ To do this permanently:
Open a new Command Prompt or PowerShell window (so the updated PATH takes effect), then reactivate your virtual environment:
```cmd
-.\venv\Scripts\activate
+.\.venv\Scripts\activate
```
#### 5. Verify the installation
diff --git a/docs/index.md b/docs/index.md
index 81e1e8a..9b8ca2a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,7 +7,7 @@ Markdown Reader is a clean and intuitive Markdown editor/reader with real-time p
## Features
* Tabbed Markdown editing with real-time HTML preview.
-* **AI-Powered Translation**: Translate Markdown documents while preserving formatting (supports OpenRouter, OpenAI, and Anthropic).
+* **AI-Powered Translation**: Translate Markdown documents while preserving formatting (supports OpenAI Compatible, OpenRouter, OpenAI, and Anthropic).
* **Built-in AI Agent Chat**: A dockable in-app chat panel can read current document context and suggest/apply edits.
* **AI Task Automation Templates**: Run reusable templates for formatting, TOC generation, summaries, and code-block cleanup.
* **Approval/Reject Workflow**: Every AI-proposed change can be explicitly applied or rejected from the panel.
@@ -48,27 +48,54 @@ cd markdown-reader
#### 2. Create a virtual environment (recommended)
```bash
-python -m venv venv
-source venv/bin/activate # macOS/Linux
-# .\venv\Scripts\activate # Windows (cmd/powershell)
+python -m venv .venv
+source .venv/bin/activate # macOS/Linux
+# .\.venv\Scripts\activate # Windows (cmd/powershell)
```
#### 3. Install dependencies
For Mac users, you should first complete the preparation steps described in the [PrepareForMacUser](./doc/PrepareForMacUser.md) file.
-For Windows users, WeasyPrint requires additional system libraries. Complete the preparation steps described in the [PrepareForWindowsUser](./doc/PrepareForWindowsUser.md) file before running `pip install`.
+For Windows users, WeasyPrint requires additional system libraries. Complete the preparation steps described in the [PrepareForWindowsUser](./doc/PrepareForWindowsUser.md) file before installing dependencies.
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
```bash
-pip install -r requirements.txt
+uv sync --python 3.14
+source .venv/bin/activate
+```
+
+If you update dependencies in `pyproject.toml`, regenerate and commit the lockfile:
+
+```bash
+uv lock
+```
+
+CI uses `uv sync --locked --extra dev`, so `uv.lock` must stay in sync with `pyproject.toml`.
+
+Or with pip:
+
+```bash
+pip install .
+```
+
+#### 4. Install pre-commit hooks (recommended)
+
+This project uses [pre-commit](https://pre-commit.com/) to automatically fix import sorting and code formatting on every commit. Run this once after cloning:
+
+```bash
+pre-commit install
```
+After this, `ruff --fix` and `ruff-format` will run automatically on staged files whenever you `git commit`.
+
---
## Running the Application
```bash
-python app.py
+uv run python app.py
```
### How to Use
@@ -132,6 +159,118 @@ The generated app will be located in the `dist/` folder. You can launch it by do
deactivate
```
+## Code Formatting (Ruff)
+
+This project uses **Ruff** to ensure consistent code formatting across all contributions.
+
+Before submitting changes, please check and format your code.
+
+### Check formatting
+
+```bash
+uv run ruff format --check .
+```
+
+If any files are not properly formatted, you will see output like:
+
+```text
+Would reformat: some_file.py
+```
+
+This means the file does not match the required formatting style.
+
+### Fix formatting
+
+To automatically format all files:
+
+```bash
+uv run ruff format .
+```
+
+## Running Tests
+
+The project uses Python's built-in `unittest` framework. Tests live in the `tests/` directory and cover AI automation logic, UI helper methods, provider configuration, and agent interaction workflows.
+
+Run the full test suite:
+
+```bash
+uv run python -m unittest discover -s tests
+```
+
+Or with pip:
+
+```bash
+python -m unittest discover -s tests
+```
+
+Run a single test file:
+
+```bash
+uv run python -m unittest tests/test_ai_automation_logic.py
+```
+
+### Test coverage overview
+
+| Test file | What it covers |
+|---|---|
+| `test_ai_automation_logic.py` | Offline fallback logic for TOC generation, summarization, code-block formatting, and task template listing |
+| `test_ai_agent_ui_helpers.py` | UI helper methods: payload validation, chat history migration, audit log capping, suggestion apply/reject |
+| `test_ai_agent_selection_only_integration.py` | Integration path for selection-only mode — verifies correct error handling when no text is selected |
+| `test_ai_provider_config_logic.py` | Provider configuration and API key management logic |
+
+Tests run automatically on every push and pull request via GitHub Actions (see `.github/workflows/python-ci.yml`).
+
+> **macOS note:** `test_ai_agent_ui_helpers.py` and `test_ai_agent_selection_only_integration.py` import `markdown_reader.ui`, which loads WeasyPrint at import time. WeasyPrint requires native system libraries (pango, cairo, gdk-pixbuf). If you see an `OSError: cannot load library 'libgobject-2.0-0'` error, follow the steps in [PrepareForMacUser.md](./PrepareForMacUser.md) first. `test_ai_automation_logic.py` and `test_ai_provider_config_logic.py` have no system library dependencies and can always run.
+
+---
+
+## Development Workflow: uv vs. pip / requirements.txt
+
+This project previously used a `requirements.txt` file and standard `pip` commands. It has since migrated to [`uv`](https://docs.astral.sh/uv/) with `pyproject.toml`. Here is what changed and why.
+
+### The old approach (requirements.txt + pip)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+`requirements.txt` is a flat list of pinned packages. It works, but has limitations:
+
+- No distinction between direct dependencies and transitive ones — everything is listed together.
+- No separation of dev-only dependencies (linters, test runners) from runtime dependencies.
+- No built-in lockfile mechanism — the file must be manually regenerated and tends to drift.
+- `pip` resolves the full dependency graph from scratch on every install, which is slow.
+
+### The new approach (pyproject.toml + uv)
+
+```bash
+uv sync # install all runtime dependencies from the lockfile
+uv sync --locked --extra dev # also install dev tools (ruff, ty, pre-commit)
+```
+
+`pyproject.toml` is the modern Python packaging standard (PEP 517/518/621). It consolidates project metadata, runtime dependencies, and tool configuration in one file. Key benefits over `requirements.txt`:
+
+- **Dependency groups**: runtime deps go under `[project.dependencies]`; dev-only tools (Ruff, ty, pre-commit) go under `[project.optional-dependencies] dev`; docs tools under `docs`. You only install what you need.
+- **Lockfile (`uv.lock`)**: records exact versions of every direct and transitive package. `uv sync --locked` guarantees identical environments across all machines and in CI — no more "works on my machine" surprises.
+- **Speed**: `uv` is written in Rust and resolves and installs packages significantly faster than `pip`.
+- **Single source of truth**: tool configuration for Ruff, ty, and isort also lives in `pyproject.toml`, eliminating separate config files.
+
+### When to update the lockfile
+
+If you add or change a dependency in `pyproject.toml`, regenerate the lockfile and commit it:
+
+```bash
+uv lock
+git add pyproject.toml uv.lock
+git commit -m "chore: update dependencies"
+```
+
+CI runs `uv sync --locked`, so a stale `uv.lock` will fail the build — this is intentional and keeps the lockfile honest.
+
+---
+
## Submit Changes to Git
```bash
git add .
@@ -146,7 +285,7 @@ git push
* HTML Preview: Dynamically generated HTML opened in the default browser
* File Conversion: `html2text` for HTML, `PyMuPDF` and `docling` for PDF import (`pypdf` is used as a fallback when PyMuPDF is unavailable)
* PDF Export: `weasyprint`
-* AI Translation: `requests` for API communication with OpenRouter, OpenAI, and Anthropic
+* AI Translation: `requests` for API communication with OpenAI Compatible, OpenRouter, OpenAI, and Anthropic
* Configuration: Per-user settings JSON for provider/model (macOS `~/Library/Application Support/MarkdownReader/settings.json`; Windows `%APPDATA%/MarkdownReader/settings.json`; Linux `~/.config/markdown-reader/settings.json`) plus OS credential storage for API keys (`keyring`)
* Auto-failover: Automatically switches AI providers when the primary provider returns rate-limit/auth/server errors
@@ -163,6 +302,7 @@ To enable AI-powered translation features, you need to set up API keys:
1. Open `Settings -> AI Provider & API Keys...`.
2. Choose provider and model.
3. Enter API key and save.
+4. If you choose `OpenAI Compatible`, you can also choose a Base URL option (`Navidia` or `Groq`).
The app stores provider and model in a per-user JSON file:
@@ -174,6 +314,9 @@ The app stores provider and model in a per-user JSON file:
- **OpenRouter** (recommended for free tier): [openrouter.ai](https://openrouter.ai/)
- **OpenAI**: [platform.openai.com](https://platform.openai.com/)
- **Anthropic**: [console.anthropic.com](https://console.anthropic.com/)
+- **OpenAI Compatible**: Create an API key from your chosen compatible provider console, then select the matching Base URL preset in this app:
+ - **Navidia preset**: [NVIDIA Integrate](https://build.nvidia.com/)
+ - **Groq preset**: [Groq Console](https://console.groq.com/keys)
API keys are saved in the OS credential store (Keychain on macOS, Credential Manager on Windows, Secret Service/KWallet on Linux when available).
@@ -197,5 +340,4 @@ All contributions are welcome, including:
- Pull requests
- Documentation improvements
-Please see our [CONTRIBUTING](CONTRIBUTING.md) guide for more details on how to get started, submit changes, or report issues.
-
+Please see our [CONTRIBUTING](CONTRIBUTING.md) guide for more details on how to get started, submit changes, or report issues.
\ No newline at end of file
diff --git a/frontend/.env.local.example b/frontend/.env.local.example
new file mode 100644
index 0000000..8953364
--- /dev/null
+++ b/frontend/.env.local.example
@@ -0,0 +1,3 @@
+# The base URL for the FastAPI backend.
+# Override this if you run the backend on a different port.
+NEXT_PUBLIC_API_BASE_URL=http://127.0.0.1:8000
diff --git a/frontend/.eslintrc.json b/frontend/.eslintrc.json
new file mode 100644
index 0000000..6b10a5b
--- /dev/null
+++ b/frontend/.eslintrc.json
@@ -0,0 +1,6 @@
+{
+ "extends": [
+ "next/core-web-vitals",
+ "next/typescript"
+ ]
+}
diff --git a/frontend/next-env.d.ts b/frontend/next-env.d.ts
new file mode 100644
index 0000000..40c3d68
--- /dev/null
+++ b/frontend/next-env.d.ts
@@ -0,0 +1,5 @@
+/// + Ask me to summarize, generate a TOC, translate, fix code blocks, or anything else… +
+ )} + {messages.map((msg) => ( +