valguard-sdk 0.3.1__py3-none-any.whl

valguard/__init__.py

@@ -0,0 +1,52 @@
+"""ValGuard integration helpers for the OpenAI-compatible layer."""
+
+from valguard.client import ChatCompletionResult, TestValidatorsResult, ValGuardClient
+from valguard.errors import ValGuardError, ValGuardErrorInfo, parse_valguard_error
+from valguard.evidence import EVIDENCE_TYP, verify_evidence, verify_proof
+from valguard.headers import ValidationHeaders, parse_validation_headers
+from valguard.webhook import (
+    WEBHOOK_SIGNATURE_HEADER,
+    sign_webhook_payload,
+    verify_webhook_signature,
+)
+
+
+def openai_client_kwargs(
+    api_key: str,
+    base_url: str,
+    agent_slug: str,
+    provider_key: str | None = None,
+) -> dict:
+    """Backward-compatible helper — prefer ValGuardClient.openai_client_kwargs().
+
+    Pass provider_key so the OpenAI client sends X-Provider-Key (BYOK).
+    """
+    return ValGuardClient(
+        api_key=api_key,
+        base_url=base_url,
+        agent_slug=agent_slug,
+        provider_key=provider_key,
+    ).openai_client_kwargs()
+
+
+__all__ = [
+    "ChatCompletionResult",
+    "EVIDENCE_TYP",
+    "TestValidatorsResult",
+    "ValGuardClient",
+    "ValGuardError",
+    "ValGuardErrorInfo",
+    "ValidationHeaders",
+    "WEBHOOK_SIGNATURE_HEADER",
+    "openai_client_kwargs",
+    "parse_response_headers",
+    "parse_valguard_error",
+    "parse_validation_headers",
+    "sign_webhook_payload",
+    "verify_evidence",
+    "verify_proof",
+    "verify_webhook_signature",
+]
+
+# Alias for symmetry with the Node SDK
+parse_response_headers = parse_validation_headers

valguard/client.py

