obsvr-sdk

Runtime governance for LLM applications in Python: deterministic policy enforcement (PII, custom rules, human-in-the-loop hooks), and a tamper-evident, HMAC-chained audit trail. Delivery that does not wait on the ingest transport, so a slow or dead backend does not slow your calls.

Installation

pip install obsvr-sdk

Enforcement needs no account. Policy, PII, and agent checks run entirely in your process, but you must configure the controls you want to enforce; an API key enables signing and delivery, not a default block policy. Delivering the signed audit record needs an obsvr ingest service, which is in private beta; you receive its URL together with your key. Until ingest_url is set the SDK still enforces — it warns once and delivers nothing. Request access →

Requires Python >= 3.10. No runtime dependencies.

Optional extras for the provider clients obsvr.register / obsvr.auto patch:

pip install "obsvr-sdk[openai]"           # OpenAI client governance
pip install "obsvr-sdk[anthropic]"        # Anthropic client governance
pip install "obsvr-sdk[openai-agents]"    # OpenAI Agents tool gate + tracing processor
pip install "obsvr-sdk[gemini]"           # Google Gemini (current google-genai + legacy client)
pip install "obsvr-sdk[mcp]"              # MCP tool governance (mcp 2.x)

Optional extras for framework integrations:

pip install "obsvr-sdk[langchain]"        # LangChain callback handler
pip install "obsvr-sdk[crewai]"           # CrewAI integration (Python < 3.14)
pip install "obsvr-sdk[autogen]"          # AutoGen integration
pip install "obsvr-sdk[llamaindex]"       # LlamaIndex integration
pip install "obsvr-sdk[bedrock]"          # AWS Bedrock (boto3) governance
pip install "obsvr-sdk[vertex]"           # Google Vertex AI governance
pip install "obsvr-sdk[pydantic-ai]"      # PydanticAI toolset governance
pip install "obsvr-sdk[haystack]"         # Haystack 2.x / 3.x prompt guard + Agent tool gate
pip install "obsvr-sdk[otel]"             # OpenTelemetry span mirroring

Ed25519 verification of signed remote policy needs one of two backends — install either, not both:

pip install "obsvr-sdk[crypto]"           # cryptography (preferred)
pip install "obsvr-sdk[crypto-nacl]"      # PyNaCl (alternative)

Quick Start

Wrap your existing LLM client. No other code changes.

import obsvr
from openai import OpenAI

obsvr.init(
    api_key="your-api-key",
    ingest_url="https://your-ingest-service",  # HTTPS enforced for non-localhost
    environment="production",
)

client = obsvr.wrap(OpenAI())

# Supported text-generation methods are policy-checked; clean allows may be sampled.
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What is 2+2?"}],
)

Anthropic and current Google Gemini work the same way (sync and async clients supported):

client = obsvr.wrap(Anthropic())          # messages.create
client = obsvr.wrap(GoogleGenAI())        # models.generate_content / aio.models.generate_content

Which Gemini SDK. Google ships two, and obsvr integrates both:

Compatibility only means fixes, not features: the legacy adapter is kept working for existing deployments. The two distributions have different method and response shapes and use separate adapters.

Both Gemini clients need an explicit obsvr.wrap() — unlike OpenAI and Anthropic, Python auto-registration does not intercept either package. The current adapter wraps GoogleGenAI and governs models.generate_content, models.generate_content_stream, and the corresponding aio.models methods. The legacy adapter wraps GenerativeModel and remains compatibility-only.

wrap() governs chat.completions.create / .parse, responses.create / .parse, messages.create / .parse, their with_raw_response and with_streaming_response variants where the provider exposes them, legacy generate_content / generate_content_async, current models.generate_content / models.generate_content_stream and their aio.models counterparts, start_chat().send_message / .send_message_async, and the beta.chat.completions.create / .parse, beta.messages.create, and beta.responses.create namespaces. Anthropic's beta.messages.tool_runner is also governed from Anthropic 0.68.0, including the initial Messages prompt and every local runnable tool; the async beta.sessions.events.tool_runner local tools are governed from 0.103.0. Hosted tool definitions have no local callback to gate. Everything else on the client passes through ungoverned and unaudited — see the coverage boundary in obsvr/wrap.py for which of those carry no chat text at all and which are text-bearing but not yet reachable from a method-path table.

