trustgate 0.1.0

TrustGate Python SDK with Automatic Context for Enterprises

trustgate-python

TrustGate Python SDK with Automatic Context for enterprises. Use the same API as OpenAI while routing through the TrustGate gateway and auto-injecting trace and workflow context (n8n, GitHub Actions, GitLab CI).

Install

pip install -e .

Usage

1. Direct client (two-keyword API)

Use tg.chat.completions.create() with the same arguments as openai.chat.completions.create(); TrustGate headers are added automatically.

from trustgate import TrustGate

tg = TrustGate(
    base_url="https://your-trustgate-gateway.example",
    api_key="your-api-key",  # optional
)

response = tg.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    temperature=0.7,
)
# response is the same shape as OpenAI (e.g. response["choices"][0]["message"]["content"])

2. Monkey patch existing OpenAI code

Route all openai.OpenAI traffic through TrustGate and inject context headers:

import trustgate
trustgate.patch_openai(base_url="https://your-trustgate-gateway.example")

import openai
client = openai.OpenAI(api_key="...")  # base_url and headers are overridden
resp = client.chat.completions.create(model="gpt-4o", messages=[...])

You can also set the gateway URL via environment:

export TRUSTGATE_BASE_URL=https://your-trustgate-gateway.example

Then call trustgate.patch_openai() with no arguments.

Automatic context (bridge headers)

The SDK detects the environment and sets:

• x-trustgate-trace-id – Execution/pipeline id (e.g. N8N_EXECUTION_ID, GITHUB_RUN_ID, CI_PIPELINE_ID) or a generated UUID.
• x-trustgate-workflow-name – Workflow/pipeline name when available (n8n workflow, GitHub workflow, GitLab job).
• x-trustgate-workflow-step – Optional step name for granular traceability (see Granular traceability); in n8n can be auto-set from N8N_NODE_ID / N8N_NODE_NAME.
• x-trustgate-source – One of n8n, github_actions, gitlab_ci, or local_script (when no env is detected, for Shadow AI monitoring).

Detection is based on environment variables:

Source	Env vars (examples)
n8n	N8N_EXECUTION_ID, N8N_WORKFLOW_NAME, N8N_NODE_ID, N8N_NODE_NAME
GitHub Actions	GITHUB_ACTIONS, GITHUB_RUN_ID, GITHUB_WORKFLOW
GitLab CI	GITLAB_CI, CI_PIPELINE_ID, CI_JOB_NAME

Metadata

Every request includes source_tool metadata (in the x-trustgate-source-tool header as JSON):

• sdk_version – TrustGate Python SDK version
• python_version – Python version (e.g. 3.11.5)
• os – OS name (e.g. Windows, Linux)

You can add or override keys per request with source_tool_override:

tg.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    source_tool_override={"step_name": "extract", "stage": "preprocessing"},
)

Granular traceability

Use workflow_step so the gateway can show different parts of the same workflow (e.g. n8n) as separate steps in the Agent Intelligence Gantt chart. Without it, all calls in one run look like a single block; with it, you see segments like Data_Extraction, Final_Summary, etc.

Direct client:

tg.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    workflow_step="Data_Extraction",
)
# later in the same workflow
tg.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    workflow_step="Final_Summary",
)

n8n (automatic): When running inside n8n, the SDK can set x-trustgate-workflow-step automatically from N8N_NODE_ID or N8N_NODE_NAME, so each node appears as its own step in the Gantt without code changes.

Monkey patch with a default step:

trustgate.patch_openai(
    base_url="https://your-gateway.example",
    workflow_step="CI_CodeReview",
)
# every OpenAI call from this process will send that step

Development

pip install -e ".[dev]"
pytest

License

MIT