Chat API¶

What it does. POST /v1/chat/completions is the endpoint you point your existing OpenAI client at. G1-Proxy screens the prompt, forwards the request to your upstream LLM, scores the answer across the nine detection axes, and hands back the ordinary OpenAI response with a geodesia object attached. Blocked requests come back with finish_reason: "content_filter", which standard OpenAI clients already handle.

Everything the endpoint does not recognise as a Geodesia control field is forwarded verbatim to the upstream — that is what makes it a drop-in replacement for vLLM, SGLang or the OpenAI API itself.

Three wire formats, one pipeline:

Call it¶

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "stream": false,
    "messages": [{"role": "user", "content": "What is the capital of France?"}]
  }' | jq '{
    answer:   .choices[0].message.content,
    decision: .glad_decision,
    brake:    .geodesia.brake,
    axes:     .geodesia.axis_energy
  }'

from openai import OpenAI

# Point the official client at the proxy. Nothing else changes.
client = OpenAI(base_url="http://localhost:8080/gw/v1", api_key="not-needed-locally")

r = client.chat.completions.create(
    model="my-model",
    messages=[{"role": "user", "content": "What is the capital of France?"}],
    stream=False,
    extra_body={                       # Geodesia extension fields go here
        "context": "",
        "thinking_level": 0,
    },
)
print(r.choices[0].message.content)

# The detection payload rides on the raw response, outside the typed model.
g = r.model_extra["geodesia"]
print(r.model_extra["glad_decision"], g["dominant_axis"])
for axis, e in g["axis_energy"].items():
    print(f"  {axis:20s} p={e['p_detector']:.3f} thr={e['threshold']:.3f} flag={e['flag']}")

import OpenAI from "openai"

const client = new OpenAI({
  baseURL: "http://localhost:8080/gw/v1",
  apiKey: "not-needed-locally",
})

const r = (await client.chat.completions.create({
  model: "my-model",
  stream: false,
  messages: [{ role: "user", content: "What is the capital of France?" }],
  // @ts-expect-error — Geodesia extension fields are not in the OpenAI types
  thinking_level: 0,
})) as any

console.log(r.choices[0].message.content)
console.log(r.glad_decision, r.geodesia.dominant_axis)

What comes back¶

The standard OpenAI body, plus three top-level fields and the geodesia object:

{
  "id": "chatcmpl-geodesia-1718000000000",
  "object": "chat.completion",
  "model": "my-model",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "The capital of France is Paris." },
      "finish_reason": "stop"
    }
  ],
  "glad_decision": "passed",
  "glad_mode": "blocking",
  "geodesia": {
    "axis_energy": {
      "halluc_context":    { "p_detector": 0.12, "flag": false, "threshold": 0.6475, "available": true },
      "halluc_closedbook": { "p_detector": 0.08, "flag": false, "threshold": 0.58,   "fact_seeking": true, "available": true },
      "prompt_safety":     { "p_detector": 0.02, "flag": false, "threshold": 0.9215, "available": true },
      "answer_safety":     { "p_detector": 0.03, "flag": false, "threshold": 0.7295, "available": true },
      "jailbreak":         { "p_detector": 0.01, "flag": false, "threshold": 0.9997, "available": true },
      "rag_jailbreak":     { "p_detector": 0.04, "flag": false, "threshold": 0.2501, "available": true },
      "profanity":         { "p_detector": 0.00, "flag": false, "threshold": 0.90,   "available": true },
      "out_of_scope":      { "p_detector": 0.01, "flag": false, "threshold": 0.90,   "available": true },
      "prompt_complexity": { "p_detector": 0.22, "flag": false, "threshold": 0.50,   "available": true }
    },
    "brake": false,
    "dominant_axis": "halluc_context"
  }
}

When the request is blocked, the content is replaced and finish_reason becomes content_filter:

{
  "choices": [
    {
      "message": { "role": "assistant", "content": "[Geodesia blocked — prompt safety (input)]" },
      "finish_reason": "content_filter"
    }
  ],
  "glad_decision": "blocked",
  "glad_mode": "blocking",
  "glad_scores": { "safety_decision_rule": "prompt_safety" }
}

Request reference¶

Standard OpenAI fields¶

Forwarded to the upstream unchanged.

Geodesia extension fields¶

Recognised by the proxy and never forwarded to the upstream.