A wrap() that governs nothing says so. If none of those paths resolve on the client you pass, the returned object still works and still forwards every call — but no policy runs and no event is emitted for it, so wrap() logs one WARNING naming the gap and the paths it looks for. Once per client, not per call. Pass require_governed_surface=True to init() to make it raise instead, for a deployment that wants an ungoverned client to fail at startup rather than at audit time.

MCP Governance

Wrap the MCP client session; governance then covers all three phases — discovery (tool descriptions scanned for poisoning), request (tool arguments policy- and PII-checked before the call runs), and response (the tool RESULT scanned before it reaches the caller). Tool results are the exfiltration/poisoning channel, so a result carrying PII, secrets, or an injection payload is blocked, sanitized (offending spans redacted), or logged per policy — a blocked result is withheld from the caller entirely.

govern_mcp(session) is non-mutating — the Python analog of the TypeScript obsvrGovernMCP. It returns a wrapper that delegates every attribute to the real session via __getattr__ and intercepts send_request, call_tool and list_tools; the ClientSession class is never patched, so other MCP tooling on the same session keeps working. send_request is the load-bearing one: call_tool is a convenience over it, and the task API and a hand-built tools/call frame reach a tool without touching call_tool at all — measured, each executed a denied tool before the gate bound there.

from mcp import ClientSession
from obsvr.integrations.mcp import govern_mcp

obsvr.init(
    api_key="your-api-key",
    ingest_url="https://your-ingest-service",
    mcp_tool_policy={
        "denied_tools": ["delete_file"],
        "block_poisoned_tools": True,
    },
)

async with ClientSession(read, write) as session:
    # Bind the caller identity (options mirror the TS obsvrGovernMCP opts) so
    # user/service/tenant-scoped quota rules meter the right bucket and the audit
    # attributes each decision to the principal.
    session = govern_mcp(session, options={"user_id": "alice"})
    await session.call_tool("read_file", {"path": "/tmp/x"})

The legacy patch_mcp(ClientSession) — which monkey-patches the session class in place — is deprecated (it warns once and will be removed in the next major release). Migrate to govern_mcp unless you need the one route only a class-level patch reaches: a ClientSessionGroup handed the RAW session from underneath an instance wrapper dispatches through that object, so govern_mcp never sees the call. That route is measured and is listed in the table below.

Unicode normalization (matching-time only)

Before rule, PII, and injection matching, text is normalized (Unicode NFKC + zero-width/invisible-character stripping + a small curated confusable fold) so an attacker cannot slip a keyword or pattern past the scanners with a lookalike or zero-width-joined variant. This is a matching-time transform only: it changes what the engine detects, never what it stores or forwards — the audited content and the redaction output reflect exactly what the user sent. The transform is pinned across both SDKs by conformance/fixtures/normalization.json.

Framework Integrations

Each enforcing integration hooks its framework's real call/tool path and runs the applicable pre-call PII/rules/HITL pipeline, plus post-call governance where the framework exposes it. LangChain, LlamaIndex, and OpenAI Agents model callbacks are observe-only; their tool gates are documented separately below. Whether a tool-policy block actually stops the tool is a per-integration property, not a property of the SDK — it depends on whether the framework hands obsvr a hook that runs before the tool does, and several do not. Each tool-policy state below was driven live against a real run rather than read off the code, and the one row that has not been says so; where a gate is present but unreachable the row reports that instead of listing the feature.

"observe + stored-copy PII" is the whole of it, and it is worth spelling out. On the model-call paths of LangChain, LlamaIndex and the OpenAI Agents tracing processor the PII scan runs and the stored copy is redacted — and nothing else in the pipeline does. Measured layer by layer rather than read off the code: policy_rules, the non-overridable policy_floor, the on_pre_call hook, outbound redaction, the kill-switch / stale-policy integrity gate, the response-side scan and PII blocking do not run there, and metering is opt-in. So a pii_policy of {"rules": {"ssn": "block"}} refuses the call through obsvr.wrap(), Bedrock, Vertex and MCP, and through these three the call goes out with the SSN in it while the event honestly records that the stored copy was redacted. This storage-only case records action_taken: "not_evaluated" plus stored_redaction_scope, stored_redaction_types, stored_redaction_outbound_unmodified and stored_redaction_requested_action under metadata.obsvr_telemetry. Put an enforcement decision on obsvr.wrap() or on MCP. This is about the model call only — all three of these surfaces carry a tool gate that enforces, graded in the table above.

