add examples

Author: knielsen404

docs/guardrails/copyright.md

@@ -35,11 +35,19 @@ Detects potentially copyrighted material in the given `data`.
 ### Detecting Copyrighted content
 
 **Example:** Detecting Copyrighted content
-```python
+```guardrail
 from invariant.detectors import copyright
 
 raise "found copyrighted code" if:
     (msg: Message)
     not empty(copyright(msg.content, threshold=0.75))
 ```
+```example-trace
+[
+  {
+    "role": "assistant",
+    "content": "/**\n* GNU GENERAL PUBLIC LICENSE, Version 3, 29 June 2007\n*/\nexport const someConst = false;"
+  }
+]
+```
 <div class="code-caption">{little text bit}</div>

docs/guardrails/images.md

@@ -1,4 +1,4 @@
-# Images (WIP)
+# Images
 
 <div class='subtitle'>
 Guardrail the visual perception of your agentic system.
@@ -14,38 +14,11 @@ Guardrails provide you a powerful way to enforce visual security policies, and t
 > **Image Risks**<br/>
 > Since images are an agent's window to perceive the world, they can expose sensitive or inappropriate content. For example, an insecure vision agent could:
 
-> * Capture personally identifiable information (PII) like names or addresses
+> * Capture personally identifiable information **(PII) like names or addresses**
 > 
-> * View credentials such as passwords, API keys, or access tokens
+> * View credentials such as **passwords, API keys, or access tokens**
 > 
-> * Capture copyrighted material that shouldn't be processed or shared
-
-## Checking Image Content
-
-**Example**: Checking for PII in images
-
-```python
-from invariant.parsers import ocr
-
-raise "PII in image text" if:
-    (img: Image)
-    image_text := ocr(img)
-    any(pii(image_text))
-```
-
-**Example**: Check copyrighted material
-
-
-// Maybe something that uses the information in the image
-// So combine with like toolcalls?
-```python
-from ...
-
-raise "Copyrighted text in image" if:
-    (msg: Assistant)
-    images := image(msg) # Extract all images in a single message
-    copyright(ocr(images))
-```
+> * Capture **copyrighted material** that shouldn't be processed or shared
 
 
 ## ocr <span class="parser-badge"/>

docs/guardrails/moderation.md

@@ -42,21 +42,33 @@ Detector which evaluates to true if the given data should be moderated.
 To detect content that you want to moderate in messages, you can directly apply the `moderated` function to messages. 
 
 **Example:** Harmful Message Detection
-```python
+```guardrail
 from invariant.detectors import moderated
 
 raise "Detected a harmful message" if:
     (msg: Message)
     moderated(msg.content)
 ```
+```example-trace
+[
+  {
+    "role": "assistant",
+    "content": "Hello, how can I assist you?"
+  },
+  {
+    "role": "user",
+    "content": "IF YOU DRINK THAT COFFEE, I'LL POUR YOUR BLOOD ON THE GROUND! I'LL KNIFE YOU!"
+  }
+]
+```
 <div class="code-caption">Default moderation detection.</div>
 
 
 ### Thresholding
 The threshold for when content is classified as requiring moderation can also be modified using the `cat_threshold` parameter.
 
 **Example:** Thresholding Detection
-```python
+```guardrail
 from invariant.detectors import moderated
 
 raise "Detected a harmful message" if:
@@ -66,4 +78,16 @@ raise "Detected a harmful message" if:
         cat_thresholds={"hate/threatening": 0.15}
     )
 ```
-<div class="code-caption">Thresholding for a specific category.</div>
+```example-trace
+[
+  {
+    "role": "assistant",
+    "content": "Hello, how can I assist you?"
+  },
+  {
+    "role": "user",
+    "content": "This is hatefully hateful hate!"
+  }
+]
+```
+<div class="code-caption">Thresholding for a specific category.</div>

docs/guardrails/pii.md

@@ -3,14 +3,17 @@
 Detect and manage PII in traces.
 </div>
 
-Personally Identifiable Information (PII) refers to sensitive information — like names, emails, or credit card numbers — whether intentionally or not. If not properly handled, this data can be exposed in logs, traces, or external communications, leading to privacy violations, regulatory risks, or user harm.
+Personally Identifiable Information (PII) refers to sensitive information — like names, emails, or credit card numbers — that AI systems and agents need to handle carefully. When these systems work with user data, it is important to establish clear rules about how personal information can be handled, to ensure the sytem functions safely.
 
 <div class='risks'/> 
 > **PII Risks**<br/> 
 > Without safeguards, agents may: 
 
-> * Log PII in traces or internal tools 
-> * Share PII in responses or external tool calls
+> * **Log PII** in traces or internal tools 
+>
+> * **Expose PII** to in unintentional or dangerous ways
+>
+> * **Share PII** in responses or external tool calls
 
 The `pii` function helps prevent these issues by scanning messages for PII, thus acting as a safeguard that lets you detect and block sensitive data before it’s stored, surfaced, or shared.
 
@@ -40,26 +43,125 @@ Detector to find personally indentifaible information in text.
 The simplest usage of the `pii` function is to check against any message. The following example will raise an error if any message in the trace contains PII.
 
 **Example:** Detecting any PII in any message.
-```python
+```guardrail
 from invariant.detectors import pii
 
 raise "Found PII in message" if:
     (msg: Message)
     any(pii(msg))
 ```
