feat(converter): add hybrid mode support for document conversion

## Scope

convert-lo provides lightweight LibreOffice conversion utilities.

convert-lo provides LibreOffice document conversion utilities with support for both CLI and server modes.

## Guidelines

## Architecture

- Keep modules small and typed.

- Raise explicit, descriptive errors.

- Avoid side effects during import.

### Conversion Modes

The `Converter` class supports two conversion backends:

1. **CLI Mode** (default fallback)

   - Uses `soffice --headless --convert-to`

   - Loads/unloads LibreOffice per conversion

   - Always available, no server required

2. **Server Mode** (unoserver)

   - Uses persistent LibreOffice listener

   - 2-4x faster for batch conversions

   - 50-75% lower CPU load

   - Requires `unoserver` running

### Hybrid Detection

By default (`server_mode="auto"`), the converter:

1. Checks for running unoserver at configured host:port

2. Uses server if available

3. Falls back to CLI mode silently

### Key Components

| Module | Purpose |

|--------|---------|

| `converter.py` | `Converter` class with hybrid mode support |

| `server.py` | `ServerManager` for lifecycle management |

| `locator.py` | LibreOffice executable discovery |

| `formats.py` | `LibreOfficeFormat` enum and validation |

| `benchmark.py` | Performance comparison script |

## Usage Patterns

### Basic Conversion (Auto-Detect)

```python

from convert_lo import Converter, LibreOfficeFormat

# Auto-detect server, fallback to CLI

converter = Converter()

result = converter.convert(

    input_file=Path("document.docx"),

    output_format=LibreOfficeFormat.PDF,

    output_dir=Path("./output"),

)

```

### Force Server Mode

```python

from convert_lo import Converter

# Require server (raises error if unavailable)

converter = Converter(server_mode="server")

# Or auto-start server if needed

converter = Converter(

    server_mode="auto",

    auto_start_server=True,

)

```

### Force CLI Mode

```python

from convert_lo import Converter

# Always use CLI (skip server detection)

converter = Converter(server_mode="cli")

```

### Context Manager (Auto Start/Stop)

```python

from convert_lo import Converter

with Converter(auto_start_server=True) as converter:

    # Server started on entry, stopped on exit

    results = converter.convert_batch(files, LibreOfficeFormat.PDF, output_dir)

```

### Manual Server Management

```python

from convert_lo import ServerManager, Converter

# Start server explicitly

manager = ServerManager(port=2003)

manager.start()

# Use converter with specific server

converter = Converter(

    server_mode="server",

    server_port=2003,

)

# ... do conversions ...

# Stop server

manager.stop()

```

### Check Server Status

```python

from convert_lo import is_server_running, ServerManager

# Check if server is running

if is_server_running("127.0.0.1", 2003):

    print("Server is available")

# Get detailed status

manager = ServerManager()

status = manager.status()

print(f"Running: {status.is_running}, PID: {status.pid}")

```

## Configuration

### Converter Parameters

| Parameter | Type | Default | Description |

|-----------|------|---------|-------------|

| `soffice_path` | `Path | None` | `None` | Auto-detect LibreOffice path |

| `server_host` | `str` | `"127.0.0.1"` | Unoserver host |

| `server_port` | `int` | `2003` | Unoserver XML-RPC port |

| `server_mode` | `"auto" | "server" | "cli"` | `"auto"` | Conversion mode |

| `auto_start_server` | `bool` | `False` | Auto-start server if needed |

### ServerManager Parameters

| Parameter | Type | Default | Description |

|-----------|------|---------|-------------|

| `host` | `str` | `"127.0.0.1"` | Server interface |

| `port` | `int` | `2003` | XML-RPC port |

| `uno_port` | `int` | `2002` | UNO port |

| `soffice_path` | `Path | None` | `None` | LibreOffice path |

| `timeout` | `int` | `30` | Startup timeout (seconds) |

### Environment Variables

| Variable | Description |

|----------|-------------|

| `LIBREOFFICE_PATH` | Override auto-detection for soffice executable |

## Supported Formats

