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:
| Call | Request | Notes |
|---|---|---|
| Chat | POST <INFERENCE_REMOTE_URL>/v1/chat/completions | Always sent with "stream": true. FACE reads server-sent events. |
| Auth | Authorization: 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/GenerateA 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
| Situation | What you see |
|---|---|
INFERENCE_REMOTE_URL unset | The process exits at boot with no inference endpoint configured: INFERENCE_REMOTE_URL is unset or blank. |
| An endpoint was never configured for one call path | That 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 empty | An 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 served | A per-call error from the plane. The boot check does not catch it. |