Metadata-Version: 2.5
Name: trigguard-litellm
Version: 0.2.0
Summary: LiteLLM ↔ TrigGuard — PARTIAL callback gate + FULLY_ENFORCED protected_completion path
Project-URL: Homepage, https://trigguardai.com
Project-URL: Repository, https://github.com/TrigGuard-AI/TrigGuard
Project-URL: Documentation, https://docs.trigguardai.com
License: MIT
Requires-Python: >=3.9
Provides-Extra: dev
Requires-Dist: litellm>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Provides-Extra: litellm
Requires-Dist: litellm>=1.0.0; extra == 'litellm'
Description-Content-Type: text/markdown

# TrigGuard LiteLLM (`trigguard-litellm`)

Authorize LLM/provider effects with TrigGuard. **Two explicit modes — do not confuse them.**

## TRIGGUARD_PROTECTED (FULLY_ENFORCED)

TrigGuard controls the **final** provider execution path:

```text
Application → ExecutionIntent → Gateway (Rust Authority) → PERMIT + EAT
  → execution-proxy (PE verify + consume) → llm connector
  → server-owned provider credential → provider effect
```

```python
from trigguard_litellm import protected_completion

result = protected_completion(
    proxy_url="https://execution-proxy.example",
    trigguard_api_key="tg_live_...",
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "hello"}],
    provider="openai",
    org_id="org_...",
    mode="TRIGGUARD_PROTECTED",
)
```

**Requirements**

- Provider secrets live only on the execution-proxy host:
  `TRIGGUARD_SERVER_OWNED_LLM_API_KEY` (or `TRIGGUARD_SERVER_OWNED_OPENAI_API_KEY`)
- Agent process must **not** hold `OPENAI_API_KEY` / equivalent (direct bypass blocked)
- Caller-supplied `api_key` in the proxy target/payload is rejected
- Disposable hermetic canary: `TRIGGUARD_LLM_DISPOSABLE_STUB=1` on the proxy

Presented PERMIT, HTTP 200, and OBSERVE are never enough.

## UNPROTECTED_OR_PARTIAL (PARTIALLY_ENFORCED)

Your workload **retains provider credentials** and may still call the provider outside TrigGuard.
The LiteLLM callback requires **PERMIT + EAT** before continuing, but there is **no** PE consume
and **no** credential sovereignty.

```python
import litellm
from trigguard_litellm import TrigGuardLiteLLMCallback

litellm.callbacks = [
    TrigGuardLiteLLMCallback(
        gateway_url="https://api.trigguardai.com",
        api_key="tg_live_...",
        mode="UNPROTECTED_OR_PARTIAL",  # default
    )
]
```

**Do not** market this mode as fully protected. There is no “green shield” for PARTIAL mode.

Set mode via constructor or `TRIGGUARD_LITELLM_MODE=TRIGGUARD_PROTECTED|UNPROTECTED_OR_PARTIAL`.

## Install

```bash
pip install trigguard-litellm
# optional LiteLLM runtime
pip install 'trigguard-litellm[litellm]'
```

## Related

- Support matrix: `docs/SUPPORT_MATRIX.md`
- Adapter contract: `docs/adapters/ADAPTER_ENFORCEMENT_CONTRACT.md`
- Execution proxy: `packages/trigguard-execution-proxy`