See `LibreOfficeFormat` enum in `formats.py` for complete list:

- **Text**: ODT, DOC, DOCX, RTF, PDF, HTML, TXT, MD, EPUB

- **Spreadsheet**: ODS, XLS, XLSX, CSV

- **Presentation**: ODP, PPT, PPTX

- **Graphics**: ODG, SVG

## Performance

### Benchmark Script

Run performance comparison:

```bash

uv run python -m convert_lo.benchmark --file-count 20 --size medium

```

Options:

- `-n, --file-count`: Number of test files (default: 10)

- `-s, --size`: Document size: small/medium/large (default: medium)

- `-f, --format`: Output format: pdf/docx/odt/txt/html (default: pdf)

### Expected Performance

| Scenario | CLI Mode | Server Mode | Speedup |

|----------|----------|-------------|---------|

| Single file | ~2-3s | ~2-3s | 1.0x |

| 10 files | ~20-30s | ~8-12s | 2-3x |

| 50 files | ~100-150s | ~30-50s | 3-4x |

Server mode shows greater benefits with:

- Larger file counts

- Complex documents

- Repeated conversions

## Error Handling

### Exceptions

| Exception | When Raised |

|-----------|-------------|

| `SofficeNotFoundError` | LibreOffice executable not found |

| `UnsupportedConversionError` | Invalid format or unsupported conversion pair |

| `ConversionError` | Conversion process fails |

### Fallback Behavior

When `server_mode="auto"`:

- Server unavailable → CLI mode (silent)

- Server conversion fails → CLI retry (logged warning)

- Auto-start fails → CLI mode (logged warning)

When `server_mode="server"`:

- Server unavailable → `ConversionError`

- Server conversion fails → CLI retry (logged warning)

## Testing

### Run Tests

```bash

uv run pytest tests/convert_lo/ -v

uv run pytest tests/convert_lo/ --cov=convert_lo --cov-report=term-missing

```

### Test Files

| File | Purpose |

|------|---------|

| `test_converter.py` | Core `Converter` tests (CLI mode) |

| `test_server.py` | `ServerManager` tests |

| `test_hybrid_converter.py` | Hybrid mode detection and fallback |

| `test_integration.py` | Real LibreOffice integration tests |

| `test_locator.py` | Executable discovery tests |

| `test_formats.py` | Format enum and validation tests |

### Mocking Server in Tests

```python

from unittest.mock import patch

# Mock server detection

with patch("convert_lo.converter.is_server_running", return_value=True):

    with patch("convert_lo.converter.UnoClient") as mock_client:

        converter = Converter(server_mode="auto")

        # Test server-based conversion

```

## Implementation Notes

1. **Thread Safety**: LibreOffice is NOT thread-safe. All conversions run sequentially.

2. **Server Lifecycle**: 

   - Server persists after conversion

   - Use context manager or explicit `stop()` for cleanup

   - Auto-start creates temporary `ServerManager`

3. **Fallback Strategy**: Server conversion failures trigger CLI retry, ensuring reliability.

4. **LSP Warnings**: Import of `unoserver.client` may show LSP errors (optional import pattern). This is expected and handled at runtime.

## Dependencies

- `unoserver>=3.6` (optional, provides server mode)

- LibreOffice (required, any recent version)

## Lessons Learned

1. **Auto-detect is key**: Users shouldn't need to know about server vs CLI. Default to `server_mode="auto"`.

2. **Graceful degradation**: Always provide CLI fallback. Server is an optimization, not a requirement.

3. **Context manager pattern**: Makes server lifecycle management trivial for users.

4. **Benchmark early**: Performance differences are significant. Include benchmarks in CI for regression detection.

# convert-lo

Lightweight helpers for converting documents with LibreOffice.

LibreOffice document conversion helpers with **hybrid mode** support for optimal performance.

## Usage

## Features

- **Hybrid conversion**: Auto-detects running unoserver, falls back to CLI mode

- **2-4x faster** batch conversions with server mode

- **50-75% lower CPU load** when using persistent server

- **Graceful degradation**: Always works, even without server

- **Context manager**: Easy server lifecycle management

