Safeguard Docs
Safeguard AI SDKs

Python reference

API reference for safeguard-sdk, the Safeguard AI SDK for Python, with sync and async clients.

Python reference

Package safeguard-sdk, import safeguard_sdk, version 0.1.0. Python 3.9 or newer, fully typed, one dependency (httpx).

from safeguard_sdk import Safeguard, AsyncSafeguard, SafeguardError

Safeguard(...) and AsyncSafeguard(...)

Safeguard(api_key=None, base_url="https://api.safeguard.sh/gpt/v1/ai", product_id=None,
          timeout=60, max_retries=2, http_client=None)

api_key defaults to SAFEGUARD_API_KEY; with neither, a SafeguardError with code MISSING_API_KEY is raised. http_client is your own httpx.Client (httpx.AsyncClient for the async client); the SDK does not close it. Use the client as a context manager, or call close() (await aclose() for async). The async client has the same methods as coroutines.

Methods

MethodReturns
context()Context
query(prompt, conversation_id=None, product_id=None, model=None)QueryResult
stream(prompt, conversation_id=None, product_id=None, model=None)Stream (context manager and iterator; AsyncStream for async)
conversations.create(title=None, product_id=None)Conversation
conversations.list(limit=None, offset=None)ConversationPage
conversations.get(conversation_id)Conversation
conversations.messages(conversation_id, limit=None, offset=None)MessagePage
conversations.iter_all(page_size=100)iterator of Conversation (async iterator for async)

Stream.final_answer() reads to the end and returns a QueryResult; it raises the error if the stream carried an Error event.

Types

Frozen dataclasses:

TypeFields
Contexttenant_id, org_id, user_id, email, product_id, products (list of Product(id, name)), scopes
Conversationid, title, message_count, created_at, updated_at
ConversationPageconversations, total
Messageid, prompt, answer, created_at
MessagePagemessages, total
QueryResultconversation_id, answer, query_id, model

Stream events: Start, Thinking, Tool, Final, Error, Done and Unknown(type, raw) for a type this version does not know.

Errors

SafeguardError(message, status, code, retry_after, request_id) is the base class. Subclasses: AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404), RateLimitError (429), APIError (5xx), APIConnectionError (no response) and APITimeoutError (a timeout, a kind of APIConnectionError). Other 4xx raise SafeguardError. See Errors and retries.

On this page