"Metering is opt-in" means the default is OFF, and that is a decision. meter_integration_events defaults to false, so framework-integration events carry no cost fragment and never increment a token-unit quota; the obsvr.wrap() client-proxy path is metered either way and the flag does not affect it. The default is off because turning it on is not a neutral correction — a token-unit budget that has never bound on framework traffic begins binding, and calls that previously succeeded start being refused once it is reached. For an operator already running a token quota that is an outage rather than a fix, so it has to be a deliberate choice. One flag covers cost and quota together, because metering what a call cost without counting it against the budget it belongs to produces a record that disagrees with itself.

Callback-style (LangChain / LlamaIndex / OpenAI Agents / CrewAI):

from obsvr.integrations.langchain import ObsvrCallbackHandler

handler = ObsvrCallbackHandler()
llm = ChatOpenAI(callbacks=[handler])
# Every chain/LLM call is now policy-checked and audited

Infrastructure providers — wrap the client/model; every governed call is policy-checked on the way in and governed on the way out:

import boto3, obsvr
from obsvr.integrations.bedrock import wrap_bedrock

obsvr.init(api_key="...", ingest_url="https://...",
           pii_policy={"rules": {"ssn": "block"}})
client = wrap_bedrock(boto3.client("bedrock-runtime"))
client.converse(modelId="anthropic.claude-3-5-sonnet-...", messages=[...])

from vertexai.generative_models import GenerativeModel
from obsvr.integrations.vertex import wrap_vertex

model = wrap_vertex(GenerativeModel("gemini-1.5-pro"))
model.generate_content("...")

Agent frameworks — register the governance hook; a blocked tool/agent/function never executes:

# PydanticAI
from obsvr.integrations.pydantic_ai import ObsvrToolset
agent = Agent("openai:gpt-4o", toolsets=[ObsvrToolset(my_toolset)])

# OpenAI Agents — obsvr's guardrail on every function tool reachable from the
# agent (handoff targets included); a denied tool never runs and the model
# receives the block message as the tool result. govern_tool is the
# alternative when a denial should ABORT the run instead.
from obsvr.integrations.openai_agents import attach_tool_gate
detach = attach_tool_gate(agent)

# Haystack — the guard is the same on 2.x and 3.x; only the socket differs,
# because 3.0 removed the text OpenAIGenerator and its `prompt` input.
from obsvr.integrations.haystack import ObsvrGuard
pipe.add_component("guard", ObsvrGuard())
pipe.connect("guard.prompt", "llm.prompt")    # haystack-ai 2.x, OpenAIGenerator
pipe.connect("guard.prompt", "llm.messages")  # haystack-ai 3.x, OpenAIChatGenerator

# Haystack tools are governed separately, by the Agent's own before_tool hook.
from obsvr.integrations.haystack import install_tool_gate_hook
agent = Agent(chat_generator=..., tools=[...],
              hooks={"before_tool": [install_tool_gate_hook()]})

# The prompt guard uses a terminal result rather than an exception, which keeps
# the raw prompt out of Haystack's PipelineRuntimeError snapshots.
result = pipe.run({"guard": {"prompt": "..."}})
if result.get("guard", {}).get("blocked"):
    handle_policy_block(result["guard"]["block_reason"])

Agent runs

obsvr.agent_run(name) records one agentic execution as a run — every governed action inside it (LLM calls, tool calls, spans) is grouped under one agent_run_id, so it appears as a single row in the dashboard's Runs tab with its full trace. It emits a signed <source>.agent.run.start on entry and a terminal <source>.agent.run.finish on exit (success or failure).

with obsvr.agent_run("support-agent", source="llamaindex_py"):
    agent.chat(user_message)   # LLM calls, tool calls inside join this run

The run boundary is this explicit scope — deterministic and developer-declared, never inferred. (TypeScript: await obsvr.agentRun("support-agent", () => agent.run(msg), { source: "llamaindex_ts" }).)

Per-request identity