@@ -0,0 +1,298 @@
+"""ValGuard client — OpenAI-compatible layer helpers."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field, replace
+from typing import Any, Dict, Mapping, Sequence, Union
+
+from .errors import ValGuardError, ValGuardErrorInfo, parse_valguard_error
+from .headers import ValidationHeaders, parse_validation_headers
+
+RAGSource = Union[str, Dict[str, str]]
+
+
+@dataclass
+class ChatCompletionResult:
+    status: int
+    data: Any
+    validation: ValidationHeaders
+    error: ValGuardErrorInfo | None
+
+
+@dataclass
+class TestValidatorsResult:
+    status: int
+    data: Any
+    validation: ValidationHeaders
+    error: ValGuardErrorInfo | None
+
+
+@dataclass
+class ValGuardClient:
+    api_key: str
+    base_url: str
+    agent_slug: str = "default"
+    flow_slug: str | None = None
+    provider_key: str | None = None
+    request_id: str | None = None
+    rag_sources: Sequence[RAGSource] = field(default_factory=list)
+    internal_secret: str | None = None
+    project_id: str | None = None
+    idempotency_key: str | None = None
+    approval_mode: str | None = None
+    traceparent: str | None = None
+    parent_span_id: str | None = None
+    agent_id: str | None = None
+
+    @classmethod
+    def from_env(cls, environ: Mapping[str, str] | None = None) -> ValGuardClient:
+        env = dict(os.environ if environ is None else environ)
+        api_key = env.get("VG_API_KEY") or env.get("VALGUARD_API_KEY")
+        base_url = env.get("VG_PROXY") or env.get("VALGUARD_BASE_URL")
+        agent_slug = env.get("VG_AGENT") or env.get("VALGUARD_AGENT") or "default"
+        provider_key = env.get("VG_PROVIDER_KEY") or env.get("OPENAI_API_KEY")
+        internal_secret = env.get("INTERNAL_PROXY_SECRET") or env.get("VG_INTERNAL_SECRET")
+        project_id = env.get("VG_PROJECT_ID") or env.get("VG_TEST_PROJECT_ID")
+
+        if not api_key and not (internal_secret and project_id):
+            raise ValueError(
+                "Missing VG_API_KEY (or INTERNAL_PROXY_SECRET + VG_PROJECT_ID for internal test endpoints)"
+            )
+        if not base_url:
+            raise ValueError("Missing VG_PROXY (layer base URL)")
+
+        return cls(
+            api_key=api_key or "",
+            base_url=base_url,
+            agent_slug=agent_slug,
+            provider_key=provider_key,
+            internal_secret=internal_secret,
+            project_id=project_id,
+        )
+
+    @property
+    def chat_completions_url(self) -> str:
+        return f"{self.base_url.rstrip('/')}/v1/chat/completions"
+
+    @property
+    def test_validators_url(self) -> str:
+        return f"{self.base_url.rstrip('/')}/internal/test-validators"
+
+    def _build_internal_test_headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        headers: dict[str, str] = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if self.internal_secret:
+            headers["X-VG-Internal-Secret"] = self.internal_secret
+        if self.project_id:
+            headers["X-VG-Project-Id"] = self.project_id
+        if not headers.get("Authorization") and not (self.internal_secret and self.project_id):
+            raise ValueError(
+                "test_validators requires api_key or both internal_secret and project_id"
+            )
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def test_validators(
+        self,
+        *,
+        output: str,
+        agent_slug: str,
+        input_text: str = "",
+        rag_sources: Sequence[RAGSource] | None = None,
+        reask_attempt: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+        timeout: float = 60.0,
+    ) -> TestValidatorsResult:
+        if not output or not agent_slug:
+            raise ValueError("test_validators requires output and agent_slug")
+
+        body: dict[str, Any] = {
+            "output": output,
+            "agent_slug": agent_slug,
+        }
+        if input_text:
+            body["input_text"] = input_text
+        if rag_sources:
+            body["rag_sources"] = list(rag_sources)
+        if reask_attempt is not None:
+            body["reask_attempt"] = reask_attempt
+
+        payload = json.dumps(body).encode("utf-8")
+        headers = self._build_internal_test_headers(
+            {"Content-Type": "application/json", **dict(extra_headers or {})}
+        )
+
+        request = urllib.request.Request(
+            self.test_validators_url,
+            data=payload,
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                status = response.status
+                raw = response.read().decode("utf-8")
+                response_headers = {k: v for k, v in response.headers.items()}
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            raw = exc.read().decode("utf-8")
+            response_headers = {k: v for k, v in exc.headers.items()}
+
+        data: Any
+        if raw:
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError:
+                data = raw
+        else:
+            data = None
+
+        validation = parse_validation_headers(response_headers)
+        error = parse_valguard_error(status, data)
+
+        if error and status >= 400:
+            raise ValGuardError(status, error)
+
+        return TestValidatorsResult(status=status, data=data, validation=validation, error=error)
+
+    def openai_client_kwargs(self) -> dict[str, Any]:
+        default_headers = self.build_headers()
+        default_headers.pop("Authorization", None)
+        return {
+            "api_key": self.api_key,
+            "base_url": f"{self.base_url.rstrip('/')}/v1",
+            "default_headers": default_headers,
+        }
+
+    def _assert_mutually_exclusive(self) -> None:
+        if self.flow_slug and self.agent_slug:
+            raise ValueError("mutually_exclusive_headers: use either with_agent or with_playbook, not both")
+
+    def build_headers(self, extra: Mapping[str, str] | None = None) -> dict[str, str]:
+        self._assert_mutually_exclusive()
+        headers: dict[str, str] = {
+            "Authorization": f"Bearer {self.api_key}",
+        }
+        if self.flow_slug:
+            headers["X-VG-Flow"] = self.flow_slug
+        else:
+            headers["X-VG-Agent"] = self.agent_slug
+        if self.provider_key:
+            headers["X-Provider-Key"] = self.provider_key
+        if self.request_id:
+            headers["X-Request-Id"] = self.request_id
+        if self.rag_sources:
+            headers["X-VG-Sources"] = json.dumps(list(self.rag_sources))
+        if self.idempotency_key:
+            headers["X-VG-Idempotency-Key"] = self.idempotency_key
+        if self.approval_mode:
+            headers["X-VG-Approval-Mode"] = self.approval_mode
+        if self.traceparent:
+            headers["traceparent"] = self.traceparent
+        if self.parent_span_id:
+            headers["X-VG-Parent-Span-Id"] = self.parent_span_id
+        if self.agent_id:
+            headers["X-VG-Agent-Id"] = self.agent_id
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def with_agent(self, agent_slug: str) -> ValGuardClient:
+        return replace(self, agent_slug=agent_slug, flow_slug=None)
+
+    def with_playbook(self, flow_slug: str) -> ValGuardClient:
+        return replace(self, flow_slug=flow_slug, agent_slug="")
+
+    def with_provider_key(self, provider_key: str) -> ValGuardClient:
+        return replace(self, provider_key=provider_key)
+
+    def with_rag_sources(self, sources: Sequence[RAGSource]) -> ValGuardClient:
+        return replace(self, rag_sources=list(sources))
+
+    def with_idempotency_key(self, key: str) -> ValGuardClient:
+        return replace(self, idempotency_key=key)
+
+    def with_approval_mode(self, mode: str) -> ValGuardClient:
+        return replace(self, approval_mode=mode)
+
+    def with_trace(
+        self,
+        *,
+        traceparent: str | None = None,
+        parent_span_id: str | None = None,
+        agent_id: str | None = None,
+    ) -> ValGuardClient:
+        return replace(
+            self,
+            traceparent=traceparent,
+            parent_span_id=parent_span_id,
+            agent_id=agent_id,
+        )
+
+    def parse_response_headers(self, headers: Mapping[str, str]) -> ValidationHeaders:
+        return parse_validation_headers(headers)
+
+    def chat_completions(
+        self,
+        *,
+        model: str,
+        messages: Sequence[Mapping[str, str]],
+        stream: bool = False,
+        temperature: float | None = None,
+        max_tokens: int | None = None,
+        extra_headers: Mapping[str, str] | None = None,
+        timeout: float = 60.0,
+    ) -> ChatCompletionResult:
+        body: dict[str, Any] = {
+            "model": model,
+            "messages": list(messages),
+            "stream": stream,
+        }
+        if temperature is not None:
+            body["temperature"] = temperature
+        if max_tokens is not None:
+            body["max_tokens"] = max_tokens
+
+        payload = json.dumps(body).encode("utf-8")
+        headers = self.build_headers({"Content-Type": "application/json", **dict(extra_headers or {})})
+
+        request = urllib.request.Request(
+            self.chat_completions_url,
+            data=payload,
+            headers=headers,
+            method="POST",
+        )
+
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                status = response.status
+                raw = response.read().decode("utf-8")
+                response_headers = {k: v for k, v in response.headers.items()}
+        except urllib.error.HTTPError as exc:
+            status = exc.code
+            raw = exc.read().decode("utf-8")
+            response_headers = {k: v for k, v in exc.headers.items()}
+
+        data: Any
+        if raw:
+            try:
+                data = json.loads(raw)
+            except json.JSONDecodeError:
+                data = raw
+        else:
+            data = None
+
+        validation = parse_validation_headers(response_headers)
+        error = parse_valguard_error(status, data)
+
+        if error and not error.soft_fail and status >= 400:
+            raise ValGuardError(status, error)
+
+        return ChatCompletionResult(status=status, data=data, validation=validation, error=error)

valguard/constants.py

@@ -0,0 +1,4 @@
+"""Product URLs — override at runtime via VG_PROXY / VG_API_KEY env vars."""
+
+PRODUCT_SITE = "https://valguard.ai"
+DOCS_QUICKSTART = f"{PRODUCT_SITE}/docs/quickstart"

valguard/errors.py

@@ -0,0 +1,55 @@
+"""Parse ValGuard layer errors and soft-fail envelopes."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ValGuardErrorInfo:
+    type: str
+    code: str | None
+    message: str | None
+    reason: str | None
+    details: Any
+    soft_fail: bool
+    body: Any
+
+
+class ValGuardError(Exception):
+    def __init__(self, status: int, info: ValGuardErrorInfo) -> None:
+        super().__init__(info.message or info.reason or f"ValGuard request failed ({status})")
+        self.status = status
+        self.info = info
+
+
+def parse_valguard_error(status: int, body: Any) -> ValGuardErrorInfo | None:
+    if not isinstance(body, dict):
+        return None
+
+    if body.get("valid") is False and body.get("validation") is not None:
+        return ValGuardErrorInfo(
+            type="validation_soft_fail",
+            code=None,
+            message="response failed validation (http 200 envelope)",
+            reason=None,
+            details=body.get("validation"),
+            soft_fail=True,
+            body=body,
+        )
+
+    error = body.get("error")
+    if not isinstance(error, dict):
+        return None
+
+    err_type = error.get("type")
+    return ValGuardErrorInfo(
+        type=str(err_type) if err_type is not None else "unknown",
+        code=error.get("code") if isinstance(error.get("code"), str) else None,
+        message=error.get("message") if isinstance(error.get("message"), str) else None,
+        reason=error.get("reason") if isinstance(error.get("reason"), str) else None,
+        details=error.get("details"),
+        soft_fail=False,
+        body=body,
+    )

