# Engine implementations

> Learn how the drivers, element sources, vision models and LLM engines are built, how the factories load them, and how Optics chooses one.

This page describes the engine implementations in the Optics Framework: drivers, element sources, vision models and LLM models. It covers the interfaces, the factories and how Optics chooses an engine.

For the list of engines you can turn on, their names in config.yaml and the pip extra for each, see [Engines and extras](https://optics-framework.org/docs/reference/engines). For their settings, see [Engine lists](https://optics-framework.org/docs/reference/config#engine-lists).

## Interfaces and factories

Each kind of engine has one interface, one factory and one package. The factories are in `optics_framework/common/factories.py`. They extend `GenericFactory` from `optics_framework/common/base_factory.py`. `OpticsBuilder` (`optics_framework/common/optics_builder.py`) calls them.

| Kind | Interface | Factory | Package | Key in config.yaml |
|---|---|---|---|---|
| Driver | `DriverInterface` (`common/driver_interface.py`) | `DeviceFactory` | `optics_framework.engines.drivers` | `driver_sources` |
| Element source | `ElementSourceInterface` (`common/elementsource_interface.py`) | `ElementSourceFactory` | `optics_framework.engines.elementsources` | `elements_sources` |
| Image detection | `ImageInterface` (`common/image_interface.py`) | `ImageFactory` | `optics_framework.engines.vision_models.image_models` | `image_detection` |
| Text detection (OCR) | `TextInterface` (`common/text_interface.py`) | `TextFactory` | `optics_framework.engines.vision_models.ocr_models` | `text_detection` |
| LLM | `LLMInterface` (`common/llm_interface.py`) | `LLMFactory` | `optics_framework.engines.llm_models` | `llm_models` |

Each factory returns an `InstanceFallback` that holds one instance per enabled entry, in config order.

### What an engine gets from config.yaml

Config.yaml validates each engine entry as a `DependencyConfig`: `enabled`, `url` and `capabilities`. Optics drops any other key. Put engine settings under `capabilities`.

`OpticsBuilder` adds some keys before it makes the engine:

- `image_detection` entries get `project_path`, `execution_output_path` and, when there are any, `templates`.
- `text_detection` entries get `execution_output_path`.

## Drivers

A driver does the user actions on the application or device under test. Every driver implements `DriverInterface` and is in `optics_framework/engines/drivers/`.

### Appium driver

**Location:** `optics_framework/engines/drivers/appium.py` (class `Appium`)

The Appium driver automates mobile apps on Android and iOS. It also drives TVs and desktop apps.

#### Key features

- Native mobile app automation
- Support for Android (UiAutomator2) and iOS (XCUITest)
- Samsung Tizen TV and LG webOS TV, and macOS, Windows and Linux desktop apps (Xa11y)
- Gesture support (swipe, scroll, tap)
- Hardware key simulation
- App lifecycle management

The differences between device families are data, not branches in the driver. `optics_framework/engines/drivers/appium_platforms.py` holds one `PlatformProfile` per family: its options class, its app id capability names and how it sends key codes. To add a TV, register a `PlatformProfile`. TV focus and web app helpers are in `appium_tv.py`.

#### Configuration

```yaml
driver_sources:
  - appium:
      enabled: true
      url: "http://localhost:4723"
      capabilities:
        platformName: "Android"
        deviceName: "emulator-5554"
        appPackage: "com.example.app"
        appActivity: ".MainActivity"
```

#### Key methods

- `launch_app()` - Launch with package/activity
- `press_coordinates()` - Tap at absolute coordinates
- `press_element()` - Tap UI elements
- `swipe()` / `swipe_percentage(x%, y%, direction, length%)` - Swipe gestures (percentages as integers 0-100)
- `scroll()` - Scroll actions
- `enter_text()` - Text input
- `press_keycode()` - Hardware key codes
- `get_app_version()` - App version info (the `appVersion` capability)

#### Special features

- Mobile-specific keycodes (BACK, HOME, MENU, etc.)
- Mobile type command support
- UI helper integration for element interaction (`appium_UI_helper.py`)

### Selenium driver

**Location:** `optics_framework/engines/drivers/selenium.py` (class `SeleniumDriver`)

The Selenium driver automates web browsers through a Selenium server or Grid.

#### Key features

- Chrome and Firefox. Another `browserName` raises an error.
- Web element interaction
- JavaScript execution
- Element lookup in `selenium_locator.py`, shared with the Selenium element sources

#### Configuration

```yaml
driver_sources:
  - selenium:
      enabled: true
      url: "http://localhost:4444"
      capabilities:
        browserName: "chrome"
        browserURL: "https://example.com"
```

- `url` defaults to `http://localhost:4444/wd/hub`.
- `browserName` is required.
- `browserURL` is the page to open. It defaults to `about:blank`.
- `element_timeout_ms` is how long to wait for an element before acting on it. It defaults to 10000.
- The driver sends every other capability to the server as it is.

#### Key methods

- `launch_app()` - Navigate to URL
- `press_element()` - Click web elements
- `enter_text()` - Form input
- `execute_script()` - JavaScript execution
- `get_text_element()` - Extract text from elements

### Playwright driver

**Location:** `optics_framework/engines/drivers/playwright.py` (class `Playwright`)

The Playwright driver automates web browsers with no server to run.

#### Key features

- Browser automation in Python, through Playwright
- Auto-waiting for elements, up to `element_timeout_ms`
- Chromium, Firefox and WebKit
- A remote browser in `url`, phone emulation (`device`) and a signed-in Chrome or Edge `profile` (`playwright_profiles.py`)

#### Configuration

```yaml
driver_sources:
  - playwright:
      enabled: true
      capabilities:
        browser: "chromium"
        headless: false
```

The driver logs a warning for a capability it does not use. See [Playwright capabilities](https://optics-framework.org/docs/reference/config#playwright-capabilities).

### How the web drivers work inside

These rules keep Playwright and Selenium uniform. Change them in one place, not per keyword.

#### Finding an element on a web page

- **Playwright.** `PlaywrightFindElement` and `PlaywrightPageSource` both resolve a value through `candidates` and `find` in `engines/drivers/playwright_locator.py`. `PlaywrightFindElement` waits up to `Playwright.element_timeout_s`. A `PlaywrightPageSource` read first waits for the page to settle (`Playwright.wait_for_page_settled`). When `driver.page` changes during a lookup, `find` looks again.
- **Selenium.** Both sources use `find` and `check` in `engines/drivers/selenium_locator.py`. The factory injects the `SeleniumDriver` wrapper, not the WebDriver, so a source reaches the WebDriver through `SeleniumDriver.require_webdriver`. Only `SeleniumFindElement.locate` waits (`element_timeout_ms`).
- **Both.** Visibility uses `utils.VISIBLE_FLAGS_JS`, and the screen's elements come from the shared `WebDomInspector`.

#### Tabs, profiles and capabilities (Playwright)

- `Playwright._follow_pages` keeps `driver.page` on the front tab. A tab or popup that opens takes over. A tab that closes hands back to the tab that opened it. `Go Back` in an opened tab with no history closes that tab.
- `capabilities.profile` copies a local Chrome or Edge profile's sign-in state into a temporary user data folder (`Playwright._open_persistent`). It drops `--use-mock-keychain` and `--password-store=basic`, so the browser decrypts the copy with the OS keychain. The copy is deleted on cleanup.
- A capability key outside `Playwright._CAPABILITIES` is logged as ignored.

#### Remote browsers (Playwright)

- A `url` on the driver entry connects to a browser instead of launching one (`Playwright._open_remote`). It uses CDP by default, or the Playwright protocol with `protocol: playwright`. Grid options go in the URL's query string. Closing the browser releases the remote session.
- `capabilities.context: existing` adopts the tab that is already open. `capabilities.storage_state` gives a new context saved sign-ins. Callers of `optics serve` and MCP send the state object, not a file path.
- `$NAME` references in the `url` and in `capabilities.headers` are expanded once, by the driver, through `config_handler.expand_env`. `resolve_config_file` leaves these two fields alone (`_DRIVER_EXPANDED`) and only checks that their variables are set. The expanded value is never stored in a local variable, and `RemoteBrowser.mask` removes it, with the URL's path and query, from error text. `expose_api._make_dependency_entry` refuses these fields from `optics serve` and MCP callers with `E0501`.
- Every synchronous Playwright call goes through `Playwright.run`, which `action_timeout_ms` bounds. `run_async` in `common/async_utils.py` needs a timeout, so element sources go through the driver's `run`.

#### Typing into a field by its caption

`Enter Text` and `Clear Element Text` on a caption type into the field that the caption names, through `Playwright._field_for` and `Appium._field_for` (the logic is in `engines/drivers/appium_fields.py`). The field is:

1. The element itself, if it is a field.
2. Else the one field whose label or hint holds the caption text.
3. Else the only field in the caption's nearest container.

A text locator that matches more than one element logs `utils.warn_if_ambiguous` from one source per driver (`PlaywrightFindElement`, `AppiumPageSource`), because `_act_until_success` runs every source. Selenium has neither of these yet.

### BLE driver

**Location:** `optics_framework/engines/drivers/ble.py` (class `BLEDriver`), on the [airhand](https://github.com/chinmayajha/airhand) client

The driver drives a device that has nothing installed: a phone, a tablet, a computer or a TV. An airhand dongle pairs with the device over Bluetooth as a keyboard, mouse and media remote. The airhand client sends it one command per line over USB serial.

- Positions go to the dongle as fractions of `frame`, so devices need no calibration.
- The dongle times taps, swipes and typing. The driver does not sleep between reports.
- A lost reply is asked for again with `result <id>`. An action is never sent two times.
- `platform` selects the shortcuts: select-all, Back, the system search for `Launch App`, and a drag or the wheel for `Scroll`. It is `android`, `ios`, `macos`, `windows` or `linux`.
- `launch` lists how `Launch App` opens an app, in order: `search_key`, `launcher_key`, `drawer_search`, `drawer_tap` or `home_icon`. A method that the platform cannot do is refused when the config loads.
- airhand errors map to Optics codes: a lost dongle or a device that stays disconnected for 10 s is `E0106` (the run stops; element fallback does not try again), other firmware is `E0501`, input the dongle cannot send is `E0403`, and any other airhand error is `E0401`.

Element methods are not supported. Elements come from `camera_screenshot` and the OCR and image strategies. See [BLE and camera](https://optics-framework.org/docs/reference/config#ble-and-camera) for the capabilities.

## Element sources

An element source finds UI elements and reads the screen. Every element source implements `ElementSourceInterface` and is in `optics_framework/engines/elementsources/`.

A source implements only the methods it can. The others raise `NotImplementedError`. The [strategies](https://optics-framework.org/docs/contribute/strategies) read which methods are real: `locate()` gives the XPath and text strategies, `capture()` gives OCR and image matching, and `get_page_source()` gives page source and interactive elements.

### Screenshot-based sources

The Appium, Selenium and Playwright screenshot sources extend `EncodedScreenshotSource` (`optics_framework/common/elementsource_interface.py`). Each gives the encoded screenshot from its backend in `capture_screenshot_bytes()`, and the shared `capture()` decodes it into a NumPy array.

#### AppiumScreenshot

**Location:** `optics_framework/engines/elementsources/appium_screenshot.py`

Captures screenshots from Appium sessions.

- Uses Appium's screenshot capability (base64 PNG, with a retry for truncated replies)
- Returns NumPy arrays for image processing
- Does not list interactive elements, locate elements or assert elements
- On a TV that cannot take a screenshot through Appium, raises `E0303`. Use `camera_screenshot` there.

#### SeleniumScreenshot

**Location:** `optics_framework/engines/elementsources/selenium_screenshot.py`

Captures screenshots from Selenium browser sessions.

- Browser screenshot capture
- Viewport screenshots
- Base64 encoding support, with a retry for remote Grid nodes

#### PlaywrightScreenshot

**Location:** `optics_framework/engines/elementsources/playwright_screenshot.py`

Captures screenshots from Playwright sessions.

- PNG from `page.screenshot()`, with no decode step in `capture_screenshot_bytes()`
- The viewport only (`full_page=False`), at CSS pixel scale

#### CameraScreenshot

**Location:** `optics_framework/engines/elementsources/camera_screenshot.py`

Captures screenshots from external cameras or capture cards.

- External camera support (`camera_index`, `camera_width`, `camera_height`)
- Video capture card support
- Production monitoring use case
- Endpoint is raw TCP (`ip:port`) or HTTP with bearer token (`http(s)://` url + `token`); env fallback via `WEBCAM_SCREENSHOT_URL` / `WEBCAM_SCREENSHOT_TOKEN` / `WEBCAM_SCREENSHOT_TCP_PORT` (see [BLE and camera](https://optics-framework.org/docs/reference/config#ble-and-camera))
- Straightens the screen with `deskew_corners`, or finds it in the frame with `find_screen` (`brightness` or `frame`, in `screen_finder.py`). Set one, not both.
- Sets `ACCEPTS_ANY_DRIVER = True`, so it works with any driver

### Page source-based sources

#### AppiumPageSource

**Location:** `optics_framework/engines/elementsources/appium_page_source.py`

Extracts and parses Appium page source XML.

- XML-based element location
- XPath support
- Element hierarchy navigation
- Interactive element detection

#### AppiumWeb

**Location:** `optics_framework/engines/elementsources/appium_web.py`

Finds CSS and DOM XPath locators in the web page of the app in front. See [Mobile web](https://optics-framework.org/docs/platforms/mobile-web).

- Android: Chrome and WebViews with debugging on; iOS: Safari, Safari sheets and inspectable WKWebViews
- Returns the element centre in screen coordinates; the session stays native
- Skipped on TVs, in iOS browser or `autoWebview` sessions, and for native locators
- Sets `SUPPLEMENTS_SCREEN_ELEMENTS = True`: its web elements are merged into the native list of interactive elements

#### SeleniumPageSource

**Location:** `optics_framework/engines/elementsources/selenium_page_source.py`

Reads the page HTML and finds elements through the WebDriver session.

- `css=` and bare CSS selectors, DOM XPath
- Visible text: exact match first, then partial, then id, name and link text
- Same lookup as `SeleniumFindElement` (`engines/drivers/selenium_locator.py`)
- Screen elements with bounds and a verified `loc`, the same list as `PlaywrightPageSource`

#### PlaywrightPageSource

**Location:** `optics_framework/engines/elementsources/playwright_page_source.py`

Extracts and parses Playwright page source.

- Reads the DOM
- Element names from `name`, `placeholder`, `aria-label`, `title` and `alt`
- Element state detection, such as checked

`WebDomInspector`, in the same file, is the shared DOM half of `PlaywrightPageSource`, `SeleniumPageSource` and `AppiumWeb`.

### Find element sources

#### AppiumFindElement

**Location:** `optics_framework/engines/elementsources/appium_find_element.py`

Direct element location using Appium's find element methods.

- Multiple locator strategies: XPath, CSS, class name, accessibility id and text
- Element interaction
- Element state checking
- Returns the page source, but does not list interactive elements

#### SeleniumFindElement

**Location:** `optics_framework/engines/elementsources/selenium_find_element.py`

Direct element location using Selenium's find element methods.

- `css=` and bare CSS selectors, DOM XPath, visible text
- Waits up to the driver's `element_timeout_ms` for an element before acting on it
- `Assert Visibility` counts only elements on screen, not hidden or clipped ones

#### PlaywrightFindElement

**Location:** `optics_framework/engines/elementsources/playwright_find_element.py`

Direct element location using Playwright's locator API.

- Auto-waiting for elements, up to the driver's element timeout
- Multiple locator types: `xpath=`, `css=`, `text=`, `label=`, `placeholder=`, `alt=`, `title=`, `role=`, `id=`, `testid=` and the `data-test` attributes (`drivers/playwright_locator.py`)
- Element state queries

### Element source selection

The factory matches each element source with a driver automatically:

```python
# Element source declares required driver type
REQUIRED_DRIVER_TYPE = "appium"

# Factory automatically matches with Appium driver
ElementSourceFactory.get_driver(config, driver_fallback)
```

`ElementSourceFactory._find_matching_driver` gives the source the first driver whose `NAME` equals its `REQUIRED_DRIVER_TYPE`. A source with `ACCEPTS_ANY_DRIVER = True` gets the first driver. A source with neither gets no driver. The factory passes the driver only if the source's `__init__` has a `driver` argument.

## Vision models

Vision models find images and text in a screenshot. They are in `optics_framework/engines/vision_models/`.

### Image detection models

#### TemplateMatch

**Location:** `optics_framework/engines/vision_models/image_models/templatematch.py` (class `TemplateMatchingHelper`)

OpenCV-based template matching with a scale sweep, plus a SIFT and FLANN fallback.

#### Key features

- Coarse-to-fine `cv2.matchTemplate` with full-resolution coordinates
- Scale sweep (`capabilities.scale_range`, default `[0.8, 1.25]`) for other screen sizes
- Local contrast equalisation for the sweep
- SIFT feature detection with FLANN matching as the last fallback (`capabilities.sift_nfeatures`, default 2000)
- Confidence thresholding
- Multiple match support (index-based)
- Template loading from project directory

#### Configuration

```yaml
image_detection:
  - templatematch:
      enabled: true
      capabilities:
        scale_range: [0.8, 1.25]
```

You do not write `project_path` or `execution_output_path` in config.yaml. `OpticsBuilder` adds them.

#### Methods

- `find_element()` - Locate template in image
- `element_exist()` - Check if template exists
- `assert_elements()` - Verify multiple templates

#### Algorithm

1. Load template image from project directory
2. Convert input and template to grayscale
3. Correlate the template at its own size on a reduced copy of the frame, then measure each candidate at full resolution
4. If nothing clears the confidence level, equalise local contrast and repeat step 3 for each scale in `scale_range`; the best-scoring scale wins
5. If nothing clears it again, detect SIFT keypoints, match them with FLANN, filter by distance ratio and verify with a homography
6. Return the center coordinates and the bounding box in frame pixels

#### RemoteOIR

**Location:** `optics_framework/engines/vision_models/image_models/remote_oir.py` (class `RemoteImageDetection`)

Remote Object Image Recognition service integration.

#### Key features

- Matching on a service that you run
- API integration: posts the screenshot and the template, base64 encoded, to `<url>/detect-image`
- `capabilities.method` names the matching method on the service

#### Configuration

```yaml
image_detection:
  - remote_oir:
      enabled: true
      url: "https://api.example.com/oir"
      capabilities:
        timeout: 30
        method: "template_matching"
```

`url` defaults to `http://127.0.0.1:8080`. The engine sends no API key.

### OCR/text detection models

Every OCR engine extends `TextInterface` and implements only `detect_text()`. It returns the full text and a list of `(bbox, text, confidence)`. The shared `find_element()` matches the text the same way for every engine, and each engine remembers its last 4 reads of the same pixels.

#### AppleVision

**Location:** `optics_framework/engines/vision_models/ocr_models/apple_vision.py` (class `AppleVisionHelper`)

OCR with the macOS Vision framework.

- macOS only
- `capabilities.recognition_level`: `accurate` (default) or `fast`. Another value raises `E0501`.
- `capabilities.languages`: defaults to `["en-US"]`

```yaml
text_detection:
  - apple_vision:
      enabled: true
      capabilities:
        recognition_level: "accurate"
        languages: ["en-US"]
```

#### RapidOCR

**Location:** `optics_framework/engines/vision_models/ocr_models/rapidocr.py` (class `RapidOCRHelper`)

OCR with RapidOCR on onnxruntime, on the CPU.

- Uses the models in the package, so it works offline
- Takes no settings

```yaml
text_detection:
  - rapidocr:
      enabled: true
```

#### EasyOCR

**Location:** `optics_framework/engines/vision_models/ocr_models/easyocr.py` (class `EasyOCRHelper`)

EasyOCR library integration for text detection.

#### Key features

- Multi-language support in the library; from config.yaml, English only
- Bounding box detection
- Confidence scores

#### Configuration

```yaml
text_detection:
  - easyocr:
      enabled: true
```

The engine reads a top-level `language` key (default `en`), but config.yaml drops keys other than `enabled`, `url` and `capabilities`. It does not read `languages` or `gpu`.

#### Methods

- `detect_text()` - Full text detection
- `find_element()` - Locate specific text (shared from `TextInterface`)

#### GoogleVision

**Location:** `optics_framework/engines/vision_models/ocr_models/googlevision.py` (class `GoogleVisionHelper`). `google_vision.py` is a shim, so both `google_vision` and `googlevision` work as the name in config.yaml.

Google Cloud Vision API integration.

#### Key features

- Cloud-based OCR
- Uses the Vision API `text_detection` call

#### Configuration

```yaml
text_detection:
  - google_vision:
      enabled: true
      capabilities:
        credentials_path: "/path/to/credentials.json"
```

- `capabilities.api_key`: a Vision API key
- `capabilities.credentials_path`: a service account key file
- Neither: Application Default Credentials, for example `GOOGLE_APPLICATION_CREDENTIALS`
- Both: `E0501`

#### PyTesseract

**Location:** `optics_framework/engines/vision_models/ocr_models/pytesseract.py` (class `PytesseractHelper`)

Tesseract OCR engine integration.

#### Key features

- Open-source OCR
- Needs the Tesseract program on your PATH
- Converts the frame to grayscale and binarises it with Otsu's threshold before it reads
- Fixed OCR and page segmentation modes: `--oem 3 --psm 6`

#### Configuration

```yaml
text_detection:
  - pytesseract:
      enabled: true
```

The engine reads no settings. It does not read `lang` or `config`.

#### RemoteOCR

**Location:** `optics_framework/engines/vision_models/ocr_models/remote_ocr.py` (class `RemoteOCR`)

Remote OCR service integration.

#### Key features

- OCR on a service that you run
- API integration: posts the screenshot to `<url>/detect-text`
- Custom OCR engines: `capabilities.method` names the engine on the service

#### Configuration

```yaml
text_detection:
  - remote_ocr:
      enabled: true
      url: "https://api.example.com/ocr"
      capabilities:
        timeout: 30
        method: "easyocr"
        language: "en"
```

The engine sends no API key.

## LLM models

LLM engines power [AI self-heal](https://optics-framework.org/docs/elements/self-heal) and the plain-English mode of `optics live`. They implement `LLMInterface` and are located in `optics_framework/engines/llm_models/`.

| Name in config | Location | Class |
|---|---|---|
| `gemini` | `engines/llm_models/gemini.py` | `GeminiLLM` |
| `openai` | `engines/llm_models/openai.py` | `OpenAILLM` |
| `anthropic` | `engines/llm_models/anthropic.py` | `AnthropicLLM` |

`LLMInterface` asks for `generate(prompt, images=None, system=None, response_schema=None, ...)`: a text prompt, optional images and optional structured JSON output. `generate_json` builds on it. See [llm_models](https://optics-framework.org/docs/reference/config#llm-models) for the settings.

## Engine discovery and loading

Engines are loaded by name, when the configuration asks for them:

`How a factory loads an engine named in config.yaml`:

```mermaid
graph LR
    A[Factory] --> B[Read Config Key]
    B --> C[Import Module]
    C --> D[Load Classes]
    D --> E[Check Interface]
    E --> F[Register]
    F --> G[Instantiate on Demand]
```

### Discovery process

1. The factory reads the name of each enabled entry, for example `appium`.
2. It imports the module with the same name from its package (`engines/drivers/`, etc.): `optics_framework.engines.drivers.appium`. If the module does not exist, it raises `E0601`.
3. It inspects the module's classes and takes the first concrete class that implements the interface. If there is none, it raises `E0603`.
4. It registers the module path in the module registry.
5. It makes the instance. It passes `config` and the extra arguments (`event_sdk` for drivers, `driver` for element sources) only if `__init__` names them.

`GenericFactory.register_package` can scan a whole package, but Optics does not call it. Only the engines you enable are imported, so a missing optional extra breaks only the engine that needs it.

### Configuration-based selection

The configuration selects the engines:

```yaml
driver_sources:
  - appium: {...}      # First priority
  - selenium: {...}     # Fallback
```

The factory creates an `InstanceFallback` wrapper that tries each in order. A call on the wrapper goes to each instance in turn, and returns the first result that does not raise. If all instances raise, the wrapper raises the last error. A result of `None` does not move to the next instance.

## Extension guide

### Adding a new driver

1. Create file in `optics_framework/engines/drivers/your_driver.py`. The file name is the name users write in config.yaml.
2. Implement `DriverInterface`
3. Set class attributes:

   ```python
   DEPENDENCY_TYPE = "driver_sources"
   NAME = "your_driver"
   ```

4. Factory automatically discovers it

Element sources find their driver by `NAME`, so keep it the same as the file name.

### Adding a new element source

1. Create file in `optics_framework/engines/elementsources/your_source.py`
2. Implement `ElementSourceInterface`. For a source that gets encoded screenshots from a backend, extend `EncodedScreenshotSource` and implement `capture_screenshot_bytes()`.
3. If driver-dependent, set:

   ```python
   REQUIRED_DRIVER_TYPE = "appium"  # or "selenium", "playwright", etc.
   ```

   For a source that works with any driver, set `ACCEPTS_ANY_DRIVER = True`.
4. Factory automatically matches with compatible driver

Raise `NotImplementedError` in the methods your source cannot do. The strategies then skip it for those methods.

### Adding a new vision model

1. Create file in appropriate subdirectory:
   - `image_models/` for image detection
   - `ocr_models/` for text detection
2. Implement `ImageInterface` or `TextInterface`. A `TextInterface` needs only `detect_text()`. An `ImageInterface` needs `element_exist()`, `find_element()` and `assert_elements()`.
3. Factory automatically discovers it

### Adding a new LLM model

1. Create file in `optics_framework/engines/llm_models/your_model.py`
2. Implement `LLMInterface`
3. Factory automatically discovers it

## Best practices

1. **Error handling**: Always handle driver initialization failures gracefully
2. **Resource cleanup**: Implement proper cleanup in `terminate()` methods
3. **Configuration validation**: Validate configuration in `__init__`
4. **Logging**: Use `internal_logger` for debug information
5. **Event tracking**: Integrate with `EventSDK` for action tracking
6. **Fallback support**: Design for graceful degradation

## Performance considerations

- **Screenshot caching**: Inside one keyword, each source's screenshot is captured once and shared. OCR engines remember their last reads of the same pixels.
- **Connection pooling**: Drivers should reuse connections when possible
- **Lazy loading**: Engines are loaded on demand, not at startup
- **Sequential fallback**: `InstanceFallback` tries the engines one at a time, in config order. They do not run in parallel.

## Related documentation

- [Components](https://optics-framework.org/docs/contribute/components): component architecture and factory system
- [Factory system](https://optics-framework.org/docs/contribute/components#factory-system): dynamic module discovery
- [Strategies](https://optics-framework.org/docs/contribute/strategies): strategy pattern and element location
- [Execution](https://optics-framework.org/docs/contribute/execution): test execution
- [Extending](https://optics-framework.org/docs/contribute/extending): creating custom engines
- [Error handling](https://optics-framework.org/docs/contribute/errors): error codes and handling
- [Architecture decisions](https://optics-framework.org/docs/contribute/decisions): factory pattern and engine design decisions
- [Engines and extras](https://optics-framework.org/docs/reference/engines): the engines you can turn on, and their pip extras