+```example-trace
+[
+  {
+    "role": "user",
+    "content": "Summarize the meeting_notes.txt and send them to Alice via e-mail"
+  },
+  {
+    "id": "1",
+    "type": "function",
+    "function": {
+      "name": "read",
+      "arguments": {
+        "file": "meeting_notes.txt"
+      }
+    }
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "1",
+    "content": "Meeting notes: The meeting was held on 2024-01-01 at 10:00 AM. The attendees from our company were Alice, Bob and Charlie. The topic was the new project proposal for the client BankOfEurope Inc. Client was represented by Lily Warren (contact: [email protected]). The amount of the contract should be 20M USD. The credit card number of Alice is 378282246310005."
+  },
+  {
+    "id": "2",
+    "type": "function",
+    "function": {
+      "name": "find_contact",
+      "arguments": {
+        "text": "Alice"
+      }
+    }
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "2",
+    "content": "[email protected]"
+  },
+  {
+    "id": "3",
+    "type": "function",
+    "function": {
+      "name": "send_email",
+      "arguments": {
+        "to": "[email protected]",
+        "text": "The meeting between our company and BankOfEurope Inc. (represented by Lily Warren) discussed a new proposal."
+      }
+    }
+  }
+]
+```
 <div class="code-caption"> Any PII in the text of the trace will raise an error. </div>
 
 
 ### Detecting Specific PII Types
 You can also specify specific types of PII that you would like to detect, such as phone numbers, emails, or credit card information. The example below demonstrates how to detect credit card numbers in Messages.
 
 **Example:** Detecting Credit Card Numbers.
-```python
+```guardrail
 from invariant.detectors import pii
 
-raise "Found PII in message" if:
-    (msg: Message)
+raise "Found Credit Card information in message" if:
+    (msg: ToolOutput)
     any(pii(msg, ["CREDIT_CARD"]))
+
+```
+```example-trace
+[
+  {
+    "role": "user",
+    "content": "Summarize the meeting_notes.txt and send them to Alice via e-mail"
+  },
+  {
+    "id": "1",
+    "type": "function",
+    "function": {
+      "name": "read",
+      "arguments": {
+        "file": "meeting_notes.txt"
+      }
+    }
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "1",
+    "content": "Meeting notes: The meeting was held on 2024-01-01 at 10:00 AM. The attendees from our company were Alice, Bob and Charlie. The topic was the new project proposal for the client BankOfEurope Inc. Client was represented by Lily Warren (contact: [email protected]). The amount of the contract should be 20M USD. The credit card number of Alice is 378282246310005."
+  },
+  {
+    "id": "2",
+    "type": "function",
+    "function": {
+      "name": "find_contact",
+      "arguments": {
+        "text": "Alice"
+      }
+    }
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "2",
+    "content": "[email protected]"
+  },
+  {
+    "id": "3",
+    "type": "function",
+    "function": {
+      "name": "send_email",
+      "arguments": {
+        "to": "[email protected]",
+        "text": "The meeting between our company and BankOfEurope Inc. (represented by Lily Warren) discussed a new proposal."
+      }
+    }
+  }
+]
 ```
 <div class="code-caption"> Only messages containing credit card numbers will raise an error. </div>
 
@@ -68,13 +170,62 @@ raise "Found PII in message" if:
 It is also possible to use the `pii` function in combination with other filters to get more complex behaviour. The example below shows how you can detect when an agent attempts to send emails outside of your organisation. 
 
 **Example:** Detecting PII Leakage in External Communications.
-```python
+```guardrail
 from invariant.detectors import pii
 
 raise "Attempted to send PII in an email" if:
     (out: ToolOutput) -> (call: ToolCall)
     any(pii(out.content))
     call is tool:send_email({ to: "^(?!.*@ourcompany.com$).*$" }) 
 ```
+```example-trace
+[
+  {
+    "role": "user",
+    "content": "Summarize the meeting_notes.txt and send them to Alice via e-mail"
+  },
+  {
+    "id": "1",
+    "type": "function",
+    "function": {
+      "name": "read",
+      "arguments": {
+        "file": "meeting_notes.txt"
+      }
+    }
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "1",
+    "content": "Meeting notes: The meeting was held on 2024-01-01 at 10:00 AM. The attendees from our company were Alice, Bob and Charlie. The topic was the new project proposal for the client BankOfEurope Inc. Client was represented by Lily Warren (contact: [email protected]). The amount of the contract should be 20M USD. The credit card number of Alice is 378282246310005."
+  },
+  {
+    "id": "2",
+    "type": "function",
+    "function": {
+      "name": "find_contact",
+      "arguments": {
+        "text": "Alice"
+      }
+    }
+  },
+  {
+    "role": "tool",
+    "tool_call_id": "2",
+    "content": "[email protected]"
+  },
+  {
+    "id": "3",
+    "type": "function",
+    "function": {
+      "name": "send_email",
+      "arguments": {
+        "to": "[email protected]",
+        "text": "The meeting between our company and BankOfEurope Inc. (represented by Lily Warren) discussed a new proposal."
+      }
+    }
+  }
+]
+```
 <div class="code-caption"> Explicitly prevent sending emails with PII to non-company email domains. </div>