How an Application is resolved¶

The proxy picks the Application in this order:

1. application_id or app_id on the body,
2. the X-Geodesia-App header,
3. the Application that owns the g1k_… key in Authorization: Bearer …,
4. otherwise default.

An explicit id always wins, including an explicit "default". The API-key fallback exists so a raw client authenticating with nothing but its key still lands on its own Application. A paused or killed Application keeps its id on the audit record but is served with the global configuration.

Streaming¶

With stream: true the response is SSE (OpenAI format) or NDJSON (Ollama format).

curl -N -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"my-model","stream":true,
       "messages":[{"role":"user","content":"Explain TLS in two sentences."}]}'

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/gw/v1", api_key="not-needed-locally")

stream = client.chat.completions.create(
    model="my-model",
    messages=[{"role": "user", "content": "Explain TLS in two sentences."}],
    stream=True,
)
for chunk in stream:
    extra = chunk.model_extra or {}
    if "geodesia" in extra:                       # first chunk: input analysis; last: full analysis
        print("\n[geodesia]", extra["geodesia"])
    delta = chunk.choices[0].delta.content if chunk.choices else None
    if delta:
        print(delta, end="", flush=True)
    if chunk.choices and chunk.choices[0].finish_reason == "content_filter":
        print("\n-- halted by Geodesia --")

const stream = await client.chat.completions.create({
  model: "my-model",
  stream: true,
  messages: [{ role: "user", content: "Explain TLS in two sentences." }],
})

for await (const chunk of stream) {
  const c = chunk as any
  if (c.geodesia) console.log("\n[geodesia]", c.geodesia)
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "")
  if (chunk.choices[0]?.finish_reason === "content_filter") {
    console.log("\n-- halted by Geodesia --")
  }
}

Where the payload arrives

1. First chunk — the input-region analysis (prompt_safety, jailbreak, and the other prompt axes) rides on the first empty-delta chunk, so you can show safety status before a single token of the answer.
2. Final chunk — or the early-stop chunk — carries the full analysis for every axis.

The mid-stream brake. The proxy re-reads the accumulating generation every cadence_tokens tokens (default 32). If an output-region axis fires before generation finishes it injects \n\n[Geodesia: generation halted — energy barrier], sends a final chunk with finish_reason: "content_filter" and the detection payload, then data: [DONE].

Tool calling — tools / tool_choice¶

tools and tool_choice are forwarded to the upstream unchanged (see Request reference above) — the proxy does not rewrite your tool schemas. What it does do is translate whatever the upstream's serving stack returns for a tool call back into standard OpenAI shape: an accumulating delta.tool_calls on each streaming chunk, message.tool_calls on the non-streaming response, and finish_reason: "tool_calls". Any provider-native tool-call syntax the underlying model would otherwise leak into plain text (e.g. a bracketed marker or an XML-ish block, depending on the serving stack) never reaches the client as content.

This requires the upstream's own serving stack to have tool-call parsing turned on — for example vLLM's --enable-auto-tool-choice --tool-call-parser <family> (the parser family must match the model's chat template). Check GET /v1/models — a "tool_calling" entry in capabilities confirms the deployment is configured for it; if it's absent, tools is still forwarded but the model's raw tool-call output may come back as plain content instead of tool_calls.

curl -N -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "stream": false,
    "tool_choice": "auto",
    "tools": [{
      "type": "function",
      "function": {
        "name": "web_search",
        "description": "Search the web and return ranked results with URLs.",
        "parameters": {
          "type": "object",
          "properties": {
            "query": { "type": "string" },
            "max_results": { "type": "integer" }
          },
          "required": ["query"]
        }
      }
    }],
    "messages": [{"role": "user", "content": "Search the web for the current prime minister of Italy."}]
  }'

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/gw/v1", api_key="not-needed-locally")

r = client.chat.completions.create(
    model="my-model",
    tool_choice="auto",
    tools=[{
        "type": "function",
        "function": {
            "name": "web_search",
            "description": "Search the web and return ranked results with URLs.",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}, "max_results": {"type": "integer"}},
                "required": ["query"],
            },
        },
    }],
    messages=[{"role": "user", "content": "Search the web for the current prime minister of Italy."}],
)
call = r.choices[0].message.tool_calls[0]
print(call.function.name, call.function.arguments)   # web_search {"query": "...", "max_results": ...}

