Python SDK 3.0.0

The current Python SDK release is 3.0.0, compatible with DeepIntShield Server 2.8.3. SDK and server versions are independent. Source-name resolution and other gateway features require a deployment that includes the corresponding server changes; installing the SDK does not update your gateway.

Breaking change: RAG document permissions

RetrievedChunk and build_chunk() no longer accept acl_tags. Remove that keyword from constructors, including calls that pass an empty list. Serialized chunks omit the field.

For raw chunk mappings passed to shield.rag.evaluate(), legacy acl_tags: [] and acl_tags: null placeholders are stripped. Any other value raises ValueError with code invalid_argument before a request is sent. Input mappings are not modified.

Authenticate the requester and enforce document permissions in your application or retriever before sending chunks. The removed field never established native document authorization. Requester fields provide policy context, and a safety allow decision does not prove permission to read a document.

After the retriever has authorized access, build chunks without acl_tags:

from deepintshield import DeepintShield, build_chunk

shield = DeepintShield.from_env()
chunk = build_chunk(
    chunk_id="chunk-17",
    document_id="refund-policy",
    content="Refunds take five business days.",
    labels=["policy"],
)
allowed, response = shield.rag.filter(
    query="How long do refunds take?",
    chunks=[chunk],
    source_id="qa-support",
)

Build model context from the returned allowed chunks. Filtering removes rejected chunks and applies gateway redactions to copies; the original chunks are unchanged. See the RAG SDK guide.

Select RAG sources by ID or name

The existing source_id parameter accepts a registered ID or exact registered source name when the gateway supports name resolution. The SDK sends the value unchanged; it does not list sources or require administrative credentials.

The gateway resolves references within the authenticated workspace, trims surrounding whitespace, checks IDs first, then matches names case-sensitively. A chunk’s nonempty source overrides the request source. Omit both to use workspace defaults. Unknown references return HTTP 404; ambiguous names return HTTP 409. Explicit invalid references do not fall back to defaults. Use stable IDs if source names may change.

Source selection supplies policy metadata and does not grant document access. See source selection and errors.

Guardrail redaction decisions

SDK 3.0.0 includes the decision-classification correction introduced in 2.8.5: allow_with_redaction is nonblocking alongside allow, redact, and monitor. For these decisions, result.allowed is True, result.blocked is False, and shield.guard() does not raise a block exception. Deny, sandbox, approval, and unknown decisions remain blocking, including when the reported mode is shadow.

Explicit evaluation does not rewrite local input or output. Consume the sanitized content in result.raw["result"] before forwarding redacted data. See chat and explicit guardrails.

Upgrade

Install the SDK with only the extras your application uses:

python -m pip install --upgrade "deepintshield==3.0.0"
# Example for a native LangGraph workflow:
python -m pip install --upgrade "deepintshield[langgraph]==3.0.0"
python -m pip check

Python 3.10 or newer is required. Review the dependency combinations before combining extras. Verify document-access checks, RAG rejection and redaction handling, and explicit guardrail outcomes in your application.

Deprecated MCP compatibility models and provider conversion loops remain in 3.0.0. Prefer shield.mcp.connect() or connection() for new integrations; see the MCP SDK guide.