## Installation

```bash

uv add convert-lo

```

Requires:

- LibreOffice (any recent version)

- `unoserver>=3.6` (optional, enables server mode)

## Quick Start

### Basic Conversion (Auto-Detect)

```python

from pathlib import Path

from convert_lo import Converter, LibreOfficeFormat

# Automatically uses server if available, otherwise CLI

converter = Converter()

result = converter.convert(

    input_file=Path("report.docx"),

    output_format=LibreOfficeFormat.PDF,

    output_dir=Path("out"),

    output_dir=Path("output"),

)

print(result.output_path)

print(f"Converted: {result.output_path}")

```

### Batch Conversion

```python

files = [Path(f"doc{i}.docx") for i in range(10)]

results = converter.convert_batch(files, LibreOfficeFormat.PDF, Path("output"))

print(f"Converted {len(results)} files")

```

### Auto-Start Server (Recommended for Batches)

```python

from convert_lo import Converter

# Automatically starts server, converts, then stops

with Converter(auto_start_server=True) as converter:

    results = converter.convert_batch(files, LibreOfficeFormat.PDF, Path("output"))

```

## Server Modes

| Mode | Behavior | Use Case |

|------|----------|----------|

| `"auto"` (default) | Detect server, fallback to CLI | General purpose |

| `"server"` | Require server, raise if unavailable | Dedicated server setups |

| `"cli"` | Always use CLI mode | Simple scripts, no server |

### Force Server Mode

```python

# Require server (raises error if unavailable)

converter = Converter(server_mode="server")

# Or auto-start if needed

converter = Converter(

    server_mode="auto",

    auto_start_server=True,

)

```

### Force CLI Mode

```python

# Skip server detection entirely

converter = Converter(server_mode="cli")

```

## Manual Server Management

```python

from convert_lo import ServerManager, Converter

# Start server explicitly

manager = ServerManager(port=2003)

manager.start()

# Use converter with specific server

converter = Converter(server_mode="server", server_port=2003)

results = converter.convert_batch(files, LibreOfficeFormat.PDF, Path("output"))

# Stop server

manager.stop()

```

### Check Server Status

```python

from convert_lo import is_server_running

if is_server_running("127.0.0.1", 2003):

    print("Server is available")

```

## Supported Formats

**Text**: ODT, DOC, DOCX, RTF, PDF, HTML, TXT, MD, EPUB  

**Spreadsheet**: ODS, XLS, XLSX, CSV  

**Presentation**: ODP, PPT, PPTX  

**Graphics**: ODG, SVG

```python

from convert_lo import LibreOfficeFormat

# All format examples

LibreOfficeFormat.PDF

LibreOfficeFormat.DOCX

LibreOfficeFormat.MARKDOWN  # or LibreOfficeFormat.MD

LibreOfficeFormat.HTML

```

## Performance

### Benchmark Script

Compare CLI vs server mode performance:

```bash

uv run python -m convert_lo.benchmark --file-count 20 --size medium

```

**Options:**

- `-n, --file-count`: Number of test files (default: 10)

- `-s, --size`: Document size: small/medium/large (default: medium)

- `-f, --format`: Output format (default: pdf)

### Expected Performance

| Scenario | CLI Mode | Server Mode | Speedup |

|----------|----------|-------------|---------|

| Single file | ~2-3s | ~2-3s | 1.0x |

| 10 files | ~20-30s | ~8-12s | **2-3x** |

| 50 files | ~100-150s | ~30-50s | **3-4x** |

Server mode benefits increase with:

- Larger file counts

- Complex documents

- Repeated conversions

## Configuration

### Converter Parameters

```python

Converter(

    soffice_path=None,        # Auto-detect LibreOffice

    server_host="127.0.0.1",  # Unoserver host

    server_port=2003,         # Unoserver XML-RPC port

    server_mode="auto",       # "auto" | "server" | "cli"

    auto_start_server=False,  # Auto-start if needed

)

```

### Environment Variables

| Variable | Description |

|----------|-------------|

| `LIBREOFFICE_PATH` | Override auto-detection for soffice |

