Docs/SDK/SDK Reference
SDK Reference
Python and TypeScript client libraries for integrating GovernanceAI into any LLM application.
Intermediate6 min readUpdated June 2026
GatewaySDK
$pip install governance-ai
The GovernanceAI SDK wraps the REST API with typed clients for Python and TypeScript. It handles authentication, retries, and response deserialization so you can focus on your application logic.
Installation
pip install governance-ai
Client initialization
from governance_ai import GovernanceClient
# Reads GOVERNANCE_API_KEY and GOVERNANCE_BASE_URL from environment
client = GovernanceClient()
# Explicit configuration
client = GovernanceClient(
api_key="gov_live_xxxx",
base_url="https://gateway.your-org.com",
timeout=30,
retries=3,
)evaluate()
The primary method. Sends a prompt through the full evaluation pipeline and returns a decision with optional model response.
| Property | Type | Default | Description |
|---|---|---|---|
| prompt | string | — | The user prompt or message to evaluate. |
| provider | string | openai | LLM provider: openai, anthropic, gemini, groq. |
| model | string | gpt-4o | Model identifier for the selected provider. |
| security_profile | string | standard | Named security profile slug to apply. |
| messages | Message[] | — | Full conversation history (replaces prompt for multi-turn). |
| metadata | dict | — | Arbitrary key-value pairs attached to the audit record. |
| dry_run | bool | false | Evaluate only — do not forward to model. |
Middleware pattern
For applications already using LangChain, the SDK provides a drop-in callback handler that wraps every chain call transparently.
from governance_ai.integrations.langchain import GovernanceCallbackHandler
from langchain_openai import ChatOpenAI
handler = GovernanceCallbackHandler(
client=client,
security_profile="strict",
block_on_deny=True,
)
llm = ChatOpenAI(
model="gpt-4o",
callbacks=[handler],
)
# All calls are now evaluated automatically
response = llm.invoke("What is the company revenue?")Block on denyWhen
block_on_deny=True, the SDK raises GovernanceBlockedError for blocked requests. Always catch this exception and surface an appropriate user-facing message rather than letting it propagate uncaught.Error handling
from governance_ai.exceptions import (
GovernanceBlockedError,
GovernancePolicyError,
GovernanceAuthError,
)
try:
result = client.evaluate(prompt=user_input)
except GovernanceBlockedError as e:
# Request was blocked by policy
return {"error": "Request not permitted.", "trace_id": e.trace_id}
except GovernancePolicyError as e:
# Policy configuration error (check your security profile)
logger.error("Policy error: %s", e)
except GovernanceAuthError:
# Invalid or expired API key
raise RuntimeError("Check GOVERNANCE_API_KEY")