feat: add observability hooks to guard and redact methods (#1099)

[frankentini]

Summary

Closes #1099.

Adds on_guard and on_redact observability callback hooks to the Python SDK so callers can plug in logging, metrics, alerting, or any custom observability pipeline without modifying the guard/redact flow.

Changes

New types (types.py)

• ObservabilityEvent — dataclass with: method, model, input_preview (first 200 chars), classification, violation_types, prompt_tokens, completion_tokens, total_tokens
• ObservabilityCallback — union type accepting sync or async callables
• ClientConfig.on_guard / ClientConfig.on_redact — optional callback slots
• Added from __future__ import annotations for compatibility

Client (client.py)

• _fire_observability() — internal helper that invokes the callback (sync or async); swallows all exceptions so a bad callback never disrupts a guard/redact call
• guard() — fires ObservabilityEvent after all four code paths: plain text, chunked text, PDF, and image
• redact() — fires ObservabilityEvent after every call (classification=None)
• create_client() — exposes on_guard / on_redact as top-level kwargs for convenience

Public API (__init__.py)

• Exports ObservabilityEvent and ObservabilityCallback

Tests (tests/test_observability.py, 404 lines, 17 tests)

• Sync and async callbacks for guard and redact
• Block classification + violation_types propagation
• Exception swallowing (bad callback must not raise)
• input_preview truncated to 200 chars
• Chunked guard fires exactly one aggregated event
• ClientConfig wiring through SafetyClient directly
• classification=None invariant for redact events

Usage

from safety_agent import create_client, ObservabilityEvent

# Sync callback
def log_event(event: ObservabilityEvent) -> None:
    print(f"[{event.method}] {event.classification} – {event.total_tokens} tokens")

client = create_client(api_key="...", on_guard=log_event)
result = await client.guard(user_input, model="openai/gpt-4o")

# Async callback
async def async_log(event: ObservabilityEvent) -> None:
    await metrics_client.record(event)

client = create_client(api_key="...", on_guard=async_log, on_redact=async_log)

Design decisions

• Fire-and-forget with swallowed exceptions — same philosophy as _post_usage(). A misconfigured callback must never degrade safety checks.
• One event per public call — chunked guard aggregates token counts before firing, so callers always see a single event per guard() invocation.
• input_preview not full input — avoids logging PII at scale while still being useful for debugging.
• classification=None for redact — redact produces sanitized text, not a pass/block verdict; marking it None keeps the type honest.

[vercel]

@frankentini is attempting to deploy a commit to the Superagent Team on Vercel.

A member of the Team first needs to authorize it.

[homanp]

@cursor review

[cursor]

Cursor Bugbot has reviewed your changes and found 2 potential issues.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit dce2496. Configure here.}

[cursor]

Redact observability placed inside wrong try/except scope

Low Severity

The _fire_observability call and ObservabilityEvent construction in redact() are placed inside the try/except Exception block meant for JSON parsing errors. While _fire_observability internally swallows exceptions, the ObservabilityEvent(...) constructor is evaluated before entering that protection. If event construction ever raises (e.g., due to future validation logic), the already-successful redact_response is discarded and a misleading "Failed to parse redact response" error is raised instead. This is inconsistent with guard(), where all observability calls sit outside try/except blocks.

Additional Locations (1)

• sdk/python/src/safety_agent/client.py#L642-L644

 

^{Reviewed by Cursor Bugbot for commit dce2496. Configure here.}

[cursor]

Callbacks silently dropped when config provided without api_key

Medium Severity

When a user calls create_client(config=ClientConfig(api_key="..."), on_guard=my_callback), the on_guard and on_redact kwargs are silently ignored. The if config is None branch is skipped (config exists), and the elif api_key: branch is also skipped (no separate api_key kwarg), so the original config object — without the user's callback — is passed directly to SafetyClient. The user's observability callback is quietly lost with no warning.

 

^{Reviewed by Cursor Bugbot for commit dce2496. Configure here.}