## Error Handling

```python

from convert_lo import (

    Converter,

    ConversionError,

    UnsupportedConversionError,

    SofficeNotFoundError,

)

try:

    result = converter.convert(file, LibreOfficeFormat.PDF, output_dir)

except UnsupportedConversionError as e:

    print(f"Format not supported: {e}")

except ConversionError as e:

    print(f"Conversion failed: {e}")

except SofficeNotFoundError as e:

    print(f"LibreOffice not found: {e}")

```

### Fallback Behavior

- **Auto mode**: Server unavailable → CLI (silent)

- **Auto mode**: Server fails → CLI retry (warning logged)

- **Server mode**: Unavailable → raises `ConversionError`

## Testing

```bash

uv run pytest tests/convert_lo/ -v

uv run pytest tests/convert_lo/ --cov=convert_lo

```

## License

MIT

from convert_lo.converter import ConversionResult, Converter

from convert_lo.exceptions import ConversionError, SofficeNotFoundError, UnsupportedConversionError

from convert_lo.formats import LibreOfficeFormat

from convert_lo.server import ServerManager, ServerStatus, get_server_mode, is_server_running

__all__ = [

    "ConversionError",

    "Converter",

    "LibreOfficeFormat",

    "SofficeNotFoundError",

    "ServerManager",

    "ServerStatus",

    "UnsupportedConversionError",

    "get_server_mode",

    "is_server_running",

]

from collections.abc import Iterable

from dataclasses import dataclass

from pathlib import Path

from typing import Literal

from convert_lo.exceptions import ConversionError, UnsupportedConversionError

from convert_lo.formats import UNSUPPORTED_CONVERSIONS, LibreOfficeFormat

from convert_lo.locator import find_soffice

from convert_lo.server import ServerManager, is_server_running

try:

    from unoserver.client import UnoClient

    HAS_UNOSERVER = True

except ImportError:

    UnoClient = None  # type: ignore[assignment, misc]

    HAS_UNOSERVER = False

logger = logging.getLogger(__name__)

