Evaluation Endpoints

import uuid

# One session id for the whole workflow (created once, reused on every call), and one
# roundtrip id per turn that pairs a request with its response.
session_id = str(uuid.uuid4())     # in practice, created once when the workflow begins
roundtrip_id = str(uuid.uuid4())   # one per turn

# One inline turn: screen the request, call the model, screen the response.
raw = client.runtime.with_raw_response.evaluate_request(
    body=request_payload,
    hl_runtime_session_id=session_id,
    extra_headers={"HL-Roundtrip-Id": roundtrip_id},
)
if raw.headers.get("hl-runtime-action") == "BLOCK":
    # Policy blocked. `raw.parse()` is a provider response-shaped block message
    # ("Message was blocked"); return it without calling the model.
    return raw.parse()

checked_request = raw.parse()  # allowed/redacted request payload — forward this, not your original
model_response = call_model(checked_request)

# Reuse the SAME roundtrip id so the two halves pair up.
resp = client.runtime.with_raw_response.evaluate_response(
    body=model_response,
    hl_runtime_session_id=session_id,
    extra_headers={"HL-Roundtrip-Id": roundtrip_id},
)
if resp.headers.get("hl-runtime-action") == "BLOCK":
    return resp.parse()  # provider response-shaped block message

return resp.parse()  # the (possibly redacted) payload to return to the caller

response = client.runtime.evaluate_request(
    body={
        "model": "gpt-4o",
        "messages": [
            {"role": "user", "content": "What is the largest moon of Jupiter?"}
        ],
    },
    hl_runtime_session_id=session_id,                 # groups this call into the session
    extra_headers={"HL-Roundtrip-Id": roundtrip_id},  # pairs this request with its response
)

response = client.runtime.evaluate_response(
    body={
        "id": "chatcmpl-123",
        "object": "chat.completion",
        "model": "gpt-4o",
        "choices": [
            {
                "index": 0,
                "message": {
                    "role": "assistant",
                    "content": "The largest moon of Jupiter is Ganymede.",
                },
                "finish_reason": "stop",
            }
        ],
    },
    hl_runtime_session_id=session_id,                 # same session id as the request
    extra_headers={"HL-Roundtrip-Id": roundtrip_id},  # same roundtrip id pairs the two halves
)

response = client.runtime.evaluate_interaction(
    metadata={
        "model": "gpt-4o",
        "provider": "openai",
        "requester_id": "agent-001",
        "external_session_id": "7f3a1c2e-0a4b-4c8d-9e1f-2b3c4d5e6f70",
    },
    interaction={
        "messages": [
            {
                "role": "user",
                "content": [{"type": "text", "text": "Summarize the latest sales report."}],
            },
            {
                "role": "assistant",
                "content": [
                    {
                        "type": "tool_use",
                        "id": "call_1",
                        "tool_name": "fetch_report",
                        "tool_input": {"name": "sales-q2"},
                    }
                ],
            },
            {
                "role": "tool",
                "content": [
                    {"type": "tool_result", "id": "call_1", "result": "Q2 revenue up 12% over Q1."}
                ],
            },
            {
                "role": "assistant",
                "content": [{"type": "text", "text": "Q2 revenue rose 12% versus Q1."}],
            },
        ]
    },
)