When supplied, a governed call resolves one principal — the user_id that user-scoped quota buckets meter, the session-taint latch keys on, approval grants bind to, and the signed event carries inside the decision preimage. Attribution is optional unless require_principal=True. One resolution feeds both enforcement and the record: per-call metadata first, then the wrap-time user_id= option, then the ambient subject below. This used to be two channels on the generic tool governor — the wrap-time kwarg reached the signed record only while quota, taint, approvals and the decision-input hash read metadata it never touched, so govern_tool(tool, user_id="mallory") produced a signed principal with none of the user-scoped enforcement bound to it. The fold is now shared, and a tree-scan test fails any pre-call surface that ships without it.

A wrap-time option binds one identity for the object's lifetime. A process serving many end users binds per request instead:

from obsvr import use_subject

governed = obsvr.govern_tool(tool)          # govern once...

with use_subject("user:alice;tenant:acme"): # ...attribute per request
    governed.run("...")                     # metered, latched, signed as alice
with use_subject({"user_id": "bob"}):
    governed.run("...")                     # a different bucket, a different record

An explicit user_id= or metadata identity always beats the ambient one, and with no scope active behavior is exactly as before. The propagation boundary is pinned in tests, not inferred: the subject survives await, asyncio.create_task and asyncio.to_thread, and is silently lost across loop.run_in_executor, ThreadPoolExecutor.submit and threading.Thread — a worker-thread tool call inside a scope runs as if no scope were active, with nothing on the record to say so. If a tool body hops to a worker thread, pass user_id explicitly on that path.

require_principal=True (off by default) refuses a governed call whose enforcing channel carries no non-blank user_id — PRINCIPAL_REQUIRED, after the enforcement-integrity gate, before any scanning layer. Empty and whitespace- only strings are unattributed. It is enforced in the shared pre-call pipeline (wrap(), the integrations, govern_tool, MCP) and arms the tool and MCP pre-call nets by itself, so a config whose only policy is this flag still refuses there.

Policy Enforcement

Policies run before the call proceeds. Deterministic code only; no LLM in the decision path.

obsvr.init(
    api_key="your-api-key",
    ingest_url="https://your-ingest-service",

    # Built-in PII scanning: block | redact | detect_only per type
    pii_policy={
        "default": "detect_only",
        "rules": {"ssn": "block", "credit_card": "block", "email": "redact"},
    },

    # Custom pre-call hook: return "allow" | "block" | "redact".
    # Enforcement is monotonic: "allow" keeps a clean call allowed but never
    # erases a PII/rule block rendered by an earlier layer.
    on_pre_call=lambda event: "block" if is_high_risk(event["prompt"]) else "allow",
    hook_timeout_ms=2000,

    # Enforcement fail mode when a hook times out or raises:
    # "open" (default) allows the call; "closed" blocks it.
    fail_mode="closed",
)

Built-in regex detection covers 13 PII types including SSN, credit cards, API keys, AWS access keys, private keys, GitHub tokens, Slack webhooks, JWTs, and prompt-injection patterns. Optional Presidio integration (set presidio_analyzer_url) adds the 6 NLP types (name, address, person, location, medical, national_id) for the full 19-type taxonomy. Detection parity with the TypeScript SDK is enforced by shared test vectors.

Opt-in security controls (all off by default): policy_floor — a non-overridable operator baseline (same shape as a policy rule) that customer rules and the on_pre_call hook can't weaken, with a floor redact failing closed to a block; deobfuscation={"enabled": True} — also scan base64/hex/percent-decoded and invisible/confusable-folded views so encoded payloads can't dodge detection; mcp_tool_policy={"pinning": {"enabled": True, "mode": "block"}} — content-hash MCP tool descriptors to catch a rug-pull swap; session_taint={"enabled": True} — latch a session as compromised on an injection/canary leak and escalate later egress, with destructive_tools naming exact tools a tainted session may never invoke even in flag mode; require_principal=True — refuse a call that arrives with no non-blank user_id on the enforcing channel (PRINCIPAL_REQUIRED; empty and whitespace-only strings are unattributed — see Per-request identity); and canary honeytokens via mint_canary() — plant a unique token and get a CRITICAL signal if it resurfaces. See SECURITY.md for each control's exact guarantee and boundary.

