From 03ccf0a53e63069ebb29a40e09c71a45cb2f2bd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jo=C3=A3o=20Andr=C3=A9=20Gomes=20Marques?=
 <joaoagm90@gmail.com>
Date: Sun, 17 May 2026 23:51:33 +0200
Subject: [PATCH] docs(guardrails): add Asqav cryptographic audit trail
 integration

Documents the Asqav LiteLLM CustomGuardrail callback shipped in the
`asqav` Python SDK (`pip install asqav[litellm]`). Asqav signs each
pre_call, post_call_success, post_call_failure, and moderation event
with a post-quantum (ML-DSA / FIPS 204) signature to produce a
tamper-evident audit trail for SOC 2, ISO 42001, and EU AI Act
evidence.

Closes BerriAI/litellm#24534.
---
 docs/proxy/guardrails/asqav.md | 112 +++++++++++++++++++++++++++++++++
 sidebars.js                    |   1 +
 2 files changed, 113 insertions(+)
 create mode 100644 docs/proxy/guardrails/asqav.md

diff --git a/docs/proxy/guardrails/asqav.md b/docs/proxy/guardrails/asqav.md
new file mode 100644
index 00000000..5008a757
--- /dev/null
+++ b/docs/proxy/guardrails/asqav.md
@@ -0,0 +1,112 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Asqav
+
+[Asqav](https://asqav.com) signs every LLM call with a post-quantum signature
+(ML-DSA / FIPS 204) and stores a tamper-evident audit trail. Use it when you
+need a cryptographically verifiable record of who called which model, with what
+inputs, and what the response was, for SOC 2, ISO 42001, or EU AI Act evidence.
+
+The integration ships as a `CustomGuardrail` callback in the
+[`asqav` Python SDK](https://pypi.org/project/asqav/). It signs the following
+LiteLLM lifecycle events:
+
+- `pre_call` - before the LLM request is dispatched
+- `post_call_success` - after a successful response, including token usage
+- `post_call_failure` - on any provider error, tagged with `risk_class=medium`
+- `moderation` - moderation hook events
+
+Signing failures are fail-open and never block LLM requests.
+
+## Quick Start
+
+### 1. Install the SDK
+
+```bash
+pip install asqav[litellm]
+```
+
+### 2. Get an API key
+
+Sign up at [asqav.com](https://asqav.com) and create a project. Copy the
+`sk_live_...` key from the dashboard.
+
+### 3. Register the callback
+
+The Asqav guardrail is registered through `litellm.callbacks`, not the
+`guardrails:` YAML block, because it observes every call rather than gating on a
+named guardrail.
+
+<Tabs>
+<TabItem label="LiteLLM Proxy (config.yaml)" value="proxy">
+
+Create a `custom_callbacks.py` next to your `config.yaml`:
+
+```python
+import asqav
+from asqav.extras.litellm import AsqavGuardrail
+
+asqav.init("sk_live_...")  # or set ASQAV_API_KEY in the environment
+
+proxy_handler_instance = AsqavGuardrail(agent_name="my-litellm-proxy")
+```
+
+Then wire it up in `config.yaml`:
+
+```yaml
+model_list:
+  - model_name: gpt-4o
+    litellm_params:
+      model: openai/gpt-4o
+      api_key: os.environ/OPENAI_API_KEY
+
+litellm_settings:
+  callbacks: custom_callbacks.proxy_handler_instance
+```
+
+Start the proxy:
+
+```bash
+litellm --config config.yaml
+```
+
+</TabItem>
+<TabItem label="LiteLLM Python SDK" value="sdk">
+
+```python
+import asqav
+from asqav.extras.litellm import AsqavGuardrail
+import litellm
+
+asqav.init("sk_live_...")
+litellm.callbacks = [AsqavGuardrail(agent_name="my-litellm-proxy")]
+
+response = litellm.completion(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+```
+
+</TabItem>
+</Tabs>
+
+### 4. Verify the audit trail
+
+Every call now appears in the Asqav dashboard with its signed envelope. Receipts
+can be exported as JSON for downstream verification.
+
+## Configuration
+
+| Parameter     | Description                                                                       |
+|---------------|-----------------------------------------------------------------------------------|
+| `api_key`     | Optional override; defaults to the key passed to `asqav.init()` or `ASQAV_API_KEY`. |
+| `agent_name`  | Name for a new agent (creates it on first run).                                   |
+| `agent_id`    | ID of an existing agent (use instead of `agent_name` to reuse).                   |
+
+## Links
+
+- Integration guide: <https://asqav.com/docs/litellm>
+- SDK source: <https://github.com/asqav/asqav-sdk>
+- PyPI: <https://pypi.org/project/asqav/>
+- Issues / questions: info@asqav.com
diff --git a/sidebars.js b/sidebars.js
index 6ff0c72f..0bc8e786 100644
--- a/sidebars.js
+++ b/sidebars.js
@@ -68,6 +68,7 @@ const sidebars = {
           "proxy/guardrails/aim_security",
           "proxy/guardrails/onyx_security",
           "proxy/guardrails/aporia_api",
+          "proxy/guardrails/asqav",
           "proxy/guardrails/azure_content_guardrail",
           "proxy/guardrails/bedrock",
           "proxy/guardrails/crowdstrike_aidr",