trustgate 0.6.0
Enterprise AI Governance & Shadow AI Hunter SDK
License: MIT
Requires Python: >=3.9
Keywords: trustgate, openai, gateway, n8n, github-actions, gitlab-ci, governance, shadow-ai

# 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

```bash
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.

```python
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. Zero-config: patch all SDKs at once

Apply TrustGate headers (and optional gateway routing) to OpenAI, Anthropic, and Google Gemini in one call. Uses `TRUSTGATE_BASE_URL` (and provider-specific env vars) when `base_url` is not set.

```python
import trustgate
trustgate.patch_all()  # or patch_all(base_url="https://your-gateway.example")
# Then use openai, anthropic, or google.generativeai as usual — all requests get x-trustgate-* headers
```

### 3. Monkey patch existing OpenAI code

Route all `openai.OpenAI` traffic through TrustGate and inject context headers:

```python
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:

```bash
export TRUSTGATE_BASE_URL=https://your-trustgate-gateway.example
```

Then call `trustgate.patch_openai()` with no arguments.

### 4. Multi-model: Anthropic and Gemini

All patches use the same **context** (`context.build_trustgate_headers`) for Shadow AI detection (e.g. `local_script`, n8n, GitHub Actions, GitLab CI).

**Anthropic** (optional dep: `pip install trustgate[anthropic]`):

```python
import trustgate
trustgate.patch_anthropic(base_url="https://your-gateway.example")

import anthropic
client = anthropic.Anthropic(api_key="...")  # base_url and x-trustgate-* headers set
```

**Gemini** — patch the new `google.genai` Client (optional dep: `pip install trustgate[gemini]`), or use the wrapper to send requests via the gateway:

```python
import trustgate
trustgate.patch_google_generativeai(base_url="https://your-gateway.example")

# Or use the wrapper for full control (gateway must proxy to Gemini):
from trustgate import TrustGateGeminiClient
client = TrustGateGeminiClient(base_url="https://your-gateway.example", api_key="...")
response = client.generate_content(model="gemini-1.5-flash", contents="Hello")
```

Env vars: `TRUSTGATE_ANTHROPIC_BASE_URL`, `TRUSTGATE_GEMINI_BASE_URL` (fallback: `TRUSTGATE_BASE_URL`).

## 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](#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`:

```python
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:**

```python
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:**

```python
trustgate.patch_openai(
    base_url="https://your-gateway.example",
    workflow_step="CI_CodeReview",
)
# every OpenAI call from this process will send that step
```

## Development

```bash
pip install -e ".[dev]"
pytest
```

## License

MIT