docs: document LiteLLM proxy model configuration

[DivyamTalwar]

Summary

Issue #170 asks how to configure Morphik with a LiteLLM proxy or another OpenAI-compatible endpoint. Morphik already reads model definitions from [registered_models] and uses api_base for LiteLLM/OpenAI-compatible model definitions, but the Docker guide and sample configs did not show that setup clearly.

This PR documents the supported registered_models.<key>.api_base path and updates the Docker guide example to match the current backend configuration shape.

Changes

• Add commented LiteLLM proxy / OpenAI-compatible endpoint examples to morphik.toml and morphik.docker.toml.
• Add commented selector examples beside [completion].model and [embedding].model so the sample config path is end to end.
• Update the Docker guide model example to use [registered_models] keys referenced from [completion] and [embedding].
• Add a Docker guide section showing a LiteLLM proxy chat model and embedding model configured with api_base.
• Clarify that custom Docker configs must be mounted into every service that reads Morphik configuration, including both morphik and worker.
• Clarify that proxy-backed backend registered-model entries use api_base, while base_url and baseUrl examples belong to separate UI/API surfaces.
• Note that proxy-backed entries may be classified as custom in Morphik metadata/provider fields even though runtime calls still use the configured model and endpoint.
• Document Docker networking guidance for same-Compose proxy services, Docker-host proxies, and Linux host-gateway setups on every proxy-calling container, including morphik and worker.
• Note that proxy keys should come from environment/secret handling, authenticated local-looking embedding proxies also need LITELLM_DUMMY_API_KEY, real proxy credentials should not be placed in registered_models.*.api_key because registered-model config can appear in logs and model metadata responses, credentials should not be embedded in api_base / base_url / baseUrl URLs, dummy values do not secure unauthenticated local proxies, and remote proxy endpoints should use HTTPS.
• Clarify that [completion].model covers query and agent traffic, while contextual chunking and parser vision model selectors should be updated separately if those flows should also use the proxy.
• Document recreating both morphik and worker after config/env changes, with a log-based smoke check for the selected proxy model keys after exercising query and ingestion traffic.
• Warn that changing embedding models or dimensions on an existing deployment requires compatible existing vectors or a re-ingestion, migration, new collection/table, or database reset plan.

Why this matters

Self-hosted users can configure an OpenAI-compatible proxy without code changes, but they need to put the endpoint on the registered model entry used for LiteLLM-backed calls. The docs now show that path directly and avoid the older base_url example shape that does not match the backend model registry.

Tests

Commands run:

• .venv/bin/python -c 'import tomli, pathlib; [tomli.loads(pathlib.Path(p).read_text()) for p in ("morphik.toml", "morphik.docker.toml")]; print("toml parse passed")' — passed.
• .venv/bin/python extraction/parse of all toml code fences in DOCKER.md — passed; 2 snippets parsed.
• .venv/bin/python extraction/parse of all yaml code fences in DOCKER.md — passed; 2 snippets parsed.
• .venv/bin/python extraction plus bash -n syntax check for all bash code fences in DOCKER.md — passed; 8 snippets checked.
• .venv/bin/python parse of the commented litellm_proxy_chat / litellm_proxy_embedding examples, plus selector-hint, expected proxy endpoint, dimension-warning, and document_analysis exclusion checks — passed; 2 entries in each sample config parsed.
• .venv/bin/python structured assertions for exact proxy docs snippets covering same-Compose endpoint, custom-config worker mount, service recreation command, traffic-gated log smoke check, selector hints, embedding-dimension warning, log/metadata-exposure warning, credential-bearing URL warning, shared-service env wording, .env secrecy wording, and extra-selector scope — passed.
• if rg -n 'api_key = "YOUR_PROXY_API_KEY"|api_key = "dummy"|Omit `api_key`|omit `api_key`|host\\.docker\\.internal:4000", api_key|litellm_proxy_(chat|embedding).*host\\.docker\\.internal:4000|base_url = "http://ollama:11434"|provider = "ollama"|model_name = "llama3\\.2"|The default `morphik\\.toml` is configured for Docker|Only if using OpenAI|Ollama completion models|Do not use `base_url`|OPENAI_API_KEY=sk-\\.\\.\\.|<openai-or-proxy-key>|in the Morphik environment|Do not add proxy credentials|Do not commit real proxy credentials in api_key fields|may appear as `custom`|Restart Morphik|other model selector settings|contextual chunking, agent, query|document analysis, or parser vision|\\[document_analysis\\]\\.model' DOCKER.md morphik.toml morphik.docker.toml -S; then echo 'stale or unsafe proxy docs pattern remains'; exit 1; else echo 'no stale or unsafe proxy docs patterns found'; fi — passed.
• rg -n 'A Docker morphik\.toml can configure local Ollama models|proxy-backed LiteLLM/OpenAI-compatible|docker compose up -d --force-recreate morphik worker|After running one query and one small ingestion|safe only when secrets are not embedded|grep -E "litellm_proxy_\\(chat\\|embedding\\)"|/api-keys accepts base_url|stores/returns it as baseUrl|classified as custom|OpenAI-compatible proxies|client-compatibility placeholder|LITELLM_DUMMY_API_KEY|registered_models\.\*\.api_key|application or worker logs and model metadata responses|credentials or bearer tokens|baseUrlURLs|parser\\.contextual_chunking_model|\\[parser\\.vision\\]\\.model|Keep dimensions compatible with existing vectors|does not rewrite existing pgvector data|my-custom-morphik\\.toml:/app/morphik\\.toml|OPENAI_API_KEY=your-openai-or-proxy-key|Keep\.env local|LiteLLM proxy example: model|litellm_proxy_chat|litellm_proxy_embedding|OPENAI_API_KEY|dummy|proxy-calling service|host-gateway|worker|morphik|general LiteLLM|HTTPS|api_base|your-openai-or-proxy-key' DOCKER.md morphik.toml morphik.docker.toml -S — passed.
• rg -n 'for key, value in (config|self\\.model_config)\\.items\\(\\)|model_params\\[key\\] = value|litellm\\.a(completion|embedding)\\(|api_base|_extract_provider|LITELLM_DUMMY_API_KEY|host\\.docker\\.internal|ingestion_worker|embedding_model|logger\\.(info|debug).*model_config|model config|baseUrl|model_config|DOCUMENT_ANALYSIS_MODEL|contextual_chunking_model|VideoParser' core/completion/litellm_completion.py core/embedding/litellm_embedding.py core/parser/morphik_parser.py core/parser/video/parse_video.py core/api.py core/config.py core/workers/ingestion_worker.py core/services_init.py core/routes/models.py -S — passed; confirmed registered-model passthrough, local embedding key handling, provider-labeling paths, worker/service embedding usage, registered-model config logging/metadata surfaces, and selector-consumer boundaries.
• git diff --check origin/main...HEAD — passed.

Also attempted:

• Live LiteLLM proxy / Docker Compose proxy flow — not run; this PR was validated with static docs/config checks only.
• python TOML parse command — not run because python is unavailable on PATH.
• python3 TOML parse command — not run because this system Python lacks tomllib.

Risk

Risk level: low

This is a docs/comment-only change. It does not change runtime defaults, model resolution, LiteLLM parameters, or Docker behavior. The main risk is example accuracy: the examples intentionally use api_base because that is the registered-model key the current backend expects for LiteLLM/OpenAI-compatible proxy model definitions. The docs now call out that embedding model or dimension changes on existing deployments require compatible existing vectors or a data migration/re-ingestion plan.

Issue

Fixes #170.

Notes for maintainers

This PR does not add base_url alias support for registered_models. If maintainers want that, it should be a separate code change with completion and embedding tests.