Configuration and transport

Constructors

Use keyword arguments directly or pass a ShieldConfig:

from deepintshield import DeepintShield, ShieldConfig

config = ShieldConfig(
    virtual_key="sk-ds-your-virtual-key",
    base_url="https://gateway.example.com/",
    timeout=20.0,
    app_name="support-copilot",
    agent_name="refund-agent",
    requester="alice@example.com",
    requester_role="support",
    persist=True,
    default_headers={"x-request-source": "web"},
)

shield = DeepintShield.from_config(config)

Setting	Default	Meaning
virtual_key	empty	Workspace virtual key. Key-dependent helpers raise if it is missing.
base_url	https://app.deepintshield.com	Hosted or self-managed gateway root. Whitespace and trailing / are removed.
timeout	30.0 seconds	Timeout for the SDK-owned synchronous httpx.Client.
default_headers	empty	Headers merged into SDK and provider requests.
app_name	deepintshield	Application attribution.
agent_name	deepintshield-agent	Stable Agentic Registry lookup key.
requester	sdk-user	Default acting user/service identifier.
requester_role	member	Default role sent to guardrail/RAG evaluation.
persist	True	Default evidence-persistence flag on explicit evaluations.

ShieldConfig.metadata is available as a configuration data field, but SDK 2.5.1 does not automatically attach it in DeepintShield.from_config(). Pass metadata= to each guardrail or RAG evaluation that needs it.

Environment variables

from deepintshield import DeepintShield

shield = DeepintShield.from_env()

Variable	Default
DEEPINTSHIELD_VIRTUAL_KEY	empty
DEEPINTSHIELD_BASE_URL	https://app.deepintshield.com
DEEPINTSHIELD_GATEWAY_URL	legacy fallback when DEEPINTSHIELD_BASE_URL is unset
DEEPINTSHIELD_TIMEOUT	30
DEEPINTSHIELD_APP_NAME	deepintshield
DEEPINTSHIELD_AGENT_NAME	deepintshield-agent
DEEPINTSHIELD_REQUESTER	sdk-user
DEEPINTSHIELD_REQUESTER_ROLE	member
DEEPINTSHIELD_PERSIST	true; 0, false, and no disable it

An invalid DEEPINTSHIELD_TIMEOUT value fails during configuration parsing. Environment values do not validate the key against the gateway until a request is made.

URLs

endpoint(provider) appends a gateway-mounted provider name without adding API version segments:

shield.endpoint("openai")       # https://app.deepintshield.com/openai
shield.openai_base_url()         # same
shield.anthropic_base_url()      # .../anthropic
shield.bedrock_endpoint_url()    # .../bedrock
shield.genai_base_url()          # .../genai

The dedicated compatibility helpers also expose /langchain, /litellm, and /pydanticai. Passthrough helpers use these exact roots:

Helper	Path
openai_passthrough_base_url()	/openai_passthrough/v1
anthropic_passthrough_base_url()	/anthropic_passthrough
genai_passthrough_base_url()	/genai_passthrough

Header helpers

shield.headers() is the minimal SDK header set: content-type, configured defaults, and x-deepintshield-vk when a key is present.

shield.create_headers() adds transport attribution:

• x-deepintshield-app
• x-deepintshield-agent
• x-deepintshield-requester
• x-deepintshield-requester-role
• optionally X-Agent-Token with identity=True

from openai import OpenAI

client = OpenAI(
    base_url=shield.endpoint("openai"),
    api_key=shield.api_key(),
    default_headers=shield.create_headers(),
)

Explicit extra values take precedence over generated headers. Treat an X-Agent-Token as a credential and never log the returned header dictionary. identity=True can perform lazy Agentic discovery/token acquisition; it is off by default so ordinary transport construction does not wait for identity.

Generic native-client wiring

base_url, headers = shield.connection(provider="openai")

with shield.http_client(provider="openai") as http:
    response = http.post(
        "/v1/chat/completions",
        json={"model": "gpt-4o-mini", "messages": []},
    )

http_client() returns a new httpx.Client; close it separately. A supplied base_url= overrides the provider-derived URL. This helper is useful only for libraries that accept an httpx.Client; prefer the typed provider builders when available.

Raw SDK requests

payload = shield.request(
    "POST",
    "/api/guardrails/evaluate",
    json_body={
        "stage": "input",
        "actor_type": "sdk_user",
        "actor_id": "alice@example.com",
        "input": "text to inspect",
    },
)

request() joins base_url and path, sends JSON through the SDK-owned client, returns the decoded JSON value, and raises DeepintShieldError for HTTP status 400 or higher. For a non-JSON success response it returns {"raw": response.text}. It does not implement retries, pagination, file upload, incremental streaming, or an asynchronous transport. Incremental chat is provided separately by shield.chat(stream=True) and ChatCompletionStream.

Connection and timeout failures preserve their httpx.HTTPError or httpx.TimeoutException type and receive SDK error metadata. Catch those separately from DeepintShieldError, or read their annotation with get_exception_error_code() as described in Error codes.

Caution

Pass SDK paths with a leading /. request() performs direct string joining; it does not normalize or URL-encode the path.

Lifetime and process use

Prefer a context manager or call close() during application shutdown:

with DeepintShield.from_env() as shield:
    result = shield.guard(stage="input", input="hello")

close() is idempotent, unregisters the client from Agentic framework resolution, and closes its connection pool. Do not use a closed instance for new requests. If several live clients share a process, scope Agentic execution with with shield.agentic.run(...): so automatic framework enforcement can select the correct workspace and key.

See Error codes for the complete structured transport-error contract.