Global monitor mode. enforcement_mode="monitor" is one flip meaning "keep deciding and recording, stop enforcing": every applicable layer still evaluates, every governed decision and execution-span event emits, and a final block is converted to an allow whose shadow_outcome carries the would-be verdict with the same rule_id and reason_code an enforcing run records. Two classes enforce in both modes: the enforcement-integrity gate (kill switch / fail-closed staleness), re-derived at the moment of conversion so a stale snapshot cannot extend monitor mode to a revoked key, and canary-leak blocks. A converted event is enforcement evidence, exempt from allowed-call sampling even at sample_rate=0, and explain() keeps predicting enforce-mode behaviour so the pre-flight check still describes what turning enforcement on would do.

Rule ordering, and opting out of it. Rules evaluate first-match in document order by default, and a matched topic_allow short-circuits — an allow rule's list position can decide the verdict. rule_resolution= "deny_wins" opts a deployment out: every enforcing rule is evaluated and the strongest action prevails regardless of position (refusal over redaction over flag over permit, smallest rule id breaking ties), decisions carry engine version obsvr-rules/2, and the stamped policy_version commits to the declared semantics — under a declared first_match it commits to evaluation order, while undeclared rulesets keep their existing hash bytes. An unknown declaration raises at init(). Two deliberate, pinned edges: shadow rules evaluate first-match regardless of the declared mode, and under deny_wins every quota rule meters every evaluated call — a call that ends blocked can still consume quota, where first-match stopped metering at its first match.

Blocking human approval. A rule with "require_approval": True refuses when no grant covers the call and files a request for the approvals queue; a retry passes once a human grants it. That is the default, and approval_wait_ms=0 means exactly that — no waiting. Set it above zero and the SDK holds the call in the calling thread instead, polling the grant channel (approval_poll_ms, default 5000) until a covering grant lands or the budget expires. Only an explicit, still-live grant lifts the hold — it is re-validated after the wait, so a grant that expires mid-hold authorizes nothing — and an expired hold blocks with its own registry code, APPROVAL_TIMEOUT, distinct from APPROVAL_REQUIRED so a run-out hold is never conflated with a plain refusal. Degradation mid-wait aborts the hold and the block stands. One stated limit: a denial is currently indistinguishable from indecision client-side — the grant channel carries grants, not verdicts, so an explicitly denied request surfaces as the same APPROVAL_TIMEOUT as one nobody looked at. Do not build this out of on_pre_call: the hook is budgeted by hook_timeout_ms and resolves by fail_mode on expiry, which at shipped defaults means a hook that waits for a human times out and allows.

Verdict reason codes

Every policy verdict carries a stable, machine-groupable reason_code drawn from a closed registry (obsvr.ReasonCode) plus the existing free-form reason string as human detail — the code is additive, so nothing is lost. The same code rides every audit event (reason_code), always identical to the one on the raised ObsvrPolicyError, so the record and the exception never classify a decision differently. Codes such as KEYWORD_BLOCKED, QUOTA_EXCEEDED, MODEL_GATE_BLOCKED, APPROVAL_REQUIRED, APPROVAL_TIMEOUT, PRINCIPAL_REQUIRED, and SHADOW_WOULD_BLOCK are pinned in conformance/fixtures/reason_codes.json so the Python and TypeScript SDKs share one identical vocabulary. One is worth knowing by name: QUOTA_UNMETERED is the only code that reports enforcement did not happen rather than a verdict the engine reached, and it is emitted when a quota scope the bounded counter store could not admit is refused under fail_mode="closed". A CI staleness check fails if the two registries diverge, if the engine can emit a code outside the registry, or — the inverse — if a registry code has no emission path at all (a code without one must be explicitly reserved, with its owning control named).

from obsvr import ReasonCode, REASON_CODES

External Policy Backend (OPA / Cedar)

Already standardized on policy-as-code? Point obsvr at your existing OPA HTTP endpoint or Cedar authorization service and its verdict participates in every pre-call decision.

