Metadata-Version: 2.4
Name: sentraguard-agent
Version: 0.1.0
Summary: SentraGuard framework-neutral guardrail core for AI agents — LangChain/LangGraph, LiteLLM, and direct provider adapters (no OpenTelemetry dependency).
Project-URL: Homepage, https://sovereignaisecurity.com
Project-URL: Repository, https://github.com/SAISec/Sentraguard-agent-sdk-python
Project-URL: Issues, https://github.com/SAISec/Sentraguard-agent-sdk-python/issues
Project-URL: Documentation, https://github.com/SAISec/Sentraguard-agent-sdk-python#readme
Author: Sovereign AI Security Labs
License: MIT
License-File: LICENSE
Keywords: agent,ai-security,guardrails,langchain,langgraph,litellm,mitre-atlas,observability,owasp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: sentraguard-sdk>=0.1.0
Provides-Extra: all
Requires-Dist: crewai>=1.0; extra == 'all'
Requires-Dist: google-adk>=1.0; extra == 'all'
Requires-Dist: langchain-core>=0.3; extra == 'all'
Requires-Dist: langchain>=0.3; extra == 'all'
Requires-Dist: langgraph>=0.2; extra == 'all'
Requires-Dist: litellm>=1.40; extra == 'all'
Requires-Dist: openai-agents>=0.0.7; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: sentraguard-sdk[anthropic]>=0.1.0; extra == 'anthropic'
Provides-Extra: crewai
Requires-Dist: crewai>=1.0; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Provides-Extra: gemini
Requires-Dist: sentraguard-sdk[google]>=0.1.0; extra == 'gemini'
Provides-Extra: google-adk
Requires-Dist: google-adk>=1.0; extra == 'google-adk'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Requires-Dist: langchain>=0.3; extra == 'langchain'
Provides-Extra: langgraph
Requires-Dist: langgraph>=0.2; extra == 'langgraph'
Provides-Extra: litellm
Requires-Dist: litellm>=1.40; extra == 'litellm'
Provides-Extra: memory
Requires-Dist: agent-memory-guard>=0.1; extra == 'memory'
Provides-Extra: openai
Requires-Dist: sentraguard-sdk[openai]>=0.1.0; extra == 'openai'
Provides-Extra: openai-agents
Requires-Dist: openai-agents>=0.0.7; extra == 'openai-agents'
Description-Content-Type: text/markdown

# sentraguard-agent

**Framework-neutral SentraGuard guardrail core for AI agents — LangChain/LangGraph, LiteLLM, and direct provider adapters. No OpenTelemetry dependency.**

`sentraguard-agent` adds capture, identity attribution, and inline policy
enforcement to AI-agent code with minimal change. The **core** (policy engine,
identity, decisions, threats mapping) is framework-neutral; **framework
adapters are namespaced**:

| Import | Covers |
|---|---|
| `sentraguard_agent` | the framework-neutral core (engine, identity, threats) |
| `sentraguard_agent.langchain` | LangChain / LangGraph hooks (callbacks, middleware, wrappers) |
| `sentraguard_agent.litellm` | LiteLLM `CustomGuardrail` + `CustomLogger` (enforce under the Proxy; capture under SDK + Proxy) |
| `sentraguard_agent.openai_agents` | OpenAI Agents SDK input/output guardrails + run hooks |
| `sentraguard_agent.google_adk` | Google ADK (Gemini) runner plugin (before_model/tool callbacks) |
| `sentraguard_agent.crewai` | CrewAI task guardrail + tool hook + event listener |
| `sentraguard_agent.providers` | direct OpenAI / Anthropic / Gemini drop-ins |

