External Endpoints
==================

Synthetic Heart supports connecting to external AI services through the
`External Endpoints` section in the Web UI. External endpoints can be used as
first-class providers for the built-in `cortex`, `vox`, `auris`, and `live`
subsystems.

Overview
--------

The External Endpoints workflow is designed to be simple and guided for users
who do not already know provider URLs or configuration details.

- Known providers are exposed as built-in presets in the Add Endpoint wizard.
- Presets pre-fill the protocol, base URL, and subsystem defaults.
- For commercial providers, only the API key is typically required.
- Custom endpoints are still supported and remain fully editable.

Supported endpoint types include:

- Gemini
- Anthropic
- OpenRouter
- GitHub Models / Copilot
- Ollama local hosts
- Selenium LLM Engine
- Generic OpenAI-compatible services
- Legacy HTTP TTS services via ``custom`` mode

Note
----

Each provider preset is implemented as a separate JSON file under the
project-level ``providers/`` directory. This keeps the core engine agnostic and
allows users to remove unused provider presets without breaking the rest of the
project.

Built-in default endpoint
-------------------------

Selenium LLM Engine is distributed as a default endpoint for new installs.
It is available automatically, but users may remove it if they do not need it.
If removed, it can be restored from the provider presets list.

Getting started
---------------

1. Open the Web UI and navigate to **Settings > External Endpoints**.
2. Click **+ Add Endpoint**.
3. Choose a provider preset or select **Custom Endpoint**.
4. Complete the form:
   - ``Name``: internal identifier (unique engine name)
   - ``Display Label``: human-readable label
   - ``Base URL``: pre-filled for known providers or entered manually
   - ``API Key``: required only when the provider needs one
   - ``Capabilities``: select which subsystems the endpoint should support
5. Save the endpoint.

After saving, Synthetic Heart performs a probe to detect capabilities, available
models, and register the endpoint with the chosen subsystems.

Provider presets
----------------

Known providers appear as a preset grid when adding a new endpoint. A preset
usually does the following:

- pre-fills the protocol and base URL
- sets sensible default capability mappings
- reduces the configuration burden to just an API key and a display name
- keeps the base URL locked by default for known providers, while still
  allowing manual override if needed

The Custom Endpoint preset is also available for any service that is not
already covered by the built-in presets.

Probe status
------------

The endpoint card displays probe status:

- ``success``: reachable endpoint, models enumerated
- ``failed``: endpoint unreachable or unsupported response
- ``pending``: probe is in progress
- ``never``: probe has not been run yet

Model list and default model
---------------------------

- After a successful probe, available models appear in the endpoint card.
- If no default model is configured, the first discovered model is set
  automatically.
- You can change the default model at any time from the card.
- If the model list is empty, verify that the endpoint supports ``/v1/models``
and returns a valid OpenAI-style response.

Subsystem mapping
-----------------

Each endpoint may be mapped to one or more subsystems:

- ``cortex``: chat and reasoning
- ``vox``: text-to-speech
- ``auris``: speech-to-text
- ``live``: real-time or multimodal behavior

The endpoint card shows the current effective mapping. To change mapping,
open the endpoint with the **Edit** button and update the capability checkboxes.

Use cases
---------

- Local development and testing:

  - Start Selenium LLM Engine and add it as an external endpoint using the
    built-in Selenium preset.
  - Confirm probe success and map the endpoint to ``cortex`` for chat usage.

- Multi-provider setups:

  - Add Gemini, Anthropic, OpenRouter, or GitHub Models endpoints.
  - Map each endpoint to the subsystems where it is strongest.

Legacy HTTP TTS endpoints
------------------------

Legacy TTS servers can still be integrated as a Vox provider using the
``custom`` protocol.

- ``Protocol``: ``custom``
- ``Base URL``: root path of the legacy TTS server
- ``Extra Config``: add at least ``{"legacy_http_tts": true}``

Optional extra config keys:

- ``tts_voice_wav``: path to the reference WAV file used by the remote server
- ``tts_endpoint_path``: custom POST path when the server does not accept
  requests at the base URL

After saving, set ``ACTIVE_VOX_ENGINE`` to the endpoint ``Name`` you created.
This registers the endpoint as a first-class Vox engine.

Troubleshooting
---------------

- If probe fails:
  - verify network connectivity from inside the container
  - use container DNS such as ``host.docker.internal`` when needed
  - verify the endpoint exposes ``/.well-known/openai-configuration`` and
    ``/v1/models``
- If the model list is missing:
  - ensure the provider returns valid ``data[]`` objects with ``id`` fields
  - check whether an API key or provider-specific permission is required

API Reference
-------------

See ``core/external_endpoints/registry.py`` and
``core/external_endpoints/probe.py`` for implementation details and field
meanings.