Auditor Development (SDK)
The Lucid SDK provides a high-level, decorator-based API for building custom safety guardrails. This guide covers the common patterns and best practices for developing effective auditors.
🏗️ The Auditor Builder
Every auditor starts with create_auditor(). This factory function initializes a builder that maps your Python functions to specific lifecycle phases.
from lucid_sdk import create_auditor
builder = create_auditor(auditor_id="my-safety-node")
🔄 Lifecycle Hooks
Lucid Auditors are Phase-Aware. You can hook into four distinct stages of an AI request's lifecycle.
1. Artifact Verification (@builder.on_artifact)
Runs at deployment time. Used to verify model weights, configuration files, or SBOMs before the workload is allowed to start.
2. Request Filtering (@builder.on_request)
Intercepts the user prompt before it reaches the AI model. * Best for: PII redaction, prompt injection detection, data sovereignty checks.
3. Execution Monitoring (@builder.on_execution)
Observes the model during inference. Does not block the request but can emit telemetry. * Best for: Measuring latency, GPU memory usage, or token counts.
4. Output Validation (@builder.on_response)
Final check before the model's response is released to the user. * Best for: Toxicity detection, hallucination checks, bias auditing.
⚖️ Audit Decisions
Your hooks must return an AuditResult. Use these convenience helpers:
| Decision | Action | Use Case |
|---|---|---|
Proceed() |
Allows the data through unchanged. | No violations found. |
Deny(reason) |
Blocks the entire request. | Critical security threat (e.g., injection). |
Redact(mods) |
Replaces sensitive data with masks. | PII found (SSN, emails). |
Warn(reason) |
Allows data but flags it in the AI Passport. | Minor policy deviation. |
📦 Emitting Evidence
By default, the SDK handles the collection and signing of hardware evidence. When you return an AuditResult, it is automatically bundled into a Measurement and pushed to the Lucid Verifier.
🧪 Testing Locally
You can test your auditor hooks directly in Python before containerizing:
# Simple unit test
result = scan_pii({"prompt": "My SSN is 123-45-6789"})
assert result.decision == "DENY"
For full integration testing, use the Interactive Demo which provides a mock attestation environment.