Quickstart

SDKs at a glance

The public SDK surface is available in the monorepo packages for Python, Node.js, Go, and C#; each one exposes a thin client that forwards headers and parses ValGuard validation metadata.

SDK packages

Install from the monorepo (packages/sdk-python, packages/sdk-node, packages/sdk-go, packages/sdk-csharp) or copy the snippets below.

Python

pip install valguard (local: pip install -e ./packages/sdk-python)

from openai import OpenAI
from valguard import ValGuardClient

vg = ValGuardClient.from_env()
client = OpenAI(**vg.openai_client_kwargs())

raw = client.with_raw_response.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hi"}],
)
print(vg.parse_response_headers(dict(raw.http_response.headers)))
print(raw.parse())

Node.js

npm install @valguard/sdk-node (local: npm install ./packages/sdk-node)

import OpenAI from "openai";
import { ValGuard } from "@valguard/sdk-node";

const vg = ValGuard.fromEnv();
const client = new OpenAI(vg.openaiOptions());

const raw = await client.withRawResponse.chat.completions.create({
  model: "openai/gpt-4o-mini",
  messages: [{ role: "user", content: "Say hi" }],
});
console.log(vg.parseResponseHeaders(raw.response.headers));
console.log(raw.parse());

Go

go get github.com/valguard/valguard/packages/sdk-go

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/valguard/valguard/packages/sdk-go/valguard"
)

func main() {
	client, err := valguard.FromEnv()
	if err != nil {
		log.Fatal(err)
	}

	result, err := client.ChatCompletions(context.Background(), valguard.ChatRequest{
		Model: "openai/gpt-4o-mini",
		Messages: []valguard.Message{
			{Role: "user", Content: "Say hi"},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(result.Validation)
}

C#

dotnet add package ValGuard.Sdk

using ValGuard.Sdk;

var vg = ValGuardClient.FromEnv();
var result = await vg.ChatCompletionsAsync(new ChatRequest(
    Model: "openai/gpt-4o-mini",
    Messages: [new ChatMessage("user", "Say hi")]));

Console.WriteLine(result.Validation);

Shadow mode

Enable shadow mode on an agent to log validation failures without blocking or re-asking. The upstream response always passes through — ideal for measuring failure rates before production enforce mode.

Dashboard requests show status shadow when a block/reask rule would have fired. Response headers include X-VG-Shadow-Mode: true and X-VG-Validation-Status: shadow.

While shadow mode is on, validation failure response settings are disabled — callers are never blocked. Tune validators, then disable shadow mode and switch critical rules to on_fail: block.

Validation webhooks

ValGuard sends an asynchronous HTTPS POST when a completion is blocked or when shadow mode records a would-block violation. Delivery is non-blocking on the layer hot path (5 second timeout per attempt).

• validation.block — a blocking validator failed and the response was not passed through (unless shadow mode is on).
• validation.shadow — shadow mode logged a failure that would have blocked or re-asked in enforce mode.

Configure the default URL under Organization settings → Validation webhooks. Per agent, set Validation webhook override to replace the org URL; leave it empty to inherit the organization webhook.

JSON body (failures are redacted according to the agent log level):

{
  "event": "validation.block",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "agent": { "slug": "default", "name": "Default" },
  "failures": [
    { "validator": "pii_email", "message": "…" }
  ]
}

The receiver should return HTTP 2xx. Non-success statuses and network errors are recorded in webhook delivery logs. Use HTTPS endpoints in production.

Monthly agent budget

Monthly budget (USD) is a soft spend cap per agent. The layer estimates cost from token usage and blocks new requests when monthly spend for that agent exceeds the budget.

• 0 disables the cap.
• Organization plan quotas and monthly validation caps still apply separately — see billing and usage in the dashboard.

Log level & privacy

Each agent has a log level (metadata default, hashed, or full). Before validation results are queued for storage, ValGuard.ai masks emails, tax IDs (NIP/PESEL/SSN), IBAN, card numbers, and sensitive JSON field values.

• metadata — recommended for production; stores rule outcomes without raw prompt/response text.
• hashed — strictest; minimal retained detail.
• full — debug only; use with consent and short retention.

payload_retention_days controls how long stored detail payloads are kept; the retention job clears those fields afterward. Webhook failure payloads follow the same redaction rules.

Validation failure response

When a blocking validator fails (and shadow mode is off), choose how the layer responds:

• HTTP error — returns 403 by default (or 400, 409, 422 per agent) with error.type, reason, and details.
• Soft envelope — HTTP 200 with valid: false plus a validation object for clients that cannot handle error status codes.

See the error reference for header and body shapes.

Streaming (stream: true)

• Passthrough SSE (warn/pass only) — If no enabled validator uses on_fail: block or on_fail: reask, chunks are forwarded immediately while assistant text is collected for post-stream validation, logging, and shadow mode.
• Buffered validation + synthesized SSE — If any enabled rule can block or reask, the layer reads the upstream stream internally, validates the assembled assistant reply, then replays OpenAI-compatible SSE with the final text (or a block/reask envelope). Mock upstream mode uses this buffered path.