From 0b4c4f0698f9fdd3338dbe755cd722973b21c2b9 Mon Sep 17 00:00:00 2001 From: Ilker Manap Date: Sun, 4 Oct 2026 12:40:26 +0200 Subject: [PATCH] Put guard policies in the configuration reference Co-Authored-By: Claude Opus 5.5 (1M context) --- docs/reference.md | 199 +++++++++++++++++++++++++++++++ internal/docgen/reference_gen.go | 36 ++++++ internal/docgen/render.go | 1 + 3 files changed, 236 insertions(+) diff --git a/docs/reference.md b/docs/reference.md index dabf5551..bfeba263 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -108,11 +108,26 @@ rather than repeated. | `path` | `string` | [OriginFile](#originfile) | | `sha256` | `string` | [OriginFile](#originfile) | | `bytes` | `int64` | [OriginFile](#originfile) | +| `name` | `string` | [Pattern](#pattern) | +| `regex` | `string` | [Pattern](#pattern) | +| `action` | `string` | [Pattern](#pattern) | | `disabled` | `bool` | [Personal](#personal) | | `rpm` | `int` | [Personal](#personal) | | `tpm` | `int` | [Personal](#personal) | | `budget` | `float64` | [Personal](#personal) | | `period` | `string` | [Personal](#personal) | +| `mode` | `string` | [Policy](#policy) | +| `fail` | `string` | [Policy](#policy) | +| `no_store` | `bool` | [Policy](#policy) | +| `input` | `Rules` | [Policy](#policy) | +| `output` | `Rules` | [Policy](#policy) | +| `tools` | `Tools` | [Policy](#policy) | +| `max_output_tokens` | `int` | [Policy](#policy) | +| `system_prompt` | `string` | [Policy](#policy) | +| `drop_client_system` | `bool` | [Policy](#policy) | +| `require_capabilities` | `bool` | [Policy](#policy) | +| `validate_structured` | `bool` | [Policy](#policy) | +| `stream` | `string` | [Policy](#policy) | | `enabled` | `bool` | [Prefix](#prefix) | | `max_nodes` | `int` | [Prefix](#prefix) | | `min_match` | `int` | [Prefix](#prefix) | @@ -156,6 +171,10 @@ rather than repeated. | `timeouts` | `Timeouts` | [Router](#router) | | `scoring` | `Scoring` | [Router](#router) | | `admission` | `Admission` | [Router](#router) | +| `pii` | `map[string]string` | [Rules](#rules) | +| `injection` | `string` | [Rules](#rules) | +| `deny` | `[]Pattern` | [Rules](#rules) | +| `max_chars` | `int` | [Rules](#rules) | | `python` | `string` | [SGLangConfig](#sglangconfig) | | `ttft_p99` | `time.Duration` | [SLO](#slo) | | `tpot_p99` | `time.Duration` | [SLO](#slo) | @@ -202,6 +221,11 @@ rather than repeated. | `first_token` | `time.Duration` | [Timeouts](#timeouts) | | `idle` | `time.Duration` | [Timeouts](#timeouts) | | `total` | `time.Duration` | [Timeouts](#timeouts) | +| `allow` | `[]string` | [Tools](#tools) | +| `deny` | `[]string` | [Tools](#tools) | +| `on_denied` | `string` | [Tools](#tools) | +| `max_calls_per_turn` | `int` | [Tools](#tools) | +| `validate_arguments` | `bool` | [Tools](#tools) | | `endpoint` | `string` | [Tracing](#tracing) | | `sample_ratio` | `float64` | [Tracing](#tracing) | | `bin` | `string` | [VLLMConfig](#vllmconfig) | @@ -247,6 +271,8 @@ rather than repeated. | `sglang` | `SGLangConfig` | [engines.Config](#enginesconfig) | | `llamacpp` | `LlamaCppConfig` | [engines.Config](#enginesconfig) | | `sim` | `SimConfig` | [engines.Config](#enginesconfig) | +| `default` | `[]string` | [guard.Config](#guardconfig) | +| `policies` | `map[string]Policy` | [guard.Config](#guardconfig) | | `work_dir` | `string` | [supervisor.Config](#supervisorconfig) | | `log_lines` | `int` | [supervisor.Config](#supervisorconfig) | | `stop_timeout` | `time.Duration` | [supervisor.Config](#supervisorconfig) | @@ -934,6 +960,20 @@ Takes a [PreviousOrigin](#previousorigin) block. `int64` +## Pattern + +### `name` + +`string` + +### `regex` + +`string` + +### `action` + +`string` + ## Personal ### `disabled` @@ -961,6 +1001,91 @@ Budget is in whole units per Period ("day" or "month"). `string` +## Policy + +### `mode` + +`string` + +Mode: enforce acts, shadow only records what it would have done, off +does nothing. Empty is enforce. + +### `fail` + +`string` + +Fail: what happens when a policy cannot judge — a judge model down or +over its latency budget. open serves, closed refuses. Empty is open. + +### `no_store` + +`bool` + +NoStore keeps nothing of the request: no stored conversation, no +memory notes, no prefix routing, no fallback outside the cluster. + +### `input` + +`Rules` + +Takes a [Rules](#rules) block. + +### `output` + +`Rules` + +Takes a [Rules](#rules) block. + +### `tools` + +`Tools` + +Takes a [Tools](#tools) block. + +### `max_output_tokens` + +`int` + +MaxOutputTokens is put in a request that asks for no limit; one +asking for more is lowered to it. + +### `system_prompt` + +`string` + +SystemPrompt is put before every request's messages. + +### `drop_client_system` + +`bool` + +DropClientSystem removes the caller's own system and developer +messages, so only the pinned prompt instructs the model. + +### `require_capabilities` + +`bool` + +RequireCapabilities refuses a request offering tools, or sending +images, to a model whose catalog entry does not say it takes them. + +### `validate_structured` + +`bool` + +ValidateStructured checks an answer against the JSON schema the +request asked for in response_format: one that does not fit is +stopped — or, streamed a sentence at a time, flagged, having been +sent already. + +### `stream` + +`string` + +Stream: sentence scans a streamed answer a sentence at a time, +releasing each once it passes; buffer_all holds the whole answer +until it is judged. Empty is sentence. + ## Prefix ### `enabled` @@ -1257,6 +1382,33 @@ Takes a [Scoring](#scoring) block. Takes a [Admission](#admission) block. +## Rules + +### `pii` + +`map[string]string` + +PII maps a kind (email, phone, iban, card, tckn, ip, secret) to what is +done when it is found: flag, redact or block. + +### `injection` + +`string` + +Injection is what is done on signs of prompt injection: flag or block. + +### `deny` + +`[]Pattern` + +Deny are patterns, matched against the text as a model reads it. + +### `max_chars` + +`int` + +MaxChars refuses text longer than this; zero is no limit. + ## SGLangConfig ### `python` @@ -1504,6 +1656,8 @@ are checked for, and what is done. Applied to every request through guard.default, and to parts of the tenancy tree by attaching them (llmgw ctl guard attach). Empty checks nothing. +Takes a [guard.Config](#guardconfig) block. + ### `firewall_networks` `[]string` @@ -1615,6 +1769,41 @@ about a hundred tokens on a slow model. `time.Duration` +## Tools + +### `allow` + +`[]string` + +Allow, when set, are the only tool names a request may offer and a +model may call. + +### `deny` + +`[]string` + +Deny are tool names never offered or called. + +### `on_denied` + +`string` + +OnDenied is strip (the tool is removed from the request) or block. +Empty is strip. + +### `max_calls_per_turn` + +`int` + +MaxCallsPerTurn stops an answer calling more tools than this. + +### `validate_arguments` + +`bool` + +ValidateArguments checks a call's arguments against the parameters +schema the request declared for the tool. + ## Tracing ### `endpoint` @@ -1931,6 +2120,16 @@ Takes a [LlamaCppConfig](#llamacppconfig) block. Takes a [SimConfig](#simconfig) block. +## guard.Config + +### `default` + +`[]string` + +### `policies` + +`map[string]Policy` + ## supervisor.Config ### `work_dir` diff --git a/internal/docgen/reference_gen.go b/internal/docgen/reference_gen.go index c2137ad0..0ddf61f5 100644 --- a/internal/docgen/reference_gen.go +++ b/internal/docgen/reference_gen.go @@ -129,6 +129,11 @@ var Reference = []Block{ {Key: "sha256", Type: "string", Doc: "", Nested: ""}, {Key: "bytes", Type: "int64", Doc: "", Nested: ""}, }}, + {Package: "guard", Name: "Pattern", Title: "Pattern", Doc: "", Fields: []Field{ + {Key: "name", Type: "string", Doc: "", Nested: ""}, + {Key: "regex", Type: "string", Doc: "", Nested: ""}, + {Key: "action", Type: "string", Doc: "", Nested: ""}, + }}, {Package: "config", Name: "Personal", Title: "Personal", Doc: "", Fields: []Field{ {Key: "disabled", Type: "bool", Doc: "Disabled refuses personal keys and personal chat; people then use the\ngateway only through projects they are members of.", Nested: ""}, {Key: "rpm", Type: "int", Doc: "", Nested: ""}, @@ -136,6 +141,20 @@ var Reference = []Block{ {Key: "budget", Type: "float64", Doc: "Budget is in whole units per Period (\"day\" or \"month\").", Nested: ""}, {Key: "period", Type: "string", Doc: "", Nested: ""}, }}, + {Package: "guard", Name: "Policy", Title: "Policy", Doc: "", Fields: []Field{ + {Key: "mode", Type: "string", Doc: "Mode: enforce acts, shadow only records what it would have done, off\ndoes nothing. Empty is enforce.", Nested: ""}, + {Key: "fail", Type: "string", Doc: "Fail: what happens when a policy cannot judge — a judge model down or\nover its latency budget. open serves, closed refuses. Empty is open.", Nested: ""}, + {Key: "no_store", Type: "bool", Doc: "NoStore keeps nothing of the request: no stored conversation, no\nmemory notes, no prefix routing, no fallback outside the cluster.", Nested: ""}, + {Key: "input", Type: "Rules", Doc: "", Nested: "guard.Rules"}, + {Key: "output", Type: "Rules", Doc: "", Nested: "guard.Rules"}, + {Key: "tools", Type: "Tools", Doc: "", Nested: "guard.Tools"}, + {Key: "max_output_tokens", Type: "int", Doc: "MaxOutputTokens is put in a request that asks for no limit; one\nasking for more is lowered to it.", Nested: ""}, + {Key: "system_prompt", Type: "string", Doc: "SystemPrompt is put before every request's messages.", Nested: ""}, + {Key: "drop_client_system", Type: "bool", Doc: "DropClientSystem removes the caller's own system and developer\nmessages, so only the pinned prompt instructs the model.", Nested: ""}, + {Key: "require_capabilities", Type: "bool", Doc: "RequireCapabilities refuses a request offering tools, or sending\nimages, to a model whose catalog entry does not say it takes them.", Nested: ""}, + {Key: "validate_structured", Type: "bool", Doc: "ValidateStructured checks an answer against the JSON schema the\nrequest asked for in response_format: one that does not fit is\nstopped — or, streamed a sentence at a time, flagged, having been\nsent already.", Nested: ""}, + {Key: "stream", Type: "string", Doc: "Stream: sentence scans a streamed answer a sentence at a time,\nreleasing each once it passes; buffer_all holds the whole answer\nuntil it is judged. Empty is sentence.", Nested: ""}, + }}, {Package: "config", Name: "Prefix", Title: "Prefix", Doc: "", Fields: []Field{ {Key: "enabled", Type: "bool", Doc: "", Nested: ""}, {Key: "max_nodes", Type: "int", Doc: "MaxNodes bounds the tree, MinMatch is the shortest match worth acting on\nin bytes, and TTL is how long an entry is believed — an engine evicts on\nits own schedule, so an old record may describe a cache that is gone.", Nested: ""}, @@ -187,6 +206,12 @@ var Reference = []Block{ {Key: "scoring", Type: "Scoring", Doc: "", Nested: "config.Scoring"}, {Key: "admission", Type: "Admission", Doc: "", Nested: "config.Admission"}, }}, + {Package: "guard", Name: "Rules", Title: "Rules", Doc: "", Fields: []Field{ + {Key: "pii", Type: "map[string]string", Doc: "PII maps a kind (email, phone, iban, card, tckn, ip, secret) to what is\ndone when it is found: flag, redact or block.", Nested: ""}, + {Key: "injection", Type: "string", Doc: "Injection is what is done on signs of prompt injection: flag or block.", Nested: ""}, + {Key: "deny", Type: "[]Pattern", Doc: "Deny are patterns, matched against the text as a model reads it.", Nested: ""}, + {Key: "max_chars", Type: "int", Doc: "MaxChars refuses text longer than this; zero is no limit.", Nested: ""}, + }}, {Package: "engines", Name: "SGLangConfig", Title: "SGLangConfig", Doc: "", Fields: []Field{ {Key: "python", Type: "string", Doc: "Python is the interpreter of the SGLang virtualenv. SGLang is launched as\na module rather than a console script, which is the documented entry\npoint and avoids depending on the script being on PATH.", Nested: ""}, }}, @@ -249,6 +274,13 @@ var Reference = []Block{ {Key: "idle", Type: "time.Duration", Doc: "", Nested: ""}, {Key: "total", Type: "time.Duration", Doc: "", Nested: ""}, }}, + {Package: "guard", Name: "Tools", Title: "Tools", Doc: "", Fields: []Field{ + {Key: "allow", Type: "[]string", Doc: "Allow, when set, are the only tool names a request may offer and a\nmodel may call.", Nested: ""}, + {Key: "deny", Type: "[]string", Doc: "Deny are tool names never offered or called.", Nested: ""}, + {Key: "on_denied", Type: "string", Doc: "OnDenied is strip (the tool is removed from the request) or block.\nEmpty is strip.", Nested: ""}, + {Key: "max_calls_per_turn", Type: "int", Doc: "MaxCallsPerTurn stops an answer calling more tools than this.", Nested: ""}, + {Key: "validate_arguments", Type: "bool", Doc: "ValidateArguments checks a call's arguments against the parameters\nschema the request declared for the tool.", Nested: ""}, + }}, {Package: "config", Name: "Tracing", Title: "Tracing", Doc: "", Fields: []Field{ {Key: "endpoint", Type: "string", Doc: "Endpoint is the collector, for example http://otel.internal:4318.\nEmpty falls back to OTEL_EXPORTER_OTLP_ENDPOINT, and to no tracing.", Nested: ""}, {Key: "sample_ratio", Type: "float64", Doc: "SampleRatio is the share of requests traced, 0 to 1, when the caller\ndid not decide it with a sampled traceparent of its own. Zero takes 1.", Nested: ""}, @@ -312,6 +344,10 @@ var Reference = []Block{ {Key: "llamacpp", Type: "LlamaCppConfig", Doc: "", Nested: "engines.LlamaCppConfig"}, {Key: "sim", Type: "SimConfig", Doc: "", Nested: "engines.SimConfig"}, }}, + {Package: "guard", Name: "Config", Title: "guard.Config", Doc: "", Fields: []Field{ + {Key: "default", Type: "[]string", Doc: "", Nested: ""}, + {Key: "policies", Type: "map[string]Policy", Doc: "", Nested: ""}, + }}, {Package: "supervisor", Name: "Config", Title: "supervisor.Config", Doc: "", Fields: []Field{ {Key: "work_dir", Type: "string", Doc: "WorkDir holds pid files and per-shard scratch space.", Nested: ""}, {Key: "log_lines", Type: "int", Doc: "LogLines is how many lines of engine output to retain per shard.", Nested: ""}, diff --git a/internal/docgen/render.go b/internal/docgen/render.go index 1aaeb06b..baf891ac 100644 --- a/internal/docgen/render.go +++ b/internal/docgen/render.go @@ -26,6 +26,7 @@ var Sources = []string{ "internal/control/catalog/catalog.go", "internal/router/admission/controller.go", "internal/accounting/cost.go", + "internal/guard/policy.go", } // notReference are files with koanf tags that an operator never writes.