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 and block calls with nothing configured but an API key. 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 (legacy google-generativeai)
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())

# Every call is now intercepted, policy-checked, and audited
client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What is 2+2?"}],
)

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

client = obsvr.wrap(Anthropic())          # messages.create
model = obsvr.wrap(genai.GenerativeModel("gemini-2.5-flash"))  # generate_content

Which Gemini SDK. Google ships two, and obsvr integrates one of them:

Compatibility only means fixes, not features: the legacy adapter is kept working because a large installed base still runs it, and instrumenting what people actually run is the point. google-genai has a different response shape, so support for it is new work rather than a rename.

Two things to know about the supported one. It needs the explicit obsvr.wrap() above — unlike the OpenAI and Anthropic clients it is not picked up by obsvr.init() alone, and a plainly constructed model emits no events at all. And its declared range is unbounded on purpose: one live cell (0.8.6) stands behind it, which shows that version works and locates no boundary, so no floor is claimed rather than one being guessed.

wrap() governs chat.completions.create / .parse, responses.create / .parse, messages.create / .parse, generate_content, and the beta.chat.completions.create / .parse, beta.messages.create, and beta.responses.create namespaces. 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 integration hooks its framework's real call/tool path and runs the same enforcement pipeline (pre-call PII/rules/HITL, and where the framework exposes it, post-call governance). 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. 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, is_obsvr_block
agent = Agent(chat_generator=..., tools=[...],
              hooks={"before_tool": [install_tool_gate_hook()]})

# A component's refusal reaches the caller of pipeline.run() wrapped, so match
# it by walking the cause chain rather than by catching the obsvr type.
try:
    pipe.run({"guard": {"prompt": "..."}})
except Exception as exc:
    if not is_obsvr_block(exc):
        raise

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

Every governed call resolves a 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. 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 user_id at all — PRINCIPAL_REQUIRED, after the enforcement-integrity gate, before any scanning layer. An empty string is a supplied principal; only an absent one refuses. 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"
    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 user_id on the enforcing channel (PRINCIPAL_REQUIRED; an empty string counts as supplied — 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 layer still evaluates, every event still 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 backend URL must be http(s); private / loopback / link-local / cloud-metadata addresses (169.254.169.254, 10/8, 127/8, ::1, …) are refused, resolving the hostname before connecting. A legitimate sidecar on localhost/a private network needs "allow_private_network": True; the cloud-metadata and link-local ranges are blocked even then.
• 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 in @obsvr/sdk), and merges can be gated on it in CI via the obsvr Evidence Verification GitHub Action.

Known Limitations & Architecture Notes

We document enforcement limits honestly.

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 and neither list may be read across to the other — the TypeScript SDK has three of its own that do not apply here (it is ESM-only, its named compatibility wrappers govern one method, and its zero-code auto-register misses three import 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.

1. Most integration tests drive hand-written fakes, not the real frameworks. Only the MCP surface runs against the real upstream package 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. The current Google Gemini SDK is not supported. obsvr binds google-generativeai, the legacy line, which reached end-of-life in August 2025. google-genai has no adapter and is not intercepted.

• 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