mirror of
https://github.com/netbirdio/netbird.git
synced 2026-07-28 08:52:37 -04:00
66e48bc933
The model-allowlist guardrail was merged into one account-wide union
and enforced flat on every request, independent of which policy,
group, or provider actually authorised it. With multiple policies —
especially a mix of guardrailed and un-guardrailed ones — this
produced two defects:
- false-allow: a model allowlisted for one group/provider leaked to
any caller, because the flat union ignored which policy authorised
the request; and
- false-deny: a policy with no guardrail (intended unrestricted) had
its traffic blocked by an unrelated policy's allowlist.
Make enforcement policy/group-aware, mirroring how llm_limit_check
already resolves caps:
- Management (SelectPolicyForRequest) is authoritative. It now uses
the request model (already carried on the wire in
CheckLLMPolicyLimitsRequest.model, previously ignored) to keep only
the applicable policies whose guardrails permit the model; a policy
with no allowlist-enabled guardrail is unrestricted. When policies
govern the (provider, groups) but none permits the model it denies
with llm_policy.model_blocked. No proto change — the field already
existed and the proxy already sends it.
- The proxy llm_guardrail becomes a per-provider fail-closed backstop.
The synthesiser emits a per-provider allowlist only when every
policy authorising that provider restricts models; a provider
reachable by any un-guardrailed policy is omitted (unrestricted).
The middleware keys the allowlist by the resolved provider id and
keeps the unknown/undetermined-model fail-closed behaviour so
path-routed providers stay enforced when management is unreachable.
Unit tests cover the selector gate (block, allow, cross-group no-leak,
un-guardrailed policy unrestricted, undetermined-model fail-closed) and
the per-provider synthesis; an e2e proves all three properties end to
end over the tunnel. Docs updated for the new config shape and the
two-layer enforcement.
Agent Networks — architecture documentation
A self-contained set of documents describing the agent-networks feature: an LLM-aware reverse-proxy middleware system plus account-level controls (budget rules, log collection toggles, PII redaction). The management server synthesises a per-peer middleware chain that the proxy executes on every LLM request.
What to read first
- 00-overview.md — the single entry point. Feature scope, the module map, and the cross-cutting topics worth keeping in mind, with links to every per-module guide.
- 01-end-to-end-flows.md — three high-level mermaid diagrams: config-to-runtime synth/delivery, per-request lifecycle through the LLM chain, and the budget-rule feedback loop.
- Per-module guides under
modules/— one file per package. Each describes the module boundary, the file-level layout, its own flow diagrams, the public contracts, the invariants it relies on, and the areas worth the closest attention.
Directory layout
docs/agent-networks/
├── README.md # you are here
├── 00-overview.md # feature summary + module map
├── 01-end-to-end-flows.md # cross-module mermaid diagrams
└── modules/
├── 10-shared-api.md # proto + OpenAPI wire contracts
├── 20-management-store.md # SQL persistence layer
├── 21-management-agentnetwork.md # domain layer + synthesizer (largest)
├── 22-management-handlers-wiring.md # HTTP API + gRPC delivery
├── 30-proxy-middleware-framework.md # generic plugin system
├── 31-proxy-middleware-builtin.md # 8 LLM-aware middlewares
├── 32-proxy-llm-parsers.md # OpenAI/Anthropic/Bedrock SDKs + pricing
├── 33-proxy-runtime.md # translate + serve + access-log
├── 40-dashboard.md # UI for everything above (lives in the dashboard repo)
└── 50-path-routed-providers.md # Vertex AI + Bedrock (path-routed, keyfile:: creds, /bedrock prefix)
The 40-dashboard.md module documents code that lives in the dashboard
repo, not in this repo. The guide is co-located here so backend readers
see the full picture in one place.
How the per-module guides are structured
Every modules/*.md follows the same template so the docs are easy to
scan:
- Module boundary — what this package owns; where it sits in the stack.
- Files — path / role.
- Architecture & flow — one or more mermaid diagrams.
- Public contracts — function signatures, gRPC messages, JSON shapes.
- Invariants — semantic guarantees the module relies on or enforces.
- Things to scrutinize — split by correctness / security / concurrency / backward-compat / performance / observability.
- Test coverage — the test files that lock down behaviour in this module.
- Known limitations / non-goals — what is intentionally out of scope.
- Cross-references — upstream/downstream module links + the end-to-end flow + the overview.
See 00-overview.md for the module map and the cross-cutting topics.