API reference

Stable top-level package surface:

import observra

Export	Kind	Purpose
configure	Function	Resolve configuration and install provider routing
ObservraConfig	Class	Immutable resolved configuration
gateway_url	Function	Gateway URL helper
gateway_headers	Function	Gateway header helper
instrument	Function	Enable installed framework integrations
GuardrailViolation	Exception	Direct guardrail-checker exception type
__version__	String	SDK version

All observra.tracing, observra.guardrails, observra.providers, and observra.instrumentation submodules are implementation details unless documented as an advanced integration point. They can change in minor releases.

configure()

observra.configure(
    *,
    gateway_url: str | None = None,
    gateway_key: str | None = None,
    insecure: bool = False,
) -> observra.ObservraConfig

Resolves configuration from explicit arguments, then environment variables, then the hosted gateway default. Raises ObservraConfigError when no gateway key resolves, gateway URL is empty, or a plaintext HTTP URL lacks insecure=True.

ObservraConfig

class ObservraConfig:
    gateway_url: str
    gateway_key: str
    insecure: bool

Configuration objects are frozen after creation. Their string representation masks gateway-key content.

instrument()

observra.instrument() -> None

Enables installed LangChain, LangGraph, LlamaIndex, CrewAI, and Semantic Kernel integrations. Safe to call multiple times.

gateway_url() and gateway_headers()

Gateway helpers exposed at package root. They build gateway URLs and headers from resolved configuration. Most applications should use configure() and normal provider clients instead of calling them directly.

GuardrailViolation

Raised only when calling direct guardrail checking with mode="block". Normal SDK-routed provider traffic records guardrail matches and does not raise this exception.

from observra.guardrails.check import check_payload

try:
    check_payload("SSN: 123-45-6789", mode="block")
except observra.GuardrailViolation as error:
    print(error.violations)

Next

• Overview
• Configuration
• Guardrails