valguard/evidence.py

@@ -0,0 +1,49 @@
+"""Offline HMAC verification for ValGuard evidence envelopes.
+
+Matches `valguard-cli verify-proof` and the proxy signer: org key is
+HMAC-SHA256(secret, key_id), signature is `sha256=` + HMAC-SHA256(org key, payload).
+The payload string is verified as stored. Do not re-serialize the envelope.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from typing import Any, Mapping
+
+EVIDENCE_TYP = "valguard-evidence/1"
+
+
+def verify_evidence(key_id: str, payload: str, signature: str, secret: str) -> bool:
+    """Return true when `signature` matches HMAC over the exact payload bytes."""
+    if not key_id or not payload or not signature or not secret:
+        return False
+    org_key = hmac.new(secret.encode(), key_id.encode(), hashlib.sha256).digest()
+    expected = "sha256=" + hmac.new(org_key, payload.encode(), hashlib.sha256).hexdigest()
+    return hmac.compare_digest(expected, signature.strip())
+
+
+def verify_proof(envelope: str | Mapping[str, Any], secret: str) -> bool:
+    """Verify a downloaded envelope object or its JSON text.
+
+    Requires `key_id`, `payload`, and `signature`. The caller supplies the
+    deployment secret (`EVIDENCE_HMAC_SECRET`, or the webhook secret when that
+    is the fallback). This does not call the API.
+    """
+    record: Any
+    if isinstance(envelope, str):
+        try:
+            record = json.loads(envelope)
+        except json.JSONDecodeError:
+            return False
+    else:
+        record = envelope
+    if not isinstance(record, Mapping):
+        return False
+    return verify_evidence(
+        str(record.get("key_id") or ""),
+        str(record.get("payload") or ""),
+        str(record.get("signature") or ""),
+        secret,
+    )

valguard/headers.py

@@ -0,0 +1,119 @@
+"""Parse ValGuard observability headers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Mapping
+
+ValidationStatus = Literal["pass", "warn", "block", "shadow", "stream_passthrough", "fail"]
+
+_VALIDATION_STATUSES = {"pass", "warn", "block", "shadow", "stream_passthrough", "fail"}
+
+
+@dataclass(frozen=True)
+class ValidationHeaders:
+    validation_status: ValidationStatus | None
+    shadow_mode: bool
+    latency_ms: int | None
+    request_id: str | None
+    input_validation_shadow: bool
+    validation_phase: Literal["input"] | None
+    overage: bool
+    target_type: str | None
+    orchestration_path: str | None
+    orchestration_validations_used: int | None
+    orchestration_executions_remaining: int | Literal["unlimited"] | None
+    idempotency_replayed: bool
+    healed: bool
+    healed_rules: tuple[str, ...]
+    healed_event_count: int | None
+    healed_trace: tuple[str, ...]
+    cache_status: str | None
+    trace_id: str | None
+    span_id: str | None
+    parent_span_id: str | None
+    agent_id: str | None
+    idempotent_run_id: str | None
+    run_id: str | None
+    run_status: str | None
+    approval_id: str | None
+    license_status: str | None
+    license_mode: str | None
+
+
+def _header_get(headers: Mapping[str, str], name: str) -> str | None:
+    lower = name.lower()
+    for key, value in headers.items():
+        if key.lower() == lower:
+            if value is None or value == "":
+                return None
+            return value
+    return None
+
+
+def _split_csv(raw: str | None) -> tuple[str, ...]:
+    if not raw:
+        return ()
+    return tuple(part.strip() for part in raw.split(",") if part.strip())
+
+
+def _parse_int(raw: str | None) -> int | None:
+    if raw is None:
+        return None
+    try:
+        return int(raw)
+    except ValueError:
+        return None
+
+
+def parse_validation_headers(headers: Mapping[str, str]) -> ValidationHeaders:
+    status = _header_get(headers, "x-vg-validation-status")
+    if status is not None:
+        status = status.lower()
+    validation_status: ValidationStatus | None
+    if status in _VALIDATION_STATUSES:
+        validation_status = status  # type: ignore[assignment]
+    else:
+        validation_status = None
+
+    phase = _header_get(headers, "x-vg-validation-phase")
+    validation_phase: Literal["input"] | None = "input" if phase == "input" else None
+
+    remaining_raw = _header_get(headers, "x-vg-requests-remaining")
+    orchestration_executions_remaining: int | Literal["unlimited"] | None
+    if remaining_raw is None:
+        orchestration_executions_remaining = None
+    elif remaining_raw == "unlimited":
+        orchestration_executions_remaining = "unlimited"
+    else:
+        orchestration_executions_remaining = _parse_int(remaining_raw)
+
+    return ValidationHeaders(
+        validation_status=validation_status,
+        shadow_mode=_header_get(headers, "x-vg-shadow-mode") == "true",
+        latency_ms=_parse_int(_header_get(headers, "x-vg-latency-ms")),
+        request_id=_header_get(headers, "x-vg-request-id"),
+        input_validation_shadow=_header_get(headers, "x-vg-input-validation") == "shadow",
+        validation_phase=validation_phase,
+        overage=_header_get(headers, "x-vg-overage") == "true",
+        target_type=_header_get(headers, "x-vg-target-type"),
+        orchestration_path=_header_get(headers, "x-vg-orchestration-path"),
+        orchestration_validations_used=_parse_int(_header_get(headers, "x-vg-orchestration-validations-used")),
+        orchestration_executions_remaining=orchestration_executions_remaining,
+        idempotency_replayed=_header_get(headers, "x-vg-idempotency-replayed") == "true",
+        healed=_header_get(headers, "x-vg-healed") == "true",
+        healed_rules=_split_csv(_header_get(headers, "x-vg-healed-rules")),
+        healed_event_count=_parse_int(_header_get(headers, "x-vg-healed-event-count")),
+        healed_trace=_split_csv(_header_get(headers, "x-vg-healed-trace")),
+        cache_status=_header_get(headers, "x-vg-cache"),
+        trace_id=_header_get(headers, "x-trace-id"),
+        span_id=_header_get(headers, "x-vg-span-id"),
+        parent_span_id=_header_get(headers, "x-vg-parent-span-id"),
+        agent_id=_header_get(headers, "x-vg-agent-id"),
+        idempotent_run_id=_header_get(headers, "x-vg-idempotent-run-id"),
+        run_id=_header_get(headers, "x-vg-run-id"),
+        run_status=_header_get(headers, "x-vg-run-status"),
+        approval_id=_header_get(headers, "x-vg-approval-id"),
+        license_status=_header_get(headers, "x-vg-license-status"),
+        license_mode=_header_get(headers, "x-vg-license-mode"),
+    )

