Sunglasses is a filter that sits ahead of your agent. Always ON. If you're building a custom Python agent on top of an LLM SDK — Anthropic, OpenAI, Gemini — this is the SDK wiring path. One import, one scan call, mandatory filter before every LLM invocation.

Who this page is for

Developers building custom Python agents on top of raw LLM SDKs (Anthropic, OpenAI, Google Gemini) or without a framework. You control the code — the filter is a 2-line drop-in before your LLM call.

The command

from sunglasses.engine import SunglassesEngine

Filter every LLM call in your custom Python agent. Import the engine, call scan() on any untrusted input, branch on decision (block / warn / allow). Drop in front of api.messages.create(), client.chat.completions.create(), or any model invocation in your code.

Benefit: You own your agent's security layer without sending anything to the cloud. Local, fast, composable with any SDK.

Full walkthrough coming next. This is an identity-first scaffold — the core command and wiring pattern are ready. The full step-by-step code walkthrough, integration examples, and troubleshooting section are being drafted now. Check back shortly.

FAQ

How do I add input filtering to a custom Python AI agent?

Import SunglassesEngine from sunglasses.engine, instantiate it once, and call engine.scan(text) before any LLM invocation. The result has a decision (block, warn, allow) — branch on it and refuse to call the LLM if blocked.

Can I use Sunglasses with the Anthropic SDK?

Yes. Scan the user input with engine.scan() before calling anthropic.messages.create(). If decision is block, return a refusal to the user. If warn or allow, proceed with the API call.

Can I use Sunglasses with the OpenAI SDK or Google Gemini?

Yes. Sunglasses is provider-agnostic. Scan the input with engine.scan() before any client.chat.completions.create() or equivalent call. The filter runs before the model is invoked — works identically regardless of which LLM provider you use.

What is the scan API signature?

engine.scan(text: str, channel: str = 'message') returns a ScanResult with fields decision ('block', 'warn', 'allow'), severity, findings (list of matched patterns), and is_clean (bool). Channel accepts 'message', 'file', 'api_response', 'web_content', 'log_memory'.

How fast is the scan?

Average scan time is 0.26ms on M3 Max. Throughput is approximately 3,830 scans per second single-threaded. For most applications the filter pass is invisible next to the LLM call latency.

Where this wiring fits

Sunglasses is one filter with four wiring options. This page covers the Custom Python Agent path. Other wiring paths:

Same filter underneath. Different wiring based on your stack.