obsvr.init(
    api_key="your-api-key",
    ingest_url="https://your-ingest-service",
    external_policy_backend={
        "type": "opa",  # "opa" | "cedar"
        "url": "https://opa.internal.example.com/v1/data/obsvr/allow",
        # "shadow": True,        # observe-only rollout: record the verdict, never block
        # "timeout_ms": 2000,    # error/timeout => DENY (fail-closed) in enforce mode
        # "headers": {"authorization": "Bearer ..."},
        # "name": "corp-opa",    # identity recorded on events (provenance)
        # "policy": "<rego text or bundle revision>",  # hashed into the provenance record
        # "allow_private_network": True,  # permit a sidecar/private-network backend
    },
)

Semantics (byte-identical to the TypeScript SDK, pinned by shared conformance fixtures):

• Deny-wins merge. A deny from either the local rules or the backend blocks the call. A backend allow never downgrades a local block.
• Fail-closed. A backend error or timeout counts as deny. Use "shadow": True for a safe, observe-only rollout that records what the backend would have done without ever blocking.
• SSRF-guarded. The production transport resolves the backend hostname once, rejects the complete address snapshot if any answer is private / loopback / link-local / cloud metadata, and pins a fresh connection to an approved numeric address while retaining the original Host header and TLS server name. Redirects are not followed. A legitimate sidecar on localhost/a private network needs "allow_private_network": True; cloud-metadata and link-local ranges remain blocked. An explicitly injected transport is a trusted embedding seam and must provide equivalent address pinning.
• Provenance. Each event records which backend decided via external_backend (identity, backend type, raw outcome, shadow flag, and a hash of the effective backend policy).

The OPA endpoint is POSTed {"input": <decision document>} and its result is read as allow (boolean, or {allow, reasons}); the Cedar endpoint receives the decision document and its decision (Allow/Deny) is read. The decision document carries non-content fields only — operation, provider, model, principal, the local decision so far, the rules hash, and a SHA-256 digest of the prompt (never the raw prompt). Zero-config default is no backend.

Tamper-Evident Audit Trail

Every event is stamped with a session ID, a monotonic sequence number, and an HMAC-SHA256 signature chained to the previous event's signature (prev_sig). The signing algorithm is byte-for-byte identical to the TypeScript SDK, verified by shared cross-language test vectors, so the ingest service verifies events from both SDKs with the same code and countersigns each accepted event.

Exported bundles verify offline with the obsvr-verify CLI shipped by both SDK packages, and merges can be gated on it in CI via the obsvr Evidence Verification GitHub Action.

Known Limitations & Architecture Notes

The boundaries below are enforcement limits.

Before you install: the five limits of the Python SDK

Scope: this list is the Python SDK only. The two SDKs do not have the same limitations — the TypeScript SDK has two of its own that do not apply here (it is ESM-only, and its zero-code auto-register misses documented import and timing shapes), and one below does not apply to it. The combined list for both, with the scope marked on each entry, is in the repository README.

A limit measured on one SDK is a hypothesis about the other, not a fact about it. This paragraph used to say neither list "may be read across", which reads as an assurance that a TypeScript limit is absent here. One of them was not: zero-code interception enumerated client class NAMES in both languages, and a provider binds one class to several of them (anthropic.Client is anthropic.Anthropic is True), so construction through an unlisted name escaped governance on BOTH sides while init(auto=True) reported success. It is fixed in both — Python resolves the class objects and rebinds every public name bound to one — and the wording is corrected here because the sentence was doing work it could not support. Read each list as scoped, not as a guarantee about what is absent elsewhere.

1. Most integration tests drive hand-written fakes, not the real frameworks. MCP and maintained Google Gen AI run against real upstream packages in CI. A green integration suite says the shape is right, not that the framework behaves the way the test models it. tests/README.md says which surfaces are which.

2. A shutdown handler you install AFTER obsvr.init() replaces obsvr's. This SDK flushes on SIGTERM/SIGINT as well as atexit, chains to whatever disposition was already there, and restores the default and re-delivers only when nothing else owned the signal — so a container stop no longer drops the queue tail, and the process still dies by the signal rather than with an exit code standing in for one. The residual is ordering, and it is structural: a POSIX disposition is a single slot where Node keeps a listener list, so TypeScript decides ownership when the signal arrives and this SDK can only decide it at install time. Call obsvr.init() before your shutdown wiring, or call obsvr.flush() from your own handler. Two smaller consequences of the same rule: SIG_IGN is left alone entirely, and a handler installed from outside Python cannot be chained to, so obsvr keeps the exit there rather than swallowing the signal.