valguard/webhook.py

@@ -0,0 +1,56 @@
+"""Verify inbound ValGuard webhook HMAC signatures."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import time
+
+WEBHOOK_SIGNATURE_HEADER = "X-VG-Signature"
+
+
+def _as_bytes(raw_body: bytes | str) -> bytes:
+    if isinstance(raw_body, str):
+        return raw_body.encode("utf-8")
+    if isinstance(raw_body, (bytes, bytearray)):
+        return bytes(raw_body)
+    raise TypeError("raw_body must be str or bytes")
+
+
+def sign_webhook_payload(raw_body: bytes | str, secret: str, unix: int | None = None) -> str:
+    """Return `t=<unix>,v1=<hex>` HMAC-SHA256 over `<unix>.<raw body>`."""
+    body = _as_bytes(raw_body)
+    ts = int(time.time()) if unix is None else int(unix)
+    mac = hmac.new(secret.encode(), f"{ts}.".encode() + body, hashlib.sha256)
+    return f"t={ts},v1={mac.hexdigest()}"
+
+
+def verify_webhook_signature(
+    raw_body: bytes | str,
+    signature_header: str | None,
+    secret: str,
+    max_age_seconds: int | None = 300,
+) -> bool:
+    """Verify `X-VG-Signature`. Accepts str or bytes bodies and legacy `sha256=` signatures."""
+    if not signature_header or not secret:
+        return False
+    try:
+        body = _as_bytes(raw_body)
+    except TypeError:
+        return False
+    header = signature_header.strip()
+    if header.startswith("t=") and ",v1=" in header:
+        try:
+            stamp, hex_sig = header.split(",v1=", 1)
+            unix = int(stamp[2:])
+        except ValueError:
+            return False
+        if max_age_seconds is not None and abs(int(time.time()) - unix) > max_age_seconds:
+            return False
+        expected = sign_webhook_payload(body, secret, unix)
+        return hmac.compare_digest(expected, f"t={unix},v1={hex_sig}")
+    if header.startswith("sha256="):
+        mac = hmac.new(secret.encode(), body, hashlib.sha256)
+        expected = f"sha256={mac.hexdigest()}"
+        return hmac.compare_digest(expected, header)
+    return False

valguard_sdk-0.3.1.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.4
+Name: valguard-sdk
+Version: 0.3.1
+Summary: OpenAI-compatible client helpers for the ValGuard integrity layer
+Author: ValGuard
+License: MIT
+Project-URL: Homepage, https://valguard.ai
+Project-URL: Documentation, https://valguard.ai/docs/quickstart
+Project-URL: Repository, https://github.com/valguard-ai/sdk-python
+Project-URL: Source, https://github.com/valguard-ai/sdk-python
+Keywords: llm,openai,validation,guardrails,valguard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == "openai"
+Dynamic: license-file
+
+# valguard-sdk (Python)
+
+Thin Python helpers for the ValGuard OpenAI-compatible integrity layer.
+
+**Package name: `valguard-sdk`.** `pip install valguard` installs an unrelated third-party project. Import this SDK as `valguard`.
+
+Public GitHub: [github.com/valguard-ai/sdk-python](https://github.com/valguard-ai/sdk-python).
+
+Set `VG_PROXY` to your layer URL — see [valguard.ai/docs/quickstart](https://valguard.ai/docs/quickstart).
+
+## Install
+
+```bash
+pip install valguard-sdk
+# or, from this repo: pip install "git+https://github.com/valguard-ai/sdk-python.git"
+pip install openai   # optional, for OpenAI SDK bridge
+```
+
+## Environment
+
+```bash
+export VG_PROXY="https://api.valguard.ai"   # your layer base URL
+export VG_API_KEY="vg_live_..."
+export VG_AGENT="invoice_extraction_agent"
+export VG_PROVIDER_KEY="sk-..."             # optional BYOK upstream key
+```
+
+## with_agent and with_playbook
+
+`with_agent` sets `X-VG-Agent`. `with_playbook` sets `X-VG-Flow`. Pass `provider_key` (or `VG_PROVIDER_KEY` via `from_env`) so `openai_client_kwargs()` includes `X-Provider-Key`.
+
+```python
+vg = ValGuardClient.from_env().with_playbook("invoice-processing")
+```
+
+## OpenAI SDK (recommended)
+
+```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": "Extract invoice JSON"}],
+)
+
+print(vg.parse_response_headers(dict(raw.http_response.headers)))
+print(raw.parse())
+```
+
+## Stdlib-only HTTP
+
+```python
+from valguard import ValGuardClient
+
+vg = ValGuardClient(
+    api_key="vg_live_...",
+    base_url="https://api.valguard.ai",
+    agent_slug="default",
+    provider_key="sk-...",
+)
+
+result = vg.chat_completions(
+    model="openai/gpt-4o-mini",
+    messages=[{"role": "user", "content": "hi"}],
+)
+print(result.validation)
+print(result.data)
+```
+
+## RAG sources
+
+```python
+vg = ValGuardClient.from_env().with_rag_sources(
+    [{"id": "doc-1", "text": "Acme revenue was $4.2M in Q3."}]
+)
+```
+
+## Errors
+
+```python
+from valguard import ValGuardClient, ValGuardError
+
+try:
+    vg.chat_completions(model="openai/gpt-4o-mini", messages=[])
+except ValGuardError as err:
+    print(err.info.type)  # validation_block, input_validation, rate_limit_exceeded, ...
+```
+
+Soft-fail agents return HTTP 200 with `valid: false` — inspect `result.error.soft_fail` instead of exceptions.
+
+## API surface
+
+| Symbol | Purpose |
+|--------|---------|
+| `ValGuardClient` | Main client + `from_env()` |
+| `openai_client_kwargs()` | Legacy functional helper |
+| `parse_validation_headers()` | Read `X-VG-*` headers, including repair, cache, trace, and approval |
+| `verify_proof()` / `verify_evidence()` | Offline HMAC check of a Proof download (`valguard-evidence/1`) |
+| `parse_valguard_error()` | Parse error / soft-fail JSON |
+| `ValGuardError` | Raised on non-2xx responses |
+
+`with_approval_mode("async")` sends `X-VG-Approval-Mode`. `with_idempotency_key` sends `X-VG-Idempotency-Key`. `with_trace` sends `traceparent`, `X-VG-Parent-Span-Id`, and `X-VG-Agent-Id`. Response repair is reported with `X-VG-Healed`, `X-VG-Healed-Rules`, `X-VG-Healed-Event-Count`, and `X-VG-Healed-Trace`. Presets are agent settings.

valguard_sdk-0.3.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+valguard/__init__.py,sha256=1P8cIULGeT7i-7gEaxhgPJwrvKg93_FsdeQeXVesDG4,1506
+valguard/client.py,sha256=o1YPeuBAu2KSDE24Bp_NtRc5-htpp3KmSW2EVMO9xOw,10455
+valguard/constants.py,sha256=yeFbbFQQPtyExivMs6j54cN2MpeQj7p3xFKjmBYFWCQ,169
+valguard/errors.py,sha256=3IR-AAEb4QBcvqwfZcnQ-NXry2ZZjSXxNY6v4k2WFCg,1659
+valguard/evidence.py,sha256=og-BGT_6CT9-jDrvB9zZ33BCuRmHjjiH0F2Y79-45E0,1722
+valguard/headers.py,sha256=ifJHIkK9ocvfQXcgoOTqMS3MeF8autKv2-i3FCNyh0g,4667
+valguard/webhook.py,sha256=QoSPiFM3KNCjEX9g82xuzQFdYnoGig-gH2Gc7pHQuwk,1924
+valguard_sdk-0.3.1.dist-info/licenses/LICENSE,sha256=sIaNvTxJRMsQ8ooaahKQdalenIj6U107Fzy1zkRI2XE,1065
+valguard_sdk-0.3.1.dist-info/METADATA,sha256=appZOE7N0eWUVFNjRIm_iPJy4RFNN2QbiqorXWU3aZU,4342
+valguard_sdk-0.3.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+valguard_sdk-0.3.1.dist-info/top_level.txt,sha256=BjdBbeksc7mnv3E4vg6h5nUkJeDgWaaawerKb06Tg3U,9
+valguard_sdk-0.3.1.dist-info/RECORD,,

valguard_sdk-0.3.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

valguard_sdk-0.3.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ValGuard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

valguard_sdk-0.3.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+valguard