It uses the published [`sentraguard-sdk`](https://pypi.org/project/sentraguard-sdk/)
distribution (import name `sentraguard`) internally as its client (transport,
auth, retries) — no new endpoints, no collector, no OTel.

> **Complete guide:** [`docs/SENTRAGUARD_AGENT_SDK_GUIDE.md`](docs/SENTRAGUARD_AGENT_SDK_GUIDE.md).
> **Live in-framework test evidence:** [`tests/integration/`](tests/integration/)
> — verified against openai-agents 0.17.4, litellm 1.88.0, google-adk 2.2.0,
> crewai 1.14.6.

## Install

```bash
pip install "sentraguard-agent[langchain]"            # LangChain / LangGraph
pip install "sentraguard-agent[litellm]"              # LiteLLM (SDK or Proxy)
pip install "sentraguard-agent[langchain,openai]"     # + guard DIRECT (non-framework) OpenAI calls
pip install "sentraguard-agent[memory]"               # + Agent Memory Guard composition
```

The `sentraguard-sdk` distribution is a **core dependency**. LangChain/LangGraph,
LiteLLM, Agent Memory Guard, and the provider drop-ins are optional extras. The
pure policy engine still imports without the frameworks for embedding/testing.

## Covering every surface

| Call path | Guarded by |
|---|---|
| LangChain / LangGraph framework calls | `sentraguard_agent.langchain` (capture + middleware + wrappers) |
| LiteLLM (SDK or Proxy) | `sentraguard_agent.litellm` (guardrail + logger) |
| **Direct** `openai`/`anthropic`/`gemini` calls outside a framework | `sentraguard_agent.providers.*` |

## 1. LangChain — zero-code-change capture (SAIS-327)

One import at startup; the handler auto-attaches to every run via
`register_configure_hook`. No edits to your `invoke`/`stream` call sites.

```python
# bootstrap_sentraguard.py
import sentraguard_agent.langchain.bootstrap as sg
from sentraguard_agent import BatchingAnalyticsSink, sdk_forwarder
from sentraguard import SentraGuard

client = SentraGuard()                      # internal SDK, auto-config
sg.install(BatchingAnalyticsSink(sdk_forwarder(client)))
```

```python
# app.py — add ONE import near the top; nothing else changes
import bootstrap_sentraguard   # noqa: F401
```

## 2. LangChain — authenticated identity (SAIS-329)

```python
agent.invoke(state, config={"metadata": {"user_id": u.id, "org_id": org.id, "session_id": sid}})
```

## 3. LangChain — inline enforcement (SAIS-330)

Prebuilt agent — **one line**:

```python
from sentraguard_agent import PolicyEngine
from sentraguard_agent.langchain import SentraGuardMiddleware

agent = create_agent(model, tools, middleware=[SentraGuardMiddleware(PolicyEngine())])
```

Custom `StateGraph` — wrap, don't rewrite:

```python
from sentraguard_agent import PolicyEngine
from sentraguard_agent.langchain import SentraGuardModelWrapper, guard_tool
eng = PolicyEngine()
model = SentraGuardModelWrapper(model, eng)
tools = [guard_tool(t, eng) for t in tools]
```

## 4. LiteLLM — SDK and Proxy

**LiteLLM SDK** — register the guardrail + logger:

```python
import litellm
from sentraguard_agent.litellm import SentraGuardLiteLLMGuardrail, SentraGuardLiteLLMLogger

litellm.callbacks = [SentraGuardLiteLLMGuardrail(), SentraGuardLiteLLMLogger()]
litellm.completion(model="gpt-4o", messages=[...])   # capture (logger) runs under the SDK
```

> **Enforcement scope (verified, litellm 1.88.0):** the pre/post-call
> **enforcement** hooks fire only under the LiteLLM **Proxy**. Under the bare SDK
> only the **logger** (capture) runs. To *enforce* on direct (non-proxy) calls,
> use the provider drop-ins (`sentraguard_agent.providers.*`) or route via the
> Proxy.

**LiteLLM Proxy** (the inline-gateway deployment, where enforcement applies) —
reference the guardrail in `config.yaml`:

```yaml
guardrails:
  - guardrail_name: sentraguard
    litellm_params:
      guardrail: sentraguard_agent.litellm.SentraGuardLiteLLMGuardrail
      mode: [pre_call, post_call]
```

> A LiteLLM model used *inside* LangChain (`ChatLiteLLM`) is already covered by
> the LangChain hooks — no LiteLLM adapter needed there.

## 5. Other agent frameworks

**OpenAI Agents SDK** — input/output guardrails (DENY trips the tripwire, halting the run) + run hooks for capture:

```python
from agents import Agent
from sentraguard_agent.openai_agents import SentraGuardAgentsGuardrail, SentraGuardRunHooks
g = SentraGuardAgentsGuardrail()
agent = Agent(name="...", input_guardrails=[g.as_input_guardrail()],
              output_guardrails=[g.as_output_guardrail()])
```

**Google ADK (Gemini)** — a runner-level plugin (blocks at `before_model_callback`, gates tools):

```python
from google.adk.runners import Runner
from sentraguard_agent.google_adk import SentraGuardADKPlugin
runner = Runner(agent=..., plugins=[SentraGuardADKPlugin()])
```

**CrewAI** — task guardrail + tool hook (enforcement is at the tool/task gate):

```python
from sentraguard_agent.crewai import SentraGuardCrewAI
sg = SentraGuardCrewAI()
task = Task(..., guardrail=sg.task_guardrail)   # + register sg.before_tool_hook as a BeforeToolCallHook
```

> Roadmap (Tier 2+): Microsoft Agent Framework, LlamaIndex, Pydantic AI, AWS Strands — see the roadmap section of `docs/SENTRAGUARD_AGENT_SDK_GUIDE.md`.

## 6. Direct provider calls

```python
from sentraguard_agent.providers.openai import OpenAI   # was: from openai import OpenAI
client = OpenAI()                                        # auto-guarded
```

## 7. Coverage modules (framework-neutral)

- **MCP security (SAIS-332):** `sentraguard_agent.mcp` — `scan_tools`, `ToolPinRegistry`.
- **Memory integrity (SAIS-333):** `sentraguard_agent.memory.MemoryGuard` (composes Agent Memory Guard).
- **Behavioural features (SAIS-331):** `sentraguard_agent.analytics_features` — `extract_features`, `score` (incl. multi-agent).
- **Threat mapping (SAIS-334):** `map_detection`, `coverage_matrix`, `export_coverage_markdown` (OWASP + MITRE ATLAS).

## License

MIT © Sovereign AI Security Labs