class Converter:

    """Convert documents using LibreOffice.

    Note: LibreOffice conversion is NOT thread-safe. All conversions

    are processed sequentially to avoid silent failures.

    Supports two conversion modes:

    - **CLI mode**: Uses headless LibreOffice CLI (default, always available)

    - **Server mode**: Uses unoserver for faster batch conversions (requires running server)

    The converter automatically detects and uses a running unoserver when available,

    falling back to CLI mode otherwise.

    Example:

        ```python

        # Auto-detect server, fallback to CLI

        converter = Converter()

        result = converter.convert(input_file, "pdf", output_dir)

        # Force server mode (raises error if server unavailable)

        converter = Converter(server_mode="server")

        result = converter.convert(input_file, "pdf", output_dir)

        # Force CLI mode

        converter = Converter(server_mode="cli")

        result = converter.convert(input_file, "pdf", output_dir)

        ```

    """

    def __init__(self, soffice_path: Path | None = None, max_workers: int = 1) -> None:

    def __init__(

        self,

        soffice_path: Path | None = None,

        server_host: str = "127.0.0.1",

        server_port: int = 2003,

        server_mode: Literal["auto", "server", "cli"] = "auto",

        auto_start_server: bool = True,

    ) -> None:

        """Initialize the converter.

        Args:

            soffice_path: Path to soffice executable. If None, auto-detects.

            max_workers: Ignored (kept for API compatibility). Conversions are

                always sequential due to LibreOffice thread-safety limitations.

            server_host: Host for unoserver connection (default: 127.0.0.1).

            server_port: Port for unoserver connection (default: 2003).

            server_mode: Conversion mode:

                - "auto": Use server if running, else CLI (default)

                - "server": Require server (raises error if unavailable)

                - "cli": Always use CLI mode

            auto_start_server: If True and server_mode is "auto" or "server",

                attempt to start unoserver if not running.

        Raises:

            ConversionError: If server mode is required but server unavailable.

        """

        self._soffice_path = soffice_path or find_soffice()

        # max_workers is ignored - LibreOffice is not thread-safe

        self._server_host = server_host

        self._server_port = server_port

        self._server_mode = server_mode

        self._auto_start_server = auto_start_server

        self._server_manager: ServerManager | None = None

        self._client: object | None = None

        # Initialize client if server is available

        self._init_server_client()

    def _init_server_client(self) -> None:

        """Initialize unoserver client if server is available."""

        if not HAS_UNOSERVER:

            logger.debug("unoserver not installed, using CLI mode")

            return

        if self._server_mode == "cli":

            logger.debug("CLI mode forced, skipping server initialization")

            return

        # Check if server is running

        server_available = is_server_running(self._server_host, self._server_port)

        if not server_available and self._auto_start_server:

            try:

                self._server_manager = ServerManager(

                    host=self._server_host,

                    port=self._server_port,

                    soffice_path=self._soffice_path,

                )

                self._server_manager.start()

                server_available = True

                logger.info("Auto-started unoserver on %s:%d", self._server_host, self._server_port)

            except ConversionError as exc:

                logger.warning("Failed to auto-start server: %s", exc)

                if self._server_mode == "server":

                    raise

        if server_available:

            self._client = UnoClient(

                server=self._server_host,

                port=str(self._server_port),

                host_location="local",

            )

            logger.info("Using unoserver on %s:%d", self._server_host, self._server_port)

        elif self._server_mode == "server":

            msg = f"Unoserver required but not available at {self._server_host}:{self._server_port}"

            raise ConversionError(msg)

        else:

            logger.info("No server available, using CLI mode")

    @property

    def is_using_server(self) -> bool:

        """Check if converter is currently using unoserver."""

        return self._client is not None

    @property

    def server_mode(self) -> Literal["auto", "server", "cli"]:

        """Return the configured server mode."""

        return self._server_mode

    def convert(

        self,

        try:

            logger.info("Converting %s to %s", input_file, output_format.value)

            if self._client is not None:

                self._convert_via_server(input_file, output_format.value, output_dir)

            else:

                self._run_conversion(input_file, output_format.value, output_dir)

        except subprocess.CalledProcessError as exc:

            msg = f"LibreOffice conversion failed for {input_file}: {exc.stderr or exc}"

        output_path = output_dir / f"{input_file.stem}.{output_format.value}"

        return ConversionResult(input_path=input_file, output_path=output_path, output_format=output_format)

    def _convert_via_server(self, input_file: Path, output_format: str, output_dir: Path) -> None:

        """Convert using unoserver.

        Args:

            input_file: Path to input file.

            output_format: Target format (e.g., 'pdf', 'docx').

            output_dir: Output directory.

        """

        if self._client is None:

            msg = "unoserver client not initialized"

            raise ConversionError(msg)

        output_path = output_dir / f"{input_file.stem}.{output_format}"

        try:

            self._client.convert(

                inpath=str(input_file),

                outpath=str(output_path),

                convert_to=output_format,

            )

        except Exception as exc:

            logger.warning("Server conversion failed, falling back to CLI: %s", exc)

            self._run_conversion(input_file, output_format, output_dir)

    def _run_conversion(self, input_file: Path, output_format: str, output_dir: Path) -> None:

        """Execute the LibreOffice conversion command.

    ) -> list[ConversionResult]:

        """Convert multiple documents sequentially.

        Note: Conversions are processed sequentially because LibreOffice

        is not thread-safe and will silently fail with concurrent processes.

        When using unoserver, this is significantly faster than CLI mode

        as LibreOffice stays loaded between conversions.

        Args:

            input_files: Iterable of input file paths.

            result = self.convert(input_file, output_format, output_dir)

            results.append(result)

        return results

    def __enter__(self) -> Converter:

        """Start server on context entry if auto_start_server is True."""

        if self._auto_start_server and self._server_manager is not None:

            self._server_manager.start()

        return self

    def __exit__(self, exc_type, exc_val, exc_tb) -> None:

        """Stop server on context exit if auto_start_server is True."""

        if self._auto_start_server and self._server_manager is not None:

            self._server_manager.stop()