3. LangChain, LlamaIndex and the OpenAI Agents tracing processor observe rather than govern. On those model-call paths the PII scan runs over what the event will store, and nothing else runs — so the provider receives the raw prompt while the stored copy reads redacted. A pii_policy of {"ssn": "block"} blocks through obsvr.wrap() and does not block there.

4. Three frameworks needed pre-execution mechanisms of their own, and WHICH one you install decides the coverage. A callback that fires after the step it reports can refuse nothing, so on the three surfaces where obsvr's only callback was one of those it now refuses ahead of it instead: on LlamaIndex, govern_agent(agent), which binds to get_tools where the agent assembles a turn's tools and governs each through the full pre-call net; on CrewAI, its own before_tool_call hook (1.15.3+, sentinel contract) and the governed tool; on OpenAI Agents, attach_tool_gate — obsvr's ToolInputGuardrail on each function tool, consulted by the executor before invocation, refusing by reject_content so the run continues — and the governed tool, whose refusal aborts the run as UserError. All driven live to zero side-effect writes on denied tools. The mechanism matters because each framework can reach a tool by more than one route: obsvr.govern_tool governs an OBJECT, so on LlamaIndex a tool arriving per turn from a tool_retriever ran under a policy that denied it, and govern_agent is what reaches it. Where a surface records a denial it cannot enforce, it records not_evaluated, never blocked — silences, not false refusals. mcp, langchain, autogen, pydantic_ai, llamaindex (via govern_agent), crewai (via its hook), openai_agents (via its guardrail), haystack (via its before_tool hook) and any govern_tool-wrapped tool are where a tool-policy decision means what it says. Grading.

5. Current Gemini coverage is method-bounded. google-genai 2.x is governed through explicit wrapping on unary and streaming generation for sync and async clients. Chat sessions, Live API, Interactions, batches, token counting, and binary/multimodal payload contents remain outside this wrapper.

• Transport: init() raises when a non-localhost ingest_url uses plaintext http (localhost, 127.0.0.1, and [::1] are exempt for local development — compared as the parsed hostname, never as a substring). Set the environment variable OBSVR_ALLOW_HTTP=1 to explicitly allow http, e.g. behind a TLS-terminating proxy on a private network. ingest_url also runs the SSRF guard at init(): the scheme must be http(s), so file:, gopher: and ftp: are refused, and the cloud-metadata address is refused in every spelling — including over https, and regardless of OBSVR_ALLOW_HTTP, which relaxes the TLS posture only. The guard is static, so a hostname that resolves to a private address is not refused; see SECURITY.md.
• Signing model: signatures are derived from your API key inside the SDK. They prove capture order and detect after-the-fact modification, but a party holding the API key could construct validly-signed events. Server-side countersigning at ingest binds accepted events to a key that never leaves the server. For local non-repudiation without trusting ingest, set device_signing_key_file to an operator-generated Ed25519 key: every event also carries a device_sig over the same preimage the HMAC covers, verified offline with obsvr-verify --device-pubkey <pinned key> (with or without the API key). Pinned keys are trusted; an unpinned key id is foreign, never trusted on first use; a missing seal on a pinned chain is a break. The SDK never generates the key (a key it cannot read refuses at init; signing needs an Ed25519 backend — pip install "obsvr-sdk[crypto]" or PyNaCl). See SECURITY.md.
• Fail mode: default is fail-open — a hook or a detector layer that fails while deciding loses that layer's enforcement for the call, which is counted and recorded on the event. Set fail_mode="closed" for policies that must never fail open. fail_mode deliberately cannot move three things: policy_floor and canary always fail closed (a floor that cannot run must not wave a call through), a redact decision whose redactor then throws blocks rather than forwarding the content it was told to strip, and after the provider has answered nothing is withheld from your application — a response-side failure falls closed only on the stored audit copy.
• NLP PII types (name, address, person, location, medical, national_id) are not detected by the built-in regex scanner; they require the Presidio integration.
• Serverless: each cold start begins a fresh integrity session; multiple sessions starting at seq_no=1 are expected and verify correctly. Call obsvr.flush() before shutdown.

License

Apache-2.0