What comes back (non-streaming):

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": { "name": "web_search", "arguments": "{\"query\": \"...\", \"max_results\": 5}" }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

Streaming carries the same call as incremental delta.tool_calls fragments — id/type/function.name on the first fragment for a given index, function.arguments concatenated across the rest — exactly the shape any OpenAI-compatible SDK already knows how to accumulate. Parallel tool calls (the model requesting more than one function in the same turn) come back as separate entries keyed by index, each with its own id.

Completing the round trip¶

After you execute the tool, send the conversation back with the assistant's tool_calls from the previous turn and one role: "tool" result message per call — the proxy forwards both unchanged to the upstream, same as any OpenAI-compatible endpoint:

{
  "model": "my-model",
  "tools": [ /* same schema as before */ ],
  "messages": [
    {"role": "user", "content": "Search the web for the current prime minister of Italy."},
    {"role": "assistant", "content": null, "tool_calls": [
      {"id": "call_abc123", "type": "function",
       "function": {"name": "web_search", "arguments": "{\"query\": \"prime minister of Italy\"}"}}
    ]},
    {"role": "tool", "tool_call_id": "call_abc123", "content": "Giorgia Meloni is the Prime Minister of Italy."}
  ]
}

Ollama format — POST /api/chat¶

The same pipeline in Ollama's wire format. Every Geodesia extension field above works identically.

curl -s http://localhost:8080/gw/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2",
    "stream": false,
    "messages": [{"role": "user", "content": "What is the capital of France?"}],
    "context": "",
    "mode": "block"
  }' | jq '{answer: .message.content, decision: .glad_decision}'

import httpx

r = httpx.post("http://localhost:8080/gw/api/chat", json={
    "model": "llama3.2",
    "stream": False,
    "messages": [{"role": "user", "content": "What is the capital of France?"}],
    "mode": "block",
}, timeout=120).json()
print(r["message"]["content"], r["glad_decision"])

const r = await fetch("http://localhost:8080/gw/api/chat", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    model: "llama3.2",
    stream: false,
    messages: [{ role: "user", content: "What is the capital of France?" }],
    mode: "block",
  }),
}).then(r => r.json())
console.log(r.message.content, r.glad_decision)

What comes back

{
  "model": "llama3.2",
  "message": { "role": "assistant", "content": "The capital of France is Paris." },
  "done": true,
  "glad_decision": "passed",
  "glad_mode": "blocking",
  "geodesia": { "axis_energy": {}, "brake": false, "dominant_axis": "halluc_context" }
}

Response reference¶

Top-level extension fields¶

The geodesia object¶

Full field-by-field treatment: API Response Format.

More examples¶

Grounded request — hallucination scored against your own text¶

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "stream": false,
    "context": "The Eiffel Tower was built between 1887 and 1889 and stands 330 metres tall.",
    "messages": [{"role":"user","content":"How tall is the Eiffel Tower?"}]
  }' | jq '{answer: .choices[0].message.content, halluc: .geodesia.axis_energy.halluc_context}'

Passthrough — see what the model would have said¶

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "stream": false,
    "mode": "passthrough",
    "messages": [{"role":"user","content":"How do I pick a lock?"}]
  }' | jq '{answer: .choices[0].message.content, decision: .glad_decision, axis: .glad_scores}'

Loosen two axes for one request¶

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "my-model",
    "stream": false,
    "threshold_overrides": {"prompt_safety": 0.70, "jailbreak": 0.55},
    "messages": [{"role":"user","content":"Explain a penetration test methodology."}]
  }'

Answer from a knowledge base¶

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "X-Geodesia-App: support_bot" \
  -d '{
    "model": "my-model",
    "stream": false,
    "rag": {"collection_id": "my-policy-docs", "top_k": 5, "verify": true},
    "messages": [{"role":"user","content":"What is our refund policy?"}]
  }' | jq '{answer: .choices[0].message.content, sources: [.geodesia.rag.sources[].title]}'

Route by Application API key¶

curl -s http://localhost:8080/gw/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer g1k_live_9c1f2a7b4e0d" \
  -d '{"model":"my-model","stream":false,
       "messages":[{"role":"user","content":"Hello"}]}'

No application_id needed — the key identifies the Application, and its policy, thresholds, cost centre and upstream binding all apply.