The OpenAI-compatible proxy

Overview

Guardrino exposes POST /v1/chat/completions. It checks the request, forwards it to the model API you configure, checks the reply, and returns it. If a check fails, the app receives a refusal instead.

• Input. The user turns of the conversation.
• Context. Tool results and documents in the messages, read as data. Image and file parts go through the extract service first, so an instruction hidden in a screenshot or a PDF is judged like any document.
• Output. The model’s reply, with the output checks (canary, personal data, URLs).

Use it

Point your client at Guardrino instead of the model provider. The request body does not change.

from openai import OpenAI

# The only change: the base URL (and the key your Guardrino deployment expects).
client = OpenAI(base_url="https://guardrino.example/v1", api_key="YOUR_KEY")

reply = client.chat.completions.create(
    model="your-model",
    messages=[{"role": "user", "content": "Summarise this ticket."}],
    user="conversation-7f3a",  # becomes the conversation_id
)

Guardrino scores a conversation as a whole. It takes the conversation_id from the X-Guardrino-Conversation header, or from the user field when there is no header, so no client change is needed.

curl https://guardrino.example/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Guardrino-Conversation: conversation-7f3a" \
  -d '{"model": "your-model", "messages": [{"role": "user", "content": "Hello"}]}'

Configuration

The proxy is set in the policy file, in the [proxy] section.

block_status = 403            # answer a refused message with HTTP 403 (default 400)

[proxy]
upstream = "https://llm.example/v1"   # the model API Guardrino forwards to
api_key = "UPSTREAM_KEY"              # optional: when unset, the caller's key is passed through
buffer_output = false                 # true: hold the reply until it has been checked

When a message is refused

A refusal comes back in the OpenAI error shape, so existing error handling in your app keeps working.

{
  "error": {
    "message": "The request was blocked by Guardrino policy.",
    "type": "guardrino_blocked",
    "param": null,
    "code": "content_blocked",
    "request_id": "req-42"
  }
}

Streamed replies