Skip to content

Model plane

All of FACE’s reasoning runs on a model plane inside the deployment’s own cluster: text generation, vision grading, and every agent (rules, posture, twins, compliance, the fetch cascade). FACE is an HTTP client of that plane. It ships no inference binary, starts no model process and has no local fallback. TIDE runs the plane, in the inference namespace, behind its model router. Nothing in FACE’s client is specific to one engine.

The contract

The plane must speak the OpenAI-compatible HTTP API:

CallRequestNotes
ChatPOST <INFERENCE_REMOTE_URL>/v1/chat/completionsAlways sent with "stream": true. FACE reads server-sent events.
AuthAuthorization: Bearer <INFERENCE_API_KEY>Sent only when INFERENCE_API_KEY is non-empty.

The model field carries a task id, not a file name: default for general reasoning, coder for code tasks, vision for vision tasks, and the token FACE_GUARD_MODEL names (usually guard) for the guard model that screens agent text. The model router uses this id to send each task to the right tier. Vision and voice calls go to VISION_REMOTE_URL and VOICE_REMOTE_URL. Both default to INFERENCE_REMOTE_URL.

FACE makes no embedding call. Its retrieval is grep over plain text, so the plane needs no embedding model for FACE. See Grounding.

Bringing a plane up and pointing FACE at it

Start an OpenAI-compatible server

In a cluster, TIDE’s inference manifests provide the plane. Use the Service URL TIDE gives you. For a local run, any OpenAI-compatible server serving a chat model works.

Set the endpoint variables

export INFERENCE_REMOTE_URL='http://127.0.0.1:<chat-port>'

In a cluster you do not set them by hand. The operator sets them on the control plane, and face-runner’s manifest sets them on the runner. INFERENCE_REMOTE_URL and VISION_REMOTE_URL point at TIDE’s model router (Service model-router in the inference namespace, port 8080), and VOICE_REMOTE_URL at the Service inference-voice in the same namespace, port 8080.

FACE sizes each model call from the decode rate the router publishes for the tier, or from the rate it measures on the plane’s own answers. The operator’s INFERENCE_DECODE_TOK_S is only the fallback (see Configuration).

Check the boot log

A healthy start logs:

🧭 Routing reasoning to the shared inference plane at <url> (no local model server)

Prove the plane answers through FACE

The boot check only proves that a URL is set. To prove that a model answers, sign in and call ModelService/Generate through FACE itself:

TOK=$(grpcurl -plaintext -d '{"method":"AUTH_METHOD_CREDENTIALS","username":"'"$ADMIN_EMAIL"'","password":"'"$ADMIN_PASSWORD"'"}' \
  127.0.0.1:$PORT semantics.v1.IdentityService/Login | grep -o '"token": "[^"]*"' | cut -d'"' -f4)
test -n "$TOK" || echo "LOGIN RETURNED NO TOKEN"
grpcurl -plaintext -H "authorization: Bearer $TOK" \
  -d '{"prompt":"Say hello in one sentence.","temperature":0,"max_tokens":40}' \
  127.0.0.1:$PORT semantics.v1.ModelService/Generate

A reply with model text and "finishReason": "stop" means the whole path works. In a cluster, run this against a kubectl port-forward to the pod’s app port. The login field is token. If that field comes back empty, the next call fails with invalid or expired session token, and the error points at the wrong call.

What each failure looks like

SituationWhat you see
INFERENCE_REMOTE_URL unsetThe process exits at boot with no inference endpoint configured: INFERENCE_REMOTE_URL is unset or blank.
An endpoint was never configured for one call pathThat RPC fails with FailedPrecondition: <what> is unavailable: no inference endpoint configured (INFERENCE_REMOTE_URL is unset or blank)…
The plane requires a token and INFERENCE_API_KEY is emptyAn HTTP 401 on each call. It is not a boot failure.
The plane is reachable but the model is still loading, or the model id is not servedA per-call error from the plane. The boot check does not catch it.